alkdev/alknet

0 Fork 0

Files

T

glm-5.2 fd83fc1685 docs(arch): channels substrate simplification + stream_type decomposition + sub-crate split

Three simplifications to the channels spec, all flowing from the review:

1. Substrate simplification (ADR-071 revised): the 9-byte chunk header is
   used in ALL substrates — in-line (TCP+TLS, WebTransport), native (QUIC
   bidi streams), and multi-connection. The ChannelsAdapter reads headers
   off every bidi stream it accepts; the transport's native multiplexing
   is a performance optimization (independent flow-control windows), not a
   protocol change. One wire format, one code path, one handler experience.
   The channel_id in the header is the correlation key across substrates.

2. Stream_type decomposition (ADR-071 revised): every stream_type is
   unidirectional. Bidirectionality is two stream_types (write + read), not
   one 'bidirectional' stream_type. Grouped in threes: 0/1/2 = data
   write/read/err, 3/4/5 = control write/read/err, % 3 formula. This
   resolves the TTY control channel's 'not actually bidirectional' flaw —
   control is now 3 (write, client→server) + 4 (read, server→client), each
   with its own reassembly buffer and EOF. Channel 0 uses [0,1] (call frames
   bidirectional via 0=in, 1=out). TTY uses [0,1,2,3,4]. ADR-072, 073, 074,
   077 updated for the new stream_type assignments.

3. Sub-crate decomposition (ADR-081 new): channels-core (pure multiplexer —
   wire format, demux/mux, ChannelBidiStreamSource, ChannelManager; depends
   on alknet-core only, no call dependency, ALPN-blind) / channels-call
   (channel 0 pre-negotiation + lifecycle op registrations; depends on
   channels-core + alknet-call) / channels-hub (relay) / channels-worker
   (ChannelClient). Isolates the call-protocol coupling from the pure
   multiplexer so the dependency graph is honest.

ADR-077 (TTY inside channels) updated: TTY now uses 5 sub-streams [0,1,2,3,4]
with control properly bidirectional via 3/4; amends ADR-052's stream_type
assignments for direct mode too (direct alknet/tty now uses 0-4, not 0-3).

Spec docs updated: channels-wire, channels-connection, channels-adapter,
channel-operations, overview, README.

2026-07-12 15:47:42 +00:00

9.4 KiB

Raw Blame History

status, last_updated

status	last_updated
draft	2026-07-12

alknet-channels

A multiplexing proxy: a ProtocolHandler on alknet/channels that decomposes a single bidirectional transport stream into N logical channels, each carrying a different ALPN. Channel 0 is pre-negotiated as alknet/call (ADR-072); every other channel is opened dynamically via call operations on channel 0 and routed through the same HandlerRegistry as top-level connections. The channels layer is a re-framing proxy — it converts between "one transport stream carrying N channels" (the wire) and "N independent AsyncRead + AsyncWrite handles" (what handlers see) — and it does no protocol work itself.

Documents

Document	Status	Description
overview.md	draft	Crate purpose, the multiplexing collapse, dependencies, ALPN, transport agnosticism, WASM, relationship to existing crates
channels-wire.md	draft	The 9-byte chunk format (`[channel_id:u32 be][stream_type:u8][length:u32 be][payload]`), stream types, sentinels, framing disambiguation, wire-level invariants (REQ-CH-01..05)
channels-connection.md	draft	`ChannelBidiStreamSource` (implements `BidiStreamSource` — ADR-070/074), `into_sub_streams()` typed destructure, recursive composition
channels-adapter.md	draft	`ChannelsAdapter` (`ProtocolHandler` on `alknet/channels`), `ChannelManager`, demux/mux contracts (REQ-CH-01..04), the two-pump pattern (ADR-078)
channel-operations.md	draft	`channel/open`, `channel/close`, `channel/control`, `channel/resources/subscribe` — call-protocol operations on channel 0, ACL flow, `direction` semantics, the hub relay contract (ADR-079)
channel-client.md	draft	`ChannelClient` — the client side of a channels connection, QUIC-only initially, bidirectionality preserved

Applicable ADRs

ADR	Title	Relevance
071	channels Wire Format — 9-Byte Chunk Header	The chunk format; unidirectional stream_types in groups of 3; substrate-agnostic; one-way door
072	Channel 0 Is Pre-Negotiated `alknet/call`	Channel 0 = call protocol, stream_types [0,1]; no special control plane
073	Channel Lifecycle Operations on the Call Protocol	`channel/open`/`close`/`control`/`resources/subscribe`; `direction` semantics; subscribe not poll
074	ChannelConnection — BidiStreamSource over Chunk Reassembly	Per-channel `BidiStreamSource` impl; `into_sub_streams()` with `SubStreamHandle` enum (Send/Recv)
075	ChannelsAdapter and ChannelManager	Substrate-agnostic demux loop; REQ-CH-01..04 contracts
076	Backpressure, Channel Limits, and ID Reuse	Bounded-buffer (1 MiB default), 256-channel cap, monotonic IDs with wrap
077	TTY Inside Channels — Sub-Streams, Not Wire Format	TTY's two modes (direct vs channels); 5 sub-streams; control bidirectional via 3/4; amends ADR-052 scope
078	Two-Pump Shutdown-on-Completion Pattern	The two-pump deadlock contract; handler-level, not channels-layer
079	Hub Relay — Translate, Not Transparently Forward	The hub translates channel 0, byte-forwards data channels with ID rewrite
080	ChannelClient — the Client Side of a Channels Connection	`ChannelClient`, QUIC-only; `AlknetClient` deferred (OQ-55)
081	channels Sub-Crate Decomposition	`channels-core` (pure multiplexer) / `channels-call` (call coupling) / hub / worker
070	BidiStreamSource Trait	The `Connection` extension point `ChannelBidiStreamSource` implements
065	`Connection::from_stream`	The transport-agnostic `Connection` the channels layer rides on
052	alknet-tty Wire Format	The 5-byte format the 9-byte format generalizes (amended by ADR-077 — scoped to direct TTY)
049	StreamingHandler for Subscriptions	The machinery `channel/resources/subscribe` uses
032	Forwarded-For Identity	The auth chain for hub-relayed channel opens
003	Crate Decomposition	alknet-channels depends on alknet-core only; no handler-depends-on-handler

Relevant Open Questions

OQ	Title	Status	Relevance
OQ-55	AlknetClient / Client Establishment Extraction	deferred(scope)	`ChannelClient` is decided (ADR-080); `AlknetClient` core extraction stays deferred — blocked on a second transport's client, not a second client
OQ-56	Full channel-level flow-control windowing	deferred(scope)	Bounded-buffer is decided (ADR-076); full windowing is an extension blocked on "a real deployment observes HOL blocking on a saturated channel where bounded buffer is insufficient"
OQ-57	Two-pump helper extraction to alknet-core	deferred(scope)	The shutdown-on-completion contract is decided (ADR-078); the helper extraction is blocked on a second two-pump handler existing (shape convergence)

Key Design Principles

Streams are streams. A TTY session, an SSH channel, a forwarded TCP connection, a QUIC bidi stream — they're all AsyncRead + AsyncWrite handles. The differences are only in how they're opened (negotiation via channel/open on channel 0) and what multiplexing layer carries them (the 9-byte chunk format). Once normalized, every channel is an ALPN routed through the same HandlerRegistry. See overview.md and ADR-071.
Channel 0 is alknet/call pre-negotiated, not a special control plane. The call protocol runs on channel 0 exactly as on a top-level alknet/call connection. Channel lifecycle operations (channel/open, channel/close, channel/control, channel/resources/subscribe) are call operations on channel 0's OperationRegistry, gated by the existing AccessControl::check. No new auth machinery, no new framing. See ADR-072, ADR-073.
The channels layer is a re-framing proxy, not a protocol engine. It converts between "one transport stream carrying N channels" (the wire) and "N independent AsyncRead + AsyncWrite handles" (what handlers see). It does no ALPN-specific parsing, no auth, no transport coupling. This makes it WASM-compatible and transport-agnostic by construction. See channels-adapter.md and ADR-075.
channel/resources/subscribe is a Subscription, not a polled Query. The call protocol has StreamingHandler / invoke_streaming (ADR-049, implemented and tested). The first consumer (the hub aggregating worker resources) needs live updates. Polling would be built and immediately reworked. See ADR-073.
Bidirectional open. Either side can open a channel to the other, just like the call protocol's operation overlay. The direction field on channel/open pins who is the ALPN-server vs ALPN-client. See ADR-073 §Direction semantics.
Wire-level invariants are contracts, not implementation details. The POC surfaced five invariants (REQ-CH-01..04, plus REQ-CH-06 for close ordering) that hang channels silently if underspecified: shutdown emits a zero-length sentinel; transport close drops all senders; the mux supports dynamic registration; unknown channel_id is lenient-dropped; bounded-buffer backpressure doesn't deadlock; data chunks flush before channel/close. See channels-wire.md and channels-adapter.md.
The hub translates, not transparently forwards. The hub terminates channel 0 on both legs, runs AccessControl::check, and re-issues channel/open on the spoke leg with forwarded_for (ADR-032). Data channels are byte-forwarded with channel_id rewrite. This preserves the auth model. See ADR-079.

References

docs/research/alknet-channels/phase-0-findings.md — Phase 0 research (vision, hub motivation, wire format, negotiation, internals, DPs, OQs)
docs/research/alknet-channels/poc-summary.md — the de-risk POC (28 tests, three validated targets, REQ-CH-01..06 wire-level invariants surfaced; REQ-CH-07 is a cosmetic clippy item, not a wire invariant)
docs/research/alknet-channels/poc-plan.md — the POC plan
/workspace/alknet-channels-poc/ — the POC codebase
docs/research/alknet-tty/phase-0-findings.md — the TTY crate's chunk format (the seed of the channels generalization)
docs/research/alknet-ssh/phase-0-findings.md — SSH's channel multiplexer (the prior art for N-channel multiplexing)
docs/architecture/crates/hub/README.md — the hub crate (the primary consumer; the relay implementation's home)

9.4 KiB Raw Blame History