kolo docsbeta

Passo 1: Construa um chat no seu terminal

Um tutorial passo a passo. Dois peers no seu computador se encontram por meio de um nó de bootstrap e conversam diretamente, sem nenhum servidor no meio.

Nesta página

Este é o primeiro passo: você constrói um chat que roda no seu terminal.

Em uns dez minutos, você vai rodar três programas no seu próprio computador: um nó de bootstrap e duas cópias de um pequeno chat. Os dois chats se encontram, se conectam diretamente e enviam um ao outro o que você digita.

Tudo fica no seu computador, no endereço 127.0.0.1. Você não precisa de conta nem de nenhum servidor nosso. Quando funcionar, a última seção leva o mesmo chat para dois computadores em redes diferentes.

1Confira o que você precisa

Você precisa do Go 1.26 ou mais recente e de três janelas de terminal. Se o Go ainda não estiver instalado, instale para o seu sistema:

Baixe o instalador para macOS (o arquivo .pkg) em go.dev/dl e execute o arquivo. Se você usa o Homebrew, também dá para instalar assim:

bash
brew install go

Confira a sua versão do Go:

Terminal
go version

Você deve ver a versão 1.26 ou uma mais recente, por exemplo:

Texto
go version go1.27.3 darwin/arm64

Agora abra três janelas de terminal e deixe uma ao lado da outra:

Abra o app Terminal e aperte Cmd+N duas vezes para ter mais duas janelas.

Neste tutorial, elas se chamam Terminal 1 (o nó de bootstrap), Terminal 2 e Terminal 3 (os dois peers do chat).

2Crie uma pasta e um módulo

No Terminal 2, crie uma pasta para o chat e entre nela:

bash
mkdir kolo-chat && cd kolo-chat

Depois crie um módulo Go dentro dela:

Terminal
go mod init example.com/kolo-chat

O Go responde:

Texto
go: creating new go.mod: module example.com/kolo-chat

3Baixe as bibliotecas

Ainda no Terminal 2, adicione as três bibliotecas do Kolo que o chat usa: a kolo-swarm, para encontrar peers e se conectar a eles, a kolo-id, para a chave de cada peer, e a kolo-relay, para o relay que você pode adicionar depois.

Terminal
go get github.com/ciranda-dev/kolo-swarm@v0.1.0 github.com/ciranda-dev/kolo-id@v0.1.0 github.com/ciranda-dev/kolo-relay@v0.1.0

O Go baixa as três com o que elas precisam e termina com estas linhas:

Texto
go: added github.com/ciranda-dev/kolo-codec v0.1.0
go: added github.com/ciranda-dev/kolo-dht v0.1.0
go: added github.com/ciranda-dev/kolo-id v0.1.0
go: added github.com/ciranda-dev/kolo-relay v0.1.0
go: added github.com/ciranda-dev/kolo-secure v0.1.0
go: added github.com/ciranda-dev/kolo-swarm v0.1.0
go: added github.com/ciranda-dev/kolo-transport v0.1.0
go: added golang.org/x/crypto v0.59.0
go: added golang.org/x/net v0.63.0
go: added golang.org/x/sys v0.50.0
go: added golang.org/x/time v0.16.0

4Escreva o programa

Crie um arquivo chamado main.go na pasta kolo-chat e cole este programa nele. Ele entra em um topic chamado chat, imprime cada linha que outro peer envia e envia cada linha que você digita para todos os peers com que está conectado.

main.go
// Command chat joins a Kolo topic through a bootstrap node and sends each line typed to every connected peer.
package main

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

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

const (
	maxLine     = 4096
	sendTimeout = 10 * time.Second
	codeTooLong = 1
)

func main() {
	boot := flag.String("bootstrap", "127.0.0.1:7447", "IP:PORT of the bootstrap node")
	topic := flag.String("topic", "chat", "topic name")
	lookupOnly := flag.Bool("lookup-only", false, "only look up peers on the topic, do not announce (for a network where announcing fails)")
	every := flag.Duration("lookup-every", 15*time.Second, "time between lookups of the topic (finds peers that join later)")
	relayAddr := flag.String("relay", "", "IP:PORT of a kolo-relay to use when a direct connection fails")
	relayKey := flag.String("relay-key", "", "public key of that relay, in hex")
	listen := flag.String("listen", "127.0.0.1:0", "local IP:PORT to listen on; \":0\" listens on every interface")
	flag.Parse()
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
	defer stop()
	log.SetFlags(log.Ltime)
	if err := run(ctx, *listen, *boot, *topic, *lookupOnly, *every, *relayAddr, *relayKey); err != nil && ctx.Err() == nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context, listen, boot, name string, lookupOnly bool, every time.Duration, relayAddr, relayHex string) error {
	var relayKey []byte
	if relayAddr != "" {
		k, err := hex.DecodeString(relayHex)
		if err != nil || len(k) != 32 {
			return fmt.Errorf("-relay-key must be 64 hex characters")
		}
		relayKey = k
	}
	server, err := netip.ParseAddrPort(boot)
	if err != nil {
		return err
	}
	id, err := koloid.Generate() // in memory only, a new identity each run
	if err != nil {
		return err
	}
	s, err := koloswarm.New(ctx, listen, id, &koloswarm.Config{LookupInterval: every})
	if err != nil {
		return err
	}
	defer s.Close()
	log.Printf("me %x", id.PublicKey()[:4])
	var opts *koloswarm.JoinOptions
	if lookupOnly {
		opts = &koloswarm.JoinOptions{Lookup: true}
	}
	if err := s.Bootstrap(ctx, []netip.AddrPort{server}); err != nil {
		return fmt.Errorf("bootstrap: %w", err)
	}
	if err := s.Join(ctx, koloswarm.Topic(sha256.Sum256([]byte("kolo-chat-example/topic/v0"+name))), opts); err != nil {
		return fmt.Errorf("join: %w", err)
	}
	log.Printf("joined %q, type a line and press Enter", name)
	if relayKey != nil {
		go reserve(ctx, s, relayAddr, relayKey, id)
	}
	dialing := map[string]bool{}

	var mu sync.Mutex
	peers := map[string]*koloswarm.Peer{}
	go func() {
		sc := bufio.NewScanner(os.Stdin)
		sc.Buffer(make([]byte, maxLine), maxLine)
		for sc.Scan() {
			mu.Lock()
			if len(peers) == 0 {
				log.Print("no peer connected yet")
			}
			for _, p := range peers {
				go send(ctx, p, sc.Bytes())
			}
			mu.Unlock()
		}
	}()
	for {
		ev, err := s.Next(ctx)
		if err != nil {
			return err
		}
		switch ev.Kind {
		case koloswarm.Connected:
			mu.Lock()
			peers[string(ev.Peer.PublicKey())] = ev.Peer
			mu.Unlock()
			path := "direct"
			if !ev.Peer.Direct() {
				path = "through the relay"
			}
			log.Printf("peer %x connected (%s)", ev.Peer.PublicKey()[:4], path)
			go receive(ctx, ev.Peer)
		case koloswarm.Found:
			log.Printf("found %x at %v, connecting", ev.PublicKey[:4], ev.Addr)
		case koloswarm.Unreachable:
			log.Printf("could not reach %x directly (%v)", ev.PublicKey[:4], ev.Err)
			if relayKey != nil && !dialing[string(ev.PublicKey)] {
				dialing[string(ev.PublicKey)] = true
				go dialRelay(ctx, s, relayAddr, relayKey, id, ev.PublicKey)
			}
		case koloswarm.Lost:
			mu.Lock()
			delete(peers, string(ev.PublicKey))
			mu.Unlock()
			log.Printf("peer %x lost: %v", ev.PublicKey[:4], ev.Err)
		}
	}
}

// send writes line on a new unidirectional stream, one stream per line.
func send(ctx context.Context, p *koloswarm.Peer, line []byte) {
	ctx, cancel := context.WithTimeout(ctx, sendTimeout)
	defer cancel()
	st, err := p.Conn().OpenUniStream(ctx)
	if err == nil {
		st.SetWriteDeadline(time.Now().Add(sendTimeout))
		if _, err = st.Write(line); err == nil {
			err = st.Close()
		}
	}
	if err != nil && ctx.Err() == nil {
		log.Printf("send to %x failed: %v", p.PublicKey()[:4], err)
	}
}

// receive prints each line p sends, one stream at a time, so a peer cannot make it read many at once.
func receive(ctx context.Context, p *koloswarm.Peer) {
	for {
		st, err := p.Conn().AcceptUniStream(ctx)
		if err != nil {
			return
		}
		st.SetReadDeadline(time.Now().Add(sendTimeout))
		b, err := io.ReadAll(io.LimitReader(st, maxLine+1))
		if err != nil || len(b) > maxLine {
			st.CancelRead(codeTooLong)
			continue
		}
		log.Printf("<%x> %s", p.PublicKey()[:4], printable(string(b)))
	}
}

// printable drops control characters, so a peer cannot move the cursor or clear the terminal.
func printable(s string) string {
	return strings.Map(func(r rune) rune {
		if unicode.IsControl(r) || r == unicode.ReplacementChar {
			return -1
		}
		return r
	}, strings.ToValidUTF8(s, ""))
}

// reserve keeps our key reserved on the relay and attaches every peer that reaches us through it.
func reserve(ctx context.Context, s *koloswarm.Swarm, addr string, key []byte, id *koloid.Identity) {
	for ctx.Err() == nil {
		res, err := kolorelay.Reserve(ctx, addr, key, id, nil)
		if err != nil {
			log.Printf("relay reservation failed: %v; retrying in 10s", err)
			select {
			case <-ctx.Done():
			case <-time.After(10 * time.Second):
			}
			continue
		}
		log.Print("reserved on the relay")
		for {
			c, err := res.Accept(ctx)
			if err != nil {
				break
			}
			go func() {
				if err := s.Attach(ctx, c, false); err != nil && ctx.Err() == nil {
					log.Printf("relayed peer %x not attached: %v", c.RemotePublicKey()[:4], err)
				}
			}()
		}
		res.Close()
	}
}

// dialRelay connects to peer through the relay and hands the connection to the swarm.
func dialRelay(ctx context.Context, s *koloswarm.Swarm, addr string, key []byte, id *koloid.Identity, peer []byte) {
	log.Printf("trying %x through the relay", peer[:4])
	c, err := kolorelay.Dial(ctx, addr, key, id, peer, nil)
	if err != nil {
		log.Printf("relay dial to %x failed: %v", peer[:4], err)
		return
	}
	if err := s.Attach(ctx, c, true); err != nil && ctx.Err() == nil {
		log.Printf("relayed peer %x not attached: %v", peer[:4], err)
	}
}

Algumas coisas que vale a pena saber sobre ele:

  • Cada execução cria uma chave nova na memória, então cada peer ganha um nome novo toda vez que você o inicia. O nome dele são os 4 primeiros bytes da sua chave pública.
  • Uma linha que você digita antes de haver algum peer conectado mostra no peer connected yet e não é enviada.
  • Ele lê o endereço do nó de bootstrap da flag -bootstrap, e 127.0.0.1:7447 é o valor padrão. -listen é o endereço em que ele escuta: 127.0.0.1:0 por padrão, o que o mantém no seu computador; use :0 para alcançar outros computadores.
  • Ele busca o topic de novo a cada 15 segundos (-lookup-every), então encontra peers que entram depois. -lookup-only busca sem se anunciar.
  • -relay e -relay-key indicam um servidor kolo-relay para tentar quando uma conexão direta falha. Sem eles, nenhum relay é usado.
  • O que outro peer envia não é confiável: o programa lê no máximo 4.096 bytes por mensagem e remove os caracteres de controle antes de imprimir.

5Inicie um nó de bootstrap no Terminal 1

O nó de bootstrap é o primeiro endereço que os peers procuram. Ele ajuda os peers a se encontrarem e depois sai do caminho: as suas mensagens nunca passam por ele.

No Terminal 1, instale o kolo-node:

Terminal
go install github.com/ciranda-dev/kolo-node/cmd/kolo-node@v0.1.0

O Go pode imprimir algumas linhas go: downloading e depois mais nada. O programa vai para a pasta bin do Go. Se no próximo passo o seu shell não encontrar o kolo-node, adicione essa pasta ao seu PATH neste terminal:

bash
export PATH="$PATH:$(go env GOPATH)/bin"

Inicie o nó só no seu computador, com a chave dele em uma pasta temporária nova:

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

-first inicia uma rede nova: este nó não tem outros nós de entrada para entrar. Ele imprime três linhas e continua rodando. Os seus horários e a sua chave vão ser diferentes:

Texto
time=2026-11-11T18:51:56.880+07:00 level=INFO msg=identity key=152978a8aa6e5a00500cdc20c26ec281ba9b3a5f1dd17fd617354488f40a3cda created=true
time=2026-11-11T18:51:56.880+07:00 level=INFO msg=started version=v0.1.0 addr=127.0.0.1:7447
time=2026-11-11T18:51:56.880+07:00 level=INFO msg=network mode=first entries=0

Deixe o Terminal 1 aberto.

6Inicie o primeiro peer no Terminal 2

No Terminal 2, dentro da pasta kolo-chat, rode o chat:

Terminal
go run .

Na primeira vez, ele leva um momento para compilar. Depois o peer imprime o nome dele e fica esperando:

Texto
18:51:59 me 19353b70
18:51:59 joined "chat", type a line and press Enter

7Inicie o segundo peer no Terminal 3

No Terminal 3, vá para a mesma pasta kolo-chat (use o caminho onde você a criou) e rode o chat de novo:

Terminal
cd kolo-chat
Terminal
go run .

Em poucos segundos, os dois peers se encontram. O Terminal 3 mostra:

Texto
18:52:07 me ffdabb7a
18:52:07 joined "chat", type a line and press Enter
18:52:07 found 19353b70 at 127.0.0.1:52144, connecting
18:52:07 peer 19353b70 connected (direct)

A porta depois de 127.0.0.1 vai ser outra. O Terminal 2 ganha uma linha com o nome do novo peer, e pode mostrar uma linha found para ele na próxima busca:

Texto
18:52:07 peer ffdabb7a connected (direct)

8Digite uma linha e veja a linha chegar

No Terminal 2, digite uma linha e aperte Enter:

Texto
hello from terminal 2

Ela aparece no Terminal 3, ao lado do nome do peer que a enviou:

Texto
18:52:23 <19353b70> hello from terminal 2

Agora responda pelo Terminal 3:

Texto
hi, terminal 3 here

E o Terminal 2 mostra:

Texto
18:52:31 <ffdabb7a> hi, terminal 3 here

9Pare tudo

Aperte Ctrl-C no Terminal 3. Esse peer para, e o Terminal 2 percebe:

Texto
18:52:46 peer ffdabb7a lost: koloswarm: connection lost

Aperte Ctrl-C no Terminal 2. Depois aperte Ctrl-C no Terminal 1; o nó se despede com estas linhas e fecha:

Texto
time=2026-11-11T18:52:54.949+07:00 level=INFO msg=stopping cause="interrupt signal received"
time=2026-11-11T18:52:54.951+07:00 level=INFO msg=stats servers=0 records=2 requests=16 limited=0 closed=0 since=58s
time=2026-11-11T18:52:54.952+07:00 level=INFO msg=stopped

Dois computadores em redes diferentes

O mesmo programa funciona entre dois computadores, por exemplo um em casa e outro no trabalho. Os exemplos do Kolo prontos, e qualquer programa que chame Bootstrap(ctx, nil) sem lista, usam os nós de entrada públicos que a Ciranda mantém no ar, então não precisam de configuração. Este chat recebe o nó de entrada de -bootstrap, então aqui você roda um nó de entrada próprio: uma terceira máquina que os dois computadores alcancem, um host com um endereço IPv4 público, como um VPS pequeno. Os passos usam 203.0.113.10 como o endereço dele; use o seu.

Nesse host, instale o kolo-node como no passo 5, abra a porta UDP 7447 no firewall dele (e no do provedor, se houver) e inicie o nó em todos os seus endereços:

Terminal
kolo-node run -listen :7447 -identity "$HOME/kolo-node/node.key" -first

Em cada computador, confira se a porta está aberta e inicie o chat escutando em todas as interfaces:

Terminal
kolo-node check 203.0.113.10:7447
Terminal
go run . -listen :0 -bootstrap 203.0.113.10:7447

O que as linhas querem dizer:

  • found <peer> at <address>, connecting: a busca retornou o outro peer, e o chat está abrindo uma conexão com ele.
  • peer <peer> connected (direct): os dois computadores falam diretamente; o host só ajudou os dois a se encontrarem.
  • could not reach <peer> directly (...): não há caminho direto. Os dois lados enviaram pacotes para abrir um (hole punching), e as redes os descartaram.
  • join: ... ao iniciar: o chat não conseguiu anunciar nem buscar o topic. Se o que falha nessa rede é o anúncio, tente -lookup-only ali: esse chat ainda encontra o outro, mas não pode ser encontrado, então inicie ele por último.

Uma rede corporativa ou uma VPN pode bloquear o anúncio, o hole punching ou os dois. Aí você precisa de um relay.

Um relay para quando não há caminho direto

Esta parte foi testada entre dois computadores pela internet, por meio de um relay em um host na nuvem.

O kolo-relay repassa pacotes cifrados entre dois peers que não conseguem se alcançar. Ele não consegue lê-los: a própria conexão kolo-secure dos peers vai dentro. No mesmo host público, crie uma segunda pasta e um módulo para o servidor do relay:

bash
mkdir kolo-relay-server && cd kolo-relay-server && go mod init kolo-relay-server
Terminal
go get github.com/ciranda-dev/kolo-id@v0.1.0 github.com/ciranda-dev/kolo-relay@v0.1.0

Salve isto como main.go. Ele guarda a chave em relay.key (ou no arquivo que você passar com -identity), então a chave não muda entre reinícios:

main.go
// Command relay runs a kolo-relay server for the chat example.
package main

import (
	"context"
	"errors"
	"flag"
	"io/fs"
	"log"
	"os"
	"os/signal"

	koloid "github.com/ciranda-dev/kolo-id"
	kolorelay "github.com/ciranda-dev/kolo-relay"
)

func main() {
	listen := flag.String("listen", ":7448", "UDP IP:PORT to listen on")
	keyFile := flag.String("identity", "relay.key", "identity file, created if missing")
	flag.Parse()
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
	defer stop()
	log.SetFlags(log.Ltime)

	id, err := koloid.Load(*keyFile)
	if errors.Is(err, fs.ErrNotExist) {
		if id, err = koloid.Generate(); err == nil {
			err = id.SaveNew(*keyFile)
		}
	}
	if err != nil {
		log.Fatal(err)
	}
	s, err := kolorelay.Listen(ctx, *listen, id, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer s.Close()
	log.Printf("relay on %v, key %x", s.Addr(), id.PublicKey())
	<-ctx.Done()
}

Abra a porta UDP 7448 no host e inicie o relay:

Terminal
go run . -listen :7448

Ele mostra uma linha, relay on <address>, key <key>, em que a chave tem 64 caracteres hexadecimais. Inicie os dois chats com o endereço do relay e essa chave completa:

Terminal
go run . -listen :0 -bootstrap 203.0.113.10:7447 -relay 203.0.113.10:7448 -relay-key <relay key>

Cada chat mostra reserved on the relay. Quando uma conexão direta falha, o chat mostra trying <peer> through the relay, depois o peer se conecta pelo relay e as linhas vão nos dois sentidos. Desse teste:

Texto
14:52:42 reserved on the relay
14:54:37 peer 8b4cc656 connected (through the relay)
14:54:50 <8b4cc656> hello

O relay só é usado porque você passou -relay; nada recorre a ele sozinho.

O que acabou de acontecer

  • Cada peer entrou no topic chat por meio da DHT do nó de bootstrap: ele se anunciou lá e procurou o topic. Foi assim que o segundo peer encontrou o primeiro. Veja Topics.
  • Depois de se encontrarem, os dois peers se conectaram diretamente. O nó de bootstrap só ajudou os dois a se conhecerem; as suas mensagens nunca passaram por ele.
  • A conexão é um canal criptografado ligado à chave de cada peer, feito pela kolo-secure. Cada lado conhece a chave completa do peer com quem fala. Veja Peers.
  • Nos primeiros passos tudo rodou em 127.0.0.1, então só programas do seu computador podiam entrar. Entre computadores, o seu próprio nó de bootstrap roda em um host que os dois alcançam e cada chat escuta em :0; a página do kolo-node explica como rodar o nó de verdade.

Próximos passos

  • Leia a página da kolo-swarm: a API, os limites e o que cada evento significa.
  • Leia os Conceitos: peers, topics, logs, réplicas, exclusão e o relay, uma página curta para cada.
  • Veja o que mais você pode construir em kolo.ciranda.dev: Casos de uso.