rustunnel/droid-wiki/features/stream-multiplexing.md

Stream multiplexing

rustunnel carries multiple SOCKS5 connections over a single persistent TLS tunnel using stream IDs.

Purpose

Avoid the overhead of establishing a new HTTPS connection for every SOCKS5 request. A single mTLS+auth session stays open, and multiple logical streams are interleaved via the binary framing protocol.

How it works

Connector side

1. A local SOCKS5 client connects to the connector's SOCKS5 proxy.
2. The connector's StreamMux::open_stream allocates the next odd stream ID.
3. It sends a CONNECT frame with the target address encoded in the payload.
4. It waits for a CONNECT_REPLY frame (status 0x00 = OK).
5. On success, it returns a mpsc::Receiver<Bytes> for tunnel-to-SOCKS5 data.
6. The connector spawns a task to read from the SOCKS5 client and send DATA frames to the tunnel.
7. Another path reads from the data_rx channel and writes raw bytes back to the SOCKS5 client.

Listener side

1. The listener receives a CONNECT frame with a stream ID and target address.
2. It resolves the target address and opens a TCP connection.
3. It spawns a task to read from the target and send DATA frames back to the tunnel.
4. It sends a CONNECT_REPLY frame to acknowledge the stream.
5. Incoming DATA frames for that stream ID are written to the target connection.
6. CLOSE frames trigger shutdown of the target connection.

Stream isolation

Each stream has its own ID. Data from one stream never mixes with another. The E2E test e2e_concurrent_streams_isolation verifies this by sending unique payloads through two concurrent streams and asserting each echo response matches its original payload.

Key abstractions

Type	File	Description
StreamMux	src/tunnel.rs	Connector-side multiplexer
ServerStreamEntry	src/tunnel.rs	Listener-side per-stream target write half
ConnectorStreamEntry	src/tunnel.rs	Connector-side per-stream data channel and reply channel

Key source files

File	Purpose
src/tunnel.rs	StreamMux, open_stream, dispatch_frame, framing loops
src/framing.rs	Frame types, CONNECT/DATA/CLOSE/ERROR encoding