fastn_net

Module protocol

Source
Expand description

Protocol multiplexing over P2P connections.

This module implements a custom protocol multiplexing system over Iroh P2P connections, deliberately deviating from Iroh’s recommended ALPN-per-protocol approach.

§Why Not Use Iroh’s Built-in ALPN Feature?

Iroh recommends using different ALPNs for different protocols. However, this approach has a significant limitation: each protocol requires a separate connection.

§The Problem with Multiple Connections

Consider a typical P2P session where an entity might:

  • Send periodic pings to check connection health
  • Proxy HTTP requests through another entity
  • Tunnel TCP connections simultaneously
  • Stream real-time data (e.g., during a call while browsing shared files)

With Iroh’s approach, each protocol would need its own connection, requiring a full TLS handshake for each. ALPN is negotiated during the TLS handshake:

Client Hello Message Structure:
┌─────────────────────────────────────┐
│ Handshake Type: Client Hello (1)    │
│ Version: TLS 1.2 (0x0303)          │
│ Random: dd67b5943e5efd07...        │
│ Cipher Suites: [...]                │
│ Extensions:                         │
│   ALPN Extension:                   │
│     - h2                           │
│     - http/1.1                     │
└─────────────────────────────────────┘

Creating additional connections means additional:

  • TLS handshakes (expensive cryptographic operations)
  • Network round trips
  • Memory overhead for connection state
  • Complexity in connection management

§Our Solution: Application-Layer Multiplexing

We use a single ALPN (/fastn/entity/0.1) and multiplex different protocols over bidirectional streams within that connection:

Single Connection between Entities
    ├── Stream 1: HTTP Proxy
    ├── Stream 2: Ping
    ├── Stream 3: TCP Tunnel
    └── Stream N: ...

Each stream starts with a JSON protocol header identifying its type.

§The Protocol “Protocol”

§Stream Lifecycle

  1. Client entity opens a bidirectional stream
  2. Client sends a JSON protocol header (newline-terminated)
  3. Server entity sends ACK to confirm protocol support
  4. Protocol-specific communication begins

§Protocol Header

The first message on each stream is a JSON-encoded ProtocolHeader containing:

  • The Protocol type (Ping, Http, Tcp, etc.)
  • Optional protocol-specific metadata

This allows protocol handlers to receive all necessary information upfront without additional negotiation rounds.

§Future Considerations

This multiplexing approach may not be optimal for all use cases. Real-time protocols (RTP/RTCP for audio/video) might benefit from dedicated connections to avoid head-of-line blocking. This design decision will be re-evaluated based on performance requirements.

Structs§

ProtocolHeader
Protocol header with optional metadata.

Enums§

Protocol

Constants§

APNS_IDENTITY
Single ALPN protocol identifier for all fastn entity connections.