kolo docsbeta

Passo 8: Usar a rede pública

Inicie o chat na rede pública por padrão, para que pessoas em redes diferentes se encontrem sem configurar nada, mantenha a sua própria rede com -bootstrap e diga o que fazer quando nenhum nó de entrada responde.

Nesta página

Nos passos anteriores o chat encontrava seus pares por um nó de bootstrap no seu próprio computador, 127.0.0.1:4000. Isso serve para duas janelas em um computador, e para mais ninguém. Agora o app entra por padrão na rede pública: a Ciranda mantém alguns nós de entrada que vêm embutidos no Kolo, gratuitos e sem garantia de disponibilidade enquanto o Kolo estiver em beta. Você não passa nada, e duas pessoas em redes diferentes se encontram.

O app tem duas formas de escolher uma rede, e nunca as mistura:

  • A rede pública, a padrão. Você não configura nada. O app não passa nenhum nó de entrada, e o kolo-swarm usa a lista embutida no kolo-dht.
  • A sua própria rede, com -bootstrap host:porta[,host:porta]. Os nós de entrada que você nomeia são usados sozinhos: os públicos não são contatados. É assim que você mantém uma rede privada, e é assim que você trabalha só neste computador: um nó de entrada em 127.0.0.1, como o de cmd/bootstrap.

Se nenhum nó de entrada responde quando o app inicia, o app avisa e nomeia estas formas. Ele nunca recorre a outra rede: um app que pediu a sua não entra em silêncio na pública.

Você escreve a lição: as configurações que escolhem a rede, em config.go, o erro de uma rede que não responde, em network.go, e as duas linhas de chatservice.go que as usam. Todo o resto é encanamento, e você o traz da tag step-8.

1Confira o que você precisa e traga os arquivos prontos

Você precisa do mesmo que no passo 7: Go 1.26 ou mais novo, Node.js, wails3, o nó de bootstrap e um pin local. Parta do projeto que você terminou no passo 7. Este passo não adiciona nenhuma biblioteca, e sobe duas para versões mais novas. Busque as tags:

Terminal
git fetch origin --tags

Traga a janela, os arquivos do módulo, a descrição da rede e os testes deste passo. Eles substituem os seus arquivos do passo 7 com o mesmo nome:

Terminal
git checkout step-8 -- frontend go.mod go.sum networkinfo.go conversations.go '*_test.go'
ArquivoO que faz
frontend/A linha sob as conversas que diz em qual rede o app entrou, e as frases de uma rede que não responde, em inglês, espanhol e português.
go.mod, go.sumO kolo-swarm e o kolo-dht v0.1.0, que têm os nós de entrada públicos (kolo-dht) e BootstrapNodes (kolo-swarm).
networkinfo.goNetworkInfo: o modo, "public" ou "own", e os nós de entrada em uso. A janela o mostra.
conversations.goStart devolve a rede, e uma conversa que não iniciou porque nenhum nó de entrada respondeu diz isso na sua linha, sem pasta para tirar do caminho.
*_test.goOs testes deste passo, e um TestMain que mantém todos os testes fora da rede pública.

A tag também tem os config.go, network.go e chatservice.go prontos, caso você queira comparar os seus com eles. Até você escrever network.go, o projeto não compila.

2Deixe vazios os nós de entrada por padrão

No passo 7 Bootstrap era um único IP:PORTA com um valor padrão. Agora é uma lista de entradas host:porta, e vazia significa a rede pública. A mesma flag, -bootstrap, e a mesma variável, KOLO_CHAT_BOOTSTRAP, nomeiam a sua.

O endereço de escuta muda junto. Um socket em 127.0.0.1 não alcança um nó de entrada público, então o padrão é 0.0.0.0:0, exceto quando todos os nós de entrada que você nomeia estão em loopback: então o app fica em 127.0.0.1:0, como antes.

Em config.go, adicione o import do kolo-swarm:

config.go
	"strconv"
	"time"

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

Em config.go, substitua os dois valores padrão do nó de bootstrap e do endereço de escuta 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
)

Em config.go, substitua as linhas de Bootstrap e Listen em 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

Em LoadConfig, substitua as linhas de bootstrap e 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)},

Em settings, os nós de entrada agora são strings. nil é a rede 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

Em resolve, apague as duas linhas que davam um valor padrão a Bootstrap e Listen. Depois substitua a leitura do endereço de bootstrap pela leitura da lista e pela escolha do endereço de escuta:

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 aceita no máximo 16 entradas, cada uma um endereço IPv4 ou um nome de host que resolve para IPv4, com uma porta de 1 a 65535. Espaços e entradas repetidas são descartados, e um endereço IPv6 em qualquer forma é recusado. -bootstrap , não lista nenhum nó de entrada: é um erro, nunca a rede pública.

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

3Diga quando ninguém responde

O Bootstrap do kolo-swarm devolve o ErrNoNodes do kolo-dht quando nenhum nó de entrada responde. Isso é uma frase para a pessoa diante da janela, não uma linha de log: qual rede foi tentada, e as formas de escolher outra. Crie network.go com o erro:

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) é verdadeiro para todos, e errors.Is(err, kolodht.ErrNoNodes) continua dizendo a causa.

Depois a chamada. bootstrapSwarm é o único lugar que alcança a rede, e é uma variável para que os testes a substituam: o TestMain que você trouxe a troca por um guarda que falha qualquer início sem -bootstrap, então nenhum teste envia um pacote a um endereço público. bootstrap transforma "nenhum nó de entrada respondeu" no erro acima, e deixa passar qualquer outro erro como está:

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) é toda a escolha. Com BootstrapNodes vazio, o kolo-swarm usa os nós de entrada públicos embutidos no kolo-dht. Com a sua lista em BootstrapNodes, usa só essa lista. Uma lista vazia que não é nil é um erro que não envia nada, e assim uma rede privada fica fora da pública.

4Entre na rede

Em chatservice.go, apague o import "net/netip": nada ali lê um endereço agora. Depois dê a sua lista ao swarm e chame 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
	}

5O que a janela faz com isso

O NetworkError viaja como o erro de uma conversa, e conversations.go copia o modo dele para a linha. A janela olha o modo e escreve a frase no idioma do navegador: inglês, espanhol ou português. Qualquer outro erro aparece como chegou:

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

Sob a lista de conversas uma linha diz em qual rede o app entrou, e os nós de entrada estão no tooltip dela:

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

6Rode

Compile o app:

Terminal
GOWORK=off wails3 build

Primeiro a sua própria rede neste computador, como antes, mas agora por nome. Inicie o nó de bootstrap e deixe-o rodando:

Terminal
go run ./cmd/bootstrap

Em outro terminal, inicie o pin local e deixe-o rodando:

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

A Alice precisa da chave pública do pin, só no terminal dela:

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

Na janela da Alice clique em New conversation, digite "Family" e clique em Create. Inicie o Bob em outro terminal, sem a variável, na mesma rede:

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

Convide o Bob e aprove-o, como no passo 7. A linha sob a lista de conversas começa com "Sua própria rede", e o tooltip dela tem 127.0.0.1:4000.

Agora veja o erro. Feche a janela da Alice e inicie-a de novo com um nó de entrada que não existe:

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

Depois de alguns segundos a Family aparece marcada com um "!" e diz que o Kolo Chat não conseguiu alcançar a sua rede, com as três formas de se conectar. A janela não entra na rede pública no lugar. Inicie a Alice de novo com -bootstrap 127.0.0.1:4000 e a Family inicia.

Agora a rede pública. Feche o nó de bootstrap: você não precisa dele, e todo app que você inicia sem -bootstrap entra na rede pública, que precisa da sua conexão com a internet e de UDP liberado para fora:

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

Nada mais muda para duas janelas em um computador: elas se encontram pelos nós de entrada públicos, e o pin local continua funcionando. Para duas pessoas em redes diferentes, o convite leva o endereço do pin, e não existe pin público, então o pin precisa de um endereço IPv4 público que as duas alcancem. Rode-o em um host como uma VPS, como em Rode um peer de fixação em uma VPS, e inicie a Alice com -pin <endereço>:7450 e a chave do host em KOLO_CHAT_PIN_KEY. Para isso ninguém precisa de um nó de bootstrap.

7Rode os testes

Os testes que você trouxe cobrem o padrão, que é a lista pública nas configurações e 0.0.0.0:0 como endereço de escuta; -bootstrap sozinho, que é usado sozinho e mantém os nós de entrada de loopback em 127.0.0.1:0; cada -bootstrap ruim, de um endereço IPv6 a 17 entradas; a lista que chega ao swarm; o erro que nomeia as três formas, para as duas redes; um erro que não é de rede, que passa como está; a linha de uma conversa que não iniciou; e um reinício com o nó de entrada fora do ar, e depois no ar. Nenhum envia um pacote a um endereço público:

Terminal
GOWORK=off go test ./...

8O que a rede pública não é

Conheça os limites:

  • Sem garantia de disponibilidade. Os nós de entrada públicos são mantidos pela Ciranda e são gratuitos, e enquanto o Kolo estiver em beta podem estar fora do ar. O app avisa e oferece a sua própria rede.
  • Sem pin público nem relay público. A rede pública ajuda os pares a se encontrarem. Ela não guarda mensagens para membros offline nem retransmite conexões: o pin é seu, e o endereço dele vai no convite. Atrás de uma rede que bloqueia o caminho direto, um relay de conexão também é seu.
  • Os nós de entrada veem quem pergunta. Um nó de entrada fica sabendo o endereço de cada app que lhe pede pares. Uma rede privada com os seus próprios nós limita isso às suas próprias máquinas. Ela não controla quem entra em uma conversa: quem controla são a chave da conversa, os convites e a lista de membros.
  • Só IPv4. -bootstrap recusa um endereço IPv6 em qualquer forma.
  • Sem teste na rede pública. Os testes deste passo usam só 127.0.0.1 e falham qualquer início que alcançaria um endereço público, então os nós de entrada públicos em si não foram exercitados aqui.

Próximos passos

  • Leia as páginas do kolo-dht e do kolo-swarm: a rede pública, os nós de entrada e BootstrapNodes.
  • Para rodar os seus próprios nós de entrada e pin para uma equipe, veja Rode a sua própria infraestrutura.
  • O exemplo pronto, kolo-chat-wails3-example, diz na página de Settings que roda na rede pública, e lista nós de entrada só quando você define os seus com -bootstrap. O docs/try-it.md dele conta como rodá-lo em um computador, em uma rede e pela internet.
  • Para comparar seus arquivos com os prontos, use a tag step-8 do repositório do starter.