rustunnel/droid-wiki/lore.md

Lore

Project origins

rustunnel was created in June 2026 as a lab and development tunneling tool. The goal was a cross-platform, self-contained Rust binary that could tunnel traffic over HTTPS with mutual TLS and an application auth token, without relying on external infrastructure.

Eras

Foundation (June 3, 2026)

The first commit (eb4ef2b) laid out the project skeleton: CLI surface using clap, a generate command for self-signed certificates, secret redaction, and a cross-platform CI matrix. A follow-up commit (70411e5) addressed initial scrutiny findings.

Secure tunnel implementation (June 3, 2026)

The core tunnel logic landed in 393100d, implementing HTTPS mTLS with an auth handshake. Shortly after, 76bda0b addressed secure-tunnel scrutiny findings. Dependency updates and CLI refinements followed in fc776fc.

SOCKS5 and multiplexing (June 3, 2026)

Three major commits transformed the architecture:

• 6466753 — Implemented a SOCKS5 proxy with stream multiplexing over HTTPS. This replaced the earlier design where each SOCKS5 request opened a new HTTPS connection.
• f871ba7 — Replaced per-SOCKS-request HTTPS connections with a single persistent multiplexed tunnel session.
• d6a0a40 — Replaced HTTP-shaped forwarding with a true persistent multiplexed tunnel using a custom binary framing protocol.

Framing hardening (June 3, 2026)

• b67248e — Fixed frame header corruption on partial reads. The framing reader was refined to never consume bytes from the buffer until a complete frame (header + payload) is available.

Operational features (June 4, 2026)

• 10b8b24 — Added operational reconnect and shutdown handling. The connector now has a background reconnect loop with exponential backoff, and both sides handle graceful shutdown on SIGINT/SIGTERM.
• 32a29c8 — Fixed flaky generate tests and formatted tunnel.rs.
• b0210a6 — Improved cross-platform CI E2E cleanup with trap and portable port killing.
• 241d7d1 — Unmasked SOCKS5 E2E curl failures in CI and added response content assertions.
• cc1eb55 — Added the project README.
• a758e8e — Added connection key encoding (connkey.rs) and the full tunnel implementation integrating keys into listen and connect.

Longest-standing code

Given the project's short lifespan (2 days), all code is roughly the same age. The modules that have survived the most rewrites are:

• src/cli.rs — CLI structure has remained stable since the first commit.
• src/redact.rs — Secret redaction has not changed since the foundation commit.
• src/errors.rs — Error types have been extended but the core structure is original.

Deprecated features

None so far. The project is new enough that no features have been removed.

Major rewrites

• From HTTP-per-stream to persistent multiplexed tunnel (June 3, 2026) — The original SOCKS5 implementation opened a new HTTPS connection for every stream. This was replaced by a single persistent tunnel with a binary framing protocol, dramatically reducing connection overhead.
• From HTTP forwarding to binary framing (June 3, 2026) — After multiplexing was introduced, the data plane switched from raw HTTP forwarding to a lightweight binary protocol with CONNECT/DATA/CLOSE/ERROR frames.