rustunnel/droid-wiki/systems/framing-protocol.md

Framing protocol

The framing protocol in src/framing.rs defines the binary message format used after the HTTP auth handshake upgrades the connection to a persistent tunnel.

Purpose

Carry multiple bidirectional streams over a single TLS connection with minimal overhead.

Frame format

All multi-byte integers are big-endian.

+--------+----------+----------+-------+-----------+
| Type   | StreamID | Len      | Flags | Payload.. |
| 1 byte | 8 bytes  | 4 bytes  | 1 byte| variable  |
+--------+----------+----------+-------+-----------+

• Type — 0x01 CONNECT, 0x02 CONNECT_REPLY, 0x03 DATA, 0x04 CLOSE, 0x05 ERROR
• StreamID — odd IDs for client-initiated streams, even reserved for server-initiated
• Len — payload length, max 4 MiB
• Flags — reserved for future use (currently always 0x00)

Key abstractions

Type	File	Description
Frame	src/framing.rs	Struct holding frame_type, stream_id, flags, payload
FrameReader	src/framing.rs	Async reader with buffering that handles partial TCP reads
FrameWriter	src/framing.rs	Async writer that serializes and flushes frames
encode_target	src/framing.rs	Encode a Socks5Target into CONNECT frame payload
decode_target	src/framing.rs	Decode a Socks5Target from CONNECT frame payload

Partial read discipline

FrameReader::read_frame loops until a complete frame is available:

1. Attempt to deserialize from the buffer.
2. If the frame is incomplete (FrameTooShort), read more bytes from the underlying TCP stream into the buffer.
3. If the connection closes with a partial frame in the buffer, return an error.
4. Only consume bytes from the buffer once the full frame is present.

This prevents header corruption when TCP segments arrive in arbitrary sizes.

Key source files

File	Purpose
src/framing.rs	Frame format, serialization, async reader/writer, target encoding