Peer-to-peer connections

Direct connects consumers and providers using the Holepunch stack. Here we explain how Direct puts it to use, from finding peers to exchanging requests and responses. For more detail on how the networking itself works, see Holepunch's documentation.

Finding a way into the network

The Direct client accesses the provider directory by connecting to one or more Direct-operated peers. These peers are reached independently through the P2P network, without a central gateway. By running many of them across different regions and data centers, we keep the network available even when a local outage takes some peers offline.

To connect this way, the client needs to discover available peers rather than contact a fixed entrypoint. Direct uses Hyperswarm for this, looking up Direct-operated peers through a distributed hash table maintained by the P2P network.

Establishing a direct connection

Once a peer has been found, Hyperswarm establishes a connection using its public key. The process of connecting is the same for both Direct-operated peers found through discovery and providers which the client has selected through the provider directory.

Part of that process is finding a path between the two machines. Even when both have internet access, their routers or firewalls may block incoming connections. Hyperswarm coordinates traffic from both sides, using hole punching where needed to establish a path through their routers.

The connection is authenticated and encrypted through Noise. When connecting to a provider, the client uses the public key from its directory entry. The handshake can therefore only succeed if the remote peer holds the matching private key, confirming that the client has reached the selected provider even if its network address has changed.

Carrying service traffic

The established connection provides an encrypted duplex stream, so requests and responses can travel in both directions. Underneath it, UDX provides reliable delivery over UDP, handling packet loss, ordering, and congestion.

Several requests can use this connection at once, even across different services. Direct uses Protomux to keep communication separated in service specific channels. Each service implementation defines the channels it uses and how they carry its messages.

Once connected, the client keeps providers ready to serve further requests while continuing to look for better candidates. It opens connections to better-suited providers and replaces those that become unhealthy or less competitive. Subsequent requests can therefore use an existing direct connection to the provider best suited to serve them.

The client handles load balancing locally, combining the capacity of multiple providers with a direct connection to whichever is best suited to each request. Applications benefit from the network's available capacity and ongoing provider verification, while requests take the direct path between consumer and provider.

Connection privacy

On a direct connection, consumers and providers can see each other's network addresses, while the traffic between them remains encrypted.

A separate connection privacy proposal explores optional Direct-operated relays to keep your address private from other peers. As with a traditional gateway, the relay would be trusted to hide each peer's address from the other side, while requests and responses remain encrypted between them.