feat: implement channels protocol + ADR-047 (openable ALPNs are operations)
ADR-047: the unifying decision that dissolves into per-ALPN ops (, ) with a marker on . Each openable ALPN registers its own ops with their own , , , and the marker. The field is replaced by (Sub/Pub). The generic ops (channel/close, channel/control, channel/resources/subscribe) stay, keyed by channel_id. Resolves Gaps A-G from the research findings (Gap B broker named out-of-scope for alkcall; Gap C relay wrapper is consumer concern; Gap D connection-owner allocates; Gap E extension trait; Gap F boolean marker on wire; Gap G ACL/ownership complementary). ADR-037 amended: dissolves; removed; generic ops stay; preview dropped from resources/subscribe. Spec docs updated: channel-operations.md (unified model, opener ledger, ACL flow), operation-registry.md (channel_open marker, ChannelOpenSpec), README.md (ADR-047), open-questions.md (OQ-31..38 resolved). Source changes: - spec.rs: ChannelOpenSpec struct, channel_open field on OperationSpec, with_channel_open builder, 3 tests - discovery.rs: spec_to_json emits channel_open boolean, operation_spec_schema includes channel_open, 2 tests - from_call.rs: rebuild_spec_for parses channel_open marker, derive_alpn_from_op_name helper, 6 tests Channels module (src/channels/, 10 files, ~2400 lines): - wire.rs: 8-byte chunk header (ChunkHeader, parse/write_header, read_header/write_chunk/write_eof async helpers), 12 tests - reassembly.rs: MpscRecvStream (tokio::mpsc::Receiver<Bytes> → AsyncRead), MpscSendStream (AsyncWrite → tokio::mpsc::Sender<Bytes>), REQ-CH-01 shutdown sentinel, REQ-CH-02 sender-drop EOF, 10 tests - mux.rs: MuxHandle (clone-able, register(channel_id)), MuxRunner (per-channel pump tasks, exits when handles drop), OpenerLedger (ADR-047 §7), 4 tests - manager.rs: ChannelManager (channel map, open_channel, install_channel_zero, route_payload, teardown_channel, clear_all), 11 tests - source.rs: ChannelBidiStreamSource (yield-once accept_bi), channel_source helper, 4 tests - adapter.rs: ChannelsAdapter (ProtocolHandler for alknet/channels, demux loop, install_channel_zero hook), 1 test - operations.rs: ChannelOperations (registers channel/close, channel/control, channel/resources/subscribe), ChannelCore (check_open/on_close wrappers), 4 tests - policy.rs: ChannelLifecyclePolicy trait, NoCap, PerIdentityChannelPolicy (default 256, per_identity_caps override), default_policy, 8 tests - env.rs: ChannelOperationEnv extension trait (ADR-047 §4), ChannelsSessionEnv impl, 2 tests - client.rs: ChannelClient (from_connection, call_open_op, take_call_connection), 1 test Verification: 432 tests pass (66 new channels + 10 marker + 356 existing), clippy clean, fmt clean, cargo doc generates. Cargo.toml: +bytes dependency.
This commit is contained in:
@@ -6,7 +6,46 @@ Accepted (amended 2026-07-18 by ADR-035 — `stream_types` field removed
|
||||
from `channel/open`; `stream_type` field removed from `channel/control`;
|
||||
`channel:stream_type_unavailable` error code removed; the channels layer
|
||||
has no `stream_type` concept — see "Amendment (ADR-035, 2026-07-18)"
|
||||
below)
|
||||
below; amended 2026-08-12 by ADR-047 — `channel/open` dissolves into
|
||||
per-ALPN ops `channels/<alpn>/sub` and `channels/<alpn>/pub`; the
|
||||
`direction` field is removed (replaced by `OperationType`); the generic
|
||||
ops `channel/close`, `channel/control`, `channel/resources/subscribe`
|
||||
stay; error codes `channel:unknown_alpn` and `channel:invalid_params`
|
||||
become ordinary `NOT_FOUND` / schema rejection — see "Amendment
|
||||
(ADR-047, 2026-08-12)" below)
|
||||
|
||||
## Amendment (ADR-047, 2026-08-12)
|
||||
|
||||
The generic `channel/open` operation is **removed**. Each openable ALPN
|
||||
registers its own ops on the call `OperationRegistry`, named
|
||||
`channels/<alpn>/sub` (`OperationType::Sub` — consumer subscribes to a
|
||||
binary stream) and/or `channels/<alpn>/pub` (`OperationType::Pub` —
|
||||
producer publishes a binary stream). The `direction` field is **removed**
|
||||
— `OperationType` carries the direction (building on ADR-046). The
|
||||
`alpn` and `params` fields move into the op's `input_schema` (the
|
||||
`alpn` is derivable from the op name; `params` is the op's input).
|
||||
|
||||
The generic ops `channel/close`, `channel/control`,
|
||||
`channel/resources/subscribe` **stay** (keyed by `channel_id`). The
|
||||
`access` preview in `channel/resources/subscribe` is **dropped** — it's
|
||||
on the op spec, available via `services/schema`. The error codes
|
||||
`channel:unknown_alpn` and `channel:invalid_params` become ordinary
|
||||
`NOT_FOUND` (op not registered) and schema rejection (input doesn't
|
||||
match `input_schema`).
|
||||
|
||||
`OperationSpec` gains a `channel_open: Option<ChannelOpenSpec>` marker
|
||||
(ADR-047 §2) — the dispatch hint that tells the channels layer "this
|
||||
op's stream is binary, allocate a channel." The op's `access_control` is
|
||||
the ACL (unchanged); the marker is orthogonal. The marker is
|
||||
wire-visible (`"channel_open": true` in `services/schema`).
|
||||
|
||||
`channel_id` allocation is amended to "the connection owner allocates"
|
||||
(ADR-047 §5) — the side that holds the `ChannelManager`. In the `Sub`
|
||||
case that's the responder; in the `Pub` case that's the initiator.
|
||||
|
||||
The body below describes the **original** (with generic `channel/open`
|
||||
and `direction`) shape; the amendments above are the operative decision.
|
||||
See ADR-047 for the unification rationale and the resolved gaps.
|
||||
|
||||
## Amendment (ADR-035, 2026-07-18)
|
||||
|
||||
|
||||
373
docs/architecture/decisions/047-openable-alpns-are-operations.md
Normal file
373
docs/architecture/decisions/047-openable-alpns-are-operations.md
Normal file
@@ -0,0 +1,373 @@
|
||||
# ADR-047: Openable ALPNs Are Operations
|
||||
|
||||
## Status
|
||||
|
||||
Accepted (amends ADR-037; refines ADR-044, ADR-046)
|
||||
|
||||
## Context
|
||||
|
||||
The channels spec (ADR-037) framed channel lifecycle as **one generic
|
||||
`channel/open` operation** whose input carries the authorization-relevant
|
||||
facts (`alpn`, `params`, `direction`) inside its JSON body. The call
|
||||
protocol's ACL machinery (`AccessControl::check` on `OperationSpec`) runs
|
||||
*before* the handler — but the generic op hides everything the ACL would
|
||||
need to see inside one op's input, where the call ACL machinery can't
|
||||
reach it.
|
||||
|
||||
The research findings
|
||||
(`/workspace/@alkdev/alknet/docs/research/call-channels-unification/
|
||||
findings.md`) surfaced the structural miss and the resolution together:
|
||||
|
||||
- **The miss.** Per-ALPN scopes (`tty:open` vs `tunnel:open`) have no
|
||||
enforcement home. ADR-011's `resource_id_path` (JSON pointer into input
|
||||
for the resource ID, checked by the ACL before the handler runs) can't
|
||||
work on a single generic op — 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 shape re-commits the structural miss
|
||||
ADR-024 (superseding ADR-023) was written to avoid: a parallel
|
||||
authorization system duplicating `AccessControl` one layer down.
|
||||
- **The resolution.** An openable ALPN is an operation. Each openable
|
||||
ALPN registers its own ops on the call `OperationRegistry`, with its
|
||||
own `access_control`, `input_schema`, `resource_id_path`, and a
|
||||
`channel_open` marker that tells the channels layer "this op's stream
|
||||
is binary, not JSON." The call protocol's existing
|
||||
`AccessControl::check` is the ACL — unchanged. The `direction` field is
|
||||
gone; `OperationType` carries the direction (`Sub` = consumer
|
||||
subscribes, `Pub` = producer publishes), building on ADR-046.
|
||||
|
||||
This is the cheapest moment to amend: no channels code exists, no
|
||||
deployments exist, the develop branch is pre-alpha. ADR-037's four op
|
||||
names were declared one-way doors, but ADR-035/046 just demonstrated that
|
||||
amendment is the normal mode here.
|
||||
|
||||
### What the research findings resolved (Gap A, E)
|
||||
|
||||
- **Gap A** (Pub handler shape) — resolved by ADR-046:
|
||||
`HandlerKind::Sink` / `SinkHandler` / `invoke_sink()`. The initiator
|
||||
streams *to* the responder via `call.published` events; the handler
|
||||
consumes the stream and returns a single `ResponseEnvelope`.
|
||||
- **Gap E** (`OperationEnv::channel_manager()` couples call to channels)
|
||||
— resolved by the extension-trait pattern: an
|
||||
`alknet-channels-call`-local trait (`ChannelOperationEnv: OperationEnv`)
|
||||
adds the `channel_manager()` accessor, and the open-op wrapper
|
||||
downcasts `context.env` at invocation time. `alkcall` (the call crate)
|
||||
stays free of any channels types; the layering is preserved.
|
||||
|
||||
### What this ADR decides (Gap B, C, D, F, G)
|
||||
|
||||
- **Gap B** (hub broker) — **out of scope for alkcall.** The broker
|
||||
(topic registry, `Pub`↔`Sub` matching by `(op_name, params_hash)`,
|
||||
N-consumer fan-out) is a hub/consumer concern, not an alkcall concern.
|
||||
alkcall provides the `Pub`/`Sub` primitives (ADR-046) and the channel
|
||||
machinery (this ADR); the hub composes the broker on top, the same way
|
||||
the hub relay composes on top of call ops. This ADR names it as
|
||||
out-of-scope so it stops re-tangling every channels-control-plane
|
||||
conversation.
|
||||
- **Gap C** (`from_call` relay wrapper) — the `from_call` forwarding
|
||||
handler for a marked op wraps with relay machinery (forward + allocate
|
||||
local-leg channel + record id mapping + byte-forward pumps) instead of
|
||||
the plain forwarding stub. The wrapping lives in a separate layer
|
||||
(`from_call` consumer code, e.g. the hub), not in alkcall's `from_call`
|
||||
core, preserving the layering. alkcall's `from_call` reconstructs the
|
||||
`channel_open` marker from discovery (Gap F) so the consumer can branch
|
||||
on it.
|
||||
- **Gap D** (`channel_id` allocation in Pub case) — the real invariant is
|
||||
"the side that holds the `ChannelManager` allocates." In the `Sub` case
|
||||
that's the responder (the side that received the open op); in the `Pub`
|
||||
case that's the initiator (the side that sent the open op, which owns
|
||||
its own channels connection). ADR-037's "responder allocates" is
|
||||
amended to "connection-owner allocates."
|
||||
- **Gap F** (`channel_open` marker wire format) — the marker is a boolean
|
||||
field `"channel_open": true` on the `services/schema` payload. The ALPN
|
||||
is derivable from the op name (`channels/<alpn>/sub` → ALPN
|
||||
`alknet/<alpn>`); the marker is the dispatch hint, not a carrier for
|
||||
the ALPN string. `spec_to_json` emits it; `rebuild_spec_for` parses it.
|
||||
- **Gap G** (`resource_id_path` ACL vs handler ownership) — complementary,
|
||||
not redundant. The ACL check (via `resource_id_path` +
|
||||
`OwnershipProvider`) is the coarse gate ("may this identity touch
|
||||
resources of this type, and if a specific resource is targeted, does
|
||||
this identity own it?"). The handler's ownership check is ALPN-specific
|
||||
business logic the ACL can't express ("is this container in a state
|
||||
that allows TTY attachment?"). The two run at different layers and
|
||||
answer different questions.
|
||||
|
||||
## Decision
|
||||
|
||||
### 1. `channel/open` dissolves into per-ALPN ops
|
||||
|
||||
The generic `channel/open` operation (ADR-037) is **removed**. Each
|
||||
openable ALPN registers its own ops on the call `OperationRegistry`,
|
||||
named `channels/<alpn>/sub` and/or `channels/<alpn>/pub`:
|
||||
|
||||
| Op | `OperationType` | Initiator role | Responder role | Stream |
|
||||
|----|-----------------|----------------|----------------|--------|
|
||||
| `channels/<alpn>/sub` | `Sub` | consumer (subscribes) | producer (streams) | server→client |
|
||||
| `channels/<alpn>/pub` | `Pub` | producer (publishes) | consumer (receives) | client→server |
|
||||
|
||||
An ALPN may register one or both ops. A peer that may subscribe is not
|
||||
the same grant as a peer that may publish — separate op types, separate
|
||||
ACLs.
|
||||
|
||||
The `direction` field from ADR-037 is **removed**. `OperationType`
|
||||
carries the direction. The "who writes first" question is
|
||||
ALPN-specific (determined by the handler's `params` contract), unchanged
|
||||
from ADR-037's "the channels layer does not enforce write order."
|
||||
|
||||
**The generic ops stay:** `channel/close`, `channel/control`,
|
||||
`channel/resources/subscribe` remain generic (keyed by `channel_id`),
|
||||
registered by `channels-call` at assembly time. Only `channel/open`
|
||||
dissolves.
|
||||
|
||||
### 2. `channel_open` marker on `OperationSpec`
|
||||
|
||||
`OperationSpec` gains an optional `channel_open` field — the marker that
|
||||
tells the channels layer "this op's stream is binary, allocate a channel
|
||||
for it":
|
||||
|
||||
```rust
|
||||
pub struct OperationSpec {
|
||||
// ... existing fields ...
|
||||
pub channel_open: Option<ChannelOpenSpec>,
|
||||
}
|
||||
|
||||
pub struct ChannelOpenSpec {
|
||||
pub alpn: &'static str, // e.g., b"alknet/tty" as str
|
||||
}
|
||||
```
|
||||
|
||||
The marker is **registry metadata, not auth machinery** — parallel to
|
||||
how `resource_id_path` tells ADR-011 where to find the resource ID. The
|
||||
op's `access_control` is the ACL (unchanged); the marker is the dispatch
|
||||
hint. The `OperationRegistry` is opaque to the marker; it's
|
||||
`channels-call` that reads it.
|
||||
|
||||
**Wire-visible.** The marker survives discovery serialization — it is
|
||||
part of the `services/schema` payload, not just the in-process struct.
|
||||
`spec_to_json` emits `"channel_open": true` when set (boolean — the ALPN
|
||||
is derivable from the op name). `rebuild_spec_for` parses it back. A
|
||||
`from_call` importer can branch on the marker to wrap with relay
|
||||
machinery (Gap C).
|
||||
|
||||
**Marked ops invoked outside a channels session.** `channels/tty/sub` 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`. The open-op wrapper resolves `channel_manager()` at
|
||||
invocation time via the extension trait (Gap E); if it returns `None`,
|
||||
the wrapper returns `channel:no_channels_session`.
|
||||
|
||||
### 3. `ChannelCore` wrapper (the open-op composition seam)
|
||||
|
||||
The ALPN crate provides:
|
||||
- The `OperationSpec` (with `channel_open` marker, `access_control`,
|
||||
`input_schema`, `resource_id_path`).
|
||||
- The open handler (ALPN-specific work — validate params, consult
|
||||
ownership, prepare the backend, return a "channel plan" — a
|
||||
`ProtocolHandler` to spawn on the channel's `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`.
|
||||
|
||||
The wrapper shape (not the invoke shape) is preferred: the ALPN's open
|
||||
handler returns a channel plan; channels-call's wrapper does the
|
||||
allocation/ledger/policy/spawn. The alternative (the handler calls
|
||||
`context.channel_core.open(...)` itself) would require 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 exact API
|
||||
shape of the channel plan is a two-way-door implementation detail; the
|
||||
architectural point is the wrapper.
|
||||
|
||||
### 4. Per-connection `ChannelManager` resolution (Gap E)
|
||||
|
||||
The `register_openable` helper registers ops at assembly time (Layer 0,
|
||||
curated, static per ADR-019). 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: an extension trait in `channels-call` (not in the call
|
||||
crate's core `OperationEnv` trait) adds the `channel_manager()` accessor:
|
||||
|
||||
```rust
|
||||
// in channels-call
|
||||
pub trait ChannelOperationEnv: OperationEnv {
|
||||
fn channel_manager(&self) -> Option<&ChannelManager>;
|
||||
}
|
||||
```
|
||||
|
||||
The wrapper handler downcasts `context.env` to
|
||||
`&dyn ChannelOperationEnv` at invocation time — static registration,
|
||||
dynamic resolution. If the downcast fails (no channels session), the
|
||||
wrapper returns `channel:no_channels_session`. This keeps `alkcall`'s
|
||||
call crate free of any channels types and preserves the layering
|
||||
(ADR-044). The `OperationEnv` is already the integration point for
|
||||
per-connection state (ADR-019); adding a `ChannelManager` accessor via
|
||||
an extension trait is the natural extension.
|
||||
|
||||
Each channels connection's `OperationEnv` overlay carries its own
|
||||
`ChannelManager` reference, so nested connections resolve correctly.
|
||||
|
||||
### 5. `channel_id` allocation: connection-owner allocates (Gap D)
|
||||
|
||||
ADR-037's "responder allocates" invariant is amended: **the side that
|
||||
holds the `ChannelManager` for that connection allocates the
|
||||
`channel_id`.** In the `Sub` case that's the responder (the side that
|
||||
received the open op — it owns its channels connection). In the `Pub`
|
||||
case that's the initiator (the side that sent the open op — it owns its
|
||||
own channels connection).
|
||||
|
||||
This is the same invariant stated correctly: the connection owner
|
||||
allocates. The "responder allocates" framing was a special case that
|
||||
happened to hold for `Sub` (the common case) but broke for `Pub` (the
|
||||
initiator owns the connection it's publishing from).
|
||||
|
||||
### 6. The discovery split
|
||||
|
||||
- **"What may I open"** (static, per-op): `services/list` (visibility-
|
||||
filtered + `AccessControl::check(calling_peer_identity)` server-side,
|
||||
per ADR-024 §6) + `services/schema` (per-op `access_control` and
|
||||
`channel_open` marker). 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. The data source lives
|
||||
in the ALPN crate, not in channels-call.
|
||||
|
||||
The `access` preview in `resources/subscribe` (ADR-037) becomes
|
||||
redundant — it's on the op spec, available via `services/schema`. It is
|
||||
dropped from the `resources/subscribe` payload; the spec is the
|
||||
authority, and carrying a preview in a different shape invites
|
||||
staleness.
|
||||
|
||||
### 7. Quota lifecycle: the opener ledger (Gap 2 from findings)
|
||||
|
||||
ADR-041's `ChannelLifecyclePolicy::on_close(&op_ctx.identity)` is called
|
||||
from the `channel/close` handler with the **closer's** identity, not the
|
||||
opener's — and is not called at all on transport drop. A peer whose
|
||||
connection dies at cap is permanently at cap (a self-DoS).
|
||||
|
||||
The fix: `channels-call` keeps a per-connection opener ledger
|
||||
(`channel_id → opener PeerId`). 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 locally, handler exit,
|
||||
connection drop — not just `channel/close`. The ledger entry is removed
|
||||
atomically with its decrement (teardown paths can race; a
|
||||
double-decrement under-counts and weakens the cap).
|
||||
|
||||
The `ChannelLifecyclePolicy` trait shape (`check_open`, `on_close`)
|
||||
survives; the change is where `on_close` is called from and where the
|
||||
opener identity comes from. `channels-core` stays auth-blind (the
|
||||
ledger lives in `channels-call`, not `channels-core`).
|
||||
|
||||
### 8. ALPN category reframe
|
||||
|
||||
ADR-086 §4 (alknet source) split the foundational handlers into
|
||||
"channels data-channel ALPNs" and "SSH (endpoint ALPN wrapping
|
||||
channels)." Under the unified model, the first category dissolves —
|
||||
they're **call apps** (the same shape as docker). They register ops on
|
||||
the call `OperationRegistry`. Some ops return JSON; some ops carry the
|
||||
`channel_open` marker and produce a binary stream. The endpoint
|
||||
(channels or bare call) determines the framing, not the app.
|
||||
|
||||
The ALPN crates served under channels (tty, tunnel, socks5, fs, sftp)
|
||||
stop being "just ALPNs" and become call apps. 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. SSH
|
||||
stays distinct (endpoint ALPN wrapping channels).
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive:**
|
||||
|
||||
- Per-ALPN ACLs have an enforcement home: each openable ALPN's op has
|
||||
its own `access_control`, checked by `OperationRegistry::invoke`
|
||||
before the handler runs, like every other op. No new auth machinery.
|
||||
- ADR-011's `resource_id_path` works for channel-open ops: the path is
|
||||
per-op (`/params/container` for tty-docker), not per-ALPN-branch-of-a-
|
||||
generic-op. The coarse ownership gate runs before the handler.
|
||||
- The `direction` field is gone; `OperationType` (`Sub`/`Pub`) carries
|
||||
the direction. Separate op types → separate ACLs. The hub-as-proxy
|
||||
pattern (worker publishes, hub owns, consumers subscribe) composes on
|
||||
top.
|
||||
- The `channel_open` marker is the dispatch hint — orthogonal to the
|
||||
ACL. The same `Pub`/`Sub` model works for JSON streams (marker absent)
|
||||
and binary streams (marker present).
|
||||
- The ALPN crates are call apps — the gating is a consequence, not the
|
||||
definition. They inherit call's auth by construction.
|
||||
- The per-connection opener ledger fixes the quota self-DoS (Gap 2).
|
||||
- The extension-trait pattern (Gap E) keeps the call crate free of
|
||||
channels types.
|
||||
|
||||
**Negative:**
|
||||
|
||||
- `OperationSpec` gains a field (`channel_open: Option<ChannelOpenSpec>`,
|
||||
defaults `None`). Every spec-constructing site adds the field,
|
||||
defaulting to `None`. This is a mechanical, additive change — the
|
||||
`Option`/`None`-default keeps it non-breaking.
|
||||
- The ALPN→path-segment mapping (`alknet/tty` → `tty`) needs pinning.
|
||||
The op name `channels/tty/sub` implies the path segment is `tty`;
|
||||
non-`alknet/*` ALPNs need a rule. The rule: the path segment is the
|
||||
ALPN with the `alknet/` prefix stripped; ALPNs without that prefix
|
||||
use their full ALPN string as the path segment (rare case, two-way-
|
||||
door).
|
||||
- The `from_call` relay wrapper (Gap C) is a consumer concern, not in
|
||||
alkcall's `from_call` core. The consumer (hub) wraps marked ops with
|
||||
relay machinery after `from_call` returns. This preserves the
|
||||
layering but means the hub has more to do than a plain
|
||||
`register_imported_all`.
|
||||
- The broker (Gap B) is out of scope. The `Pub`/`Sub` primitives are the
|
||||
building blocks; the hub composes the broker on top. Designing the
|
||||
broker blind would produce a half-design.
|
||||
|
||||
## Door type
|
||||
|
||||
**One-way (control-plane shape).** The per-ALPN op names
|
||||
(`channels/<alpn>/sub`, `channels/<alpn>/pub`), the `channel_open`
|
||||
marker on `OperationSpec`, and the removal of `channel/open` /
|
||||
`direction` are one-way: once consumers register open ops and clients
|
||||
call them by name, changing the shape requires a protocol migration.
|
||||
The `ChannelCore` wrapper shape, the extension-trait pattern, and the
|
||||
opener ledger are two-way-door implementation details within the
|
||||
one-way decision.
|
||||
|
||||
The `channel_open` marker's wire shape (`"channel_open": true` boolean)
|
||||
is one-way: `services/schema` consumers will read it, and changing the
|
||||
shape would break them. The `ChannelOpenSpec` in-process struct carrying
|
||||
the ALPN is a two-way-door detail (the wire shape is boolean; the
|
||||
in-process struct is free to evolve).
|
||||
|
||||
## References
|
||||
|
||||
- ADR-037: channel lifecycle operations (amended by this ADR —
|
||||
`channel/open` dissolves; generic ops stay; `direction` removed)
|
||||
- ADR-041: per-identity channel cap (amended by this ADR — the opener
|
||||
ledger; the trait shape survives)
|
||||
- ADR-046: Publish operation type and `HandlerKind::Sink` (the
|
||||
`Pub`/`Sub` primitives this ADR builds on; Gap A resolved)
|
||||
- ADR-024: peer-graph routing model (the `AccessControl::check` path
|
||||
this ADR preserves; the precedent for avoiding a parallel auth
|
||||
system)
|
||||
- ADR-011: dynamic resource ownership (`resource_id_path` works again
|
||||
under per-ALPN ops)
|
||||
- ADR-019: operation registry layering (`OperationEnv` as the
|
||||
integration point; the extension-trait pattern extends it)
|
||||
- ADR-044: channels sub-crate decomposition (the layering this ADR
|
||||
preserves — channels types stay out of the call crate)
|
||||
- ADR-042: hub relay (the relay contract unchanged in shape; the op
|
||||
name changes, the marker replaces prefix-matching)
|
||||
- `/workspace/@alkdev/alknet/docs/research/call-channels-unification/
|
||||
findings.md` — the research that surfaced the unification and the
|
||||
gaps this ADR resolves
|
||||
Reference in New Issue
Block a user