alkdev/alkcall
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8066d08395aec4d53130ca3f32f50375cdd7d07b
alkcall/docs/architecture/README.md
glm-5.2 f305f8c0a5 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.
2026-08-12 12:13:53 +00:00

164 lines
12 KiB
Markdown
Raw Blame History

---
status: draft
last_updated: 2026-08-12
---
# alkcall
The call + channels RPC crate. Structured JSON RPC (operations, streaming
subscriptions, service discovery) and N-channel multiplexing over one
transport stream (channel 0 pre-negotiated as `alknet/call`).
This crate unifies `alknet-call` and `alknet-channels` from the alknet
mono-repo, plus the vendored core types formerly in `alknet-core`. The
source architecture docs were ported from
`/workspace/@alkdev/alknet/docs/architecture/` and renumbered as alkcall
ADRs (ADR-001..045). The ALPN strings (`alknet/call`, `alknet/channels`)
are wire-stable and unchanged — see ADR-004.
## Documents
| Document | Status | Description |
|----------|--------|-------------|
| [call-README.md](call-README.md) | draft | Call protocol index — adapter, stream model, registry, client (ported from alknet call/README.md) |
| [call-protocol.md](call-protocol.md) | draft | CallAdapter, hand-rolled EventEnvelope framing (ADR-014), stream model, PendingRequestMap, bidirectional calls |
| [operation-registry.md](operation-registry.md) | draft | OperationSpec, Handler, OperationRegistry, AccessControl, service discovery |
| [client-and-adapters.md](client-and-adapters.md) | draft | CallClient (transport-agnostic spawn_dispatch), from_call, OperationAdapter trait, no-env-vars invariant |
| [channels-README.md](channels-README.md) | draft | Channels protocol index — wire format, adapter, lifecycle, client (ported from alknet channels/README.md) |
| [channels-overview.md](channels-overview.md) | draft | The multiplexing collapse, crate dependencies, transport agnosticism, WASM |
| [channels-wire.md](channels-wire.md) | draft | The 8-byte chunk format, sentinels, wire-level invariants (REQ-CH-01..05) |
| [channels-connection.md](channels-connection.md) | draft | ChannelBidiStreamSource, accept_bi yields one BiStream per channel |
| [channels-adapter.md](channels-adapter.md) | draft | ChannelsAdapter, ChannelManager, demux/mux contracts |
| [channel-operations.md](channel-operations.md) | draft | channel/open, channel/close, channel/control, channel/resources/subscribe |
| [channel-client.md](channel-client.md) | draft | ChannelClient — transport-agnostic from_connection primary |
## Applicable ADRs
### Core (vendored types) — ADR-001..012
| ADR | Title | Relevance |
|-----|-------|-----------|
| [001](decisions/001-alpn-protocol-dispatch.md) | ALPN-Based Protocol Dispatch | HandlerRegistry, ALPN routing |
| [002](decisions/002-protocol-handler-trait.md) | ProtocolHandler Trait | The trait every handler implements |
| [003](decisions/003-auth-as-shared-core.md) | Auth as Shared Core | IdentityProvider, Identity, AuthToken |
| [004](decisions/004-alpn-convention-and-connection-model.md) | ALPN String Convention | `alknet/` prefix, one ALPN per connection |
| [005](decisions/005-bistream-type-definition.md) | BiStream Type Definition | BiStream, handlers receive Connection |
| [006](decisions/006-authcontext-structure.md) | AuthContext Structure | AuthContext fields, hybrid resolution |
| [007](decisions/007-connection-from-stream-generic-single-stream.md) | Connection::from_stream | Generic single-stream connections |
| [008](decisions/008-bidistreamsource-trait.md) | BidiStreamSource Trait | Connection extension point |
| [009](decisions/009-bistream-as-the-handler-leaf.md) | BiStream as the Handler Leaf | accept_bi returns BiStream (concrete) |
| [010](decisions/010-secret-material-flow-and-capability-injection.md) | Secret Material Flow | No secrets on wire; Capabilities |
| [011](decisions/011-dynamic-resource-ownership-for-runtime-spawned-resources.md) | Dynamic Resource Ownership | OwnershipProvider, resource_id_path |
| [012](decisions/012-connectioncredentials-decouple-dial-from-call.md) | ConnectionCredentials | Transport-level credentials, auth_token is per-request |
### Call protocol — ADR-013..030
| ADR | Title | Relevance |
|-----|-------|-----------|
| [013](decisions/013-irpc-as-call-protocol-foundation.md) | ~~irpc as Call Protocol Foundation~~ | **Superseded** by ADR-014 |
| [014](decisions/014-irpc-never-integrated-hand-rolled-framing.md) | Hand-Rolled EventEnvelope Framing | The call wire format ADR; supersedes ADR-013 |
| [015](decisions/015-call-protocol-stream-model.md) | Call Protocol Stream Model | Bidi streams, EventEnvelope, ID correlation |
| [016](decisions/016-operation-error-schemas.md) | Operation Error Schemas | call.error with typed details |
| [017](decisions/017-privilege-model-and-authority-context.md) | Privilege Model | internal = authority switch; Visibility |
| [018](decisions/018-handler-registration-provenance-and-composition-authority.md) | Handler Registration | Registration bundle, provenance, composition authority |
| [019](decisions/019-operation-registry-layering.md) | Operation Registry Layering | Curated + session + connection overlays; OperationEnv trait |
| [020](decisions/020-abort-cascade-for-nested-calls.md) | Abort Cascade | call.aborted cascades; abort-dependents default |
| [021](decisions/021-streaming-handler-for-subscriptions.md) | Streaming Handler | StreamingHandler, invoke_streaming() |
| [022](decisions/022-call-protocol-client-and-adapter-contract.md) | Client and Adapter Contract | CallClient, from_call, OperationAdapter |
| [023](decisions/023-callclient-peer-scoped-registry-filtering.md) | ~~Peer-Scoped Registry Filtering~~ | **Superseded** by ADR-024 |
| [024](decisions/024-peer-graph-routing-model.md) | Peer-Graph Routing Model | PeerCompositeEnv, PeerRef, AccessControl peer auth |
| [025](decisions/025-peerentry-and-identity-id-decoupling.md) | PeerEntry and Identity.id Decoupling | PeerId = Identity.id (stable) |
| [026](decisions/026-forwarded-for-identity.md) | Forwarded-For Identity | Metadata only, never used by ACL |
| [027](decisions/027-from-jsonschema-as-http-adapter.md) | from_jsonschema as HTTP Adapter | FromJsonSchema provenance stays; impl in alknet-http |
| [028](decisions/028-from-call-manual-free-function.md) | from_call Is a Manual Free Function | Assembly layer calls it after dial |
| [029](decisions/029-aggregated-peer-env-wiring.md) | Aggregated Peer-Environment Wiring | Dispatcher hub wiring |
| [030](decisions/030-peer-composite-env-peer-operations.md) | PeerCompositeEnv::peer_operations | OperationEnv::peer_operations override |
### Shared — ADR-031..033
| ADR | Title | Relevance |
|-----|-------|-----------|
| [031](decisions/031-crate-decomposition.md) | Crate Decomposition | alkcall unifies core+call+channels |
| [032](decisions/032-one-way-door-decision-framework.md) | One-Way Door Decision Framework | Reversal cost classification |
| [033](decisions/033-rust-canonical-implementation.md) | Rust as Canonical Implementation Language | Rust canonical, TS reference |
### Channels — ADR-034..045
| ADR | Title | Relevance |
|-----|-------|-----------|
| [034](decisions/034-channels-wire-format.md) | Channels Wire Format | 8-byte chunk header; one-way door |
| [035](decisions/035-channels-pure-channel-multiplexing.md) | Pure Channel Multiplexing | No stream_type; BiStream-only; handler owns sub-mux |
| [036](decisions/036-channel-0-pre-negotiated-call.md) | Channel 0 Pre-Negotiated | Channel 0 = alknet/call |
| [037](decisions/037-channel-lifecycle-operations.md) | Channel Lifecycle Operations | channel/open, close, control, resources/subscribe |
| [038](decisions/038-channelconnection-bidistreamsource.md) | ChannelConnection | Per-channel BidiStreamSource; yield-once accept_bi |
| [039](decisions/039-channelsadapter-and-channelmanager.md) | ChannelsAdapter and ChannelManager | Demux/mux; ALPN-blind, auth-blind |
| [040](decisions/040-backpressure-channel-limits-id-reuse.md) | Backpressure, Limits, ID Reuse | Bounded-buffer; 256-channel memory bound |
| [041](decisions/041-per-identity-channel-cap.md) | Per-Identity Channel Cap | ChannelLifecyclePolicy; 256 per PeerId |
| [042](decisions/042-hub-relay-translate-not-forward.md) | Hub Relay | Translate channel 0, byte-forward data channels |
| [043](decisions/043-channelclient.md) | ChannelClient | Transport-agnostic from_connection |
| [044](decisions/044-channels-subcrate-decomposition.md) | Channels Sub-Crate Decomposition | channels-core / channels-call (modules in alkcall) |
| [045](decisions/045-alknetclient-native-dial-seam.md) | AlknetClient Dial Seam | spawn_dispatch / from_connection take-over; dial in consumer |
| [046](decisions/046-publish-operation-type-and-handler-kind-sink.md) | Publish Operation Type and HandlerKind::Sink | `OperationType::Pub` (client→server streaming); `SinkHandler` + `HandlerKind::Sink`; `call.published` wire event; `invoke_sink()` dispatch; `Subscription` renamed to `Sub` |
| [047](decisions/047-openable-alpns-are-operations.md) | Openable ALPNs Are Operations | `channel/open` dissolves into per-ALPN ops `channels/<alpn>/sub`/`pub`; `channel_open` marker on `OperationSpec`; `ChannelCore` wrapper; extension-trait `ChannelOperationEnv`; connection-owner allocates `channel_id`; opener ledger (Gap 2 fix); ALPNs are call apps |
## Relevant Open Questions
See [open-questions.md](open-questions.md) for the full tracker. Key
questions affecting this crate:
- **OQ-01**: Call protocol pub/sub primitive (partially resolved) —
ADR-046 adds the `Pub` primitive (client→server streaming). The
fan-out/broker is deferred to channels (Gap B in ADR-047 is named
out-of-scope for alkcall; the hub composes the broker on top).
- **OQ-02**: Full channel-level flow-control windowing (deferred(scope))
— bounded-buffer is decided (ADR-040); full windowing blocked on a real
HOL-blocking deployment observation.
- **OQ-03**: Channels add/strip API shape (open) — whether the 8-byte
header add/strip is built into the read/write path or a standalone
utility.
## Key Design Principles
1. **One connection, full access**: An `alknet/call` connection gives
access to the entire operation registry.
2. **Protocol is symmetric**: Both sides can initiate calls. Producer/
consumer, not server/client.
3. **Hand-rolled framing (no irpc)**: EventEnvelope is hand-rolled
length-prefixed JSON. See ADR-014.
4. **Operation registry is layered**: Curated (static) + session +
connection overlays. OperationEnv is a trait. See ADR-019.
5. **No secret material on the wire**: Capabilities injected at assembly
layer. See ADR-010.
6. **Abort cascades to descendants**: Default abort-dependents.
See ADR-020.
7. **Peer authorization via AccessControl**: No remote_safe flag.
See ADR-024.
8. **Streams are streams**: Every channel is a BiStream. The handler
owns its sub-stream multiplexing. See ADR-035.
9. **Channel 0 is alknet/call**: Channel lifecycle is call operations on
channel 0. See ADR-036, ADR-037.
10. **Wire formats are stable**: EventEnvelope shape and the 8-byte chunk
header are one-way doors. See ADR-014, ADR-034.
## References
- `@alkdev/alknet: docs/architecture/` — the source architecture docs
these were ported from (renumbered from alknet ADR-001..094 to alkcall
ADR-001..045)
- `@alkdev/alktype` — the binary struct engine, used for channels chunk
header layout and JSON payload schema validation
- `@alkdev/pubsub` — the TypeScript EventEnvelope prior art the call
wire format was derived from
> **Note**: The source ADRs and spec docs were ported from the parent
> `@alkdev/alknet` workspace where this crate originated. They are
> preserved here as the authoritative spec for alkcall; the alknet
> mono-repo will consume alkcall's versions when it is reworked.
>
> **Cross-references to non-ported ADRs**: Some spec docs and ADRs
> reference alknet ADRs by their original numbers (e.g., ADR-052 for
> TTY's wire format, ADR-082 for alknet-tls, ADR-086 for endpoint types).
> These are ADRs for sibling crates that are not part of alkcall. They
> retain their alknet numbering (052, 082, 086, etc.) — any ADR number
> outside the alkcall range 001..045 is an alknet source ADR, found at
> `/workspace/@alkdev/alknet/docs/architecture/decisions/`.
Reference in New Issue View Git Blame Copy Permalink