You will run three programs on one machine, all on 127.0.0.1:
- a kolo-node bootstrap server, the address new peers join through;
- two copies of a small chat program built on kolo-swarm.
The two chat peers join the same topic, find each other through the node, connect directly and send each other the lines you type. The node only helps them meet; your messages never go through it.
You need Go 1.26 or newer.
This walk-through keeps everything on your computer, with an entry node of your own on loopback. A library with no list of entry nodes joins the public network instead, through the two public entry nodes that Ciranda runs, built into kolo-dht.
Run a bootstrap node
Install kolo-node:
go install github.com/ciranda-dev/kolo-node/cmd/kolo-node@latestIn a first terminal, start it on loopback, with its key in a new temporary directory:
dir=$(mktemp -d)
kolo-node run -listen 127.0.0.1:7447 -identity "$dir/node.key" -first-first starts a new network: this node has no other entry nodes to join. Leave it running. From another terminal, kolo-node check 127.0.0.1:7447
prints ok 127.0.0.1:7447.
Write the chat program
Make a new module and add the two libraries it uses:
mkdir chat && cd chat
go mod init chat
go get github.com/ciranda-dev/kolo-id github.com/ciranda-dev/kolo-swarmSave this as main.go:
// Command chat joins a topic and sends each line you type to every peer on it.
package main
import (
"bufio"
"context"
"crypto/sha256"
"flag"
"fmt"
"io"
"log"
"net/netip"
"os"
"strings"
"sync"
"unicode"
koloid "github.com/ciranda-dev/kolo-id"
koloswarm "github.com/ciranda-dev/kolo-swarm"
)
func main() {
flag.Parse()
if flag.NArg() == 0 {
log.Fatal("usage: chat IP:PORT...")
}
var servers []netip.AddrPort
for _, a := range flag.Args() {
ap, err := netip.ParseAddrPort(a)
if err != nil {
log.Fatal(err)
}
servers = append(servers, ap)
}
ctx := context.Background()
id, err := koloid.Generate()
if err != nil {
log.Fatal(err)
}
s, err := koloswarm.New(ctx, "127.0.0.1:0", id, nil)
if err != nil {
log.Fatal(err)
}
defer s.Close()
if err := s.Bootstrap(ctx, servers); err != nil {
log.Fatal(err)
}
topic := koloswarm.Topic(sha256.Sum256([]byte("kolo chat example")))
if err := s.Join(ctx, topic, nil); err != nil {
log.Fatal(err)
}
fmt.Printf("you are %x; type a line and press Enter\n", id.PublicKey()[:4])
var mu sync.Mutex
peers := map[*koloswarm.Peer]bool{}
go func() {
for {
ev, err := s.Next(ctx)
if err != nil {
return
}
switch ev.Kind {
case koloswarm.Connected:
mu.Lock()
peers[ev.Peer] = true
mu.Unlock()
fmt.Printf("* %x joined\n", ev.Peer.PublicKey()[:4])
go receive(ctx, ev.Peer)
case koloswarm.Lost:
mu.Lock()
delete(peers, ev.Peer)
mu.Unlock()
fmt.Printf("* %x left\n", ev.Peer.PublicKey()[:4])
}
}
}()
lines := bufio.NewScanner(os.Stdin)
for lines.Scan() {
mu.Lock()
for p := range peers {
go send(ctx, p, lines.Text())
}
mu.Unlock()
}
}
// send opens a one-way stream per message; closing it marks the end.
func send(ctx context.Context, p *koloswarm.Peer, msg string) {
st, err := p.Conn().OpenUniStream(ctx)
if err != nil {
return
}
st.Write([]byte(msg))
st.Close()
}
func receive(ctx context.Context, p *koloswarm.Peer) {
for {
st, err := p.Conn().AcceptUniStream(ctx)
if err != nil {
return
}
msg, _ := io.ReadAll(io.LimitReader(st, 4096))
// The text comes from another machine: drop control characters
// before printing it to a terminal.
clean := strings.Map(func(r rune) rune {
if unicode.IsControl(r) {
return -1
}
return r
}, string(msg))
fmt.Printf("%x: %s\n", p.PublicKey()[:4], clean)
}
}Run two peers
In a second terminal:
go run . 127.0.0.1:7447In a third terminal, run the same command again. After a moment each peer
prints * <key> joined with the first bytes of the other's public key.
Type a line in one terminal and press Enter: it shows up in the other one,
next to the sender's key. Stop a peer with Ctrl-C and the other prints
* <key> left.
What just happened
- Each peer made a new kolo-id key. Its public key is its name on the network. See Peers.
- Both joined the topic
sha256("kolo chat example"). Joining withniloptions announces the peer on the topic and looks the topic up. See Topics. - The second peer found the first through the node's kolo-dht server and dialed it. The connection is a kolo-secure channel tied to each peer's key, so each side knows whose key it is talking to.
- Each message travels on its own one-way stream, straight from one peer to the other.
Next steps
- To keep a history that peers can check, write messages to a kolo-log log and copy it with kolo-sync. See Logs and Replicas.
- To run peers on different machines, call
Bootstrap(ctx, nil)with no list: the peers join the public network through the public entry nodes, free, with no uptime guarantee while Kolo is a beta. For a network of your own, run a few kolo-node servers on hosts with a public IPv4 address and pass their addresses to every peer. The kolo-node page has the details. - Two peers that cannot reach each other directly can use a relay, if you choose to run one.