HRPC and direct RPC compared

TL;DR

On an open connection, HRPC and a direct TCP RPC cost about the same: tens of microseconds for a small call on Linux loopback. The DHT shows up around that call: joining the network, the first call to a peer, how long a failure takes to surface, and how little the error says. A site with fixed hosts and internal DNS finds a known-endpoint RPC simpler to run and to diagnose. HRPC pays off where addresses change, peers sit behind NAT, or nobody wants to run a PKI. MDK ships HRPC only.

Overview

This page compares HRPC over HyperDHT, the transport on every MDK hop, with a direct RPC that dials a known host and port and authenticates both ends as strongly. It covers setup effort, failure modes, latency and diagnosability, then when the DHT is most valuable. MDK has no known-endpoint transport to switch to; the comparison helps choose a deployment and set expectations with a network team. How Kernel learns a Worker key is a separate question, answered by the deployment topologies.

Two direct baselines are measured:

• HTTPS with mutual TLS and a private CA, the usual way to authenticate a direct RPC
• Noise over TCP: the handshake and RPC framing HRPC already uses (@hyperswarm/secret-stream, protomux-rpc) with pinned keys, dialed at host:port. A known-endpoint MDK transport would most likely take this shape.

What differs

Setup effort

The hosted-site reference lists every key, allowlist and bootstrap setting a managed site sets.

Failure modes

Each row is a measured drill against a peer on the same host, on a three-node private DHT unless the row names the public DHT. The method section describes the drills.

HRPC fails closed in bounded time even when the caller sets no timeout, because HyperDHT gives up on a peer that stops answering; plain TCP does not. The price is that every failure is the same CHANNEL_CLOSED, seconds rather than milliseconds later, so a dead peer, a wrong key and a missing allowlist entry look identical to the caller. Noise over TCP fails a closed port or a rejected key within 2 ms, but also as CHANNEL_CLOSED, because protomux-rpc reports every closed stream that way; a known-endpoint transport keeps TCP's diagnosability only if it passes the socket error through.

MDK adds its own bounds on top:

• An MDK client request times out after 30 s by default with ERR_MDK_REQUEST_TIMEOUT, and a Gateway app built on createMdkClient sees a transport failure as ERR_MDK_CLIENT_UNAVAILABLE: CHANNEL_CLOSED: channel closed
• Kernel calls to a Worker time out after 30 s with ERR_CHANNEL_TIMEOUT, and the Kernel health monitor pings each Worker every 5 s with a 3 s timeout; the first missed ping marks it SICK, which stops command dispatch to it
• The 10 s pool linger belongs to @hyperswarm/rpc's pooled request(), which the Gateway's Kernel client and Kernel's Worker calls use; the app runtime client holds its connection open while a call is in flight, so Gateway calls to apps are not cut

Latency

Measured on Linux loopback, one request at a time. p50 and p99 come from 1,000 calls for 256 B and 200 calls for 64 KiB; the first call opens a new connection to an announced peer, 20 times.

HRPC replies between 16 and 64 KiB stall now and then for 3 to 6 ms; a 1 MiB reply measured 6.5 ms p50. On the macOS host every HRPC call on an open connection is slower: 0.44 ms for 256 B and 10 ms for 64 KiB, growing linearly to 155 ms for 1 MiB, against 0.05 ms and 0.28 ms for Noise over TCP on the same machine. Benchmark on the OS the site runs, not on a developer laptop.

The public DHT changes the steps around the call, not the call. From the macOS host, joining took 6.2 to 6.8 s, announcing 3.6 s, and a first call to a peer 527 ms p50 with a 1.39 s maximum; calls on an open connection matched the private DHT. A component that restarts on the public DHT is therefore unreachable for about 10 s, and every first contact with a peer costs about half a second.

At MDK's cadences (telemetry pulls every 10 s, health pings every 5 s) per-call cost does not decide between the two. Start-up, reconnects and failure detection do.

Diagnosability

When the DHT is most valuable

HRPC over HyperDHT earns its keep when:

• Addresses change: DHCP leases, rescheduled containers or hosts that move, so config must never name an IP
• Peers sit behind NAT or a firewall with no inbound rule, for example a Gateway outside the site network dialing its Kernel
• Nobody wants to run a PKI: keys need no CA, no issuance and no expiry
• Identity must outlive the address: allowlists name keys, so renumbering a network changes nothing
• One configuration must hold from a laptop to a multi-host site

A known-endpoint RPC is simpler when:

• Hosts are fixed and internal DNS already names them
• Outbound UDP to the public bootstrap nodes is blocked, so HRPC needs a private bootstrap anyway
• Operations depend on port probes, load balancer health checks or packet inspection
• A PKI or service mesh already issues and rotates certificates
• A failure must surface in milliseconds with a specific cause

A managed site that runs MDK today keeps HRPC and narrows its cost: pin every key, prefer local or single-process discovery where Kernel and its Workers share a host, and run a private bootstrap where outbound UDP is blocked. The locked-down managed site shape covers those choices.

Method

• One host, loopback only, so the numbers isolate transport overhead and leave out network round trips. They compare transports; they are not capacity figures.
• Linux is Node 24.22 in a node:24-bookworm-slim arm64 container under OrbStack on an Apple M3 Max; macOS is Node 24.16 on the same machine.
• HRPC is @hyperswarm/rpc 3.5.0 on hyperdht 6.34.1, the versions MDK pins. The private DHT is three hyperdht/testnet nodes on loopback; the public DHT uses the default bootstrap set.
• Each call sends a 256 B request, after 50 warm-up calls on the same connection.
• Failure drills run the peer as a separate process, send SIGKILL or SIGSTOP 200 ms before the call, and cap each wait at 60 s. The kill and freeze drills ran on macOS; the others ran on both hosts, and their timings, set by protocol timers, matched.

Next steps

• Deployment topologies: pick how Kernel learns Worker keys before choosing a network design
• Hosted-site reference configuration: apply the key, allowlist and bootstrap settings for a managed site
• Benchmark your site: measure Kernel, Gateway and Workers on your own hardware