kolo docsbeta

Paso 8: Usar la red pública

Arranca el chat en la red pública por defecto, para que personas en redes distintas se encuentren sin configurar nada, mantén tu propia red con -bootstrap y di qué hacer cuando ningún nodo de entrada responde.

En esta página

En los pasos anteriores el chat encontraba a sus pares con un nodo de bootstrap en tu propio equipo, 127.0.0.1:4000. Eso sirve para dos ventanas en un equipo, y para nadie más. Ahora la app se une por defecto a la red pública: Ciranda ejecuta unos cuantos nodos de entrada que vienen integrados en Kolo, gratuitos y sin garantía de disponibilidad mientras Kolo esté en beta. No pasas nada, y dos personas en redes distintas se encuentran.

La app tiene dos formas de elegir una red, y nunca las mezcla:

  • La red pública, la predeterminada. No configuras nada. La app no pasa ningún nodo de entrada, y kolo-swarm usa la lista integrada en kolo-dht.
  • Tu propia red, con -bootstrap host:puerto[,host:puerto]. Los nodos de entrada que nombras se usan solos: no se contacta con los públicos. Así mantienes una red privada, y así trabajas solo en este equipo: un nodo de entrada en 127.0.0.1, como el de cmd/bootstrap.

Si ningún nodo de entrada responde cuando arranca la app, la app lo dice y nombra estas formas. Nunca recurre a otra red: una app que pidió la tuya no se une en silencio a la pública.

Tú escribes la lección: los ajustes que eligen la red, en config.go, el error de una red que no responde, en network.go, y las dos líneas de chatservice.go que los usan. Todo lo demás es fontanería, y la traes desde la etiqueta step-8.

1Comprueba lo que necesitas y trae los archivos dados

Necesitas lo mismo que en el paso 7: Go 1.26 o superior, Node.js, wails3, el nodo de bootstrap y un pin local. Parte del proyecto que terminaste en el paso 7. Este paso no añade ninguna biblioteca, y sube dos a versiones más nuevas. Trae las etiquetas:

Terminal
git fetch origin --tags

Trae la ventana, los archivos del módulo, la descripción de la red y las pruebas de este paso. Reemplazan tus archivos del paso 7 con el mismo nombre:

Terminal
git checkout step-8 -- frontend go.mod go.sum networkinfo.go conversations.go '*_test.go'
ArchivoQué hace
frontend/La línea bajo las conversaciones que dice a qué red se une la app, y las frases de una red que no responde, en inglés, español y portugués.
go.mod, go.sumkolo-swarm y kolo-dht v0.1.0, que tienen los nodos de entrada públicos (kolo-dht) y BootstrapNodes (kolo-swarm).
networkinfo.goNetworkInfo: el modo, "public" u "own", y los nodos de entrada en uso. La ventana lo muestra.
conversations.goStart devuelve la red, y una conversación que no arrancó porque ningún nodo de entrada respondió lo dice en su fila, sin carpeta que apartar.
*_test.goLas pruebas de este paso, y un TestMain que mantiene todas las pruebas fuera de la red pública.

La etiqueta también tiene los config.go, network.go y chatservice.go terminados, por si quieres comparar los tuyos con ellos. Hasta que escribas network.go, el proyecto no compila.

2Deja vacíos los nodos de entrada por defecto

En el paso 7 Bootstrap era un único IP:PUERTO con un valor por defecto. Ahora es una lista de entradas host:puerto, y vacía significa la red pública. El mismo flag, -bootstrap, y la misma variable, KOLO_CHAT_BOOTSTRAP, nombran la tuya.

La dirección de escucha cambia con ello. Un socket en 127.0.0.1 no puede llegar a un nodo de entrada público, así que el valor por defecto es 0.0.0.0:0, salvo cuando todos los nodos de entrada que nombras están en loopback: entonces la app se queda en 127.0.0.1:0, como antes.

En config.go, añade el import de kolo-swarm:

config.go
	"strconv"
	"time"

	koloswarm "github.com/ciranda-dev/kolo-swarm"
)

En config.go, reemplaza los dos valores por defecto del nodo de bootstrap y de la dirección de escucha por:

config.go
// Defaults of the settings that have one. Everything else must be configured.
const (
	loopbackListen        = "127.0.0.1:0"    // the default when every entry node is on this computer
	publicListen          = "0.0.0.0:0"      // the default otherwise: the public network cannot be reached from loopback
	defaultPinAddr        = "127.0.0.1:7450" // where `kolo-pin run` listens unless told otherwise
	defaultPinTTL         = 30 * 24 * time.Hour
	defaultPinQuota       = 16 << 20 // bytes
	defaultLookupInterval = 5 * time.Second
)

En config.go, reemplaza las líneas de Bootstrap y Listen en Config por:

config.go
	Bootstrap       string        // -bootstrap, KOLO_CHAT_BOOTSTRAP: host:port of the entry nodes of your own network, comma-separated, used alone. Default: the public network
	Listen          string        // -listen, KOLO_CHAT_LISTEN: local IP:PORT of every conversation. Default 127.0.0.1:0 when every entry node is on loopback, else 0.0.0.0:0; a fixed port allows one conversation

En LoadConfig, reemplaza las líneas de bootstrap y listen por:

config.go
		{"bootstrap", "KOLO_CHAT_BOOTSTRAP", "host:port of the entry nodes of your own network, comma-separated, used alone (default: the public network)", text(&c.Bootstrap)},
		{"listen", "KOLO_CHAT_LISTEN", "local IP:PORT to listen on (default " + loopbackListen + " when every entry node is on loopback, else " + publicListen + ")", text(&c.Listen)},

En settings, los nodos de entrada ahora son cadenas. nil es la red pública:

config.go
	token           []byte   // nil: the app issues one
	bootstrap       []string // the entry nodes of your own network; nil is the public network
	inConversation  bool     // the key and the pin are known: from the configuration, or later from an invite

En resolve, borra las dos líneas que daban un valor por defecto a Bootstrap y Listen. Luego reemplaza el análisis de la dirección de bootstrap por el análisis de la lista y la elección de la dirección de escucha:

config.go
	var err error
	if s.Bootstrap != "" {
		s.bootstrap, err = koloswarm.ParseNodes(s.Bootstrap)
		switch {
		case err != nil:
			return s, &ConfigError{Setting: "bootstrap", Err: fmt.Errorf("%w: %w", ErrMalformed, err)}
		case len(s.bootstrap) == 0:
			return s, &ConfigError{Setting: "bootstrap", Err: fmt.Errorf("%w: lists no entry node", ErrMalformed)}
		}
	}
	if s.Listen == "" {
		s.Listen = publicListen
		if loopbackOnly(s.bootstrap) {
			s.Listen = loopbackListen
		}
	}

ParseNodes acepta como máximo 16 entradas, cada una una dirección IPv4 o un nombre de host que resuelve a IPv4, con un puerto de 1 a 65535. Los espacios y las entradas repetidas se descartan, y una dirección IPv6 en cualquier forma se rechaza. -bootstrap , no lista ningún nodo de entrada: es un error, nunca la red pública.

Añade loopbackOnly antes de fixedPort:

config.go
// loopbackOnly says whether every entry node is a loopback IPv4 literal, so the app can stay on 127.0.0.1.
func loopbackOnly(nodes []string) bool {
	if len(nodes) == 0 {
		return false
	}
	for _, n := range nodes {
		if a, err := netip.ParseAddrPort(n); err != nil || !a.Addr().IsLoopback() {
			return false
		}
	}
	return true
}

3Di cuándo no responde nadie

Bootstrap de kolo-swarm devuelve ErrNoNodes de kolo-dht cuando ningún nodo de entrada responde. Eso es una frase para la persona que está frente a la ventana, no una línea de log: qué red se intentó, y las formas de elegir otra. Crea network.go con el error:

network.go
package main

import (
	"context"
	"errors"
	"fmt"
	"strings"

	kolodht "github.com/ciranda-dev/kolo-dht"
	koloswarm "github.com/ciranda-dev/kolo-swarm"
)

// ErrNetwork matches every NetworkError.
var ErrNetwork = errors.New("the network cannot be reached")

// NetworkError says that no entry node answered, and names the three ways to choose a network.
type NetworkError struct {
	Network NetworkInfo
	Err     error // kolo-dht's ErrNoNodes
}

func (e *NetworkError) Error() string {
	var b strings.Builder
	if e.Network.Mode == "own" {
		fmt.Fprintf(&b, "Kolo Chat could not reach your network: no entry node answered (%s, from -bootstrap). Check that they run and that the addresses are right.", strings.Join(e.Network.Nodes, ", "))
	} else {
		b.WriteString("Kolo Chat could not reach the public network: no entry node answered. Check your internet connection and try again.")
	}
	b.WriteString(" You have three ways to connect. Public network, the default: run by Ciranda, free, with no uptime guarantee while Kolo is a beta.")
	b.WriteString(" Your own network: start Kolo Chat with -bootstrap host:port, the entry node of a kolo-node you run.")
	b.WriteString(" This computer only: run kolo-node with -first on 127.0.0.1 and start Kolo Chat with -bootstrap 127.0.0.1:PORT.")
	return b.String()
}
func (e *NetworkError) Unwrap() error        { return e.Err }
func (e *NetworkError) Is(target error) bool { return target == ErrNetwork }

errors.Is(err, ErrNetwork) es verdadero para todos, y errors.Is(err, kolodht.ErrNoNodes) sigue diciendo la causa.

Luego la llamada. bootstrapSwarm es el único lugar que llega a la red, y es una variable para que las pruebas la reemplacen: el TestMain que trajiste la cambia por un guardia que falla cualquier arranque sin -bootstrap, así que ninguna prueba envía un paquete a una dirección pública. bootstrap convierte "ningún nodo de entrada respondió" en el error de arriba, y deja pasar cualquier otro error tal cual:

network.go
// bootstrapSwarm is what bootstrap calls: the tests replace it, so that none of them reaches the public network.
var bootstrapSwarm = func(ctx context.Context, sw *koloswarm.Swarm, set settings) error {
	return sw.Bootstrap(ctx, nil) // the swarm reads set.bootstrap from its Config, and uses the public nodes when it is empty
}

// bootstrap joins the network the settings choose, and turns "no entry node answered" into a NetworkError. It never
// falls back to another network.
func bootstrap(ctx context.Context, sw *koloswarm.Swarm, set settings) error {
	err := bootstrapSwarm(ctx, sw, set)
	if errors.Is(err, kolodht.ErrNoNodes) {
		return &NetworkError{Network: set.network(), Err: err}
	}
	return err
}

Bootstrap(ctx, nil) es toda la elección. Con BootstrapNodes vacío, kolo-swarm usa los nodos de entrada públicos integrados en kolo-dht. Con tu lista en BootstrapNodes, usa solo esa lista. Una lista vacía que no es nil es un error que no envía nada, y así una red privada se mantiene fuera de la pública.

4Únete a la red

En chatservice.go, borra el import "net/netip": nada ahí analiza ya una dirección. Luego dale tu lista al swarm y llama a bootstrap:

chatservice.go
	swarmCfg := &koloswarm.Config{LookupInterval: c.set.LookupInterval, MaxTopics: swarmTopics, DHT: dhtConfig(), BootstrapNodes: c.set.bootstrap}
	if c.sw, err = koloswarm.New(c.ctx, c.set.Listen, c.id, swarmCfg); err != nil {
		return err
	}
	if err = bootstrap(c.ctx, c.sw, c.set); err != nil {
		return err
	}

5Qué hace la ventana con esto

El NetworkError viaja como el error de una conversación, y conversations.go copia su modo en la fila. La ventana mira el modo y escribe la frase en el idioma del navegador: inglés, español o portugués. Cualquier otro error se muestra tal como llegó:

frontend/src/App.jsx
              {networkFault(row) ? (
                <>
                  <p className="error">{networkFault(row)}</p>
                  <p className="note">{networkText('network.options')}</p>
                </>
              ) : (
                <p className="error">{row.error}</p>
              )}

Bajo la lista de conversaciones una línea dice a qué red se unió la app, y los nodos de entrada están en su tooltip:

frontend/src/Conversations.jsx
        <p className="note" title={network.nodes.join(', ')}>{networkLine(network)}</p>

6Ejecútalo

Compila la app:

Terminal
GOWORK=off wails3 build

Primero tu propia red en este equipo, como antes, pero ahora por nombre. Arranca el nodo de bootstrap y déjalo en marcha:

Terminal
go run ./cmd/bootstrap

En otra terminal, arranca el pin local y déjalo en marcha:

Terminal
go run github.com/ciranda-dev/kolo-pin/cmd/kolo-pin run -data .data/pin -max-bytes 100MB

Alice necesita la clave pública del pin, solo en su terminal:

Terminal
export KOLO_CHAT_PIN_KEY=$(go run github.com/ciranda-dev/kolo-pin/cmd/kolo-pin id -data .data/pin)
Terminal
./bin/kolo-chat -data .data/alice-8 -bootstrap 127.0.0.1:4000

En la ventana de Alice haz clic en New conversation, escribe "Family" y haz clic en Create. Arranca a Bob en otra terminal, sin la variable, en la misma red:

Terminal
./bin/kolo-chat -data .data/bob-8 -bootstrap 127.0.0.1:4000

Invita a Bob y apruébalo, como en el paso 7. La línea bajo la lista de conversaciones empieza con "Tu propia red", y su tooltip tiene 127.0.0.1:4000.

Ahora mira el error. Cierra la ventana de Alice y arráncala de nuevo con un nodo de entrada que no existe:

Terminal
./bin/kolo-chat -data .data/alice-8 -bootstrap 127.0.0.1:9

Tras unos segundos Family aparece marcada con un "!" y dice que Kolo Chat no pudo conectar con tu red, con las tres formas de conectarse. La ventana no se une a la red pública en su lugar. Arranca a Alice otra vez con -bootstrap 127.0.0.1:4000 y Family arranca.

Ahora la red pública. Cierra el nodo de bootstrap: no lo necesitas, y toda app que arrancas sin -bootstrap se une a la red pública, que necesita tu conexión a internet y UDP permitido hacia fuera:

Terminal
./bin/kolo-chat -data .data/alice-8

Nada más cambia para dos ventanas en un equipo: se encuentran a través de los nodos de entrada públicos, y el pin local sigue funcionando. Para dos personas en redes distintas, la invitación lleva la dirección del pin, y no hay ningún pin público, así que el pin debe tener una dirección IPv4 pública a la que lleguen las dos. Ejecútalo en un host como un VPS, como en Ejecuta un peer de anclaje en un VPS, y arranca a Alice con -pin <dirección>:7450 y la clave del host en KOLO_CHAT_PIN_KEY. Para eso nadie necesita un nodo de bootstrap.

7Ejecuta las pruebas

Las pruebas que trajiste cubren el valor por defecto, que es la lista pública en los ajustes y 0.0.0.0:0 como dirección de escucha; -bootstrap solo, que se usa solo y mantiene los nodos de entrada de loopback en 127.0.0.1:0; cada -bootstrap malo, desde una dirección IPv6 hasta 17 entradas; la lista que llega al swarm; el error que nombra las tres formas, para ambas redes; un error que no es de red, que pasa tal cual; la fila de una conversación que no arrancó; y un reinicio con el nodo de entrada caído, y luego en pie. Ninguna envía un paquete a una dirección pública:

Terminal
GOWORK=off go test ./...

8Lo que la red pública no es

Conoce los límites:

  • Sin garantía de disponibilidad. Los nodos de entrada públicos los ejecuta Ciranda y son gratuitos, y mientras Kolo esté en beta pueden estar caídos. La app lo dice y ofrece tu propia red.
  • Ni pin público ni relay público. La red pública ayuda a que los pares se encuentren. No guarda mensajes para miembros sin conexión ni retransmite conexiones: el pin es tuyo, y su dirección va en la invitación. Detrás de una red que bloquea el camino directo, un relay de conexión también es tuyo.
  • Los nodos de entrada ven quién pregunta. Un nodo de entrada conoce la dirección de cada app que le pide pares. Una red privada con tus propios nodos limita eso a tus propias máquinas. No controla quién entra en una conversación: lo controlan la clave de la conversación, las invitaciones y la lista de miembros.
  • Solo IPv4. -bootstrap rechaza una dirección IPv6 en cualquier forma.
  • Sin probar en la red pública. Las pruebas de este paso usan solo 127.0.0.1 y fallan cualquier arranque que llegaría a una dirección pública, así que aquí no se ejercitaron los nodos de entrada públicos en sí.

Siguientes pasos

  • Lee las páginas de kolo-dht y kolo-swarm: la red pública, los nodos de entrada y BootstrapNodes.
  • Para ejecutar tus propios nodos de entrada y pin para un equipo, mira Ejecuta tu propia infraestructura.
  • El ejemplo terminado, kolo-chat-wails3-example, dice en su página de Settings que funciona en la red pública, y lista nodos de entrada solo cuando fijas los tuyos con -bootstrap. Su docs/try-it.md cuenta cómo ejecutarla en un equipo, en una red y a través de internet.
  • Para comparar tus archivos con los terminados, usa la etiqueta step-8 del repositorio del starter.