kolo docsbeta

kolo-dht

Find peers by topic without a central server, and connect to them through NATs.

On this page

kolo-dht is a Kademlia DHT, hardened after S/Kademlia, that runs on the same UDP socket as the node's kolo-transport QUIC listener. A peer announces a 32-byte topic with a record signed by its kolo-id key. Another peer looks the topic up, the server that stored the record coordinates a hole punch as described in RFC 5128, tested against the NAT behaviors of RFC 4787, and the caller gets a kolo-secure connection pinned to the announced key. Nothing relays application data.

All steps

A lookup, step by step

This example uses 8-bit IDs. Real IDs have 256 bits, the table keeps 20 servers per bucket and up to 10 queries run at once.

  1. Your routing table gives the servers it knows closest to the topic: here A, B and C. Distance is the XOR of the two IDs.
  2. You send LOOKUP to them at once. Each reply carries servers closer to the topic, a token and any records.
  3. C knows D and E, which are closer. You ask them as soon as the reply arrives: there are no fixed rounds.
  4. E knows F and G, closer still. The list is sorted by distance after every reply.
  5. The walk stops when the 20 closest servers it knows have answered or timed out, or after 100 queries. Each record is signed by the peer that announced it, and the signature is checked.
  6. A lookup returns records, not connections. Connect is a separate call, through a server that stored the record.
All steps

Connecting through two NATs

Both peers sit behind home routers. A bootstrap node on the internet puts them in touch; the packets then flow directly.

  1. A and B each announce a signed record on the topic to a bootstrap node, each from behind its own NAT.
  2. A looks the topic up. The reply carries B's signed record, with its public key and its address, and the node that stored it.
  3. A sends CONNECT to that node, which passes the request on to B. Neither peer can reach the other yet: both NATs only let answers in.
  4. Both send PUNCH packets to each other at the same time. Each NAT sees its own peer's packet go out and opens a mapping, so the other's packets are let in.
  5. The direct path is up: packets flow between A and B without the node. kolo-secure then proves both keys on the connection.

Install

go get github.com/ciranda-dev/kolo-dht

Builds without cgo.

Config.Trace is a callback for every punch probe sent and received, the sockets of a birthday punch and each proved address. Config holds this func field, so it cannot be compared with ==: use reflect.DeepEqual.

Quick start

One server and two peers on loopback: bob announces a topic, alice finds it, connects and gets her message echoed back.

main.go
package main

import (
	"context"
	"crypto/sha256"
	"fmt"
	"io"
	"log"
	"net"
	"net/netip"
	"time"

	kolodht "github.com/ciranda-dev/kolo-dht"
	koloid "github.com/ciranda-dev/kolo-id"
)

func node(ctx context.Context, server bool) *kolodht.Node {
	id, err := koloid.Generate()
	if err != nil {
		log.Fatal(err)
	}
	n, err := kolodht.New(ctx, "127.0.0.1:0", id, &kolodht.Config{Server: server})
	if err != nil {
		log.Fatal(err)
	}
	return n
}

func addr(n *kolodht.Node) netip.AddrPort { return n.Addr().(*net.UDPAddr).AddrPort() }

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	server := node(ctx, true)
	defer server.Close()
	alice, bob := node(ctx, false), node(ctx, false)
	defer alice.Close()
	defer bob.Close()
	for _, n := range []*kolodht.Node{alice, bob} {
		if err := n.Bootstrap(ctx, []netip.AddrPort{addr(server)}); err != nil {
			log.Fatal(err)
		}
	}

	topic := kolodht.Topic(sha256.Sum256([]byte("kolo example topic")))
	if err := bob.Announce(ctx, topic); err != nil {
		log.Fatal(err)
	}
	go func() {
		c, err := bob.Accept(ctx)
		if err != nil {
			return
		}
		s, err := c.AcceptStream(ctx)
		if err != nil {
			return
		}
		io.Copy(s, s)
		s.Close()
	}()

	peers, err := alice.Lookup(ctx, topic)
	if err != nil || len(peers) == 0 {
		log.Fatalf("lookup: %d peers, %v", len(peers), err)
	}
	c, err := alice.Connect(ctx, peers[0])
	if err != nil {
		log.Fatal(err)
	}
	defer c.Close()
	s, err := c.OpenStream(ctx)
	if err != nil {
		log.Fatal(err)
	}
	if _, err := s.Write([]byte("hello kolo")); err != nil {
		log.Fatal(err)
	}
	s.Close()
	reply, err := io.ReadAll(s)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s from %x\n", reply, c.RemotePublicKey())
}

It prints hello kolo from and bob's public key in hex. With no list, Bootstrap(ctx, nil) joins the public network through the entry nodes built into the library; see Public and private networks. To keep your own network, run a few nodes with Config.Server on public addresses, such as kolo-node, and pass their addresses to Bootstrap.

API reference

The API reference is generated from the Go source and is in English.

Package kolodht · github.com/ciranda-dev/kolo-dht · v0.1.0

Package kolodht finds Kolo peers by topic on a Kademlia DHT over UDP and punches through NATs to a kolo-secure connection pinned to the announced key. IPv4 only (IPv6 is refused); experimental until v1.0.0.

Constants

const DefaultRandomPunchInterval = 20 * time.Second

DefaultRandomPunchInterval is the default Config.RandomPunchInterval.

Variables

var (
	// ErrInvalidConfig means a Config field is out of range, here or in kolo-secure or kolo-transport (wrapped too).
	ErrInvalidConfig = errors.New("kolodht: invalid config")
	// ErrInvalidArgument means a nil or zero identity, an IPv6 address, IPv4-mapped included (v0.1.x is IPv4 only), a record that cannot be
	// used, or too many announcements.
	ErrInvalidArgument = errors.New("kolodht: invalid argument")
	// ErrClosed means the node is closed.
	ErrClosed = errors.New("kolodht: closed")
	// ErrNoNodes means no server answered.
	ErrNoNodes = errors.New("kolodht: no server answered")
	// ErrNotStored means no server stored the announcement.
	ErrNotStored = errors.New("kolodht: announcement not stored")
	// ErrUnreachable means no relay led to a connection, or both sides have a random NAT mapping.
	ErrUnreachable = errors.New("kolodht: peer unreachable")
	// ErrTryLater means a punch with a random mapping on one side is over a budget here or at the peer, or this node
	// already runs its attempts toward the peer's host or key.
	ErrTryLater = errors.New("kolodht: try later")
)

Functions

func Closer

func Closer(target, a, b [32]byte) bool

Closer reports whether a is closer to target than b by XOR distance, compared as big-endian unsigned integers.

func Distance

func Distance(a, b [32]byte) [32]byte

Distance returns the Kademlia XOR distance between two 32-byte IDs, such as a topic and a node ID.

func PublicServers

func PublicServers() []netip.AddrPort

PublicServers returns a copy of the built-in public entry nodes, the servers Bootstrap uses when it is given nil, so a node that bootstraps from them tells them its IP address.

Types

type Config

type Config struct {
	// Secure is passed to kolo-secure, and Secure.Transport to kolotransport.Listen. A zero Transport.KeepAlivePeriod
	// becomes 5s, so NAT filters stay open for punched connections, unless Transport.IdleTimeout is 5s or less.
	Secure *kolosecure.Config
	// Server answers DHT queries, stores records and relays connect requests; only servers enter routing tables.
	Server bool
	// MaxRecords caps the records a server stores, all topics. Default 65536, from 16 to 1,000,000.
	// A full store takes about MaxRecords x 710 bytes of heap, 44 MiB at the default.
	MaxRecords int
	// MaxRecordsPerTopic caps the records of one topic. Default 512, from 1 to 65536. One IPv4 /24 may hold a sixteenth
	// of them (at least 1), so filling a topic takes 16 networks.
	MaxRecordsPerTopic int
	// MaxRecordsPerIP caps the records from one announcing IPv4 address, all topics. Default 256, from 1 to 65536.
	MaxRecordsPerIP int
	// MaxAnnouncements caps the topics this node announces at once. Default 16, from 1 to 256.
	MaxAnnouncements int
	// MaxInflight caps the requests waiting for a reply. Default 160, from 8 to 4096.
	MaxInflight int
	// MaxRelays caps the connect requests a server relays at once. Default 64, from 1 to 4096.
	MaxRelays int
	// MaxPunches caps the punch requests this node answers at once, and the live connections punches made on birthday
	// sockets of their own (4 per /24); a new one past that is refused. Default 16, from 1 to 256.
	MaxPunches int
	// MaxRequestsPerIP caps the requests per second from one IPv4 address. Default 50, from 1 to 10,000.
	MaxRequestsPerIP int
	// MaxRequestsPerPrefix caps the requests per second from one IPv4 /24. Default 200, from MaxRequestsPerIP to 100,000.
	MaxRequestsPerPrefix int
	// MaxRequests caps the requests per second from everyone. Default 10,000, from MaxRequestsPerPrefix to 1,000,000.
	MaxRequests int
	// RequestTimeout bounds the wait for one reply. Default 1s, from 100ms to 10s.
	RequestTimeout time.Duration
	// PunchTimeout bounds one connect attempt through one relay, a 35s random punch included. Default 45s, from 1s to 2m.
	PunchTimeout time.Duration
	// MaxRandomPunches caps the punches with a random mapping on one side that this node runs at once.
	// Default 1, from 1 to 16.
	MaxRandomPunches int
	// MaxRandomPunchesPerTarget caps the random punches toward one peer IPv4 address. Default 1, from 1 to MaxRandomPunches.
	MaxRandomPunchesPerTarget int
	// MaxRandomPunchesPerRequester caps the random punches answered for one requester IPv4 address. Default 1, from 1 to
	// MaxRandomPunches.
	MaxRandomPunchesPerRequester int
	// RandomPunchInterval is the least time from the end of one random punch to the next. Default 20s, from 1s to 10m.
	RandomPunchInterval time.Duration
	// MaxPunchSockets caps the sockets running punches hold besides the node's own; a birthday punch needs 255. Default
	// 256, or half the soft RLIMIT_NOFILE if less, from 1 to 16384.
	MaxPunchSockets int
	// RandomPunchCooldown is the least time from the end of a burst to the next toward its IP (and /24 at the announcer)
	// or by its storer, doubled per burst toward the IP that connected nothing, up to 16x. Default 1m, from 1s to 1h.
	RandomPunchCooldown time.Duration
	// MaxRandomPunchesPerMinute caps those bursts started in any minute. Default 4, from 1 to 64.
	MaxRandomPunchesPerMinute int
	// Trace, if set, gets every punch probe and step, from the punch goroutines and never with a lock held. It must
	// return fast; a slow one slows the probes. A panic in it drops that event and is not passed on. Default nil.
	Trace func(TraceEvent)
}

Config sets the limits of a Node. A zero field takes its default; out of range is ErrInvalidConfig.

type Node

type Node struct {
	// contains filtered or unexported fields
}

Node is a DHT node with one UDP socket for its DHT datagrams and its kolo-secure connections.

func New
func New(ctx context.Context, addr string, id *koloid.Identity, cfg *Config) (*Node, error)

New opens a UDP socket on addr, such as "127.0.0.1:0" or ":4000", for the DHT and for kolo-secure connections as id. v0.1.x is IPv4 only: an IPv6 addr, IPv4-mapped included, is ErrInvalidArgument.

func (Node) Accept
func (n *Node) Accept(ctx context.Context) (*kolosecure.Conn, error)

Accept waits for the next inbound connection, punched or direct, that no Connect in progress claimed. Unclaimed connections wait in a queue of Secure.MaxPending (default 64); when it is full, new ones are closed.

func (Node) Addr
func (n *Node) Addr() net.Addr

Addr returns the local address of the node's socket.

func (Node) Announce
func (n *Node) Announce(ctx context.Context, topic Topic) error

Announce stores a signed record of this node at the servers closest to topic and refreshes it until Unannounce or Close; it returns once one stored it (the README lists its errors). Announcing a topic again does nothing.

func (Node) Bootstrap
func (n *Node) Bootstrap(ctx context.Context, servers []netip.AddrPort) error

Bootstrap pings servers, keeps those that answer and looks up our own ID: ErrNoNodes if none answered, and ErrInvalidArgument before sending anything if any address is IPv6, IPv4-mapped included.

A nil servers list means PublicServers: the public entry nodes learn our IP and, once we Announce, store the topic and our address. To stay private pass your own servers; an empty list that is not nil is ErrInvalidArgument.

func (Node) Close
func (n *Node) Close() error

Close stops announcing, closes the socket and every connection of the node, and waits for its goroutines. It is safe to call more than once.

func (Node) Connect
func (n *Node) Connect(ctx context.Context, r Record) (*kolosecure.Conn, error)

Connect punches through up to 3 relays of r, PunchTimeout each, and returns a connection pinned to r.PublicKey. A relay that fails does not stop the next; only our own limits and the context do (the README lists the errors).

func (Node) Lookup
func (n *Node) Lookup(ctx context.Context, topic Topic) ([]Record, error)

Lookup returns the records of topic stored at the servers closest to it, verified and merged by key, freshest first. Our own record is left out. It returns ErrNoNodes if no server answered.

func (Node) Stats
func (n *Node) Stats() Stats

Stats returns the node's current state and counters; it is safe during traffic and after Close.

func (Node) Unannounce
func (n *Node) Unannounce(topic Topic)

Unannounce stops refreshing the record of topic; the servers drop it within 20 minutes.

type Record

type Record struct {
	// Topic is the topic the peer announced.
	Topic Topic
	// PublicKey is the peer's kolo-id public key.
	PublicKey ed25519.PublicKey
	// Addr is the peer's address as the freshest server stored it.
	Addr netip.AddrPort
	// contains filtered or unexported fields
}

Record is a peer found on a topic: its kolo-id key and address, signed by that key and verified by Lookup. It also holds the servers that stored it, which Connect uses as relays.

func (Record) Addrs
func (r Record) Addrs() []netip.AddrPort

Addrs returns every address Connect may probe or dial for r: Addr and each relay's stored peer address, once each, IPv4 only. Random-port probes go to the IPs of these addresses.

type Stats

type Stats struct {
	// Servers is the number of servers in the routing table.
	Servers int
	// Records is the number of records this server stores.
	Records int
	// Requests counts the requests that passed the rate limits since New.
	Requests uint64
	// Limited counts the requests the rate limits dropped since New.
	Limited uint64
}

Stats is a snapshot of a node's state and counters; the counters only grow, so callers take differences.

type Topic

type Topic [32]byte

Topic is a 32-byte value peers announce and look up, such as a hash of an application's topic name.

type TraceEvent

type TraceEvent struct {
	// Kind is the step; the fields below are set as its constant says.
	Kind TraceKind
	// Local and Remote are the local socket address and the peer address.
	Local, Remote netip.AddrPort
	// Size is the probe size in bytes and TTL its IP TTL (0 is the system default).
	Size, TTL int
	// Count is the number of sockets or probes.
	Count int
}

TraceEvent is one step of a punch, passed to Config.Trace. Which fields are set depends on Kind.

func (TraceEvent) String
func (e TraceEvent) String() string

String formats e as one log line.

type TraceKind

type TraceKind int

TraceKind says what a TraceEvent reports.

const (
	// TraceProbeSent: a probe of Size bytes left Local for Remote, at TTL (0 is the system default).
	TraceProbeSent TraceKind = iota + 1
	// TraceProbeReceived: a probe of Size bytes for a punch of ours reached Local from Remote.
	TraceProbeReceived
	// TraceBirthdayOpened: Count sockets, the node's own included, now probe Remote (birthday punch).
	TraceBirthdayOpened
	// TraceRandomProbes: up to Count probes to random ports of Remote's IP start (Remote's port is 0).
	TraceRandomProbes
	// TraceProved: Remote echoed our nonce to Local, so the punch may dial it.
	TraceProved
)
func (TraceKind) String
func (k TraceKind) String() string

String returns the name of k.

Good to know

Public and private networks

PublicServers() returns a copy of the public entry nodes built into the library, as []netip.AddrPort. Ciranda runs them for everyone, free, with no uptime guarantee while Kolo is a beta. Node.Bootstrap(ctx, nil) uses them, so a node with no setup joins the public network and finds peers on other networks.

To keep a network apart from it, pass your own servers: a first entry node runs with kolo-node run -first, and every other node bootstraps from it. An empty list that is not nil is ErrInvalidArgument and sends no packet, so an application that must stay private can never join the public network by mistake. Who sees what when the list is nil: the two entry nodes see your IP address and port as soon as you bootstrap. After Announce, the topic and your address are stored on the public network's servers, readable by anyone who looks the topic up; a topic is not a secret, since whoever knows its 32 bytes can find the record. The entry nodes have no key, so a client cannot check who answers at an address, and their addresses are compiled into each release, so a client of an old release keeps asking those addresses. Records are still verified and every connection is pinned to the announced key, so an entry node cannot impersonate a peer, but it can hand a client a bad server list or not answer. A nil slice counts as nil: a []netip.AddrPort variable that you never appended to also joins the public network.

Limits

  • IPv4 only. New, Bootstrap and Connect refuse an IPv6 address with ErrInvalidArgument, the IPv4-mapped form ::ffff:a.b.c.d included. A datagram from an IPv6 source is dropped.
  • A zero Config field takes its default. A value out of range is ErrInvalidConfig.
  • MaxRecords: 65536 records per server, all topics (16 to 1,000,000). A record takes up to about 710 heap bytes, so a full store takes about 44 MiB at the default; count it in GOMEMLIMIT. A full server refuses new records and never evicts live ones.
  • MaxRecordsPerTopic: 512 (1 to 65536). One IPv4 /24 holds at most a sixteenth of them, 32 at the default.
  • MaxRecordsPerIP: 256 per announcing IPv4 address, all topics (1 to 65536).
  • MaxAnnouncements: 16 topics this node announces (1 to 256). Past it, Announce returns ErrInvalidArgument.
  • MaxInflight: 160 requests waiting for a reply (8 to 4096). Other requests wait for a slot.
  • MaxRelays: 64 connect requests a server relays at once (1 to 4096).
  • MaxPunches: 16 punch requests answered at once (1 to 256). It also caps the connections held on birthday sockets of their own, 4 per /24. Past that, a new random punch is answered try later, and an established one is never closed.
  • MaxRequestsPerIP: 50 requests a second per IPv4 address (1 to 10,000). MaxRequestsPerPrefix: 200 a second per IPv4 /24 (MaxRequestsPerIP to 100,000). MaxRequests: 10,000 a second in total (MaxRequestsPerPrefix to 1,000,000). Requests past them are dropped before they are decoded, in 1-second windows, and counted in Stats().Limited.
  • ANNOUNCEs that need a key agreement or a signature check (a new record, address, signature or share; a plain refresh does not) have their own budget: 20 a second per IPv4 address, 100 per /24 and 1000 in all (or the request limits above if lower). Past it the ANNOUNCE gets no reply and counts in Stats().Limited; the announcer tries again at its next refresh. A sender with a valid round-trip token could otherwise make the server spend about 50 microseconds per datagram with random bytes.
  • RequestTimeout: 1s wait for one reply (100ms to 10s). A routing table entry is dropped after 4 failed requests in a row.
  • PunchTimeout: 45s per relay, a 35s random punch and its handshake included (1s to 2m). Two consistent mappings give up on a relay after their probe window: 10 probes 1s apart, plus 2 x RequestTimeout.
  • MaxRandomPunches: 1 punch with a random mapping on one side at once, both roles (1 to 16). MaxRandomPunchesPerTarget and MaxRandomPunchesPerRequester: 1 per peer or requester IPv4 address (1 to MaxRandomPunches).
  • RandomPunchInterval: 20s from the end of one random punch to the next (DefaultRandomPunchInterval, 1s to 10m).
  • RandomPunchCooldown: 1m between two bursts toward one IPv4 address, or started by one storer (1s to 1h). For an IP or /24 it doubles after each burst that connected nothing from the probed /24, up to 16 times as long.
  • MaxRandomPunchesPerMinute: 4 bursts started in any minute, both roles (1 to 64).
  • MaxPunchSockets: 256 sockets held by punches besides the node's own, or half the soft RLIMIT_NOFILE if less (1 to 16384). A birthday punch needs 255; below that it is always answered try later.
  • Secure: passed to kolo-secure. A zero KeepAlivePeriod becomes 5s unless IdleTimeout is 5s or less, to keep NAT mappings of punched connections open.
  • Accept queue: Secure.MaxPending, 64 by default. When it is full, new connections are closed with code 1.
  • A datagram is at most 1200 bytes. A reply carries at most 20 nodes and 16 records.
  • Routing table: 256 buckets of 20, at most 2 entries per IPv4 /24 in a bucket and 10 in the table. A full bucket keeps its oldest entry unless it has been silent for 15 minutes and then fails a ping. Maintenance sends 5 pings every 40s.
  • Each record is stored at each of the up to 20 closest servers that answered the announcer's lookup; Announce succeeds when at least one stored it. The announcer refreshes it every 15s and looks the topic up again every 5 minutes. A server drops a record 20 minutes after its last refresh, so after Unannounce it is gone within 20 minutes.
  • A lookup asks 10 servers at once and at most 100 in all. One Lookup checks at most 160 signatures.
  • Connect asks up to 3 relays, one after another. A node runs at most 2 punch attempts at once toward one destination host. A server relays at most 2 requests at once per requester host and 4 per target.
  • Bootstrap uses at most 64 addresses. A node checks at most 10 new servers at once, with at most 1 check ping a second per address, 4 per /24 and 40 in all.
  • Round-trip tokens: the secret changes every 40s, so a token is accepted for 40 to 80s.
  • Probes: with two consistent mappings, 10 probes 1s apart. With one random mapping, 1750 probes 20ms apart (35s) to random ports 1000 to 65535, while the random side opens 256 sockets (its own included) and sends at TTL 5 until the peer reaches one. A peer answers at most 4 probes per punch, and a punch session sends to at most 8 addresses.
  • NAT class: the last 16 samples, one per server /24. At least 3 samples are needed; below that the class is unknown and behaves as consistent. A sample expires after 30 minutes.
  • Node IDs: one IPv4 address has at most 8 IDs, and a server changes its ID choice at most once a minute.

Security

  • Records are signed with Ed25519ctx under the context kolo-dht/announce/v1, over the topic, the key and the announcer's address as the storing server saw it, so a record cannot be moved to another address. kolo-id rejects small-order keys.
  • Replies carry an HMAC-SHA256 round-trip token bound to the requester's IPv4 address and port. A server stores or relays nothing for an address that has not received a packet from it.
  • Each PUNCH carries a counter and an HMAC-SHA256 under a secret the announcer and the server agreed at ANNOUNCE (X25519, HKDF-SHA256). The announcer drops a PUNCH with a wrong MAC or a replayed counter and sends nothing back. Its OK answer is signed under kolo-dht/punch-reply/v1, so a lying relay is skipped at once.
  • Only an address that echoed a probe nonce is dialed. A lying server, or a record that names a stranger, makes a node send at most 1 probe at the announcer and 10 at the connector, and never a QUIC packet.
  • Random-port probes go only to a peer IP that servers in two /16s stored the record at.
  • An address learned from another node is used only if it is global or in the same scope (loopback, link-local, private) as that node.
  • Not closed, by design: two colluding servers in two /16s, both among the closest for a topic, can make each connector send one window of random-port probes (1750 probes, 61 KB) to an IP they choose. That is at most about 1.1 KB/s per connector, about 60 B/s toward one IP, or about 1 KB/s with a host in that IP's /24.
  • Not closed, by design: attackers that complete real punches from 3 /24s can keep an announcer's one random punch busy, and attackers that hold connections from 4 /24s can block new birthday punches to it. Peers already connected stay connected.
  • Experimental. The API may change before v1.0.0.

Known limits

  • Two peers that both have a random NAT mapping cannot connect: Connect returns ErrUnreachable.
  • Two peers behind one NAT connect only if it hairpins.
  • The birthday punch (one random mapping) is checked only in an in-process NAT simulator, not on real NATs. Its analytic success rate is about 0.999. Real NATs that allocate ports another way, cap mappings per host or rate limit new ones may do worse.
  • On a network whose servers all share one /16, a Connect from a consistent mapping to a random one returns ErrUnreachable at once.
  • Not guaranteed: finding every peer of a topic (servers can be offline, full or lying), resistance to an attacker with many /24 prefixes, privacy of topics and addresses, and reaching an announcer behind a NAT that drops mappings in under 15s.

Errors

ErrorMessage
ErrClosedkolodht: closed
ErrInvalidArgumentkolodht: invalid argument
ErrInvalidConfigkolodht: invalid config
ErrNoNodeskolodht: no server answered
ErrNotStoredkolodht: announcement not stored
ErrTryLaterkolodht: try later
ErrUnreachablekolodht: peer unreachable

Every blocking call (Bootstrap, Announce, Lookup and Connect) returns ctx.Err() as soon as its context is done, and ErrClosed after Close, Bootstrap included. A deadline that has already passed counts as done even if the runtime has not yet marked the context (a request timeout can fire first on a coarse timer, such as Windows or a busy VM), so the call returns context.DeadlineExceeded, not ErrNoNodes or ErrUnreachable, and a server is not marked failed for a request the deadline cut short.

Test with errors.Is. ErrInvalidConfig wraps a kolo-secure or kolo-transport config error, so that library's own sentinel matches too; other errors from opening the socket pass through unchanged.

References