kolo-swarm se une a topics y mantiene como mucho una conexión de kolo-secure por clave remota con los peers que encuentra en ellos. Un Swarm ejecuta su propio nodo de kolo-dht: anuncia y busca los topics a los que se ha unido, se conecta a los peers que encuentra con backoff y jitter, y acepta a los peers que marcan hacia él. Con relays en Config.Relays, a un peer al que no llega directamente lo llama a través de un kolo-relay que los dos peers tienen en su lista. Una conexión que la aplicación abrió de otra forma entra mediante Attach. Prefiere los caminos directos y usa un relay en último lugar, como hace ICE (RFC 8445), y limita las conexiones por dirección contra los ataques de eclipse que describen Heilman et al..
Unirse a un topic
Tú das un topic; kolo-swarm encuentra sus peers y te entrega conexiones, una por peer.
- Join anuncia tu registro firmado en el topic en hasta 20 servidores del DHT cercanos a él, y busca el topic.
- Cada registro encontrado es un evento Found. Por defecto kolo-swarm conecta con hasta 3 peers a la vez y mantiene como máximo 64 peers, conectados o en marcación.
- Connect pide a un servidor que guardó el registro del peer que pase la petición. Luego los dos lados envían paquetes para abrir un camino directo (hole punching).
- kolo-secure prueba las claves de los dos peers en la conexión nueva.
- En un stream nuevo, el peer con la clave mayor envía hello con los topics en los que encontró al otro. La clave menor decide y responde con un número de generación.
- Se mantiene una conexión por peer; una duplicada se cierra. La app recibe Connected, y Lost cuando termina. Las reconexiones esperan de 1 segundo a 10 minutos.
Instalación
go get github.com/ciranda-dev/kolo-swarmCompila sin cgo.
Inicio rápido
Un servidor de kolo-dht y dos swarms en loopback se unen a un mismo topic, se conectan y se devuelven un mensaje.
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"
koloswarm "github.com/ciranda-dev/kolo-swarm"
)
func swarm(ctx context.Context, server netip.AddrPort) *koloswarm.Swarm {
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)
}
if err := s.Bootstrap(ctx, []netip.AddrPort{server}); err != nil {
log.Fatal(err)
}
return s
}
func connected(ctx context.Context, s *koloswarm.Swarm) *koloswarm.Peer {
for {
ev, err := s.Next(ctx)
if err != nil {
log.Fatal(err)
}
if ev.Kind == koloswarm.Connected {
return ev.Peer
}
}
}
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
sid, err := koloid.Generate()
if err != nil {
log.Fatal(err)
}
server, err := kolodht.New(ctx, "127.0.0.1:0", sid, &kolodht.Config{Server: true})
if err != nil {
log.Fatal(err)
}
defer server.Close()
saddr := server.Addr().(*net.UDPAddr).AddrPort()
alice, bob := swarm(ctx, saddr), swarm(ctx, saddr)
defer alice.Close()
defer bob.Close()
topic := koloswarm.Topic(sha256.Sum256([]byte("kolo example topic")))
if err := bob.Join(ctx, topic, &koloswarm.JoinOptions{Announce: true}); err != nil {
log.Fatal(err)
}
if err := alice.Join(ctx, topic, &koloswarm.JoinOptions{Lookup: true}); err != nil {
log.Fatal(err)
}
pa, pb := connected(ctx, alice), connected(ctx, bob)
fmt.Printf("alice connected to %x (direct %v)\n", pa.PublicKey()[:8], pa.Direct())
go func() {
st, err := pb.Conn().AcceptStream(ctx)
if err != nil {
return
}
io.Copy(st, st)
st.Close()
}()
st, err := pa.Conn().OpenStream(ctx)
if err != nil {
log.Fatal(err)
}
if _, err := st.Write([]byte("hello kolo")); err != nil {
log.Fatal(err)
}
st.Close()
reply, err := io.ReadAll(st)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%s from %x\n", reply, pa.PublicKey()[:8])
}Imprime los primeros 8 bytes de la clave de bob con direct true (la conexión vino de kolo-dht) y después hello kolo de vuelta. Sin lista, Bootstrap(ctx, nil) entra en la red pública a través de los nodos de entrada incluidos en kolo-dht. Para una red privada, haz bootstrap desde unos cuantos servidores de kolo-dht propios, como kolo-node; consulta Redes públicas y privadas.
Referencia de la API
La referencia de la API se genera a partir del código Go y está en inglés.
Package koloswarm joins Kolo topics and keeps connections to the peers found on them.
A Swarm owns a kolo-dht node. It announces and looks up the topics it joined, dials the peers it finds with backoff, accepts the peers that dial it, and keeps at most one kolo-secure connection per remote key, within fixed limits on peers, inbound peers, dials and handshakes. It uses relays only when Config.Relays lists some: then a peer it cannot reach directly is dialed through a kolo-relay that both peers list. Connect dials a known key at a known address, and a connection the application opened another way enters through Attach.
Bootstrap with no servers and no Config.BootstrapNodes joins the public network: Ciranda's entry nodes learn the node's IP address and public key, and an announced topic hash and IP address become visible there. Pass an explicit list to stay private.
v0.1.x is IPv4 only, and IPv6 input, IPv4-mapped included, is refused with ErrInvalidArgument.
Experimental: the API may change before v1.0.0.
Variables
var (
// ErrInvalidConfig means a Config field is out of range, here or in kolo-dht (whose error is wrapped).
ErrInvalidConfig = errors.New("koloswarm: invalid config")
// ErrInvalidArgument means a nil identity or Conn, an IPv6 address (v0.1.x is IPv4 only), invalid JoinOptions, a
// topic already joined, MaxTopics reached, or a Connect key, topic or address that cannot be used.
ErrInvalidArgument = errors.New("koloswarm: invalid argument")
// ErrClosed means the swarm is closed.
ErrClosed = errors.New("koloswarm: closed")
// ErrRefused means a connection was refused by Allow, a limit, the lack of a shared topic, or the peer; for
// Connect also the key's, host's or address's backoff, the dial rate, or Leave of the topic.
ErrRefused = errors.New("koloswarm: connection refused")
// ErrWait wraps ErrRefused: Connect was refused for now by a backoff (of the key, the address, the key at the
// address, or the host), the dial rate, a dial to the host in progress, or MaxConnecting dials running.
ErrWait = fmt.Errorf("%w: wait", ErrRefused)
// ErrDuplicate means the pair of keys already has a connection that this one does not replace, or, for Connect, a
// lookup dial, a proved dial or a hello of the key, or a Connect dial of it at the same address.
ErrDuplicate = errors.New("koloswarm: duplicate connection")
// ErrProtocol means the peer sent a malformed hello, or none in time.
ErrProtocol = errors.New("koloswarm: protocol error")
// ErrLost means a connection ended for another reason: the peer closed it, or it timed out or failed; or a Connect
// dial failed.
ErrLost = errors.New("koloswarm: connection lost")
)Funciones
func LoadNodes
func LoadNodes(path string) ([]string, error)LoadNodes reads a file of bootstrap nodes: one host:port per line, as in ParseNodes, where "#" starts a comment and blank lines are ignored. It reads only a regular file of at most 64 KiB; a bad line is ErrInvalidArgument.
func ParseNodes
func ParseNodes(s string) ([]string, error)ParseNodes parses a comma-separated list of at most 16 bootstrap nodes, each host:port with an IPv4 address or a host name and a port from 1 to 65535. Spaces around entries and empty entries are ignored and duplicates dropped; IPv6 in any form, port 0, more entries or anything else invalid is ErrInvalidArgument.
Tipos
type Config
type Config struct {
// DHT is passed to kolodht.New. A zero MaxAnnouncements becomes MaxTopics, a lower one is refused, and zero
// kolo-transport MaxDialed, MaxConns and MaxMemory are raised to cover MaxPeers, and MaxMemory also the growth
// WindowGrowth allows. With Allow set, WindowGrowth lets the connections Allow admitted grow their windows.
DHT *kolodht.Config
// MaxPeers caps connected peers plus dials in progress, inbound and outbound. Default 64, from 1 to 1024.
MaxPeers int
// MaxInbound caps the peers that connected to us. Default MaxPeers/2 rounded up, from 1 to MaxPeers.
MaxInbound int
// MaxConnectPeers caps the places Swarm.Connect holds. Default MaxPeers/4, from 1 to MaxPeers - MaxInbound; when
// MaxInbound equals MaxPeers it must be unset, and Connect is always refused.
MaxConnectPeers int
// MaxTopics caps the topics joined at once. Default 16, from 1 to 32.
MaxTopics int
// MaxConnecting caps kolo-dht Connect calls in progress, and separately relay dials and Swarm.Connect dials, and
// is also the Swarm.Connect dial starts per RetryMin. Default 3, from 1 to 16.
MaxConnecting int
// MaxHandshakes caps hellos in progress. From 4 up, a quarter is kept for Attach and another for known keys (an
// outbound slot, or an outbound connection that lasted 15s). Default 16, from 1 to 256.
MaxHandshakes int
// MaxHandshakesPerIP caps hellos in progress from one source host, or through one relay. Default 4 (or
// MaxHandshakes if lower), from 1 to MaxHandshakes.
MaxHandshakesPerIP int
// MaxCandidates caps the keys kept from lookups, split equally between joined topics; the backoff of up to twice
// as many dropped keys, and keys Swarm.Connect dialed, is kept. Default 1024, from 16 to 32768.
MaxCandidates int
// MaxEvents caps the queued Found events, and separately the queued Unreachable events; more are dropped.
// Default 64, from 16 to 4096.
MaxEvents int
// HelloTimeout bounds the hello on a new connection. Default 10s, from 1s to 60s.
HelloTimeout time.Duration
// LookupInterval is the time between lookups of a topic, plus up to a fifth of it at random. Default 10m, from
// 1s to 1h.
LookupInterval time.Duration
// RetryMin is the shortest wait before dialing a key again, and the period in which Swarm.Connect starts at most
// MaxConnecting dials, so raising it slows Connect. Default 1s, from 100ms to 1m.
RetryMin time.Duration
// RetryMax is the longest wait before dialing a key again. Default 10m, from RetryMin to 1h.
RetryMax time.Duration
// Allow, if set, is asked before every dial and every new connection; false or a panic refuses. addr is the
// address to dial or the connection's remote address, zero when the Conn has none.
Allow func(key ed25519.PublicKey, addr netip.AddrPort) bool
// BootstrapNodes are the entry nodes Bootstrap uses when it is given none: at most 16 host:port entries, each an
// IPv4 address or a host name resolved to IPv4, as from ParseNodes or LoadNodes. The default is empty, and Bootstrap
// then falls back to kolo-dht's public entry nodes, which then receive this node's IP address and public key; set
// it to stay off the public network.
BootstrapNodes []string
// Relays, if not empty, connect peers that cannot connect directly: at most 16, in order of preference. While a
// topic is joined with Announce the swarm keeps a reservation at each and admits the peers that come through
// them, and a key whose kolo-dht Connect failed is dialed through them in turn, the one that carried it last
// first, with the swarm's own DHT.Secure settings. Two peers meet through any relay both list. Empty never uses
// a relay.
Relays []Relay
}Config sets the limits of a Swarm. A zero field takes its default; out of range is ErrInvalidConfig.
type Conn
type Conn interface {
RemotePublicKey() ed25519.PublicKey
OpenStream(ctx context.Context) (*kolotransport.Stream, error)
AcceptStream(ctx context.Context) (*kolotransport.Stream, error)
OpenUniStream(ctx context.Context) (*kolotransport.SendStream, error)
AcceptUniStream(ctx context.Context) (*kolotransport.ReceiveStream, error)
Context() context.Context
Close() error
CloseWithError(code uint64, msg string) error
}Conn is an authenticated connection to one peer; *kolosecure.Conn and *kolorelay.Conn both satisfy it. RemotePublicKey must be a key the connection has proved, as those two do; the swarm trusts it without a check.
type Event
type Event struct {
Kind EventKind
Topic Topic // set for Found and Unreachable
PublicKey ed25519.PublicKey // the remote key, or the relay's key for RelayChanged
Addr netip.AddrPort // the remote address; zero for RelayChanged
Peer *Peer // set for Connected and Lost
Err error // set for Unreachable and Lost, and for RelayChanged when the reservation is not held
}Event is one thing that happened in the swarm; which fields are set depends on Kind.
type EventKind
type EventKind intEventKind says what an Event reports.
const (
// Found means a lookup of Topic returned PublicKey at Addr, for the first time since it was last absent.
Found EventKind = iota + 1
// Connected means Peer is connected; its Conn is ready for streams.
Connected
// Unreachable means kolo-dht could not connect to PublicKey, found on Topic; Err is kolodht.ErrUnreachable. With
// Config.Relays set, it comes only after the relays failed too.
Unreachable
// Lost means the connection of a Peer returned by an earlier Connected ended. Err says why, with nothing the peer
// chose: ErrDuplicate (replaced, or closed as a duplicate), ErrClosed (closed here), ErrRefused or ErrProtocol (the
// peer refused it), or ErrLost (anything else).
Lost
// RelayChanged means the reservation at the relay whose key is PublicKey is held (Err nil) or not held; Err is
// then kolorelay.ErrNotAllowed, kolorelay.ErrLimit, kolorelay.ErrReservationEnded, kolosecure.ErrUnexpectedPeer,
// ErrInvalidConfig (that relay's key cannot be used; the swarm stops using it), ErrClosed (no announced topic is
// joined) or ErrLost (anything else). Topic, Addr and Peer are zero. Only the newest one per relay waits in the
// queue.
RelayChanged
)The event kinds.
func (EventKind) String
func (k EventKind) String() stringString returns the kind's name.
type JoinOptions
type JoinOptions struct {
// Announce publishes our record on the topic.
Announce bool
// Lookup finds the other peers of the topic and dials them.
Lookup bool
// MaxPeers caps the peers dialed or admitted for this topic. Default and maximum: Config.MaxPeers.
MaxPeers int
}JoinOptions says how to join a topic. Announce publishes our record; Lookup finds and dials others.
type Peer
type Peer struct {
// contains filtered or unexported fields
}Peer is a connected peer: one connection to one remote key.
func (Peer) Addr
func (p *Peer) Addr() netip.AddrPortAddr returns the peer's UDP address, or the zero AddrPort if its Conn has no RemoteAddr method.
func (Peer) Conn
func (p *Peer) Conn() ConnConn returns the connection; the peer is lost when its Context ends.
func (Peer) Direct
func (p *Peer) Direct() boolDirect reports whether the connection is direct, from kolo-dht or Connect, rather than through one of Config.Relays or from Attach.
func (Peer) Outbound
func (p *Peer) Outbound() boolOutbound reports whether the peer holds one of our outbound places (not capped by MaxInbound), whichever side opened the kept connection.
func (Peer) PublicKey
func (p *Peer) PublicKey() ed25519.PublicKeyPublicKey returns a copy of the peer's kolo-id public key.
func (Peer) Topics
func (p *Peer) Topics() []TopicTopics returns the topics this peer currently shares with us, as far as the peer claimed them: a topic hash is not secret, so any peer can claim it. Config.Allow, which sees the key, is where to admit only known members.
type Relay
type Relay struct {
// Addr is the relay's host:port, an IPv4 address or a host name resolved to IPv4, in the form of a
// BootstrapNodes entry. A name must point to one relay process.
Addr string
// PublicKey is the relay's kolo-id public key.
PublicKey ed25519.PublicKey
}Relay is a kolo-relay that peers of the network may list, used when a direct connection fails.
func LoadRelays
func LoadRelays(path string) ([]Relay, error)LoadRelays reads a file of relays, one host:port@key per line as in ParseRelays, where "#" starts a comment and blank lines are ignored. It reads only a regular file of at most 64 KiB; a bad line is ErrInvalidArgument.
func ParseRelays
func ParseRelays(s string) ([]Relay, error)ParseRelays parses a comma-separated list of at most 16 relays, each host:port@key with the key as 64 hex characters. Spaces and empty entries are ignored and duplicates dropped; one key with two addresses, one address with two keys, IPv6 in any form, port 0 or anything else invalid is ErrInvalidArgument.
type Swarm
type Swarm struct {
// contains filtered or unexported fields
}Swarm keeps connections to the peers of the topics it joined, on its own kolo-dht node.
func New
func New(ctx context.Context, addr string, id *koloid.Identity, cfg *Config) (*Swarm, error)New opens a kolo-dht node on addr, such as "127.0.0.1:0" or ":4000", as id, and starts the swarm on it. v0.1.x is IPv4 only: an IPv6 addr, IPv4-mapped included, is ErrInvalidArgument.
func (Swarm) Addr
func (s *Swarm) Addr() net.AddrAddr returns the local address of the node's UDP socket.
func (Swarm) Attach
func (s *Swarm) Attach(ctx context.Context, c Conn, outbound bool) errorAttach runs the hello on a connection the application opened (outbound if we did) and returns nil once the peer is admitted. The connection must authenticate RemotePublicKey itself, as kolo-secure and kolo-relay do: the hello carries no proof, so a key the peer merely claims lets it impersonate any key. The swarm owns c from the call on; both ends must call it at once (see the README). With Config.Relays, it counts as relayed: a direct connection to the key replaces it.
func (Swarm) Bootstrap
func (s *Swarm) Bootstrap(ctx context.Context, servers []netip.AddrPort) errorBootstrap passes servers to kolo-dht Bootstrap; its ErrNoNodes passes through, and its ErrInvalidArgument is wrapped in ours. An IPv6 server address, IPv4-mapped included, is ErrInvalidArgument. With no servers it resolves Config.BootstrapNodes instead (ErrNoNodes if none resolves), each name within 5s and ctx.
With neither, a nil servers list joins the public network: Ciranda's entry nodes built into kolo-dht learn this node's IP address and public key, and Join with Announce publishes the topic hash and IP address there. A nil slice from a flag or an empty parse counts as nil. To stay private, pass your own non-empty list or set Config.BootstrapNodes; an empty list that is not nil is ErrInvalidArgument and sends nothing.
func (Swarm) Close
func (s *Swarm) Close() errorClose closes every peer connection and the node, and waits for the swarm's goroutines. It is safe to call more than once.
func (Swarm) Connect
func (s *Swarm) Connect(ctx context.Context, topic Topic, pub ed25519.PublicKey, addr netip.AddrPort, from netip.Addr) errorConnect dials pub at addr, which the peer at from supplied (zero: unknown, so global addresses only), and runs the hello for topic; it returns nil once this dial's connection is admitted. Errors: ErrInvalidArgument for unusable arguments, ErrRefused for Allow, a limit or the peer (ErrWait when a backoff, the dial rate or dials in progress refuse it for now), ErrDuplicate when the key already has a place or a hello, or a Connect dial at addr, and ErrLost when the dial fails (wrapping kolosecure.ErrUnexpectedPeer when another key answered). See the guide for the rest.
func (Swarm) Join
func (s *Swarm) Join(ctx context.Context, topic Topic, opts *JoinOptions) errorJoin announces topic, looks it up, or both (nil opts), and connects to the peers found. With Announce it returns once kolo-dht stored our record, and its errors pass through; the topic is then not joined. Lookups run every LookupInterval in the background. If Leave(topic) runs during Join, Join returns context.Canceled. With Announce and Config.Relays, it first waits for the first reservation attempt at each relay, in parallel, except relays known down.
func (Swarm) Leave
func (s *Swarm) Leave(topic Topic)Leave stops announcing and looking up topic, and closes the peers that share no other topic with us; with Config.Relays, those closes may finish after it returns.
func (Swarm) Next
func (s *Swarm) Next(ctx context.Context) (Event, error)Next returns the next event. Connected and Lost are never dropped; Found and Unreachable are dropped past MaxEvents. A peer can be replaced by a newer connection to the same key: its Lost, with ErrDuplicate, comes before the new Connected.
func (Swarm) PublicKey
func (s *Swarm) PublicKey() ed25519.PublicKeyPublicKey returns a copy of the swarm's kolo-id public key.
type Topic
type Topic = kolodht.TopicTopic is a 32-byte topic, the same type as kolo-dht's.
Conviene saber
Redes públicas y privadas
Una red es el conjunto de servidores de kolo-dht que se conocen entre sí, y un nodo pertenece a la red de los nodos de entrada desde los que hace bootstrap. Sin ninguna lista, Bootstrap(ctx, nil) entra en la red pública a través de los nodos de entrada incluidos en kolo-dht (kolodht.PublicServers), que Ciranda ejecuta para todos, gratis y sin garantía de disponibilidad mientras Kolo sea una beta. Config.BootstrapNodes está vacía por defecto; cuando se rellena, o cuando pasas servidores, se usan esos en su lugar. Una lista vacía que no es nil es ErrInvalidArgument y no envía nada, de modo que una aplicación que debe seguir siendo privada nunca entra por error en la red pública.
Quién se entera de qué en la red pública: sin lista, los dos nodos de entrada reciben la dirección IP y la clave pública del nodo con su primer paquete, y todo nodo de la red pública al que consulta, o que lo consulta, también las ve. Con Join y Announce, el hash del topic y la dirección IP del nodo se guardan en la red pública, y cualquiera que busque ese topic puede leerlos; Lookup solo enseña el hash del topic a los nodos a los que pregunta. Nada oculta la dirección. Para seguir siendo privado, no te apoyes nunca en el valor por defecto: pasa tu propia lista a Config.BootstrapNodes o a Bootstrap. Una lista nil significa la red pública también cuando viene de una opción, de un archivo de configuración o de un resultado vacío de ParseNodes, así que comprueba que no esté vacía antes de la llamada; una lista vacía que no es nil es ErrInvalidArgument y sirve de guarda, por ejemplo servers := []netip.AddrPort{} antes de añadir tus propias entradas.
- La red pública no necesita configuración. Otra red pública, cuyos operadores publican sus nodos de entrada, se alcanza poniendo esa lista en
Config.BootstrapNodes(desdeParseNodesoLoadNodes), o pasándosela aBootstrap. - Una red privada ejecuta sus propios nodos de entrada. Su primer nodo de entrada arranca sin lista (kolo-node
run -first, o un servidor de kolo-dht que nunca llama aBootstrap), los demás nodos de entrada hacen bootstrap desde él, y cada miembro lista solo esos nodos de entrada. Ejecuta al menos dos en hosts que se mantengan encendidos, con su puerto UDP abierto.
ParseNodes analiza una lista separada por comas y LoadNodes lee un archivo, una entrada por línea, con comentarios # y líneas en blanco ignoradas; se aceptan un BOM UTF-8 y CRLF, y solo se lee un archivo regular de como mucho 64 KiB. Una entrada es host:port con una dirección IPv4 o un nombre de host y un puerto de 1 a 65535. IPv6 en cualquier forma, el puerto 0, más de 16 entradas o una línea incorrecta es ErrInvalidArgument.
Los nombres de host de la lista se resuelven a IPv4 en cada Bootstrap, con el resolvedor del sistema, en paralelo, cada nombre en 5s y dentro del plazo de ctx: como mucho 8 direcciones por nombre y 64 en total, las direcciones literales primero. La dirección de un nombre solo se conserva si es global o está en el ámbito de la dirección propia del swarm (loopback, link-local o privada), de modo que una respuesta DNS no puede apuntar el swarm a una red local que no se le dio; con una dirección no especificada como 0.0.0.0 solo cuentan las respuestas globales. Las direcciones literales se conservan tal como se configuraron. Los nombres que no se resuelven se omiten; si no se resuelve ninguno, Bootstrap devuelve ErrNoNodes.
Qué es: separación por topología. Un servidor de kolo-dht solo conoce otros servidores por los servidores a los que consulta y por los que le envían peticiones, y una búsqueda solo consulta servidores conocidos de esa forma, así que dos redes con nodos de entrada distintos nunca ven los servidores, los registros ni los peers de la otra (un test lo comprueba con dos redes en un mismo host).
Qué no es: control de acceso. La lista no es un secreto. Cualquiera que conozca una dirección de entrada puede hacer bootstrap desde ella, buscar topics y anunciarse en ellos, y un nodo de entrada que además conoce los servidores de otra red une las dos. Decide quién puede conectarse con Config.Allow y las claves de kolo-secure, admite miembros con kolo-invite y confía solo en registros firmados.
Este programa arranca una red privada en loopback: un primer nodo de entrada, un segundo que se une a él, y dos swarms que hacen bootstrap solo desde ellos y se conectan.
// Command private starts a private network on loopback: two entry nodes of its own and two swarms that bootstrap
// only from them.
package main
import (
"context"
"crypto/sha256"
"fmt"
"log"
"net"
"net/netip"
"time"
kolodht "github.com/ciranda-dev/kolo-dht"
koloid "github.com/ciranda-dev/kolo-id"
koloswarm "github.com/ciranda-dev/kolo-swarm"
)
func identity() *koloid.Identity {
id, err := koloid.Generate()
if err != nil {
log.Fatal(err)
}
return id
}
// entryNode starts a kolo-dht server; with no servers it is the first node of a new network.
func entryNode(ctx context.Context, servers []netip.AddrPort) *kolodht.Node {
n, err := kolodht.New(ctx, "127.0.0.1:0", identity(), &kolodht.Config{Server: true})
if err != nil {
log.Fatal(err)
}
if len(servers) > 0 {
if err := n.Bootstrap(ctx, servers); err != nil {
log.Fatal(err)
}
}
return n
}
func addr(n *kolodht.Node) netip.AddrPort { return n.Addr().(*net.UDPAddr).AddrPort() }
func connected(ctx context.Context, s *koloswarm.Swarm) *koloswarm.Peer {
for {
ev, err := s.Next(ctx)
if err != nil {
log.Fatal(err)
}
if ev.Kind == koloswarm.Connected {
return ev.Peer
}
}
}
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
first := entryNode(ctx, nil)
defer first.Close()
second := entryNode(ctx, []netip.AddrPort{addr(first)})
defer second.Close()
// The list an application would read from its own config, a flag or an environment variable.
nodes, err := koloswarm.ParseNodes(addr(first).String() + "," + addr(second).String())
if err != nil {
log.Fatal(err)
}
topic := koloswarm.Topic(sha256.Sum256([]byte("kolo private example")))
var swarms []*koloswarm.Swarm
for range 2 {
s, err := koloswarm.New(ctx, "127.0.0.1:0", identity(), &koloswarm.Config{BootstrapNodes: nodes})
if err != nil {
log.Fatal(err)
}
defer s.Close()
if err := s.Bootstrap(ctx, nil); err != nil {
log.Fatal(err)
}
if err := s.Join(ctx, topic, nil); err != nil {
log.Fatal(err)
}
swarms = append(swarms, s)
}
p := connected(ctx, swarms[0])
connected(ctx, swarms[1])
fmt.Printf("private network: %d entry nodes, connected to %x\n", len(nodes), p.PublicKey()[:8])
}Imprime private network: 2 entry nodes, connected to y 16 caracteres hexadecimales. La misma red con kolo-node, en loopback, con las claves en un directorio temporal nuevo:
dir=$(mktemp -d)
kolo-node run -listen 127.0.0.1:7447 -identity "$dir/a/node.key" -first
kolo-node run -listen 127.0.0.1:7448 -identity "$dir/b/node.key" -bootstrap 127.0.0.1:7447Los miembros listan entonces ambos nodos de entrada, por ejemplo en un archivo leído con LoadNodes:
# entry nodes of our network
127.0.0.1:7447
127.0.0.1:7448 # second entry nodeRelay como alternativa
Dos peers cuya conexión directa falla, por ejemplo dos ordenadores detrás de cortafuegos que solo dejan salir tráfico, pueden encontrarse a través de un kolo-relay. Cada lado mantiene su propia conexión de kolo-secure a través de él, así que el relay copia bytes cifrados, y el destino demuestra su clave igual que en una conexión directa. kolo-sync acepta una conexión así igual que una directa.
Los relays son un ajuste de la red, como los nodos de entrada: Config.Relays es una lista ordenada de como mucho 16 valores Relay (Addr, PublicKey), vacía por defecto, y con la lista vacía el swarm no ejecuta nada de código de relay. ParseRelays y LoadRelays leen la lista como host:port@key, con la clave en 64 caracteres hexadecimales, con las reglas de ParseNodes y LoadNodes:
# relays of our network
203.0.113.20:7448@<64 hex characters>
relay.example.org:7448@<64 hex characters> # resolved to IPv4 at each useNew rechaza con ErrInvalidConfig una dirección IPv6 en cualquier forma, el puerto 0, un nombre incorrecto, una clave que no tiene 32 bytes o que es la nuestra, 17 entradas, y una clave en dos direcciones o una dirección con dos claves. Un duplicado exacto se descarta.
- Un peer que anuncia un topic mantiene una reserva en cada relay de la lista, hecha antes de que
Joinanuncie. Un swarm que solo se une a topics conLookupno tiene ninguna. Tras el últimoLeaveanunciado, el swarm cierra sus reservas y los peers entrantes que llegaron a través de ellas. - Dos peers se encuentran a través de cualquier relay que los dos tengan en su lista, identificado por su clave; las listas no tienen que compartir orden. Listas sin ningún relay en común no dan ninguna conexión a través de relay.
- En el primer contacto, los relays solo se prueban cuando el
Connectdirecto ha fallado, no cuando respondió «inténtalo más tarde»: primero el relay que llevó esa clave la última vez, luego el orden de la lista, saltando los relays que se sabe que están caídos. A una clave que antes necesitó un relay se la llama directamente y a través de sus relays a la vez, y una conexión directa que funciona sustituye a la que pasa por el relay (LostconErrDuplicate, y luegoConnectedconDirect()true). - El primer contacto puede tardar hasta 3 ×
PunchTimeoutde kolo-dht (135s con su valor por defecto) cuando las perforaciones empiezan pero nunca conectan, y después una llamada a través de relay de como mucho 60s por cada relay que se prueba. - Un
Peera través de relay tieneDirect()false y unAddr()cero. SuConn()es un*kolorelay.ConncuyoRelayPublicKey()identifica el relay. Las conexiones a través de relay usan los propios ajustesDHT.Securedel swarm, y aAllowse le pregunta por un peer que llega a través de relay con una dirección cero antes del handshake de extremo a extremo. RelayChangedinforma de la reserva de cada relay de la lista:Errnil cuando se mantiene, okolorelay.ErrNotAllowed,kolorelay.ErrLimit,kolorelay.ErrReservationEnded,kolosecure.ErrUnexpectedPeer(respondió otra clave),ErrInvalidConfig(la clave no se puede usar; ese relay deja de usarse),ErrClosedoErrLost.
Lo que llega a saber quien opera un relay está en la página de kolo-relay.
Límites
- Solo IPv4. Una dirección IPv6, incluida la IPv4-mapped, pasada a
New,BootstrapoAttachesErrInvalidArgument. Un registro de búsqueda o una conexión de kolo-dht con una de ellas se descarta antes de queAllowla vea. - Un campo de
Configa cero toma su valor por defecto. Un valor fuera de rango esErrInvalidConfig. MaxPeers: 64 peers conectados más las llamadas en curso, entrantes y salientes (de 1 a 1024).MaxInbound:MaxPeers/2 redondeado hacia arriba, 32 con el valor por defecto (de 1 aMaxPeers). Cada topic tiene el mismo reparto: los peers entrantes ocupan como mucho ceil(MaxPeersdel topic xMaxInbound/MaxPeers) de sus plazas, 32 de 64 con los valores por defecto. Una conexión sin ningún topic compartido que tenga sitio se cierra con el código 3.JoinOptions.MaxPeers: por defecto y como máximo,Config.MaxPeers. Fuera de rango esErrInvalidArgument.MaxTopics: 16 topics unidos a la vez (de 1 a 32). Por encima,JoindevuelveErrInvalidArgument. Un hello lleva como mucho 32 topics.MaxConnecting: 3 llamadas aConnectde kolo-dht a la vez (de 1 a 16), y aparte otras tantas llamadas a través de relay.Config.Relays: como mucho 16 relays, vacía por defecto.MaxHandshakes: 16 hellos en curso (de 1 a 256). A partir de 4, una cuarta parte se reserva paraAttachy otra cuarta parte para claves conocidas.MaxHandshakesPerIP: 4 hellos desde una misma dirección IPv4 o a través de un mismo relay, oMaxHandshakessi es menor (de 1 aMaxHandshakes). Como mucho se ejecutan 2 hellos a la vez por clave.MaxCandidates: 1024 claves de búsquedas entre todos los topics, repartidas a partes iguales entre los topics unidos (de 16 a 32768). Se conserva el estado de backoff de hasta el doble de claves descartadas.MaxEvents: 64 eventosFounden cola y, aparte, 64Unreachable(de 16 a 4096); los más nuevos se descartan. Como mucho esperan 2 xMaxPeers+ 2 xMaxEventseventos.HelloTimeout: 10s para un hello completo (de 1s a 60s). Cada paso del hello tiene 2s, oHelloTimeoutsi es más corto. Un hello que se pasa de su ventana cierra la conexión con el código 5.LookupInterval: 10m entre búsquedas de un topic, más hasta una quinta parte al azar (de 1s a 1h). Las búsquedas se saltan mientras el topic esté en su límite.RetryMin: 1s (de 100ms a 1m).RetryMax: 10m (deRetryMina 1h). La espera antes de volver a conectarse a una clave tras n fallos esRetryMin+ uniform[0, min(RetryMax,RetryMin·2^n) -RetryMin).- Una conexión que dura 15s pone a cero el contador de fallos de su clave; una que termina antes cuenta como fallo.
- El
ErrTryLaterde kolo-dht no es un fallo, pero cada uno alarga la espera de la clave, desde elRandomPunchIntervalde kolo-dht (20s por defecto) hastaRetryMax, o ese intervalo si es más largo. - Un host admite como mucho dos llamadas a la vez.
- Un HELLO ocupa como máximo 1026 bytes y un REPLY como máximo 1044.
DHT: unMaxAnnouncementsa cero pasa a serMaxTopics, y uno menor esErrInvalidConfig. Los límites de kolo-transport a cero se suben:MaxDialedaMaxPeers+MaxHandshakes+MaxPendingde kolo-secure, como mínimo 32 (144 con los valores por defecto);MaxConnsaMaxInbound+MaxHandshakes+MaxPending, como mínimo 100 (112 con los valores por defecto);MaxMemorya (MaxConns+MaxDialed) xMaxConnReceiveWindow, como mínimo 1 GiB. Dimensiónalos según la memoria que pueda usar el proceso y ponGOMEMLIMITun poco por debajo.BootstrapNodes: vacía por defecto, como mucho 16 entradas. Cada nombre es una consulta DNS en cadaBootstrap, y 16 nodos de entrada son más de lo que una red necesita para seguir siendo alcanzable; el tope es el mismo que el de kolo-node, así que una misma lista sirve en ambos.- Fijos: como mucho 8 direcciones por nombre de bootstrap y 64 en total, 5s por nombre resuelto en paralelo dentro de
ctx, y un archivo deLoadNodesde como mucho 64 KiB. - En loopback todos los peers son un mismo host para los límites por dirección de kolo-dht y kolo-transport. Los tests con muchos peers locales tienen que subirlos.
Transferencias más rápidas para peers admitidos
Un stream de kolo-transport mueve como mucho una ventana por tiempo de ida y vuelta, y las ventanas empiezan pequeñas en toda conexión porque un peer hostil puede hacer que una aplicación retenga memoria para datos sin leer. kolo-transport puede hacerlas crecer en una conexión que la aplicación marca como de confianza, y nunca llega a saber quién es un peer. El swarm marca una conexión cuando Allow ha admitido a su peer, así que el crecimiento es solo para los peers que tú elegiste:
cfg := &koloswarm.Config{
DHT: &kolodht.Config{Secure: &kolosecure.Config{Transport: &kolotransport.Config{
WindowGrowth: true,
MaxStreamReceiveWindow: 256 << 10,
MaxConnReceiveWindow: 256 << 10, // equal, so a connection nobody marked keeps exactly the old windows
}}},
Allow: func(key ed25519.PublicKey, addr netip.AddrPort) bool { return paired[string(key)] },
}- El crecimiento se concede a toda conexión que
Allowadmitió, por el camino aceptado, el marcado yAttach, cuando el swarm ya la ha convertido en unPeer. Para una aplicación cuyoAllowes una lista de emparejados, eso es solo el peer emparejado. - Una conexión que
Allowrechazó, o que el swarm no admitió por otro motivo (sin topic compartido, lleno), nunca se marca. SinAllowno hay decisión de confianza, así que el swarm no marca nada y ninguna conexión crece, aunqueWindowGrowthesté activado. Una conexión por relay tampoco se marca nunca. WindowGrowthestá desactivado por defecto y entonces ninguna ventana crece. Cuando el swarm derivaMaxMemory(un valor cero) le suma el crecimiento que permiteMaxGrownMemory(64 MiB por defecto), así que la comprobación de memoria de kolo-transport sigue pasando con cualquierMaxPeers.
Seguridad
AttachyConnconfían en la clave que informa una conexión: la conexión debe autenticarRemotePublicKeypor sí misma, como hacen kolo-secure y kolo-relay, porque el hello no lleva ninguna prueba.Peer.Topicses lo que el peer dijo. UsaConfig.Allowpara admitir solo claves que conozcas.MaxInboundreserva parte de las plazas, en total y por topic, para peers elegidos a partir de búsquedas, frente a ataques de eclipse.- La mitad de la cuota de candidatos de cada topic se reserva para claves conocidas. El resto es una muestra aleatoria uniforme de los demás registros de la búsqueda; nunca cuentan el orden de los registros, la antigüedad declarada ni la dirección que dicen tener.
- Una conexión de
Attachnunca sustituye a una de kolo-dht (ErrDuplicate). Una de kolo-dht sí sustituye a una adjuntada. - El
Errde un eventoLostes un centinela sin más, sin nada que haya elegido el peer. Peer.Conn().Close()termina una conexión actual, por ejemplo después de vetar una clave.- Experimental. La API puede cambiar antes de v1.0.0.
Límites conocidos
- Dos peers solo se encuentran a través de un relay cuando sus
Config.Relayscomparten uno. Quien llama no puede saber dónde reservó el otro lado, así que prueba sus relays de uno en uno. - No se garantiza: encontrar o alcanzar todos los peers (los límites de kolo-dht), que lo que se diga de los topics sea cierto, la resistencia frente a muchas claves desde una o muchas direcciones (una avalancha puede llenar la parte muestreada de cada cuota), ni el reparto justo entre topics más allá de los límites por topic.
- En una apertura simultánea, cada lado puede ver
Connected,Lost,Connectedpara una misma clave. - Un peer cuyas conexiones perforadas están llenas responde «inténtalo más tarde» mientras duren, así que su clave puede quedarse esperando sin ningún evento
Unreachable.
Errores
| Error | Mensaje |
|---|---|
ErrClosed | koloswarm: closed |
ErrDuplicate | koloswarm: duplicate connection |
ErrInvalidArgument | koloswarm: invalid argument |
ErrInvalidConfig | koloswarm: invalid config |
ErrLost | koloswarm: connection lost |
ErrProtocol | koloswarm: protocol error |
ErrRefused | koloswarm: connection refused |
ErrWait | %w: wait |
Comprueba con errors.Is. ErrInvalidConfig envuelve un error de configuración de kolo-dht, y Bootstrap envuelve el ErrInvalidArgument de kolo-dht en el nuestro, así que coinciden los dos centinelas; el ErrNoNodes de kolo-dht, y el ErrNotStored o ErrNoNodes de Join con Announce, se transmiten sin cambios. El Err de un evento Lost es ErrDuplicate (código de cierre 2), ErrRefused (3 o 4), ErrProtocol (5), ErrClosed (cerrado aquí) o ErrLost.
Referencias
- Heilman, Kendler, Zohar and Goldberg, Eclipse Attacks on Bitcoin's Peer-to-Peer Network, USENIX Security 2015.
- Toma: los límites de conexiones contra los ataques de eclipse.
- RFC 8445, ICE: A Protocol for NAT Traversal (Proposed Standard, July 2018).
- Toma: el camino por relay en último lugar.
- No implementa: ICE en sí.
- RFC 8656, TURN: Relay Extensions to STUN (Proposed Standard, February 2020).
- Toma: la duración de las asignaciones.
- No implementa: el formato de mensajes de TURN.
- RFC 9000, QUIC: A UDP-Based Multiplexed and Secure Transport (Proposed Standard, May 2021).
- Toma: los códigos de error de aplicación (sección 20.2).
- RFC 1123, Requirements for Internet Hosts - Application and Support (Internet Standard, October 1989).
- Toma: la comprobación de la sintaxis de los nombres de host (sección 2.1).