# 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.