alkcall/docs/architecture/decisions/034-channels-wire-format.md

ADR-034: alknet-channels Wire Format — 8-Byte Chunk Header

Status

Accepted (revised 2026-07-12: substrate simplification + stream_type decomposition; amended 2026-07-18 by ADR-035: wire format is 8 bytes, not 9; stream_type removed from the channels header — see "Amendment (ADR-035, 2026-07-18)" below)

Amendment (ADR-035, 2026-07-18)

The 9-byte chunk header is amended to 8 bytes: [channel_id:u32 BE][length:u32 BE][payload]. The stream_type byte is removed from the channels header — the channels layer has no stream_type concept, not in its header, not in its code, not in its mental model. The handler owns its sub-stream multiplexing on the BiStream the channels layer gives it (per ADR-035, the channels-layer consequence of ADR-009's BiStream handler leaf). What was the channels header's stream_type byte is now the first byte of the payload, owned by the handler's framing (TTY's 5-byte format, call's length-prefixed JSON, tunnel's raw bytes, SSH's channel protocol).

The stream_type decomposition (unidirectional halves, mod 3 formula, 85 groups) is removed from the channels layer. The stream_type concept survives in TTY's 5-byte format (ADR-052, amended by Phase 7), which the channels layer carries transparently in its payload. The total header for a TTY chunk inside channels is 13 bytes (8 channels + 5 TTY), not 9; the two length fields are close but not identical (ch_len = tty_len + 5). This is the documented cost of clean separation of concerns — see ADR-035 §"Consequences" for the full cost/benefit.

The body below describes the current (9-byte) shape; the amendment above is the operative decision. The 9-byte description is kept as the historical context for the amendment. See ADR-035 for the resolution rationale and the cross-ADR impacts.

Context

alknet-channels is a multiplexing proxy: a ProtocolHandler on alknet/channels that carries N logical channels, each with a different ALPN, over transport stream(s). The wire format is the substrate that makes this work.

Two prior formats inform this design:

1. SSH's channel multiplexer (RFC 4254) — ChannelId(u32) with string-named types negotiated per channel, all traffic interleaved on one encrypted transport stream.
2. alknet-tty's chunk format (ADR-052) — [stream_type: u8][length: u32 be] [payload], a fixed set of four sub-streams (stdin/stdout/stderr/control) within one bidi stream. Validated by two POCs and in production code.

The channels format is the generalization: add a channel_id: u32 prefix to TTY's 5-byte header, turning a fixed 4-channel multiplexer into an arbitrary N-channel multiplexer. The de-risk POC (28 tests) validated the core mechanics.

The substrate simplification

Different transports have different native multiplexing capabilities. QUIC has native bidi streams; TCP+TLS does not. The initial framing of this ADR treated the 9-byte header as "the in-line substrate format" — used when the transport has no native multiplexing, with a separate substrate for QUIC native streams. That framing adds complexity (two substrates, a channel_id↔stream-ID mapping) for no benefit.

The simplification: the 9-byte header is used in all substrates, on every bidi stream that carries channels. The channel_id in the header is the logical correlation key. The transport's native multiplexing (when present) is a performance optimization (independent flow-control windows per stream), not a protocol change. The ChannelsAdapter reads the 9-byte header off every bidi stream it accepts — on a transport with one stream (in-line), the header demuxes N channels from that stream; on a transport with N streams (QUIC native), each stream carries one logical channel and the header provides stream_type and channel_id correlation. Same code path, same wire format, same handler experience.

The stream_type decomposition

The initial framing had stream_type 3 as "bidirectional" (control messages). This is a design flaw: one stream_type both sides write to is not properly multiplexed — it loses independent flow control, independent EOF, and clean separation of concerns. The TTY crate's control channel already exhibits this problem ("the control channel isn't actually bidirectional… the adapter ignores Exit from the client" — phase-0 findings §Less Straightforward Parts).

The fix: every stream_type is unidirectional. Bidirectionality is achieved by having two stream_types (one write, one read), the same way QUIC bidi streams are two unidirectional halves. Control becomes 3 (write, client→server) and 4 (read, server→client), not one "bidirectional" 3.

Decision

Chunk header

[channel_id: u32 be][stream_type: u8][length: u32 be][payload bytes]

9 bytes of header. The channel_id is the addition over TTY's 5-byte format; stream_type and length are identical to TTY's fields (ADR-052), preserving the framing-disambiguation soundness property.

field	width	meaning
channel_id	u32 BE	The logical channel this chunk belongs to. Channel 0 is pre-negotiated as alknet/call (ADR-036). Channels 1..N are opened dynamically via channel/open.
stream_type	u8	The unidirectional sub-stream within the channel. See "Stream types" below.
length	u32 BE	The payload length in bytes. 0 = EOF sentinel (same convention as TTY — ADR-052 §Sentinels).

MAX_CHUNK_LEN

16 * 1024 * 1024 (16 MiB), matching TTY's cap (ADR-052 §5). A chunk with length > MAX_CHUNK_LEN returns ChunkTooLarge and does not corrupt the stream — the demux drops the chunk and continues. The header is always exactly 9 bytes, so the demux can always resync by reading the next 9-byte header.

Stream types — unidirectional, grouped in threes

Every stream_type is unidirectional. Bidirectionality is two stream_types (write + read), not one "bidirectional" stream_type. The stream_types are grouped in threes:

Group	stream_type	direction	purpose
Data	0	write (client→server)	data in (stdin equivalent)
	1	read (server→client)	data out (stdout equivalent)
	2	read (server→client)	data err (stderr equivalent, optional)
Control	3	write (client→server)	control in (ALPN-specific format)
	4	read (server→client)	control out (ALPN-specific format)
	5	read (server→client)	control err (optional)
Future	6/7/8	write/read/read	next group, same pattern
	9/10/11	write/read/read	next group
	...

Formula: stream_type % 3 == 0 → write half (in), stream_type % 3 == 1 → read half (out), stream_type % 3 == 2 → diagnostic read half (err).

256 values / 3 = 85 groups. The u32 channel_id space (~4 billion channels before wrap, ADR-040) combined with 85 stream_type groups is effectively unlimited for the intended use cases.

Why unidirectional: each stream_type gets its own reassembly buffer, its own flow control, its own EOF. The TTY control channel becomes actually bidirectional because there are two unidirectional streams (3 in, 4 out), not one stream both sides write to. This resolves the "control channel isn't actually bidirectional" problem the TTY crate has today. The same principle applies to any future channel type — control is two halves, not one shared stream.

Control payload format is ALPN-specific, not channels-enforced. The channels layer is blind to what stream_types 3/4/5 carry — it reassembles bytes and delivers them to the handler. The TTY crate happens to use JSON for its control channel (resize, signal, eof, exit) because its control messages map cleanly to JSON; another ALPN might use a binary control format. The channels layer does not mandate JSON on control stream_types. This is the same ALPN-blindness principle that applies to the data stream_types: the channels layer routes bytes, the handler interprets them.

Per-ALPN stream_type sets

ALPN	Active stream_types	Why
alknet/call (channel 0)	[0, 1]	call frames bidirectional via 0=in, 1=out
alknet/tty	[0, 1, 2, 3, 4]	data in/out/err + control in/out
alknet/tunnel	[0, 1]	data in/out only (no channels-layer control needed)
alknet/ssh	[0, 1]	SSH multiplexes internally, including its own control

The active set is declared at channel/open time (ADR-037 stream_types field) and fixed for the channel's lifetime. A tunnel that wants keepalive could declare [0, 1, 3, 4].

Substrate modes — same wire format, different stream counts

The 9-byte header is used in all substrates, on every bidi stream. The difference between substrates is only how many bidi streams the transport yields:

Substrate	Transport	Streams	Header role
In-line	TCP+TLS, WebTransport session, SSH direct-tcpip	1	Header demuxes N channels from that 1 stream
Native	QUIC (quinn/iroh)	N	Each stream carries 1 logical channel; header provides stream_type + channel_id correlation
Multi-connection	Any, N connections	N × M	Each connection is self-contained (own channel 0, own demux); header is per-connection

The ChannelsAdapter::handle loop: accept_bi() → for each stream, read the 9-byte header → route by (channel_id, stream_type) → reassemble. On an in-line transport, accept_bi() yields once then ConnectionClosed — the header does all the demux. On QUIC, accept_bi() yields repeatedly — each stream is a channel, and the header provides stream_type and channel_id correlation. Same code path, same wire format, same handler experience.

Why keep the header on QUIC when the stream already separates channels:

• stream_type decomposition. TTY needs 5 sub-streams. On QUIC, one stream per channel + the header carrying stream_type is simpler than 5 streams per channel and matches the in-line case's shape. Per-stream-type flow control is handled at the reassembly buffer level (ADR-040) regardless of substrate.
• channel_id correlation. The hub relay forwards a channel from the browser leg to the spoke leg, mapping browser_id ↔ spoke_id. If channel_id is in the header on every stream, the relay correlates by reading the header — regardless of substrate. If channel_id lived only in the channel/open response, the relay would need a stream-ID-to- channel_id mapping per leg.
• Uniform handler experience. The handler receives a Connection and calls accept_bi() or into_sub_streams(). It doesn't know or care whether the substrate is in-line or native — the ChannelBidiStreamSource wraps the reassembled stream either way.

The "bloat" (9 bytes/chunk on transports that have native multiplexing) is the cost of uniformity. For the intended use cases (TTY, SSH, tunnels, call operations), this is noise. The high-throughput escape hatch is multi-connection, not stripping the header.

Framing disambiguation (carried from ADR-052 §5)

Channel 0 is just another channel — its chunks have channel_id=0 in the header. Disambiguation between channel 0 (call protocol) and data channels is by channel_id, not by a special first-byte trick. Within a channel, stream_type 0 (write half) from the server is invalid, so 0x00 as the first byte of a chunk payload from the server is unambiguous.

Zero-length sentinel = EOF

A zero-length chunk is delivered as an empty Bytes, which the reassembled stream interprets as EOF (same convention as TTY — ADR-052 §Sentinels). This is the clean-shutdown signal for a (channel_id, stream_type) pair.

Sync core / async shell split

The wire format's core is pure byte manipulation — parse_header(&[u8; 9]) -> ChunkHeader and write_header(channel_id, stream_type, length, &mut [u8; 9]). No async, no platform dependencies. Compiles under wasm32-unknown-unknown (validated by the POC). The async shell (demux/mux) wraps this core with read_exact/write_all on the transport and mpsc routing. This split keeps the WASM-compatible core separate from the tokio-dependent shell.

Consequences

Positive:

• One wire format across all substrates. The ChannelsAdapter code path is the same regardless of transport; the transport's native multiplexing is a performance optimization, not a protocol change.
• Every stream_type is unidirectional — proper multiplexing with independent flow control and EOF per half. The TTY control channel becomes actually bidirectional (3 in, 4 out), resolving the "not actually bidirectional" flaw.
• The hub relay correlates by channel_id in the header, uniformly across substrates — no stream-ID-to-channel_id mapping per leg.
• WASM-compatible by construction — the pure core has no platform deps.
• The framing-disambiguation property from ADR-052 carries forward unchanged.

Negative:

• 9 bytes per chunk on all substrates, including QUIC where the transport already separates streams. This is 4 bytes more than using the QUIC stream ID directly as the channel_id. For the intended use cases this is noise; for high-throughput bulk transfer, the answer is multi-connection, not stripping the header.
• All channels on one in-line connection share one transport stream's flow-control window. A slow consumer on one channel can backpressure others. Mitigated by bounded-buffer backpressure (ADR-040), not eliminated. The native substrate (QUIC streams) avoids this — each channel gets its own flow-control window. For high-throughput, use native or multi-connection.

Door type

One-way. The chunk header layout (channel_id:u32 + stream_type:u8 + length:u32, 9 bytes) and the stream_type group assignments (0/1/2 = data, 3/4/5 = control, % 3 formula) are wire-format commitments. Changing them after deployments exist requires a version migration.

Amended by ADR-035 (2026-07-18): the header layout is now channel_id:u32 + length:u32 (8 bytes); the stream_type byte and its decomposition are removed from the channels layer. The one-way door is re-cast (the channels crate is not yet implemented, so this is the right time to cast it). See ADR-035 for the amended door-type discussion.

The MAX_CHUNK_LEN value (16 MiB) is a two-way-door implementation detail within the one-way format.

References

• ADR-035: channels pure channel multiplexing (amends this ADR — wire format is 8 bytes, not 9; stream_type removed from the channels header; the stream_type decomposition is removed from the channels layer; the handler owns its sub-stream multiplexing on the BiStream)
• ADR-052: alknet-tty wire format (the 5-byte format this generalizes; amended by ADR-077 — scoped to direct TTY; re-amended by ADR-035 — TTY always uses its 5-byte format, carried transparently in the channels payload)
• ADR-007: Connection::from_stream (the transport-agnostic Connection)
• ADR-008: BidiStreamSource trait (the extension point the channels connection implements; its docstring already anticipated per-channel streams)
• ADR-036: channel 0 pre-negotiated (now uses stream_types [0, 1])
• ADR-037: channel lifecycle operations (stream_types field examples updated)
• ADR-038: ChannelBidiStreamSource (into_sub_streams returns unidirectional handles)
• ADR-040: backpressure (bounded-buffer applies at reassembly regardless of substrate)
• ADR-077: TTY inside channels (5 sub-streams; control properly bidirectional via 3/4)
• docs/research/alknet-channels/poc-summary.md — the POC that validated the format (28 tests, WASM compile check)
• docs/research/alknet-channels/phase-0-findings.md §The Wire Format, §Less Straightforward Parts (the control-channel bidirectionality problem)