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 on127.0.0.1, such as the node ofcmd/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:
git fetch origin --tagsBring 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:
git checkout step-8 -- frontend go.mod go.sum networkinfo.go conversations.go '*_test.go'| File | What 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.sum | kolo-swarm and kolo-dht v0.1.0, which have the public entry nodes (kolo-dht) and BootstrapNodes (kolo-swarm). |
networkinfo.go | NetworkInfo: the mode, "public" or "own", and the entry nodes in use. The window shows it. |
conversations.go | Start 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.go | The 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:
"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:
// 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:
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 conversationIn LoadConfig, replace the lines of bootstrap and listen with:
{"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:
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 inviteIn 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:
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:
// 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:
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:
// 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:
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:
{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:
<p className="note" title={network.nodes.join(', ')}>{networkLine(network)}</p>6Run it
Build the app:
GOWORK=off wails3 buildFirst your own network on this computer, as before, but now by name. Start the bootstrap node, and keep it running:
go run ./cmd/bootstrapIn another terminal, start the local pin, and keep it running:
go run github.com/ciranda-dev/kolo-pin/cmd/kolo-pin run -data .data/pin -max-bytes 100MBAlice needs the pin's public key, in her terminal only:
export KOLO_CHAT_PIN_KEY=$(go run github.com/ciranda-dev/kolo-pin/cmd/kolo-pin id -data .data/pin)./bin/kolo-chat -data .data/alice-8 -bootstrap 127.0.0.1:4000In Alice's window click New conversation, type "Family" and click Create. Start Bob in another terminal, without the variable, on the same network:
./bin/kolo-chat -data .data/bob-8 -bootstrap 127.0.0.1:4000Invite 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:
./bin/kolo-chat -data .data/alice-8 -bootstrap 127.0.0.1:9After 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:
./bin/kolo-chat -data .data/alice-8Nothing 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:
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.
-bootstraprefuses an IPv6 address in any form. - Not tested on the public network. The tests of this step bind
127.0.0.1only 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. Itsdocs/try-it.mdtells 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-8of the starter repository.