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:
go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0Confira:
wails3 versionVocê deve ver:
v3.0.0No Linux, rode wails3 doctor: ele lista os pacotes do sistema que a janela
precisa.
2Pegue o starter
git clone https://github.com/ciranda-dev/kolo-chat-wails3-starter.git && cd kolo-chat-wails3-starterA 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.
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.0O Go adiciona o que falta (o starter já tinha as outras duas):
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.04Rode 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:
go run ./cmd/bootstrapEle imprime uma linha e continua rodando. Seu horário será diferente:
2026/11/12 19:20:21 bootstrap node on 127.0.0.1:40005Escreva 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
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
// 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
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
// 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
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
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
// 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:
wails3 generate bindingsVocê deve ver algo assim; suas contagens e seu tempo serão diferentes:
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:
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:
Start()
.then((id) => setMe(id))
.catch((err) => {
setFailed(true)
setError(errorText(err))
})Ela escuta o número de peers, que move o selo:
const offPeers = Events.On("chat:peers", (e) => setPeers(Number(e.data) || 0))E cada mensagem que outro peer envia:
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:
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:
wails3 buildO 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:
./bin/kolo-chat.\bin\kolo-chat.exe./bin/kolo-chatDuas 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:
2026/11/12 19:38:12 peer connected: 3db98117Terminal 3:
2026/11/12 19:38:12 peer connected: 17a2e0e9Digite 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-bootstrapo 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.