kolo docsbeta

Primeiros passos

Rode um nó de bootstrap e dois peers de chat em uma máquina. Os peers se encontram pelo topic e conversam diretamente.

Nesta página

Você vai rodar três programas em uma máquina, todos em 127.0.0.1:

  1. um servidor de bootstrap kolo-node, o endereço por onde os novos peers entram;
  2. duas cópias de um pequeno programa de chat feito com kolo-swarm.

Os dois peers de chat entram no mesmo topic, se encontram por meio do nó, se conectam diretamente e enviam um ao outro as linhas que você digita. O nó só ajuda os dois a se encontrarem; as suas mensagens nunca passam por ele.

Você precisa do Go 1.26 ou mais recente.

Este passo a passo mantém tudo no seu computador, com um nó de entrada próprio no loopback. Uma biblioteca sem lista de nós de entrada entra, em vez disso, na rede pública, pelos dois nós de entrada públicos que a Ciranda mantém no ar, embutidos na kolo-dht.

Rode um nó de bootstrap

Instale o kolo-node:

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

Em um primeiro terminal, inicie o nó no loopback, com a chave dele em um novo diretório temporário:

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

-first inicia uma rede nova: este nó não tem outros nós de entrada para entrar. Deixe o nó rodando. Em outro terminal, kolo-node check 127.0.0.1:7447 imprime ok 127.0.0.1:7447.

Escreva o programa de chat

Crie um novo módulo e adicione as duas bibliotecas que ele usa:

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

Salve isto 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)
	}
}

Rode dois peers

Em um segundo terminal:

Terminal
go run . 127.0.0.1:7447

Em um terceiro terminal, rode o mesmo comando de novo. Depois de um instante, cada peer imprime * <key> joined com os primeiros bytes da chave pública do outro. Digite uma linha em um terminal e aperte Enter: ela aparece no outro, ao lado da chave de quem enviou. Pare um peer com Ctrl-C e o outro imprime * <key> left.

O que aconteceu

  • Cada peer criou uma nova chave kolo-id. A chave pública é o nome dele na rede. Veja Peers.
  • Os dois entraram no topic sha256("kolo chat example"). Entrar com as opções nil anuncia o peer no topic e faz a busca pelo topic. Veja Topics.
  • O segundo peer encontrou o primeiro pelo servidor kolo-dht do nó e se conectou a ele. A conexão é um canal kolo-secure ligado à chave de cada peer, então cada lado sabe com qual chave está falando.
  • Cada mensagem viaja no seu próprio stream de mão única, direto de um peer para o outro.

Próximos passos

  • Para manter um histórico que os peers possam verificar, escreva as mensagens em um log kolo-log e copie esse log com a kolo-sync. Veja Logs e Réplicas.
  • Para rodar peers em máquinas diferentes, chame Bootstrap(ctx, nil) sem lista: os peers entram na rede pública pelos nós de entrada públicos, de graça e sem garantia de disponibilidade enquanto o Kolo for uma beta. Para uma rede própria, rode alguns servidores kolo-node em hosts com um endereço IPv4 público e passe os endereços deles para todos os peers. A página do kolo-node tem os detalhes.
  • Dois peers que não conseguem se alcançar diretamente podem usar um relay, se você decidir rodar um.