glm-5.2
a3cb44968e
Prune the channels spec to reflect the stream-unification resolution (docs/research/stream-unification/findings.md): the channels wire format goes from 9 bytes to 8 bytes, the channels layer no longer carries a stream_type concept, into_sub_streams() is removed, and TTY always uses its 5-byte format (carried transparently in the channels payload). ADR-093 is the umbrella decision (the channels-layer consequence of ADR-092's BiStream handler leaf): every channel is a BiStream, the handler owns its sub-stream multiplexing, the channels layer routes by channel_id only. Amends ADR-071 (8-byte header, no stream_type), ADR-074 (into_sub_streams removed, accept_bi yields BiStream), reverses ADR-077 (TTY always 5-byte), and the channels-facing clauses of ADR-072/073/075/076/080/081. Adds ADR-092 forward-reference note (into_sub_streams preservation subsequently reversed by ADR-093) and the missing ADR-092 cross-reference on ADR-070. Adds OQ-68 (add/strip API shape — built-in vs utility; the contract is decided in ADR-093, the function surface is open; two-way door, low priority, decision-ready when the channels crate's implementation begins). Rewrites the 7 channels spec docs (README, overview, channels-wire, channels-connection, channels-adapter, channel-operations, channel-client) to describe the post-amendment shape as current, with the 8-byte header, the add/strip composition, single accept_bi accessor, BiStream per channel, and TTY-always-5-byte. Touch-up cross-references in hub README, client README, ADR-085, and the OQ-45/47/65 question files (TTY-internal stream_type 3 → STREAM_CTRL_IN; channels 9-byte → 8-byte).
4.3 KiB
OQ-68: Channels Add/Strip API Shape (Built-In vs. Utility)
-
Origin:
docs/research/stream-unification/findings.md§"The add/strip utility";docs/architecture/decisions/093-channels-pure-channel-multiplexing.md§"What this ADR does NOT decide";docs/architecture/crates/channels/channels-wire.md§"The add/strip composition" -
Status: open
-
Door type: two-way (the contract — channels strips its 8-byte header on read, handler parses its own framing from the payload — is decided in ADR-093; the function surface — whether add/strip is built into the read/write path or exposed as a standalone utility — is reversible without breaking the wire format or the handler contract)
-
Priority: low
-
Impacts: None — the add/strip contract is decided (ADR-093); this OQ is about the API shape, not the contract. The channels crate can ship with either shape and switch later without a wire-format change.
-
Investigation target: work through 2+ example handler compositions (TTY inside channels, tunnel inside channels, a recursive
alknet/channels-inside-alknet/channelscomposition) to see where the add/strip naturally lives. If the header add/strip is built into the channels read/write path, the handler never sees thechannel_id— theBiStreamthe handler receives is the payload bytes. If the add/strip is a standalone utility, the handler (or a test helper, or the hub relay'schannel_idrewrite) can call it explicitly. The question is which shape is cleaner for the common case (handler inside channels) without foreclosing the less-common cases (recursive composition, the hub relay, test helpers). -
Resolution: Not yet decided. The two options:
Option A — Built into read/write (the default). The channels layer's
accept_bireturns aBiStreamwhose bytes are the payload (the channels header is stripped internally). The handler'sAsyncWriteon theBiStreamre-adds the 8-byte header internally (the handler writes payload bytes; the channels layer frames them). The handler never sees thechannel_id; the add/strip is invisible. This is the cleanest shape for the common case (a handler inside channels). The utility (add_channel_id/strip_channel_id) is still available internally (the channels layer calls it), and may be exposed publicly for the less-common cases (recursive composition, the hub relay, test helpers) — but the handler boundary doesn't require it.Option B — Standalone utility (the explicit alternative). The channels layer exposes
add_channel_id(channel_id, payload_bytes) -> chunkandstrip_channel_id(chunk) -> (channel_id, payload_bytes)as the primary API. The handler (or a wrapper, or a test helper) calls them explicitly. This is the shape the stream-unification research proposed. It's more explicit (the handler sees thechannel_id, can log it, can route on it) but pushes the add/strip to the handler boundary, not the channels read/write path. The handler'sBiStreamis the raw chunk bytes (header + payload), not the payload alone.The trade-off: Option A is cleaner for the common case (the handler doesn't care about
channel_id; the channels layer owns it entirely) but may require an escape hatch for the less-common cases (the hub relay needs to rewritechannel_id; recursive composition needs to re-add a header; test helpers may want to construct chunks directly). Option B is more uniform (the same add/strip pair at every level, including the handler boundary) but pushes work to the handler that the channels layer could own. The investigation target (2+ example compositions) is what surfaces which shape is cleaner in practice.This question is decision-ready when the channels crate's implementation begins. Until then, the contract (channels strips, handler parses payload) is decided (ADR-093); the function surface is not.
-
Cross-references: ADR-093 (the umbrella decision that decides the add/strip contract and leaves the function surface to this OQ);
docs/research/stream-unification/findings.md§"The add/strip utility" (the research that proposed the utility);docs/architecture/crates/channels/channels-wire.md§"The add/strip composition" (the spec that records the contract and points to this OQ)