ADR-0006: Private world transport via HyperDHT TCP tunnel

Status: Accepted
Date: 2026-07-30

Context

Guests must reach a host Squid without public port forwards. Holesail implements this pattern but is AGPL-3.0. Re-encoding the full Minecraft protocol over Protomux is version-fragile.

Decision

Implement an in-house Apache-2.0 HyperDHT byte pipe:

Host: dht.createServer + pipe each connection to 127.0.0.1:squidPort
Guest: local loopback accept + dht.connect(worldKey) + pipe
Opaque TCP bytes (no MC packet parse on the tunnel)

Do not hard-depend on holesail.

Optional: capability proof on stream open (hyperswarm-capability).

Consequences

Positive

Works for any Squid-supported protocol version
License-safe
Matches peardock “data plane” concept without AGPL

Negative / tradeoffs

One pipe per client connection (resource management needed)
Latency = P2P RTT (not LAN)

Follow-ups

Phase 2 lib/world-tunnel
Concurrency limits and backpressure

1.0 KiB Raw Blame History