aeroxy/tunnix

1. What this repo is

- tunnix is a single Rust binary that runs in two major modes: server and client.

- Its core job is to carry SOCKS5, HTTP proxy, remote shell, and file-transfer traffic through an HTTP/SSE tunnel, encrypted end-to-end.

2. Top-level architecture

- The client sits next to local apps and exposes a local proxy port.

- The server sits on the remote host and exposes HTTP endpoints.

- Traffic flows: local app → client listener → encrypted tunnel over HTTP/SSE → server router → target TCP service.

3. Client ingress boundary

- proxy.rs accepts incoming TCP connections on the local port and peeks the first byte to auto-detect protocol.

- socks5.rs handles SOCKS5 CONNECT sessions.

- http_proxy.rs handles HTTP proxying, including HTTP CONNECT and plain HTTP forwarding.

- This means the client is the protocol adapter between local apps and the tunnel.

4. Connection handling and multiplexing

- relay.rs is the bidirectional pipe between a local connection and a tunnel session.

- It tracks connection IDs and lets many local connections share one tunnel transport.

- The tunnel is session-based rather than one TCP socket per target connection.

5. Tunnel transport

- tunnel.rs implements the client side of the HTTP/SSE transport.

- The transport uses POST /send/{session} for encrypted binary payloads and GET /stream/{session} as an SSE event stream.

- This design avoids WebSockets and works in environments that allow plain HTTP but block direct TCP.

6. Server-side HTTP boundary

- server.rs is the remote HTTP server, built on hyper.

- It strips optional path prefixes, routes session traffic, and exposes HTTP endpoints such as health checks.

- It is the network-facing boundary on the remote host; everything past it is internal tunnel/session handling.

7. Cryptography and shared wire format

- crypto.rs provides the end-to-end protection layer.

- The repo uses Argon2id to derive keys from the shared password and ChaCha20-Poly1305 for authenticated encryption.

- protocol.rs likely defines the framing/messages that both sides use inside the encrypted channel.

8. Optional remote execution path

- exec.rs implements remote-exec, which is an opt-in shell/command execution channel over the same tunnel.

- On the server side it requires explicit authorization via --allow-exec.

- The PTY-based design matters architecturally: it is interactive, terminal-aware, and Unix-only.

9. Optional file transfer path

- transfer.rs and archive.rs implement push/pull.

- Files and directories are packed into tar archives, compressed with zstd, then sent through the encrypted tunnel.

- This is a separate application-layer stream from proxy traffic, but it reuses the same auth and transport infrastructure.

10. Configuration and hot reload

- config.rs loads CLI flags, config files, defaults, and environment-based password input.

- reload.rs watches config changes and reloads selected fields without restart.

- Hot-reloadable settings include password, headers, path prefix, and some response text; listener addresses and logging level require restart.

11. Important integration boundaries

- The client boundary is “local app protocol termination” for SOCKS5 and HTTP proxy.

- The server boundary is “HTTP ingress” and “remote TCP egress” to target services.

- A reverse proxy or platform URL may sit in front of the server; path_prefix and custom headers exist specifically to survive those deployment constraints.

12. Tests and operational packaging

- tests/transfer_roundtrip.rs validates the archive/transfer path.

- tests/reconnect_on_url_change.rs covers tunnel resilience when the server URL changes.

- The repo also includes a Homebrew formula and Cargo-based build/release tooling, indicating it is packaged as a deployable CLI binary rather than a library.