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).
251 lines
13 KiB
Markdown
251 lines
13 KiB
Markdown
# ADR-081: alknet-channels Sub-Crate Decomposition
|
|
|
|
## Status
|
|
|
|
Accepted (amended 2026-07-18 by ADR-093 — the 9-byte wire format is now
|
|
8-byte; `ChannelSubStreams` / `SubStreamHandle` removed; the channels
|
|
layer has no `stream_type` concept — see "Amendment (ADR-093, 2026-07-18)"
|
|
below)
|
|
|
|
## Amendment (ADR-093, 2026-07-18)
|
|
|
|
The wire format in `channels-core` is now **8-byte** (not 9-byte); the
|
|
`ChannelSubStreams` / `SubStreamHandle` typed destructure accessor is
|
|
**removed** (the channels layer has no `stream_type` concept —
|
|
`accept_bi` yields a `BiStream`, and the handler owns its sub-stream
|
|
multiplexing). The channel 0 pre-negotiation in `channels-call` no
|
|
longer constructs "reassembly buffers with `stream_types` [0, 1]" — it
|
|
constructs one reassembly buffer for `channel_id = 0`, yielding a
|
|
`BiStream` to the `CallAdapter`. The "What moves where" table's "9-byte
|
|
wire format" row is now "8-byte wire format"; the `ChannelSubStreams`
|
|
row is removed. The two-crate split (`channels-core` /
|
|
`channels-call`), the dep graph, and the "hub and worker are consumers"
|
|
principle are unchanged. See ADR-093 for the resolution rationale.
|
|
|
|
## Context
|
|
|
|
The initial channels spec (ADR-071-080) framed `alknet-channels` as a
|
|
single crate depending on both `alknet-core` and `alknet-call`. The
|
|
dependency on `alknet-call` arises because channel lifecycle operations
|
|
(`channel/open`, `channel/close`, `channel/control`,
|
|
`channel/resources/subscribe`) register on the call protocol's
|
|
`OperationRegistry`, and channel 0 is pre-negotiated as `alknet/call`
|
|
(ADR-072).
|
|
|
|
This creates two issues:
|
|
|
|
1. **The dependency graph conflates the pure multiplexer with the call-
|
|
protocol coupling.** The wire format, demux/mux, and
|
|
`ChannelBidiStreamSource` are ALPN-blind and call-protocol-blind — they
|
|
depend on `alknet-core` only. The channel 0 pre-negotiation and lifecycle
|
|
op registrations are the call-protocol coupling. Baking both into one
|
|
crate means any consumer that wants the multiplexer also pulls in the
|
|
call-protocol coupling, even if they don't need channel 0 to be
|
|
`alknet/call`.
|
|
|
|
2. **The "no special-casing for downstream crates" principle is
|
|
violated.** The user's constraint: "we don't want to be doing anything
|
|
special for downstream crates unless it's needed/useful to the point of
|
|
they all kind of benefit." The call-protocol coupling is a channels-crate
|
|
concern (channels needs call for orchestration), not a downstream-crate
|
|
concern. Separating them makes the dependency graph honest: the pure
|
|
multiplexer has no opinion about channel 0; the call-protocol coupling
|
|
is isolated where it belongs.
|
|
|
|
The substrate simplification (ADR-071 revised) strengthened this: the wire
|
|
format is the same across all substrates, and the `ChannelsAdapter` is
|
|
substrate-agnostic. The pure multiplexer (`channels-core`) is cleanly
|
|
separable from the call-protocol orchestration (`channels-call`).
|
|
|
|
## Decision
|
|
|
|
### Two crates, not four
|
|
|
|
```
|
|
alknet-channels-core — the pure multiplexer (wire format, demux/mux,
|
|
│ ChannelBidiStreamSource, ChannelManager). Depends
|
|
│ on alknet-core only. ALPN-blind, call-protocol-blind,
|
|
│ transport-blind.
|
|
└── alknet-channels-call — channel 0 pre-negotiation + lifecycle op
|
|
registrations on the call protocol's
|
|
OperationRegistry. Depends on channels-core +
|
|
alknet-call.
|
|
```
|
|
|
|
There are no `channels-hub` or `channels-worker` sub-crates. The hub and
|
|
worker are **consumers** of channels, not sub-crates of it. The existing
|
|
`alknet-hub` crate (`docs/architecture/crates/hub/README.md`) IS the hub —
|
|
it depends on `channels-call` and uses the channels protocol as its
|
|
substrate. A worker is just a worker — it depends on `channels-call` and
|
|
uses `ChannelClient` (ADR-080) to dial. The hub relay logic (ADR-079) lives
|
|
in `alknet-hub`, not in a channels sub-crate.
|
|
|
|
### `alknet-channels-core`
|
|
|
|
The pure multiplexer. Contains:
|
|
|
|
- The 9-byte chunk wire format (`parse_header` / `write_header` — ADR-071)
|
|
- The demux/mux (`Demux`, `MuxHandle`/`MuxRunner` — ADR-075)
|
|
- `ChannelBidiStreamSource` (implements `BidiStreamSource` — ADR-074)
|
|
- `ChannelSubStreams` / `SubStreamHandle` (the typed destructure accessor)
|
|
- `ChannelManager` (the shared state — channel_id → ChannelState, but
|
|
**without** the `call_ops: Arc<OperationRegistry>` field; the manager is
|
|
ALPN-blind and call-protocol-blind)
|
|
- `ChannelsAdapter` (the `ProtocolHandler` on `alknet/channels` — the
|
|
read/demux loop, substrate-agnostic per ADR-071 revised)
|
|
|
|
Depends on `alknet-core` only. No `alknet-call` dependency. No opinion about
|
|
what channel 0 carries — that's the consumer's concern.
|
|
|
|
The `ChannelsAdapter::handle` in `channels-core` does NOT preinstall channel
|
|
0 as `alknet/call`. It runs the demux loop and routes chunks by
|
|
`channel_id`. Channel 0 is just another channel; what ALPN it carries is
|
|
determined by the consumer (the `channels-call` crate pre-negotiates it as
|
|
`alknet/call`; a hypothetical other consumer could pre-negotiate it
|
|
differently).
|
|
|
|
### `alknet-channels-call`
|
|
|
|
The call-protocol coupling. Contains:
|
|
|
|
- Channel 0 pre-negotiation as `alknet/call` (ADR-072) — the
|
|
`preinstall_channel_0` logic that constructs channel 0's reassembly
|
|
buffers with stream_types [0, 1] and hands the `Connection` to the
|
|
`CallAdapter`.
|
|
- The four lifecycle operations (ADR-073): `channel/open`,
|
|
`channel/close`, `channel/control`, `channel/resources/subscribe` —
|
|
registered on the call protocol's `OperationRegistry` at assembly time.
|
|
- `ChannelOperations` (the registration helper that closes over a
|
|
`ChannelManager` clone).
|
|
- `ChannelClient` (ADR-080) — the client-side type that dials a transport,
|
|
establishes the channels connection, and exposes `open_channel(alpn,
|
|
params) -> Channel`. This is the worker/client entry point; it lives here
|
|
because it needs channel 0 pre-negotiation (which is in `channels-call`).
|
|
|
|
Depends on `channels-core` + `alknet-call`. This is where the
|
|
call-protocol coupling lives, isolated from the pure multiplexer.
|
|
|
|
### Hub and worker are consumers, not sub-crates
|
|
|
|
The hub and worker are architectural roles, not channels sub-crates:
|
|
|
|
- **The hub** is the existing `alknet-hub` crate. It depends on
|
|
`channels-call` and uses the channels protocol as its substrate. The hub
|
|
relay logic (ADR-079 — translate `channel/open` on channel 0,
|
|
byte-forward data channels with `channel_id` rewrite) lives in
|
|
`alknet-hub`, alongside its existing peer lifecycle, aggregated env, and
|
|
service discovery responsibilities. There is no `channels-hub` sub-crate;
|
|
`alknet-hub` IS the channels hub.
|
|
|
|
- **A worker** is any crate that uses `ChannelClient` (ADR-080, in
|
|
`channels-call`) to dial a hub. There is no `channels-worker` sub-crate;
|
|
a worker depends on `channels-call` and uses `ChannelClient` directly.
|
|
The worker may be a CLI binary, a docker-side connector, an SSH-side
|
|
connector, or any other role that dials into a hub's channels connection.
|
|
|
|
This means the channels crate provides the substrate (`channels-core` +
|
|
`channels-call`); the hub and worker crates are consumers that build on it.
|
|
The dependency direction is: `alknet-hub` → `channels-call` →
|
|
`channels-core` → `alknet-core`; a worker → `channels-call` →
|
|
`channels-core` → `alknet-core`. The channels crate has no dependency on
|
|
`alknet-hub` or any worker crate.
|
|
|
|
### What moves where
|
|
|
|
| Component | Original (ADR-071-080) | Now |
|
|
|-----------|------------------------|-----|
|
|
| 9-byte wire format | `alknet-channels` | `channels-core` |
|
|
| Demux/Mux | `alknet-channels` | `channels-core` |
|
|
| `ChannelBidiStreamSource` | `alknet-channels` | `channels-core` |
|
|
| `ChannelSubStreams` | `alknet-channels` | `channels-core` |
|
|
| `ChannelManager` (without `call_ops`) | `alknet-channels` | `channels-core` |
|
|
| `ChannelsAdapter` (demux loop only) | `alknet-channels` | `channels-core` |
|
|
| Channel 0 pre-negotiation | `alknet-channels` (ADR-072) | `channels-call` |
|
|
| `channel/open`/`close`/`control`/`resources/subscribe` ops | `alknet-channels` (ADR-073) | `channels-call` |
|
|
| `ChannelOperations` registration helper | `alknet-channels` | `channels-call` |
|
|
| `ChannelClient` (ADR-080) | `alknet-channels` | `channels-call` |
|
|
| Hub relay (ADR-079) | `alknet-channels` (spec) | `alknet-hub` (the existing hub crate, consuming `channels-call`) |
|
|
|
|
### Relationship to `alknet-hub`
|
|
|
|
The existing `alknet-hub` crate (`docs/architecture/crates/hub/README.md`)
|
|
is the hub pattern: peer lifecycle, aggregated env, service discovery. With
|
|
channels as the substrate, `alknet-hub` gains a dependency on
|
|
`channels-call` and incorporates the relay logic (ADR-079). The hub spec
|
|
(`crates/hub/README.md`) will be updated to reflect that the hub uses
|
|
channels as its transport substrate — one channels connection per leg
|
|
(browser↔hub, hub↔spoke), with the relay translating `channel/open` and
|
|
byte-forwarding data channels. The hub's existing responsibilities (peer
|
|
lifecycle, aggregated env, service discovery, worker supervision) are
|
|
unchanged; channels is the substrate they run on.
|
|
|
|
This makes "channels hub" and "hub" the same thing — the hub IS built on
|
|
channels. There is no separate channels-hub concept.
|
|
|
|
## Consequences
|
|
|
|
**Positive:**
|
|
- The dependency graph is honest: `channels-core` is the pure multiplexer
|
|
with no call dependency; the call-protocol coupling is isolated in
|
|
`channels-call`. A consumer that wants the multiplexer without the
|
|
call-protocol orchestration can depend on `channels-core` only.
|
|
- The "no special-casing for downstream crates" principle is preserved:
|
|
`channels-core` doesn't know about `alknet-call`, `alknet-tty`, or any
|
|
handler crate. The call-protocol coupling is a channels-crate concern,
|
|
not a downstream-crate concern.
|
|
- Hub and worker are consumers, not sub-crates. The existing `alknet-hub`
|
|
crate IS the channels hub — it depends on `channels-call` and uses
|
|
channels as its substrate. A worker depends on `channels-call` and uses
|
|
`ChannelClient`. The channels crate has no dependency on `alknet-hub` or
|
|
any worker crate. This is the cleanest dependency direction: channels
|
|
provides the substrate; hub and worker consume it.
|
|
- The WASM and cross-platform story gets easier: `channels-core` is
|
|
WASM-compatible by construction (pure byte manipulation, no platform
|
|
deps); `channels-call` inherits the call protocol's WASM constraints; the
|
|
hub and worker crates are platform-specific as needed.
|
|
|
|
**Negative:**
|
|
- Two channels crates instead of one. The assembly layer must depend on
|
|
`channels-core` + `channels-call` instead of one `alknet-channels`. This
|
|
is the cost of the clean separation; the assembly layer already wires
|
|
multiple crates, so this is consistent with the existing pattern.
|
|
- The `ChannelsAdapter` in `channels-core` doesn't preinstall channel 0 —
|
|
the consumer does. This means `channels-core`'s `ChannelsAdapter::handle`
|
|
exposes a hook (callback or trait method) for the consumer to install
|
|
channel 0. `channels-call` provides the `preinstall_channel_0`
|
|
implementation; a different consumer could provide a different one. This
|
|
is a slightly more complex adapter shape than "channel 0 is always call,"
|
|
but it's the cost of the clean separation.
|
|
|
|
## Door type
|
|
|
|
**One-way (crate structure).** The two-crate split (`channels-core` /
|
|
`channels-call`) is one-way — once consumers depend on `channels-core`
|
|
without `channels-call`, re-merging them is a breaking change. The hub and
|
|
worker being consumers (not sub-crates) is also one-way — it establishes
|
|
the dependency direction (hub/worker → channels, not channels → hub/worker).
|
|
|
|
## References
|
|
|
|
- ADR-003: crate decomposition (no-handler-depends-on-another-handler —
|
|
preserved; the channels sub-crates depend on core/call, not on handlers)
|
|
- ADR-071: channels wire format (revised — substrate simplification; the
|
|
wire format is in `channels-core`; **amended by ADR-093 — 8-byte header,
|
|
no `stream_type`**)
|
|
- ADR-093: channels pure channel multiplexing (amends this ADR — 8-byte
|
|
wire format; `ChannelSubStreams` / `SubStreamHandle` removed; the
|
|
channels layer has no `stream_type` concept)
|
|
- ADR-072: channel 0 pre-negotiated (moves to `channels-call`)
|
|
- ADR-073: channel lifecycle operations (move to `channels-call`)
|
|
- ADR-074: ChannelBidiStreamSource (in `channels-core`; **amended by
|
|
ADR-093 — `into_sub_streams` removed, `accept_bi` yields `BiStream`**)
|
|
- ADR-075: ChannelsAdapter and ChannelManager (split: core demux in
|
|
`channels-core`, call coupling in `channels-call`)
|
|
- ADR-079: hub relay (in `alknet-hub` — the hub crate consumes
|
|
`channels-call`; there is no `channels-hub` sub-crate, per this ADR's
|
|
Decision §"No hub/worker sub-crates")
|
|
- ADR-080: ChannelClient (in `channels-call`; there is no
|
|
`channels-worker` sub-crate — a worker is any crate that uses
|
|
`ChannelClient` to dial)
|
|
- `docs/architecture/crates/hub/README.md` — the existing hub crate (the
|
|
relay's consumer) |