kolo docsbeta

Paso 2: Construye un chat de escritorio

Un tutorial paso a paso. Completa la parte de Kolo de una ventana de escritorio ya hecha: dos instancias se encuentran a través de un nodo de bootstrap y chatean directamente, sin ningún servidor en medio.

En esta página

En el paso anterior construiste un chat en tu terminal. Ahora construyes un chat de escritorio.

En unos quince minutos vas a escribir la parte de Kolo de un pequeño chat de escritorio. La ventana, hecha con Wails 3 y React, ya está lista (es JavaScript simple; TypeScript también funciona): solo escribes el servicio en Go que hay detrás, que encuentra otras copias de la app y habla con ellas directamente.

Todo se queda en tu ordenador, en la dirección 127.0.0.1. Ejecutas un nodo de bootstrap y dos copias de la app. No necesitas ninguna cuenta ni ningún servidor nuestro.

1Comprueba lo que necesitas

Necesitas Go 1.26 o superior, Node.js con npm, Git y tres ventanas de terminal. Si aún no tienes Go, sigue el primer paso de Construye un chat en tu terminal. Después instala la herramienta de línea de comandos de Wails 3, que compila la app:

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

Compruébalo:

Terminal
wails3 version

Debes ver:

Texto
v3.0.0

En Linux, ejecuta wails3 doctor: lista los paquetes del sistema que necesita la ventana.

2Consigue el starter

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

La ventana ya está hecha, así que este tutorial solo cubre la parte de Kolo: el servicio de chatservice.go, que hoy solo declara sus métodos.

3Añade las bibliotecas de Kolo

Añade tres bibliotecas: kolo-id crea la clave de cada usuario, kolo-dht ejecuta el nodo de bootstrap que ya está en el starter y kolo-swarm encuentra peers y habla con ellos.

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

Go añade lo que falta (el starter ya tenía las otras dos):

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

4Ejecuta el nodo de bootstrap

El nodo de bootstrap es la primera dirección que consulta una app. Ayuda a las copias a encontrarse y luego se aparta: tus mensajes nunca pasan por él. Ya está en el starter, en cmd/bootstrap. En el Terminal 1, arráncalo y déjalo abierto:

Terminal
go run ./cmd/bootstrap

Imprime una línea y sigue en marcha. Tu hora será distinta:

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

5Escribe el servicio de chat

Abre chatservice.go y borra lo que hay. Después pega los bloques de abajo uno tras otro, cada uno continuando donde terminó el anterior, con una línea en blanco entre funciones. Cada bloque trae una nota breve sobre por qué está ahí. La ventana llama a Start y Send; el servicio envía a la ventana un evento chat:msg por cada mensaje que llega y un evento chat:peers cada vez que cambia el número de peers conectados.

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
}

Un mensaje pasa de Go a la ventana como un ChatMsg: quién lo envió y qué dice. El servicio guarda los peers conectados en un mapa, tras un mutex, porque el swarm y la ventana lo llaman desde goroutines distintas.

Identidad

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 crea un par de claves nuevo en memoria en cada arranque, así que cada ejecución es un usuario nuevo. La clave pública, en hexadecimal, es el nombre de ese usuario: la ventana la muestra y los demás peers la ven como remitente. Start se la devuelve a la ventana. La marca started hace que una segunda llamada a Start devuelva la misma clave y no haga nada más, lo que importa porque la ventana puede llamarla dos veces en desarrollo.

Swarm y 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 un endpoint UDP en un puerto libre de 127.0.0.1 y lo une a la identidad. LookupInterval hace que busque el tema de nuevo cada cinco segundos, así encuentra a un peer que arranca más tarde. Bootstrap pide al nodo del paso 4 los primeros contactos: sin él, el swarm no tiene a quién preguntar.

Únete al tema

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
}

Un tema son 32 bytes, aquí el SHA-256 de un nombre fijo, así que todas las copias de la app derivan el mismo tema sin coordinarse. Join con Announce y Lookup activados dice "estoy aquí" y "quién más está aquí" en una sola llamada. Bloquea, así que corre en su propia goroutine, junto al bucle que lee los eventos del swarm y entrega cada peer recién conectado a addPeer.

Acepta 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)
			}()
		}
	}()
}

Un peer conectado es una conexión QUIC. addPeer la guarda, para que Send pueda llegar a ella, y después acepta streams de ese peer. Un stream es un mensaje: el código lee hasta que el remitente lo cierra, y io.LimitReader corta a los 64 KiB para que un peer no pueda hacer que la app lea sin fin. Cuando la conexión termina, el peer se quita del mapa.

Abre streams y envía

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 un stream nuevo hacia cada peer conectado, escribe el texto y cierra el stream, que es lo que marca el final del mensaje. Un error con un peer no detiene a los demás, y el primer error se devuelve a la ventana.

Emite los eventos a la ventana

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

La ventana no puede leer un stream de Go, así que emit le envía un evento llamado chat:msg con la clave del remitente y el texto, y emitPeers envía chat:peers con el número de peers conectados, que es lo que cambia la insignia de "Waiting for peer" a "1 peer".

6Cómo habla la ventana con Go

Wails convierte los métodos públicos del servicio en funciones de JavaScript. Haz que las genere ahora que Start y Send existen:

Terminal
wails3 generate bindings

Debes ver algo así; tus cuentas y tu tiempo serán distintos:

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

El código React del starter ya las usa. Solo importan estas pocas líneas. Las funciones son imports normales de los bindings generados:

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

La ventana llama a Start una vez al abrirse y guarda la clave que devuelve:

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

Escucha el número de peers, que mueve la insignia:

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

Y cada mensaje que envía otro peer:

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

Cuando pulsas Send, la ventana llama a Send y muestra el mensaje como tuyo cuando ya salió:

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

Compila y abre dos instancias

En el Terminal 2, desde la carpeta del proyecto, compila la app. Esto también compila la ventana:

Terminal
wails3 build

El binario es bin/kolo-chat. En macOS puede aparecer un aviso del linker sobre la versión de macOS; es inofensivo. Con el nodo de bootstrap aún en marcha en el Terminal 1, arranca la app en el Terminal 2 y otra vez en el Terminal 3:

bash
./bin/kolo-chat

Se abren dos ventanas, las dos con "Waiting for peer". En pocos segundos cada terminal registra la conexión de la otra instancia y la insignia pasa a "1 peer". Tus claves serán distintas.

Terminal 2:

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

Terminal 3:

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

Escribe en una ventana y pulsa Send: el mensaje aparece en la otra, junto a los ocho primeros caracteres de la clave del remitente. Si pulsas Send antes de que la otra ventana se haya unido, la ventana muestra no peers connected: espera un momento e inténtalo de nuevo.

Qué acaba de pasar

  • Cada copia se unió al tema a través del DHT del nodo de bootstrap, se anunció y buscó el tema. Mira Temas.
  • Después las dos copias se conectaron directamente. El nodo de bootstrap solo les ayudó a encontrarse; tus mensajes nunca pasaron por él.
  • La conexión está cifrada y ligada a la clave de cada peer. Mira Peers.
  • Aquí el nodo de bootstrap se ejecuta en 127.0.0.1, así que todo se queda en tu ordenador. El Kolo Chat terminado usa la red pública por defecto, y -bootstrap lo apunta a un nodo de entrada propio.

Siguientes pasos

  • Lee la página de kolo-swarm: su API, sus límites y qué significa cada evento.
  • Haz lo mismo en una terminal: Construye un chat en tu terminal, que también cubre dos ordenadores en redes distintas.
  • El código terminado de este ejemplo está en el repositorio kolo-chat-wails3-example de la organización ciranda-dev.

¿Quieres más? Ahora añade un pin: Paso 3: Guarda mensajes para peers sin conexión.