kolo docsbeta

Primeros pasos

Ejecuta un nodo de bootstrap y dos peers de chat en una misma máquina. Los peers se encuentran por topic y hablan directamente.

En esta página

Vas a ejecutar tres programas en una misma máquina, todos en 127.0.0.1:

  1. un servidor de bootstrap kolo-node, la dirección por la que entran los peers nuevos;
  2. dos copias de un pequeño programa de chat hecho con kolo-swarm.

Los dos peers de chat se unen al mismo topic, se encuentran a través del nodo, se conectan directamente y se envían las líneas que escribes. El nodo solo les ayuda a encontrarse; tus mensajes nunca pasan por él.

Necesitas Go 1.26 o posterior.

Este recorrido mantiene todo en tu ordenador, con un nodo de entrada propio en loopback. Una biblioteca sin lista de nodos de entrada entra en cambio en la red pública, a través de los dos nodos de entrada públicos que ejecuta Ciranda, incluidos en kolo-dht.

Ejecuta un nodo de bootstrap

Instala kolo-node:

go install github.com/ciranda-dev/kolo-node/cmd/kolo-node@latest

En un primer terminal, arráncalo en loopback, con su clave en un directorio temporal nuevo:

Terminal
dir=$(mktemp -d)
kolo-node run -listen 127.0.0.1:7447 -identity "$dir/node.key" -first

-first arranca una red nueva: este nodo no tiene otros nodos de entrada a los que unirse. Déjalo en marcha. Desde otro terminal, kolo-node check 127.0.0.1:7447 muestra ok 127.0.0.1:7447.

Escribe el programa de chat

Crea un módulo nuevo y añade las dos bibliotecas que usa:

Terminal
mkdir chat && cd chat
go mod init chat
go get github.com/ciranda-dev/kolo-id github.com/ciranda-dev/kolo-swarm

Guarda esto como main.go:

main.go
// Command chat joins a topic and sends each line you type to every peer on it.
package main

import (
	"bufio"
	"context"
	"crypto/sha256"
	"flag"
	"fmt"
	"io"
	"log"
	"net/netip"
	"os"
	"strings"
	"sync"
	"unicode"

	koloid "github.com/ciranda-dev/kolo-id"
	koloswarm "github.com/ciranda-dev/kolo-swarm"
)

func main() {
	flag.Parse()
	if flag.NArg() == 0 {
		log.Fatal("usage: chat IP:PORT...")
	}
	var servers []netip.AddrPort
	for _, a := range flag.Args() {
		ap, err := netip.ParseAddrPort(a)
		if err != nil {
			log.Fatal(err)
		}
		servers = append(servers, ap)
	}
	ctx := context.Background()

	id, err := koloid.Generate()
	if err != nil {
		log.Fatal(err)
	}
	s, err := koloswarm.New(ctx, "127.0.0.1:0", id, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer s.Close()
	if err := s.Bootstrap(ctx, servers); err != nil {
		log.Fatal(err)
	}
	topic := koloswarm.Topic(sha256.Sum256([]byte("kolo chat example")))
	if err := s.Join(ctx, topic, nil); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("you are %x; type a line and press Enter\n", id.PublicKey()[:4])

	var mu sync.Mutex
	peers := map[*koloswarm.Peer]bool{}
	go func() {
		for {
			ev, err := s.Next(ctx)
			if err != nil {
				return
			}
			switch ev.Kind {
			case koloswarm.Connected:
				mu.Lock()
				peers[ev.Peer] = true
				mu.Unlock()
				fmt.Printf("* %x joined\n", ev.Peer.PublicKey()[:4])
				go receive(ctx, ev.Peer)
			case koloswarm.Lost:
				mu.Lock()
				delete(peers, ev.Peer)
				mu.Unlock()
				fmt.Printf("* %x left\n", ev.Peer.PublicKey()[:4])
			}
		}
	}()

	lines := bufio.NewScanner(os.Stdin)
	for lines.Scan() {
		mu.Lock()
		for p := range peers {
			go send(ctx, p, lines.Text())
		}
		mu.Unlock()
	}
}

// send opens a one-way stream per message; closing it marks the end.
func send(ctx context.Context, p *koloswarm.Peer, msg string) {
	st, err := p.Conn().OpenUniStream(ctx)
	if err != nil {
		return
	}
	st.Write([]byte(msg))
	st.Close()
}

func receive(ctx context.Context, p *koloswarm.Peer) {
	for {
		st, err := p.Conn().AcceptUniStream(ctx)
		if err != nil {
			return
		}
		msg, _ := io.ReadAll(io.LimitReader(st, 4096))
		// The text comes from another machine: drop control characters
		// before printing it to a terminal.
		clean := strings.Map(func(r rune) rune {
			if unicode.IsControl(r) {
				return -1
			}
			return r
		}, string(msg))
		fmt.Printf("%x: %s\n", p.PublicKey()[:4], clean)
	}
}

Ejecuta dos peers

En un segundo terminal:

Terminal
go run . 127.0.0.1:7447

En un tercer terminal, vuelve a ejecutar el mismo comando. Al cabo de un momento, cada peer muestra * <key> joined con los primeros bytes de la clave pública del otro. Escribe una línea en un terminal y pulsa Intro: aparece en la otra, junto a la clave de quien la envió. Detén un peer con Ctrl-C y el otro mostrará * <key> left.

Qué acaba de pasar

  • Cada peer creó una clave nueva de kolo-id. Su clave pública es su nombre en la red. Consulta Peers.
  • Los dos se unieron al topic sha256("kolo chat example"). Unirse con opciones nil anuncia el peer en el topic y busca el topic. Consulta Topics.
  • El segundo peer encontró al primero a través del servidor kolo-dht del nodo y se conectó a él. La conexión es un canal kolo-secure ligado a la clave de cada peer, así que cada lado sabe con qué clave está hablando.
  • Cada mensaje viaja por su propio stream de un solo sentido, directamente de un peer al otro.

Siguientes pasos

  • Para guardar un historial que los peers puedan comprobar, escribe los mensajes en un log de kolo-log y cópialo con kolo-sync. Consulta Logs y Réplicas.
  • Para ejecutar peers en máquinas distintas, llama a Bootstrap(ctx, nil) sin lista: los peers entran en la red pública a través de los nodos de entrada públicos, gratis y sin garantía de disponibilidad mientras Kolo sea una beta. Para una red propia, pon en marcha unos cuantos servidores kolo-node en máquinas con una dirección IPv4 pública y pasa sus direcciones a cada peer. La página de kolo-node tiene los detalles.
  • Dos peers que no pueden alcanzarse directamente pueden usar un relay, si decides ejecutar uno.