Most of the time two peers connect directly: the kolo-dht server that stored a record helps them open a path through their NATs. Some pairs cannot connect that way, for example when both peers are behind NATs that pick a new random port for every destination, or behind a firewall that only lets traffic out. For those, kolo-relay can help.
How it works
Direct, or through a relay
The relay is never a silent fallback: your app chooses it, by its address and key.
- When a direct path exists, the peers connect directly and no relay takes part.
- The target dials the relay with kolo-secure and sends Reserve. The relay keeps the reservation for up to an hour.
- The initiator dials the relay and sends Connect with the target's key.
- The relay tells the target with Incoming and the initiator's key. The target accepts or refuses, and the relay answers OK.
- The relay splices the two streams. Inside them the peers run their own kolo-secure connection, end to end, and the target checks it is the announced initiator.
- The relay cannot read the packets. It learns both keys, both addresses, when the session starts and ends, and the sizes and timing of the packets. Each session has limits: 1 hour, 1 GiB each way, 60 seconds idle.
- You run a relay on a host with a reachable IPv4 address.
- A peer reserves a slot on the relay under its key.
- Another peer asks the relay for that key, and the relay joins the two and copies bytes between them.
The two peers then run an ordinary kolo-secure connection end to end, through the relay. The relay forwards ciphertext it cannot read.
Off unless you list one
- Nothing in Kolo picks a relay on its own. A relay is used only when your
application lists it: in kolo-swarm's
Config.Relays, or with-relay host:port@keyin the Kolo examples. - kolo-dht never relays data. When a direct connection is not possible,
its
ConnectreturnsErrUnreachable. - With relays listed, kolo-swarm tries the direct connection first and the relays when that fails. With an empty list it runs no relay code at all.
- With kolo-relay alone, your application passes the relay's address and
key to every
ReserveandDial, and a relayed connection it opened enters a swarm throughAttach. - There is no public relay. You run your own with
kolo-node relay: see Run your own infrastructure.
Which connection am I on?
Direct first, relay as a fallback. On first contact, kolo-swarm tries the relays only after the direct connection failed, which can take up to 3 times 45 seconds when punches start but never connect. A peer that needed a relay before is dialed directly and through the relays at once, and a direct connection that works replaces the relayed one.
In Go, Peer.Direct() is false for a peer reached through a relay, and its
Conn() is a *kolorelay.Conn whose RelayPublicKey() names the relay.
kolo-sync takes either connection the same way.
Good to know
What the operator of a relay can see, in the words of kolo-relay's README:
What the relay learns: both keys of every session, both clients' addresses, which keys hold reservations, when sessions start and end, and the sizes and timing of the inner packets. It cannot read or change them, and it can always drop, delay or end them.
Kolo is IPv4 only, on the relay too.