Skip to content

Remote comms: Add direct transport support (QUIC + TCP) for Node.js connections #645

@sirtimid

Description

@sirtimid

Problem

Currently only WebSocket/WebRTC transports are configured in connection-factory.ts, limiting Node.js environments to relay-based connections. Direct connections would provide better performance for server-to-server communication.

Proposal

Add support for direct transports — QUIC (UDP) and TCP — for Node.js-to-Node.js communication without requiring a relay server.

QUIC (quic-v1)

Uses @chainsafe/libp2p-quic (Rust-backed native bindings, Node.js only). Advantages over TCP:

  • No head-of-line blocking — natively multiplexes streams over UDP
  • Faster connection setup — single RTT for encrypted, multiplexed connection
  • Ossification resistance — fully encrypted headers

See: https://libp2p.io/guides/quic/

TCP

Uses @libp2p/tcp for standard TCP connections. Useful as a fallback where UDP/QUIC may be blocked.

API Design

User-facing (RemoteCommsOptions): Users declare addresses — the platform auto-detects required transports.

await kernel.initRemoteComms({
  directListenAddresses: [
    '/ip4/0.0.0.0/udp/0/quic-v1',  // QUIC
    '/ip4/0.0.0.0/tcp/0',           // TCP
  ],
});

Address discovery: kernel.getStatus() exposes listenAddresses with OS-assigned ports. Peers exchange addresses out-of-band and register them via kernel.registerLocationHints().

Acceptance Criteria

  • directListenAddresses option on RemoteCommsOptions for users to declare listen addresses
  • NodejsPlatformServices auto-detects QUIC (/quic-v1) and TCP (/tcp/) from address strings
  • ConnectionFactory accepts multiple directTransports (array of transport + listen addresses)
  • QUIC transport loaded via @chainsafe/libp2p-quic when QUIC addresses present
  • TCP transport loaded via @libp2p/tcp when TCP addresses present
  • Both transports can be used simultaneously
  • Direct addresses tried before relay fallback in candidateAddressStrings()
  • kernel.getStatus() exposes listenAddresses when remote comms connected
  • kernel.registerLocationHints() available for out-of-band address exchange
  • Bootstrap peer discovery conditional (omitted when no relays provided)
  • Browser environments continue to work (WebSocket/WebRTC only)
  • Unit tests for transport configuration, address merging, and auto-detection
  • E2E tests for direct QUIC and TCP connections between Node.js instances

Metadata

Metadata

Assignees

Labels

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions