kolo docsbeta

Step 8: Use the public network

Start the chat on the public network by default, so people on different networks find each other with no setup, keep your own network with -bootstrap, and say what to do when no entry node answers.

On this page

In the previous steps the chat found its peers through a bootstrap node on your own computer, 127.0.0.1:4000. That works for two windows on one computer, and for nobody else. Now the app joins the public network by default: Ciranda runs a few entry nodes that are built into Kolo, free, with no uptime guarantee while Kolo is a beta. You pass nothing, and two people on different networks find each other.

The app has two ways to choose a network, and it never mixes them:

  • The public network, the default. You set nothing. The app passes no entry node, and kolo-swarm uses the list built into kolo-dht.
  • Your own network, with -bootstrap host:port[,host:port]. The entry nodes you name are used alone: the public ones are not contacted. This is how you keep a private network, and how you run on this computer only: one entry node on 127.0.0.1, such as the node of cmd/bootstrap.

If no entry node answers when the app starts, the app says so and names these ways. It never falls back to another network: an app that asked for yours does not quietly join the public one.

You write the lesson: the settings that choose the network, in config.go, the error for a network that does not answer, in network.go, and the two lines of chatservice.go that use them. Everything else is plumbing, and you bring it in from the tag step-8.

1Check what you need and bring in the given files

You need what step 7 needed: Go 1.26 or newer, Node.js, wails3, the bootstrap node and a local pin. Start from the project you finished in step 7. This step adds no library, and moves two to newer versions. Fetch the tags:

Terminal
git fetch origin --tags

Bring in the window, the module files, the description of the network and the tests of this step. They replace your files of step 7 with the same names:

Terminal
git checkout step-8 -- frontend go.mod go.sum networkinfo.go conversations.go '*_test.go'
FileWhat it does
frontend/The line under the conversations that says which network the app joins, and the sentences of a network that does not answer, in English, Spanish and Portuguese.
go.mod, go.sumkolo-swarm and kolo-dht v0.1.0, which have the public entry nodes (kolo-dht) and BootstrapNodes (kolo-swarm).
networkinfo.goNetworkInfo: the mode, "public" or "own", and the entry nodes in use. The window shows it.
conversations.goStart returns the network, and a conversation that did not start because no entry node answered says so in its row, with no folder to move aside.
*_test.goThe tests of this step, and a TestMain that keeps every test off the public network.

The tag also holds the finished config.go, network.go and chatservice.go, in case you want to compare yours with them. Until you write network.go, the project does not build.

2Leave the entry nodes empty by default

In step 7 Bootstrap was one IP:PORT with a default. Now it is a list of host:port entries, and empty means the public network. The same flag, -bootstrap, and the same variable, KOLO_CHAT_BOOTSTRAP, name your own.

The listen address changes with it. A socket on 127.0.0.1 cannot reach a public entry node, so the default is 0.0.0.0:0, except when every entry node you name is on loopback: then the app stays on 127.0.0.1:0, as before.

In config.go, add the kolo-swarm import:

config.go
	"strconv"
	"time"

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

In config.go, replace the two defaults of the bootstrap node and the listen address with:

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
)

In config.go, replace the lines of Bootstrap and Listen in Config with:

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

In LoadConfig, replace the lines of bootstrap and listen with:

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

In settings, the entry nodes are strings now. nil is the public network:

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

In resolve, delete the two lines that gave Bootstrap and Listen a default. Then replace the parsing of the bootstrap address with the parsing of the list and the choice of the listen address:

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 accepts at most 16 entries, each an IPv4 address or a host name that resolves to IPv4, with a port from 1 to 65535. Spaces and repeated entries are dropped, and an IPv6 address in any form is refused. -bootstrap , lists no entry node: it is an error, never the public network.

Add loopbackOnly before 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
}

3Say when nobody answers

kolo-swarm's Bootstrap returns kolo-dht's ErrNoNodes when no entry node answers. That is a sentence for the person at the window, not a log line: which network was tried, and the ways to choose another. Create network.go with the 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) is true for every one, and errors.Is(err, kolodht.ErrNoNodes) still tells the cause.

Then the call. bootstrapSwarm is the only place that reaches the network, and it is a variable so that the tests replace it: the TestMain you brought in swaps it for a guard that fails any start with no -bootstrap, so no test sends a packet to a public address. bootstrap turns "no entry node answered" into the error above, and passes every other error as it is:

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) is the whole choice. With BootstrapNodes empty, kolo-swarm uses the public entry nodes built into kolo-dht. With your list in BootstrapNodes, it uses that list alone. A list that is empty and not nil is an error that sends nothing, which is how a private network stays off the public one.

4Join the network

In chatservice.go, delete the "net/netip" import: nothing there parses an address now. Then give the swarm your list and call 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
	}

5What the window does with it

The NetworkError travels as the error of a conversation, and conversations.go copies its mode into the row. The window checks the mode and writes the sentence in the language of the browser: English, Spanish or Portuguese. Any other error shows as it came:

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

Under the list of conversations a line says which network the app joined, and the entry nodes are in its tooltip:

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

6Run it

Build the app:

Terminal
GOWORK=off wails3 build

First your own network on this computer, as before, but now by name. Start the bootstrap node, and keep it running:

Terminal
go run ./cmd/bootstrap

In another terminal, start the local pin, and keep it running:

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

Alice needs the pin's public key, in her terminal only:

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

In Alice's window click New conversation, type "Family" and click Create. Start Bob in another terminal, without the variable, on the same network:

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

Invite Bob and approve him, as in step 7. The line under the list of conversations starts with "Your own network", and its tooltip has 127.0.0.1:4000.

Now see the error. Close Alice's window and start her again with an entry node that is not there:

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

After a few seconds Family is marked with a "!" and says that Kolo Chat could not reach your network, with the three ways to connect. The window does not join the public network in its place. Start Alice again with -bootstrap 127.0.0.1:4000 and Family starts.

Now the public network. Close the bootstrap node: you do not need it, and every app you start without -bootstrap joins the public network, which needs your internet connection and UDP allowed out:

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

Nothing else changes for two windows on one computer: they find each other through the public entry nodes, and the local pin keeps working. For two people on different networks, the invite carries the pin's address, and there is no public pin, so the pin must have a public IPv4 address that both reach. Run it on a host such as a VPS, as in Run a pinning peer on a VPS, and start Alice with -pin <address>:7450 and the host's key in KOLO_CHAT_PIN_KEY. Nobody needs a bootstrap node for that.

7Run the tests

The tests you brought in cover the default, which is the public list in the settings and 0.0.0.0:0 as the listen address; -bootstrap alone, which is used alone and keeps loopback entry nodes on 127.0.0.1:0; every bad -bootstrap, from an IPv6 address to 17 entries; the list that reaches the swarm; the error that names the three ways, for both networks; an error that is not a network error, which passes through; the row of a conversation that did not start; and a restart with the entry node down, then up. None of them sends a packet to a public address:

Terminal
GOWORK=off go test ./...

8What the public network is not

Know the limits:

  • No uptime guarantee. The public entry nodes are run by Ciranda and are free, and while Kolo is a beta they can be down. The app says so, and offers your own network.
  • No public pin, no public relay. The public network helps peers find each other. It does not keep messages for offline members or relay connections: the pin is yours, and its address goes in the invite. Behind a network that blocks a direct path, a connection relay is yours too.
  • Entry nodes see who asks. An entry node learns the address of every app that asks it for peers. A private network with your own nodes keeps that to your own machines. It does not control who joins a conversation: the conversation key, the invites and the member list do.
  • IPv4 only. -bootstrap refuses an IPv6 address in any form.
  • Not tested on the public network. The tests of this step bind 127.0.0.1 only and fail any start that would reach a public address, so the public entry nodes themselves were not exercised here.

Next steps

  • Read the kolo-dht and kolo-swarm pages: the public network, the entry nodes and BootstrapNodes.
  • To run your own entry nodes and pin for a team, see Run your own infrastructure.
  • The finished example, kolo-chat-wails3-example, says in its Settings page that it runs on the public network, and lists entry nodes only when you set your own with -bootstrap. Its docs/try-it.md tells how to run it on one computer, on a network and across the internet.
  • To compare your files with the finished ones, check out the tag step-8 of the starter repository.