alkdev/alknet

0 Fork 0

Files

T

deepseek-v4-pro 90a8fa7328 findings: reframe — channels is call with a binary data plane, not 'call + data channels'; retire 'call++' for 'binary-stream call apps'; two modes: default call (JSON) and channels (binary framing)

2026-07-19 17:09:16 +00:00

51 KiB

Raw Blame History

status, last_updated

status	last_updated
draft	2026-07-19

call-channels-unification — Findings: openable ALPNs are operations

Status: Draft findings, iterating. Per the research-then-sync pattern (see docs/research/stream-unification/findings.md for the precedent), this doc iterates in docs/research/; we fix inter-document drift here, then sync to docs/architecture/ and the ADRs only after it settles.

Scope: The control plane for channels-served ALPNs — how channel/open is authorized, how per-ALPN ACLs are expressed, how the quota lifecycle is accounted, and how the ALPN categorization from ADR-086 reframes under "an openable ALPN is an operation." This is above the channels wire format (ADR-071/093, settled) and below the ALPN handler's data-plane protocol (each handler's own wire format). The transport leaf (BiStream as the handler-facing duplex type) is settled in ADR-092 and is not re-litigated here. The channels wire format (8-byte header, no stream_type) is settled in ADR-093 and is not re-litigated here.

Date: 2026-07-19

Origin: An outside review surfaced three high-value gaps in the channels control plane after ADR-094 (per-identity channel cap) landed. Working through the first gap — channel/open ACL granularity — surfaced a larger unification: channels is call with a binary data plane — the same protocol, two chunk formats (JSON vs binary). The ALPN crates served under channels are call apps in the same shape alknet-docker is a call app. This doc records both the gaps and the unification.

TL;DR

The previous framing — "channel lifecycle goes through one generic channel/open operation, and AccessControl::check on that op is the ACL" — was a symptom. The actual question is the separation of concerns between the call protocol (which already has per-op ACL, identity, composition, ownership, and subscriptions) and the channels layer (which provides binary framing for ops whose response isn't JSON), and the resolution is an openable ALPN is an operation: each openable ALPN registers its own open op (channels/tty/open, channels/tunnel/open, etc.) on the call OperationRegistry, with its own access_control, input_schema, resource_id_path, and a channel_open marker that tells the call adapter "this op's response is a binary stream, not a JSON response."

This dissolves the channel/open ACL granularity gap (each ALPN has its own ACL — checked by the existing OperationRegistry::invoke before the handler runs, like every other op), makes the resource_id_path from ADR-050 work for channel-open ops (the path is per-op, not per-ALPN-branch-of-a-single-op), and lets the two direction values (initiator-to-responder vs responder-to-initiator) become two verbs (channels/<alpn>/open and channels/<alpn>/expose) with separate ACLs. Both are specced; the call protocol's subscription model is the matching mechanism between them — a worker exposing a resource and a consumer opening it are matched by (op_name, params_hash) on the hub, which proxies the data plane between them.

Channels is call with a binary data plane. The call protocol already has the subscription model, ACL, identity, composition, and ownership. Channels adds one thing: binary framing (8-byte headers, channel multiplexing) for ops whose response isn't JSON. A call connection has two modes:

Default call (alknet/call): all ops return JSON on a single stream. The subscription model works — events are JSON chunks.
Channels (alknet/channels): call on channel 0 (JSON control plane), binary streams on channels 1..N (data plane). The subscription model works identically — the only difference is the chunk format on the data-plane channels.

The ALPN crates served under channels (tty, tunnel, socks5, fs, sftp) stop being "just ALPNs" and become call apps with binary-stream ops — the same shape as alknet-docker (a call app with JSON ops), but where some ops carry the channel_open marker and produce a binary stream instead of a JSON response. The hub/worker composition story unifies: a hub composes call apps, full stop; some ops return JSON, some ops carry the channel_open marker and produce a binary stream.

Three further gaps fall out of this framing:

Quota lifecycle leaks (ADR-094 amendment). The per-identity cap's on_close is called from the channel/close handler with op_ctx.identity (the closer, not the opener) and is not called at all on transport drop (REQ-CH-02 clears the channel map without touching the policy). A peer whose connection dies at cap is permanently at cap — a self-DoS. Fix: decouple the decrement from channel/close and tie it to channel-state deallocation on the side that counted, via a per-connection opener ledger in channels-call (keeping channels-core auth-blind) decremented on every teardown path.
Connection-count DoS is an unowned layer (new OQ against alknet-endpoint). The per-identity cap bounds channels, but each transport connection still costs a channel-0 buffer, a CallAdapter, and demux tasks before any channel/open — and ADR-094 explicitly says connections are unbounded. This is not a channels-ACL problem; it belongs at the endpoint/accept layer (per-identity connection cap, analogous shape to ChannelLifecyclePolicy). No doc owns it today. Naming it as a separate layer stops it from re-tangling every channels-ACL conversation.
ALPN category reframe (ADR-086 amendment). ADR-086 §4 split the foundational handlers into "channels data-channel ALPNs" and "SSH (endpoint ALPN wrapping channels)." Under the unified model, the first category is reframed: they're not "ALPNs gated by channels" — they're call apps with binary-stream ops. They inherit call's auth/composition/identity by construction (they are call apps); the binary-stream part is the channel_open marker on the op spec. The "flat ALPN list" re-implementation problem dissolves because they're call apps, not a separate category that each re-implements auth. SSH stays distinct (endpoint ALPN wrapping channels).

No production/backward-compat constraint. The develop branch is a rewrite of main (pre-alpha). The decision is purely "what's cleanest," not "what's least disruptive." ADR-073's four op names are declared one-way doors, but there's no code and no deployments; ADR-093/094 just demonstrated that amendment is the normal mode here. This is the cheapest moment to amend.

Terminology (three axes, not one)

The doc uses three independent role axes. They overlap in common cases but are not the same thing — a hub can be a responder on one leg and an initiator on another, a producer on one channel and a consumer on another.

Axis	Roles	What it means
Deployment	hub, worker (spoke), browser	Where the code runs. Hub relays; worker/spoke hosts resources; browser is the end-user client.
Call protocol	initiator, responder	Who sends the call op. The initiator calls `channels/tty/open`; the responder receives it.
Data plane	producer, consumer	Who runs the `ProtocolHandler` (produces the data stream) vs who receives it. The producer is the side that spawns the handler on the `BiStream`.

The old "ALPN-server"/"ALPN-client" vocabulary is retired. Call++ apps are not TLS-layer ALPNs; "producer"/"consumer" describes the data-plane role without implying a TLS ALPN. The ChannelDirection enum uses Open (initiator is consumer, responder is producer — the common case) and Expose (initiator is producer, responder is consumer).

Assembly layer is the CLI binary that wires crates together at startup (ADR-019, ADR-024). It constructs backends, injects capabilities, registers ops, and builds the ALPN lists. It is the trust boundary — handlers never hold vault references or construct their own transports. In this doc, "assembly time" means "at startup, in the CLI binary, before any connections exist."

Layering (to keep the questions separate)

The outsider's layer map, plus the ALPN-category layer this doc adds:

Layer	Question it answers	Owner	Status
Endpoint accept	May this identity hold N connections?	`alknet-endpoint`	Unowned (Gap 3). ADR-094 explicitly says connections are unbounded. New OQ against `alknet-endpoint`.
`channels-core`	Byte routing; per-connection memory bounds	ADR-075/076	Decided, coherent. Auth-blind by design (ADR-075).
`channels-call`, op-level	May you call `channel/open` at all?	`AccessControl::check`	Decided. (Under the unified model: per-ALPN ops, each with its own ACL — Gap 1 resolved.)
`channels-call`, quota	How many slots may you hold?	ADR-094	Decided, lifecycle buggy (Gap 2). Trait shape survives; the change is where `on_close` is called from and where the opener identity comes from.
`channels-call`, per-ALPN/direction	May you open this ALPN, this direction?	Per-ALPN op's `access_control` (this doc)	Resolved. Each openable ALPN is its own op; the op's `access_control` is the per-ALPN/direction ACL.
ALPN handler (data plane)	May you touch container abc123?	ADR-050 ownership, handler-internal	Decided (call/docker land). Unchanged under the unified model.

The tangle was that layers 5 and 6 got blurred ("ACL is checked on channel/open" is true but only for layer 3, because the single generic op couldn't see alpn/direction/params), and layer 1 got silently assumed away.

The structural tangle (the actual gaps)

Gap 1 — `channel/open` ACL granularity is underspecified

The call crate's ACL is per-operation: OperationSpec.access_control, checked before the handler runs by OperationRegistry::invoke. But channel/open is one operation whose input decides what's really being requested (alpn, params, direction). One op-level AccessControl cannot express "peer X may open alknet/tty but not alknet/tunnel."

The specs gesture at per-ALPN ACLs — channel/resources/subscribe returns access: { required_scopes: ["tty:open"] } per ALPN, "advisory... the real check happens on channel/open" (channel-operations.md:150) — but no mechanism is specified for that real check. HandlerRegistry carries no AccessControl. Nobody registers alpn → required_scopes anywhere.

Three candidate shapes were considered (the outsider's analysis):

(a) A per-ALPN ACL map held by ChannelOperations, checked inside the channel/open handler after the op-level check. Parallel to how the quota policy slots in.

(b) A ChannelOpenSpec registry (alpn → AccessControl + params schema + resource_id_path + allowed directions) consulted inside the handler after the op-level check.

(c) is the worst: allocation and handler spawn happen before authorization, refusal semantics diverge per ALPN, and every handler crate reimplements scope checking.

(b) looks like minimal churn, but notice what the registry actually is: a parallel structure holding ACLs, input schemas, resource pointers, and discovery data, with its own check invocation — a shadow OperationRegistry. The repo has been here before: ADR-028 was superseded by ADR-029 exactly because "a parallel authorization system duplicated the existing AccessControl," and ADR-029's whole thesis is that peer authorization is just AccessControl::check on the existing path. (b) re-commits that structural miss one layer down.

Gap 2 — The quota's accounting lifecycle leaks

ADR-094 increments in the channel/open handler and decrements in the channel/close handler via policy.on_close(&op_ctx.identity). Two problems:

Responder-initiated close decrements the wrong ledger. If A opens (counted against A on B's policy) and B later sends channel/close (e.g., TTY exit happens on B's side — REQ-CH-06 makes B the closer), the close handler runs on A with op_ctx.identity = B. B's count for A is never decremented; A's policy decrements a channel it never counted.
Transport drop leaks the quota. REQ-CH-02 clears the channel map on transport EOF, but nothing calls on_close. Since the policy is shared across connections (that's the whole point), a peer whose connection dies at 256 open channels is permanently at cap — a self-DoS.

The conceptual fix: decouple the decrement from the channel/close operation and tie it to channel-state deallocation on the side that counted. channels-call keeps its own channel_id → opener PeerId ledger per connection (keeping channels-core auth-blind) and decrements on any teardown path — close received, close sent locally, handler exit, or connection drop. The ledger entry must be removed atomically with its decrement: handler-exit, close-received, close-sent-locally, and connection-drop can race, and a double-decrement under-counts and weakens the cap.

Gap 3 — Connection-count DoS is an unowned layer

The per-identity cap bounds channels, but each transport connection still costs a channel-0 buffer, a CallAdapter, and demux tasks before any channel/open — and ADR-094 explicitly says connections are unbounded. This is not a channels-ACL problem and shouldn't be solved there; it belongs at the endpoint/accept layer (per-identity connection cap, analogous shape to ChannelLifecyclePolicy). Right now no doc owns it. Naming it as a separate layer stops it from re-tangling every channels-ACL conversation.

Gap 4 — ALPN category blur (the user's insight)

ADR-086 §4 split the foundational handlers into "channels data-channel ALPNs" (gated by channels, opened via channel/open, inherit ACL + bidirectionality) and "SSH" (endpoint ALPN wrapping channels). The "channels data-channel ALPNs" framing implies they're a separate kind of thing that channels happens to gate — and each would re-implement auth in a flat ALPN list. Under the unified model, they're not a separate category: they're call apps with binary-stream ops. They inherit call's auth by construction (they are call apps). The gating is a consequence, not the definition.

This also touches the HTTP/ WebSocket path: ADR-048 says "WebSocket carries the native call-protocol session." Under the unified model, a browser that wants to open a TTY channel needs to call channels/tty/open, which lives on channel 0 inside a channels connection. So WebSocket may carry either alknet/call (bare, for call-only clients) or alknet/channels (8-byte chunk framing, with call on channel 0 inside). Channels framing is required for binary-stream clients; a call-only client (e.g. a dashboard doing docker JSON ops) can use bare alknet/call over WebSocket. OQ-65 ("WebSocket carrying channels, not just call?") is resolved: WebSocket may carry either; channels required for binary streams.

The resolution: openable ALPNs are operations

The core observation: ADR-073's claim is "no new auth machinery — channel lifecycle goes through the existing AccessControl::check." But the single generic channel/open operation is precisely what breaks that promise: it hides the authorization-relevant facts (alpn, direction, params) inside one op's input, where the call ACL machinery can't see them. Consequences:

Per-ALPN scopes (tty:open vs tunnel:open) have no enforcement home.
ADR-050's resource_id_path (ownership via JSON pointer into input) is declared per OperationSpec — a single channel/open can't use it because the pointer differs per ALPN (/params/container for tty-docker, /params/target for tunnel).
The two direction values are wildly different grants ("may you consume my TTY" vs "may you register a service I will consume as a client") squeezed under one ACL.

The fix that requires new machinery is keeping the generic op; the fix that requires none is the opposite of what's specced. An openable ALPN is an operation.

The marker on `OperationSpec`

OperationSpec gains a channel_open field:

pub struct OperationSpec {
    // ... existing fields ...
    pub access_control: AccessControl,
    pub resource_id_path: Option<String>,
    /// Marker consumed by layers that manage binary streams. When set,
    /// the op produces a binary stream alongside (or instead of) the JSON
    /// response. The marker is registry metadata, not auth machinery —
    /// it's how layers like channels-call know an op is a channel-open
    /// op, parallel to how `resource_id_path` is how ADR-050 knows where
    /// to find the resource id. The op's `access_control` is the ACL
    /// (unchanged); the marker is the dispatch hint.
    pub channel_open: Option<ChannelOpenSpec>,
}

pub struct ChannelOpenSpec {
    pub alpn: &'static str,         // e.g., "alknet/tty"
    pub direction: ChannelDirection, // Open or Expose
}

pub enum ChannelDirection {
    /// Initiator wants to consume a resource the responder will produce.
    /// Initiator is the consumer; responder is the producer (runs the
    /// data-plane handler). Common case: "open me a TTY on your docker
    /// container."
    Open,
    /// Initiator is the producer (runs the data-plane handler);
    /// responder is the consumer. The worker-expose case: "I'm exposing
    /// a TTY for you to consume."
    Expose,
}

The marker is registry metadata, not auth machinery — it doesn't violate ADR-073's "no new auth machinery" promise. The op's access_control is the ACL (unchanged, checked by OperationRegistry::invoke before the handler runs); the marker is the dispatch hint that tells channels-call to wrap the handler with the channel machinery.

The marker is wire-visible. channel_open must survive discovery serialization — it is part of the services/schema payload, not just the in-process struct. Otherwise the hub (and any from_call importer) can't see it. The services/schema handler already serializes the full OperationSpec to JSON; channel_open is included in that serialization.

from_call relay wrapper. A FromCall-imported marked op cannot be the standard forwarding stub. The hub's version must do forward + allocate local-leg channel + record id mapping + start the byte-forward pumps. When from_call imports a marked op on a channels-backed connection, it wraps it with relay machinery instead of the plain forwarding stub. ADR-022's provenance table (leaves are forwarding stubs, no composition authority) gets a note for this case: a FromCall-imported marked op is a leaf for composition purposes but carries relay machinery that allocates channels and spawns byte-forward tasks. This is the load-bearing piece of the relay under the unified model.

Marked ops invoked outside a channels session. channels/tty/open is registered on the call registry — which means it's also visible/invocable on a bare top-level alknet/call connection, where there is no ChannelManager and no data plane. The wrapper resolves OperationEnv::channel_manager() at invocation time; if it returns None, the wrapper returns channel:no_channels_session. Relatedly, the HTTP-side adapters (to_openapi, to_mcp) must exclude marked ops — "produces a binary stream" is not expressible over a request/response export.

Two verbs: `open` and `expose`

direction becomes two verbs, not a field:

channels/<alpn>/open — the initiator wants to consume a resource the responder will produce. Responder is the producer. The common case: "open me a TTY on your docker container." Consumer → hub → producer: both legs are channels/tty/open. Specced.
channels/<alpn>/expose — the initiator wants to produce a resource for the responder to consume. Initiator is the producer. The worker-expose case: worker → hub, worker is making a resource available for the hub to proxy to consumers. Specced.

Separate verbs → separate ACLs. A peer that may expose a TTY is not the same grant as a peer that may open one. The verb split also enables the hub-as-proxy pattern: a worker exposes a resource to the hub, the hub owns it, and consumers open it from the hub.

Matching: the call protocol's subscription model. The hub matches expose and open by (op_name, params_hash). When a worker calls channels/tty/expose, the hub records the exposed resource keyed by the hash of the op name + params. When a consumer calls channels/tty/open with matching params, the hub finds the exposed resource and proxies the data plane between them. This is a pubsub model where the topic is (op_name, params_hash) — the call protocol's existing subscription mechanism (OperationType::Subscription) is the natural fit for the expose side: the worker subscribes to consumer demand for that resource, and the hub delivers matching open requests as subscription events. Stream deduplication falls out naturally: if two consumers open the same resource, the hub fans out from one producer stream rather than opening duplicate channels to the worker.

The `ChannelCore` seam (wrapper shape — flag for POC)

The ALPN crate's open-op handler does ALPN-specific work (validate params, consult ownership, prepare the backend) and returns a "channel plan." channels-call wraps it: the wrapper allocates the channel_id, gets the BiStream from ChannelManager, records the opener in the ledger (Gap 2), consults ChannelLifecyclePolicy, spawns the ProtocolHandler on the BiStream with the plan's backend, returns {channel_id}.

The ALPN crate provides:

The OperationSpec (with channel_open marker, access_control, input_schema, resource_id_path).
The open handler (the ALPN-specific work — validate params, consult ownership, prepare the backend, return a plan).
The ProtocolHandler for the data plane (unchanged — used by both direct connections and channels-opened sessions; both paths converge at the BiStream).

channels-call provides:

The ChannelCore (channel-id allocation, ChannelManager integration, per-connection opener ledger, ChannelLifecyclePolicy consultation, teardown hooks).
A register_openable(spec, open_handler, channel_core) helper that wraps the ALPN's open handler with the channel machinery and registers the op on the call OperationRegistry.

This keeps the ALPN crate's handler focused on ALPN concerns (params, backend) and lets channels-call own the channel machinery. The alternative (invoke shape — the handler calls context.channel_core.open(...) itself) requires either OperationContext to carry a channel_core reference (inverting the call → channels-call dependency) or a generic extension mechanism on OperationContext (more complexity than the wrapper). The wrapper shape is preferred; the exact API shape (plan vs callback) is POC-worthy — flag this as the thing to pressure-test in a small POC (one ALPN crate, one open op, one channels connection, prove the wrapper allocates the channel and spawns the handler).

Per-connection state plumbing (POC-critical). register_openable registers ops "at assembly time" (Layer 0, curated, static per ADR-024). But the wrapper needs the per-connection ChannelManager — the op arrives on channel 0 of one specific channels connection, and the channel must be allocated on that connection's manager. A globally-registered handler closing over a static ChannelCore has no way to know which channels connection invoked it.

The resolution: the OperationEnv trait (already on OperationContext.env) gains an optional fn channel_manager(&self) -> Option<&ChannelManager>. The wrapper handler resolves it at invocation time — static registration, dynamic resolution. This also handles the "no channels session" case (Issue 3): if channel_manager() returns None, the wrapper returns channel:no_channels_session. The OperationEnv is already the integration point for per-connection state (ADR-024); adding a ChannelManager accessor is the natural extension.

This also affects recursive channels (inner connection needs its own binding): each channels connection's OperationEnv overlay carries its own ChannelManager reference, so nested connections resolve correctly.

The discovery split

Under the unified model, the discovery question splits cleanly:

"What may I open" (static, per-op): services/list (visibility- filtered + AccessControl::check(calling_peer_identity) server-side, per ADR-029 §6) + services/schema (per-op access_control). The existing server-side ACL-filtered discovery is preserved; the spec is the authority. channel:forbidden on the open op is the real check; the preview is "here's what the spec says, you can fail fast."
"What is currently there" (dynamic, ALPN-level): channel/resources/subscribe. Each ALPN crate that registers open ops also provides a resource enumerator (which containers are running, which TTY sessions are active). channel/resources/subscribe aggregates across all registered openable ALPNs. This is the data source the outsider's Gap 1(c) was missing — and it naturally lives in the ALPN crate, not in channels-call.

The access preview in resources/subscribe (ADR-073) becomes redundant — it's on the op spec, available via services/schema. We drop it from the resources/subscribe payload; the spec is the authority, and carrying a preview in a different shape invites staleness.

The exact aggregation shape (per-ALPN channels/<alpn>/resources/ subscribe ops merged by the generic channel/resources/subscribe, vs. callbacks registered with channels-call at registration time) is a POC-worthy detail. The architectural point is that the data source lives in the ALPN crate.

The ALPN three-category reframe (ADR-086 amendment)

ADR-086 §4 split the foundational handlers into two categories. Under the unified model, the first category is reframed. The three categories become:

Category	TLS-layer?	Identity at TLS?	How they're reached	Examples
Entry points	yes	no	TLS ALPN negotiation	`h2`, `http/1.1`, `alknet/register`
Endpoints	yes	yes	TLS ALPN negotiation	`alknet/channels`, `alknet/call`, `alknet/ssh`
Binary-stream call apps (was "channels data-channel ALPNs")	no	n/a (inside channels)	`channels/<alpn>/open` / `expose` op on channel 0	`alknet/tty`, `alknet/tunnel`, `alknet/socks5`, `alknet/fs`, `alknet/sftp`

The third category changes description. Previously "ALPNs gated by channels" (implying they're a separate kind of thing that channels happens to gate, and each re-implements auth in a flat ALPN list). Now "call apps with binary-stream ops" (they are call apps; they inherit call's auth/composition/identity by construction; the binary-stream part is the channel_open marker). The gating is a consequence, not the definition.

Direct registration remains possible. The category table says binary-stream call apps are not TLS-layer ALPNs, but the ProtocolHandler is still usable by both direct connections (HandlerRegistry → ProtocolHandler → BiStream) and channels-opened sessions. ADR-077's two-mode survives at the mechanism level; the canonical composition is through the call protocol. The table describes the canonical path, not a prohibition on direct use.

Naming. "Binary-stream call apps" is the working name. "Channels-served ALPNs" is descriptive. The final naming is a separate (cosmetic) decision tracked as an OQ; this doc uses "binary-stream call apps" as the working name.

What this means for the ALPN crates (the lineage)

The lineage makes the unification obvious in retrospect: call → docker → tty → channels. Docker was the first call-consuming app (wraps bollard in JSON ops — ADR-058). Working docker surfaced TTY (exec needs a terminal). Working TTY surfaced channels (terminal output isn't JSON). The loop closes: the ALPN crates that channels serves become channels-consuming apps in the same shape docker is a call-consuming app. The only difference is that some ops produce a binary stream instead of (or alongside) a JSON response.

The dependency split parallels channels-core / channels-call (ADR-081):

Data-plane core (the ProtocolHandler, wire format, backend trait) — depends on alknet-core only. No call dep. ADR-057's "tty does not depend on call" property survives here.
Control-plane layer (the open/expose ops, registration helper) — depends on the data-plane core + alknet-call + alknet-channels-call (for the channel machinery). ADR-057 is amended: the data plane stays call-free; the control plane is call by construction.

Whether that's a sub-crate split (alknet-tty-core + alknet-tty) or a feature flag (alknet-tty with a channels feature) is a packaging choice — two-way-door, not architecture. The architectural point is the dependency boundary.

SSH stays distinct

SSH is an endpoint ALPN that wraps channels. Under the unified model, the channels inside SSH have call on channel 0, and the call registry has the open ops. An SSH client opens an SSH channel; the SSH server translates that to channels/<alpn>/open on channel 0 internally (SSH server as translator, same shape as the hub relay — ADR-079). The SSH client doesn't know about call; it just opens SSH channels. SSH's category (endpoint ALPN wrapping channels) is unchanged. This is SSH-implementation detail and SSH is deferred, but the shape holds.

The hub-relay flow (walked end-to-end)

This is the flow the outsider flagged as "where ADR-073's single-op design was doing the most implicit work." Walking it under the unified model to verify it holds.

Consumer → hub → producer, "open me a TTY" (the common case)

Consumer (browser, another worker, another hub) sends channels/tty/open with {params: {backend: docker, cmd: ["bash"], container: "abc123"}} on its channel 0 (call op on the consumer→hub leg).
Hub's CallAdapter receives channels/tty/open. The OperationRegistry checks the op's access_control against the consumer's identity. The op's spec has channel_open: Some(ChannelOpenSpec { alpn: "alknet/tty", direction: Open }). Consumer is the initiator / consumer.
Hub's CallAdapter recognizes the channel_open marker. The hub does NOT run a local TtyAdapter — the hub never runs protocol-specific handlers (ADR-079). It forwards to the producer (spoke/worker) via from_call: hub re-issues channels/tty/open on the producer leg with forwarded_for = consumer.
Producer's CallAdapter receives channels/tty/open. OperationRegistry checks the op's access_control against the hub's identity (the direct caller per ADR-032). The producer's ownership store verifies the hub owns container:abc123 (per ADR-050). The producer consults ChannelLifecyclePolicy::check_open(hub) (Gap 2 — keyed by direct caller, opener recorded in the per-connection ledger).
Producer's ChannelCore allocates channel_id, spawns TtyAdapter on the channel's BiStream with the docker backend, records opener (hub) in the ledger, returns {channel_id}.
Hub receives the producer's {channel_id}, opens a matching channel on the consumer's side (hub is the responder for the consumer leg), records the channel_id mapping consumer_id ↔ producer_id, returns {channel_id: consumer_id} to the consumer.
Hub byte-forwards between consumer_id and producer_id with 4-byte channel_id rewrite (ADR-079 unchanged).

The hub ran zero protocol-specific auth and zero protocol-specific data-plane work. It ran channels/tty/open's access_control (call-protocol machinery) and forwarded. The relay contract from ADR-079 holds unchanged in shape; only the op name changed (from generic channel/open to per-ALPN channels/tty/open).

Worker → hub → consumer, "worker exposes a resource" (the proxy case)

The expose verb is specced alongside open. The call protocol's subscription model is the matching mechanism between them.

Concrete example. A worker runs on a remote instance (vastai, runpod, a docker container). It wraps an opencode server's OpenAPI spec via from_openapi (call ops, JSON) and registers channels/tty/open for terminal access. The worker connects to a hub and calls channels/tty/expose as a Subscription — "I have this resource; notify me when a consumer wants it." The hub records the exposed resource keyed by (op_name, params_hash). Later, a consumer (browser, another worker, another hub) calls channels/tty/open with matching params. The hub matches by hash, delivers the open request to the worker's subscription, the worker allocates the channel, and the hub proxies the data plane between them.

Step-by-step:

Worker calls channels/tty/expose (Subscription) with {params: {backend: docker, container: "abc123", cmd: ["bash"]}} on its channel 0. Worker is the initiator / producer.
Hub's CallAdapter receives channels/tty/expose. OperationRegistry checks the op's access_control against the worker's identity. The op's spec has channel_open: Some(ChannelOpenSpec { alpn: "alknet/tty", direction: Expose }).
Hub recognizes the channel_open marker. The hub records the exposed resource in its subscription table keyed by ("channels/tty/expose", hash(params)). The subscription is held open — no channel is allocated yet. The worker is waiting for a consumer.
Later, a consumer calls channels/tty/open (Query/Mutation) with matching params {container: "abc123", cmd: ["bash"]}.
Hub checks access_control against the consumer's identity. Hub computes params_hash and looks up the expose subscription table. Finds the worker's subscription.
Hub delivers the open request to the worker's subscription as an event. The worker's expose handler runs: validates params, consults ownership (ADR-050 — the hub owns the container), prepares the TtyBackend. Worker's ChannelCore allocates channel_id on the worker→hub leg, spawns TtyAdapter, records opener (hub) in the ledger, returns {channel_id}.
Hub receives the worker's {channel_id}, allocates a matching channel on the consumer→hub leg, records the mapping consumer_id ↔ worker_id, returns {channel_id: consumer_id} to the consumer.
Hub byte-forwards between consumer_id and worker_id with 4-byte channel_id rewrite (ADR-079 unchanged).

Stream deduplication (single-producer, N-consumer). If a second consumer calls channels/tty/open with the same params, the hub matches the same worker subscription. The hub does NOT deliver another event to the worker — it already has the producer channel. Instead, it allocates a second consumer leg and fans out from the existing producer channel: worker_channel → consumer_1_channel and worker_channel → consumer_2_channel. One producer stream, N consumer streams, hub fans out. The (op_name, params_hash) key naturally deduplicates — it's a pubsub topic, and the hub is the broker.

The hub-as-proxy pattern. The hub is a consumer of the worker's resource and a producer for downstream consumers. The relay is protocol-agnostic: swap channel IDs, tunnel reads/writes between BiStreams. From the worker's perspective, the hub is the sole consumer — the hub owns the resource and re-exposes it under its own authority (the forwarded_for chain carries attribution, not authority; ADR-032). From the downstream consumer's perspective, the hub is the producer — it doesn't know or care that the real backend is on a worker.

Teardown. If the worker disconnects before a consumer arrives, the subscription is cancelled (connection drop → subscription teardown). If a consumer disconnects, the hub closes that consumer leg but keeps the producer channel open for other consumers. When the last consumer disconnects, the hub may close the producer channel or keep it (subscription stays open for future consumers — policy decision, not architecture).

The `channel_id` allocation symmetry

In both cases, channel_id allocation is by the responder (DP-1, unchanged). In the open case, the responder is the spoke (spoke allocates). In the expose case, the responder is the hub on the worker→hub leg (hub allocates) and the downstream consumer on the hub→consumer leg (consumer allocates). The hub relay records the mapping across legs. This preserves ADR-073's "channel_id allocation is always by the responder" invariant.

What goes where (ADR plan)

ADR	Scope	Status
ADR-095 (new)	"Openable ALPNs are operations" — channels is call with a binary data plane. The mental model, the `channel_open` marker on `OperationSpec`, the `ChannelCore` seam (wrapper shape, POC-flagged), the two-verb split, the subscription-based expose/open matching, the discovery split, the three-category ALPN reframe. The unifying ADR.	Ready to draft.
ADR-073 amendment	`channel/open` dissolves into per-ALPN ops in `channels/<alpn>/open` and `channels/<alpn>/expose`. `channel/close`, `channel/control`, `channel/resources/subscribe` stay generic (keyed by `channel_id`). The `direction` field is removed (becomes the verb). Error codes: `channel:unknown_alpn` becomes "operation not found"; `channel:invalid_params` becomes ordinary schema rejection.	Ready to draft.
ADR-094 amendment (Gap 2)	The per-connection opener ledger in `channels-call`. The decrement is keyed by the opener (from the ledger), not the closer. The decrement is called from every teardown path (close received, close sent, handler exit, connection drop), not just `channel/close`. The trait shape (`check_open`, `on_close`) survives. The teardown hooks (connection-drop, handler-exit) are new structural requirements on `channels-call`.	Ready to draft.
ADR-086 §4 amendment	"Channels data-channel ALPNs" → "binary-stream call apps" (or whatever the naming OQ settles). The category distinction holds (them vs SSH); the description changes from "gated by channels" to "call apps with binary-stream ops."	Ready to draft.
ADR-048 amendment + OQ-65 resolution	WebSocket may carry either `alknet/call` (bare, for call-only clients) or `alknet/channels` (8-byte chunk framing, call on channel 0 inside). Channels framing required for binary-stream clients. OQ-65 resolved. "Native session, not gateway" survives (the decision).	Ready to draft.
ADR-057 amendment	TTY data plane stays call-free; control plane (open/expose ops) depends on call. "Self-contained negotiation framing" becomes the data-plane negotiation (the 5-byte format's negotiation frame); the control-plane negotiation is the call op.	Ready to draft.
ADR-058 clarification	The boundary criterion (EventEnvelope-compatible → call op; incompatible → binary stream with call control plane) is preserved and sharpened. Probably a note, not a full amendment.	Ready to draft.
New OQ (Gap 3)	Per-identity connection cap against `alknet-endpoint`. Named, `deferred(scope)` — the deployment shape that needs it isn't concrete yet. Owned by `alknet-endpoint`, not channels.	Ready to open.

What changes in each crate

`alknet-call`

OperationSpec gains channel_open: Option<ChannelOpenSpec> (the marker). This is a one-way-door API change (every spec-constructing code adds the field, defaulting to None).
No other change. The OperationRegistry is unchanged — it still invokes ops by name, checks access_control, runs the handler. The marker is opaque to the registry; it's channels-call that reads it.

`alknet-channels-call`

Gains the ChannelCore (channel-id allocation, ChannelManager integration, per-connection opener ledger, ChannelLifecyclePolicy consultation, teardown hooks).
Gains the register_openable(spec, open_handler, channel_core) helper that wraps the ALPN's open handler with the channel machinery and registers the op on the call OperationRegistry.
The channel/close handler no longer calls policy.on_close(&op_ctx.identity) directly; instead, the per-connection ledger is walked on every teardown path and on_close is called per opener. (Gap 2.)
The generic ops (channel/close, channel/control, channel/resources/subscribe) stay in channels-call, keyed by channel_id.
The teardown hooks (connection-drop, handler-exit) are new. The connection-drop hook needs to interpose before channels-core's REQ-CH-02 clears the channel map — channels-call walks its ledger and decrements every opener before the map is cleared.

`alknet-channels-core`

Unchanged. The pure multiplexer (ADR-075/093) is auth-blind by design and stays that way. The per-connection opener ledger lives in channels-call, not channels-core.

`alknet-tty` (the first binary-stream call app)

Data plane (the TtyAdapter, the 5-byte wire format, the TtyBackend trait) is unchanged. Used by both direct connections (HandlerRegistry → ProtocolHandler → BiStream) and channels-opened sessions (channels/tty/open → allocate channel → spawn TtyAdapter on the channel's BiStream). Both paths converge at the BiStream.
Control plane (new): registers channels/tty/open and channels/tty/expose on the call OperationRegistry at assembly time, alongside its ProtocolHandler on the HandlerRegistry for direct connections. The op specs carry the channel_open marker, the access_control (e.g., required_scopes: ["tty:open"] and required_scopes: ["tty:expose"]), the input_schema (the NegotiateRequest), and the resource_id_path (e.g., /params/container for docker-backed TTY). channels/tty/expose is registered as a Subscription op type — the worker subscribes to consumer demand; the hub delivers matching open requests as subscription events.
The open handler validates params, consults ownership (ADR-050), prepares the TtyBackend, returns a "channel plan" to the ChannelCore wrapper, which spawns the TtyAdapter.
Dependency: data-plane core depends on alknet-core only (ADR-057's property survives); control plane depends on alknet-core + alknet-call + alknet-channels-call.
Optional: registers channels/tty/list-sessions etc. if session management is wanted. The ALPN gets a full management plane over the call protocol — which it didn't have before.

`alknet-tunnel`, `alknet-socks5`, `alknet-fs`, `alknet-sftp`

Same shape as TTY: data plane (ProtocolHandler) unchanged; control plane (open/expose ops) new. Each registers its open ops on the call registry at assembly time.
These crates are not yet specced (per ADR-085). When specced, they follow the binary-stream call app pattern from the start.

`alknet-hub`

Unchanged in shape. The hub composes call apps — docker (JSON ops), tty (open op + binary stream), tunnel (open op + binary stream), agent, etc. All register ops on the call registry. The hub's assembly layer wires them uniformly. The hub doesn't distinguish "call app" from "channels app" — both are just apps with ops registered. Some ops return JSON; some ops carry the channel_open marker and produce a binary stream. The composition model is uniform.
The relay contract (ADR-079) is unchanged in shape. The op name changes (from generic channel/open to per-ALPN channels/<alpn>/open); the marker (not prefix-matching) is how the hub recognizes and translates channel-open ops.
from_call relay wrapper. When from_call imports a marked op on a channels-backed connection, it wraps it with relay machinery (forward + allocate local-leg channel + record id mapping + start byte-forward pumps) instead of the plain forwarding stub. ADR-022's provenance table gets a note: a FromCall-imported marked op is a leaf for composition purposes but carries relay machinery.

`alknet-worker`

Same as hub. A worker registers its ops on its call registry. The worker's assembly layer wires them uniformly.

`alknet-endpoint`

Unchanged (for now). Gap 3 (per-identity connection cap) is a new OQ against alknet-endpoint, deferred until a deployment forces it. Named now to stop the re-tangle.

`alknet-http`

WebSocket may carry either alknet/call (bare, for call-only clients) or alknet/channels (8-byte chunk framing, call on channel 0 inside). Channels framing required for binary-stream clients. ADR-048 amended; OQ-65 resolved.
The HTTP adapter's call-protocol surface (registration, browser API routes) is unchanged — it's call ops, not channels ops.
The MCP/OpenAPI adapters (to_openapi, to_mcp) must exclude marked ops — "produces a binary stream" is not expressible over a request/response export.

Open questions

Per-connection state plumbing (POC-critical). The OperationEnv::channel_manager() accessor is the proposed resolution for per-connection ChannelManager resolution. The exact trait shape (return type, whether it's on OperationEnv or a separate extension trait) is POC-worthy. The architectural point is that the OperationEnv is the integration point for per-connection state (ADR-024), and the wrapper resolves the ChannelManager at invocation time — static registration, dynamic resolution.
ChannelCore seam: wrapper vs invoke. This doc specs the wrapper shape (the ALPN's open handler returns a "channel plan"; channels- call's wrapper does the allocation/ledger/policy/spawn). The alternative (invoke — the handler calls context.channel_core.open(...) itself) inverts the call → channels-call dependency or requires a generic extension mechanism on OperationContext. The wrapper is preferred. The exact API shape (plan vs callback) is POC-worthy — flag for a small POC during implementation. Not a blocker for the architecture decision.
Resource enumeration aggregation shape. Each ALPN crate provides a resource enumerator. The generic channel/resources/subscribe aggregates. Exact shape (per-ALPN channels/<alpn>/resources/subscribe ops merged by the generic op, vs. callbacks registered with channels-call at registration time) is a POC-worthy detail. The architectural point is that the data source lives in the ALPN crate.
Naming the third category. "Binary-stream call apps" (the working name) vs "channels-served ALPNs" (descriptive) vs "data-channel call apps." Cosmetic but in a lot of tables. Tracked as an OQ.
Op naming vs OQ-13. channels/tty/open implies the ops belong to the channels service, but the TTY crate registers them — the docker precedent (docker/container/list) suggests tty/open. Since relay recognition is via the marker (not name prefix), nothing constrains the name; but the ALPN→path-segment mapping (alknet/tty → tty) needs pinning either way, including what non-alknet/* ALPNs do.
Expose subscription matching. The (op_name, params_hash) key is the proposed matching mechanism between expose and open. The exact hash function, collision handling, and the subscription lifecycle (when does the hub tear down an expose subscription with no consumers?) are POC-worthy details. The architectural point is that the call protocol's Subscription op type is the natural fit for the expose side, and the hub is the broker.
Does ProtocolHandler want channel-context? Probably not for TTY/tunnel/ssh (they just want a BiStream), but maybe for ALPNs that want the opener's identity for per-session logging/ACL. An optional channel-context passed alongside the BiStream. Not a blocker; defer. Two-way-door implementation detail.
Per-identity connection cap (Gap 3). A per-identity connection cap at the endpoint/accept layer, analogous to ChannelLifecyclePolicy but before any ChannelsAdapter / CallAdapter / channel-0 buffer exists. Lives in alknet-endpoint. deferred(scope) — the deployment shape that needs it isn't concrete yet. Named now to stop the re-tangle.
channel-operations.md §ACL-flow forwarded_for inconsistency. Step 4 says "the spoke's ownership store verifies the hub (or the forwarded_for browser, per policy) owns container:abc123." This contradicts ADR-032 (forwarded_for is metadata, not authority — AccessControl::check never reads it) and ADR-050 §4c ("the spoke sees the hub as the owner"). The "(or the forwarded_for browser, per policy)" clause is a spec inconsistency. Fix while editing. The spoke authorizes the hub, full stop; the hub's per-browser ACL is the hub's own layer.

References

ADR-073: channel lifecycle operations (amended by this resolution — channel/open dissolves into per-ALPN ops; generic ops stay)
ADR-094: per-identity channel cap (amended by this resolution — the ledger + teardown hooks; the trait shape survives)
ADR-079: hub relay — translate, not forward (unchanged in shape; the op name changes, the marker replaces prefix-matching)
ADR-050: dynamic resource ownership (the resource_id_path mechanism that works again under per-ALPN ops)
ADR-028: the "parallel authorization system" precedent (superseded by ADR-029 for exactly the structural miss this resolution avoids re-committing one layer down)
ADR-029: peer-graph routing (the existing AccessControl::check path this resolution preserves)
ADR-086: endpoint types and entry points (§4 amended — the "channels data-channel ALPNs" category reframed to "binary-stream call apps")
ADR-048: WebSocket native session (amended — WebSocket may carry either alknet/call or alknet/channels; channels framing required for binary-stream clients; OQ-65 resolved)
ADR-057: alknet-tty does not depend on call (amended — the data plane stays call-free; the control plane depends on call)
ADR-058: alknet-docker on alknet/call (the boundary criterion preserved and sharpened — EventEnvelope-compatible → call; incompatible → binary stream with call control plane)
ADR-075: ChannelsAdapter and ChannelManager (the auth-blindness this resolution preserves — the ledger lives in channels-call, not channels-core)
ADR-092: BiStream as the handler leaf (the transport-leaf layer, settled; this doc is the layer above it)
ADR-093: channels pure channel multiplexing (the wire format, the handler-owns-sub-multiplexing property — both preserved)
docs/research/stream-unification/findings.md — the precedent for this research-then-sync pattern
docs/architecture/crates/channels/channel-operations.md — the spec this resolution rewrites (per-ALPN open ops; generic close/control/resources; the ACL-flow forwarded_for fix)
docs/architecture/crates/call/operation-registry.md — OperationSpec, AccessControl, OperationRegistry::invoke (the machinery this resolution reuses verbatim, with the channel_open marker added)

51 KiB Raw Blame History