kolo docsbeta

Passo 2: Construa um chat para desktop

Um tutorial passo a passo. Complete a parte do Kolo de uma janela de desktop já pronta: duas instâncias se encontram por um nó de bootstrap e conversam diretamente, sem nenhum servidor no meio.

Nesta página

No passo anterior você construiu um chat no seu terminal. Agora você constrói um chat para desktop.

Em cerca de quinze minutos você vai escrever a parte do Kolo de um pequeno chat de desktop. A janela, feita com Wails 3 e React, já está pronta (é JavaScript puro; TypeScript também funciona): você só escreve o serviço em Go por trás dela, que encontra outras cópias do app e fala com elas diretamente.

Tudo fica no seu computador, no endereço 127.0.0.1. Você roda um nó de bootstrap e duas cópias do app. Nada aqui precisa de conta ou de um servidor nosso.

1Confira o que você precisa

Você precisa do Go 1.26 ou mais novo, do Node.js com npm, do Git e de três janelas de terminal. Se ainda não tem o Go, siga o primeiro passo de Construa um chat no seu terminal. Depois instale a ferramenta de linha de comando do Wails 3, que compila o app:

Terminal
go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0

Confira:

Terminal
wails3 version

Você deve ver:

Texto
v3.0.0

No Linux, rode wails3 doctor: ele lista os pacotes do sistema que a janela precisa.

2Pegue o starter

Terminal
git clone https://github.com/ciranda-dev/kolo-chat-wails3-starter.git && cd kolo-chat-wails3-starter

A janela já está pronta, então este tutorial cobre só a parte do Kolo: o serviço em chatservice.go, que hoje só declara seus métodos.

3Adicione as bibliotecas do Kolo

Adicione três bibliotecas: o kolo-id cria a chave de cada usuário, o kolo-dht roda o nó de bootstrap que já está no starter e o kolo-swarm encontra peers e fala com eles.

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

O Go adiciona o que falta (o starter já tinha as outras duas):

Texto
go: added github.com/ciranda-dev/kolo-relay v0.1.0
go: added github.com/ciranda-dev/kolo-swarm v0.1.0
go: added golang.org/x/time v0.16.0

4Rode o nó de bootstrap

O nó de bootstrap é o primeiro endereço que um app consulta. Ele ajuda as cópias a se encontrarem e depois sai de cena: suas mensagens nunca passam por ele. Ele já está no starter, em cmd/bootstrap. No Terminal 1, inicie e deixe aberto:

Terminal
go run ./cmd/bootstrap

Ele imprime uma linha e continua rodando. Seu horário será diferente:

Texto
2026/11/12 19:20:21 bootstrap node on 127.0.0.1:4000

5Escreva o serviço de chat

Abra chatservice.go e apague o que tem nele. Depois cole os blocos abaixo um após o outro, cada um continuando de onde o anterior parou, com uma linha em branco entre as funções. Cada bloco vem com uma nota curta sobre por que ele está ali. A janela chama Start e Send; o serviço envia à janela um evento chat:msg para cada mensagem que chega e um evento chat:peers sempre que o número de peers conectados muda.

Estado

chatservice.go
package main

import (
	"context"
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"io"
	"log"
	"net/netip"
	"sync"
	"time"

	koloid "github.com/ciranda-dev/kolo-id"
	koloswarm "github.com/ciranda-dev/kolo-swarm"
	"github.com/wailsapp/wails/v3/pkg/application"
)

const maxMessage = 64 * 1024

// ChatMsg is the payload of the "chat:msg" event; From is the sender's kolo-id (hex public key).
type ChatMsg struct {
	From string `json:"from"`
	Text string `json:"text"`
}

type ChatService struct {
	mu      sync.Mutex
	started bool
	id      string
	ctx     context.Context
	peers   map[string]*koloswarm.Peer
}

Uma mensagem passa do Go para a janela como um ChatMsg: quem enviou e o que diz. O serviço guarda os peers conectados em um mapa, atrás de um mutex, porque o swarm e a janela o chamam de goroutines diferentes.

Identidade

chatservice.go
// Start joins the network and returns this user's kolo-id (hex public key).
func (c *ChatService) Start() (string, error) {
	c.mu.Lock()
	if c.started {
		id := c.id
		c.mu.Unlock()
		return id, nil
	}
	c.started = true
	c.peers = map[string]*koloswarm.Peer{}
	c.mu.Unlock()

	ctx := context.Background()
	c.ctx = ctx

	id, err := koloid.Generate()
	if err != nil {
		return "", err
	}
	c.mu.Lock()
	c.id = id.PublicKeyString()
	c.mu.Unlock()

koloid.Generate cria um par de chaves novo em memória a cada início, então cada execução é um usuário novo. A chave pública, em hexadecimal, é o nome desse usuário: a janela a mostra e os outros peers a veem como remetente. Start a devolve à janela. A marca started faz uma segunda chamada a Start devolver a mesma chave e não fazer mais nada, o que importa porque a janela pode chamá-la duas vezes em desenvolvimento.

Swarm e bootstrap

chatservice.go
	sw, err := koloswarm.New(ctx, "127.0.0.1:0", id, &koloswarm.Config{LookupInterval: 5 * time.Second})
	if err != nil {
		return "", err
	}
	boot := netip.MustParseAddrPort("127.0.0.1:4000")
	if err := sw.Bootstrap(ctx, []netip.AddrPort{boot}); err != nil {
		return "", err
	}

koloswarm.New abre um endpoint UDP em uma porta livre de 127.0.0.1 e o liga à identidade. LookupInterval faz o swarm buscar o tópico de novo a cada cinco segundos, e assim ele encontra um peer que começa depois. Bootstrap pede ao nó do passo 4 os primeiros contatos: sem ele, o swarm não tem a quem perguntar.

Entre no tópico

chatservice.go
	// swarm events
	go func() {
		for {
			ev, err := sw.Next(ctx)
			if err != nil {
				log.Print("swarm: ", err)
				return
			}
			if ev.Kind == koloswarm.Connected && ev.Peer != nil {
				c.addPeer(ev.Peer)
			}
		}
	}()

	// join the fixed chat topic
	sum := sha256.Sum256([]byte("kolochat/v1"))
	var topic koloswarm.Topic
	copy(topic[:], sum[:])
	go func() {
		if err := sw.Join(ctx, topic, &koloswarm.JoinOptions{Announce: true, Lookup: true}); err != nil {
			log.Print("join: ", err)
		}
	}()
	return id.PublicKeyString(), nil
}

Um tópico tem 32 bytes, aqui o SHA-256 de um nome fixo, então toda cópia do app deriva o mesmo tópico sem combinar nada. Join com Announce e Lookup ligados diz "estou aqui" e "quem mais está aqui" em uma só chamada. Ele bloqueia, então roda na própria goroutine, ao lado do laço que lê os eventos do swarm e entrega cada peer recém-conectado a addPeer.

Aceite streams

chatservice.go
func (c *ChatService) addPeer(p *koloswarm.Peer) {
	key := hex.EncodeToString(p.PublicKey())
	c.mu.Lock()
	c.peers[key] = p
	c.mu.Unlock()
	log.Print("peer connected: ", key[:8])
	c.emitPeers()

	go func() {
		defer func() {
			c.mu.Lock()
			delete(c.peers, key)
			c.mu.Unlock()
			log.Print("peer gone: ", key[:8])
			c.emitPeers()
		}()
		for {
			s, err := p.Conn().AcceptStream(c.ctx)
			if err != nil {
				return
			}
			go func() {
				defer s.Close()
				data, err := io.ReadAll(io.LimitReader(s, maxMessage))
				if err != nil || len(data) == 0 {
					return
				}
				c.emit(key, data)
			}()
		}
	}()
}

Um peer conectado é uma conexão QUIC. addPeer a guarda, para que Send consiga alcançá-la, e depois aceita streams desse peer. Um stream é uma mensagem: o código lê até o remetente fechá-lo, e io.LimitReader para em 64 KiB para que um peer não faça o app ler sem fim. Quando a conexão acaba, o peer sai do mapa.

Abra streams e envie

chatservice.go
func (c *ChatService) Send(text string) error {
	if len(text) > maxMessage {
		return errors.New("message too long")
	}
	c.mu.Lock()
	peers := make([]*koloswarm.Peer, 0, len(c.peers))
	for _, p := range c.peers {
		peers = append(peers, p)
	}
	c.mu.Unlock()
	if len(peers) == 0 {
		return errors.New("no peers connected")
	}
	var firstErr error
	for _, p := range peers {
		s, err := p.Conn().OpenStream(c.ctx)
		if err != nil {
			if firstErr == nil {
				firstErr = err
			}
			continue
		}
		if _, err := s.Write([]byte(text)); err != nil && firstErr == nil {
			firstErr = err
		}
		s.Close()
	}
	return firstErr
}

Send abre um stream novo para cada peer conectado, escreve o texto e fecha o stream, o que marca o fim da mensagem. Um erro com um peer não impede os outros, e o primeiro erro volta para a janela.

Emita os eventos para a janela

chatservice.go
// emit hands a received message to the window as the "chat:msg" event.
func (c *ChatService) emit(from string, data []byte) {
	application.Get().Event.Emit("chat:msg", ChatMsg{From: from, Text: string(data)})
}

// emitPeers tells the window how many peers are connected, as the "chat:peers" event.
func (c *ChatService) emitPeers() {
	c.mu.Lock()
	n := len(c.peers)
	c.mu.Unlock()
	application.Get().Event.Emit("chat:peers", n)
}

A janela não consegue ler um stream do Go, então emit envia a ela um evento chamado chat:msg com a chave do remetente e o texto, e emitPeers envia chat:peers com o número de peers conectados, que é o que muda o selo de "Waiting for peer" para "1 peer".

6Como a janela fala com o Go

O Wails transforma os métodos públicos do serviço em funções de JavaScript. Faça-o gerá-las agora que Start e Send existem:

Terminal
wails3 generate bindings

Você deve ver algo assim; suas contagens e seu tempo serão diferentes:

Texto
Wails v3.0.0 › Generate Bindings
 INFO  Processed: 291 Packages, 1 Service, 2 Methods, 0 Enums, 0 Models, 0 Events in 811.469125ms.

O código React do starter já as usa. Só estas poucas linhas importam aqui. As funções são imports normais dos bindings gerados:

frontend/src/App.jsx
import { Start, Send } from "../bindings/github.com/ciranda-dev/kolo-chat-wails3-starter/chatservice.js"
import { Events } from "@wailsio/runtime"

A janela chama Start uma vez ao abrir e guarda a chave que ele devolve:

frontend/src/App.jsx
    Start()
      .then((id) => setMe(id))
      .catch((err) => {
        setFailed(true)
        setError(errorText(err))
      })

Ela escuta o número de peers, que move o selo:

frontend/src/App.jsx
    const offPeers = Events.On("chat:peers", (e) => setPeers(Number(e.data) || 0))

E cada mensagem que outro peer envia:

frontend/src/App.jsx
    const off = Events.On("chat:msg", e => {
      const data = e.data
      const from = typeof data === 'object' && data ? (data.from ?? '') : ''
      const text = typeof data === 'object' && data ? (data.text ?? '') : String(data ?? '')
      setMessages((prev) => appendMessage(prev, { id: nextId.current++, from, text, mine: false }))
    })

Quando você clica em Send, a janela chama Send e mostra a mensagem como sua depois que ela saiu:

frontend/src/App.jsx
    Send(text)
      .then(() => {
        setError('')
        setMessages((prev) => appendMessage(prev, { id: nextId.current++, from: me, text, mine: true }))
        setDraft('')
      })
      .catch((err) => {
        setError(errorText(err))
      })

Compile e abra duas instâncias

No Terminal 2, na pasta do projeto, compile o app. Isso também compila a janela:

Terminal
wails3 build

O binário é bin/kolo-chat. No macOS pode aparecer um aviso do linker sobre a versão do macOS; ele é inofensivo. Com o nó de bootstrap ainda rodando no Terminal 1, inicie o app no Terminal 2 e de novo no Terminal 3:

bash
./bin/kolo-chat

Duas janelas abrem, as duas com "Waiting for peer". Em poucos segundos cada terminal registra a conexão da outra instância e o selo muda para "1 peer". Suas chaves serão diferentes.

Terminal 2:

Texto
2026/11/12 19:38:12 peer connected: 3db98117

Terminal 3:

Texto
2026/11/12 19:38:12 peer connected: 17a2e0e9

Digite em uma janela e clique em Send: a mensagem aparece na outra, ao lado dos oito primeiros caracteres da chave do remetente. Se você clicar em Send antes de a outra janela entrar, a janela mostra no peers connected: espere um momento e tente de novo.

O que acabou de acontecer

  • Cada cópia entrou no tópico pelo DHT do nó de bootstrap, se anunciou e buscou o tópico. Veja Tópicos.
  • Depois as duas cópias se conectaram diretamente. O nó de bootstrap só ajudou a se encontrarem; suas mensagens nunca passaram por ele.
  • A conexão é cifrada e ligada à chave de cada peer. Veja Peers.
  • Aqui o nó de bootstrap roda em 127.0.0.1, então tudo fica no seu computador. O Kolo Chat pronto usa a rede pública por padrão, e -bootstrap o aponta para um nó de entrada próprio.

Próximos passos

  • Leia a página do kolo-swarm: a API, os limites e o que cada evento significa.
  • Faça o mesmo em um terminal: Construa um chat no seu terminal, que também cobre dois computadores em redes diferentes.
  • O código pronto deste exemplo está no repositório kolo-chat-wails3-example da organização ciranda-dev.

Quer mais? Agora adicione um pin: Passo 3: Guarde mensagens para peers offline.