Networking

At the core of iroh is the ability to connect any two devices, no matter where they are.

Nodes

The primary functionality of the networking is to establish connections between two nodes, regardless of where they are located. To make this feasible the nodes are addressed by NodeId rather than by IP address and port. The NodeId is created from the public portion of a cryptographic keypair use for signing messages.

A node still needs to bind to an IP address and port to be reachable, and IP addresses are still part of the addressing, though not the primary addressing mechanism. Multiple nodes can run on the same machine, but not share the same port.

Networking nodes are created and controlled by the Endpoint struct in the iroh-net library. Often wrapped in the higher abstraction provided by Node, when using multiple of iroh's layers together.

On layer 0 an iroh network is a collection of nodes. By default an node does not dial out to other nodes, but waits for incoming connections. Instead actions like joining a document or subscribing to a gossip topic will kick of connections to nodes in the same document or topic.

Connections

An iroh connection uses QUIC as the transport protocol, exposing a full QUIC API to application developers. QUIC is a modern transport protocol that provides a reliable, encrypted, multiplexed connection between two nodes. QUIC is build on top of UDP, and is designed to deal with a wider variety of network situations than TCP.

Iroh integrates with QUIC and the UDP transport to create direct connections between nodes. It dynamically routes the QUIC UDP packets via the best path to the peer, regularly performing latency probes to find the best path between nodes. Typically a connection starts relayed to ensure immediate connectivity. Iroh than coordinates holepunching to establish a direct connection between peers, once the direct connection exists the QUIC connection is seemlessly routed over it. When the network situation changes iroh quicly adapts to the new routes and seemlessly moves the connection over.

For connections where no holepunching is needed iroh can establish a connection without a relay server. For this the application can explicitly provide IP addressing information for a peer node, or rely on a pluggable discovery mechanism.

Relays

The relay server is an important component to ensure a connection can be established swiftly between any two iroh nodes, regardless of their location. It helps when strict firewall rules or NAT configurations are on the network path. As the relay server is publicly reachable by all nodes it can pass UDP packets between nodes until they manage to establish a direct connection. It also plays a vital role in the holepunching by informing nodes of their networking situation and coordinating between nodes.

Since all traffic between nodes is encrypted for the destination node only, relay servers have very little knowledge and cannot inspect the contents of forwarded packets.

API docs

See the reference documentation for more technical details and the API provided.