glm-5.2
0de2cebb1d
Commits the concrete adapter shape deferred by ADR-033: read-sync / write-async split with honker NOTIFY/LISTEN for no-restart cache invalidation, against SQLite, in a separate alknet-store-sqlite crate. Two constraints drive the design: (1) the hot-path read trait (IdentityProvider::resolve_from_fingerprint, CredentialStore::get) is sync — called in the accept loop, no .await — so a SQLite-backed adapter must cache in memory and serve sync reads from the cache; (2) auth changes must take effect without a restart (an early issue the project already fixed for ConfigIdentityProvider via ArcSwap config reload). honker's SQLite NOTIFY/LISTEN (single-digit-ms wake, no polling) is the cache-invalidation mechanism that makes both hold: write commits to SQLite + emits NOTIFY, the running process's LISTEN wakes, the in-memory index reloads and atomically swaps, the next read sees the new state. Same ArcSwap-reload pattern as config, generalized from 'config file is source of truth' to 'SQLite is source of truth, honker signals when it changed.' New async IdentityStore write trait (put_peer / update_peer / remove_peer) extends the sync IdentityProvider read trait for peer mutations. ConfigIdentityProvider does NOT implement it (config reload is its write path — a posture enforced by the absence of a backend, not a type-system constraint); SqliteIdentityProvider implements both. CredentialStore::put/delete refined to async (within ADR-031's one-way door — the contract was get/put/delete keyed by provider persisting EncryptedData never decrypting; sync-vs-async was unspecified). CredentialStoreError renamed to shared StoreError covering both traits. alknet-store-sqlite is one crate implementing both IdentityStore and CredentialStore with shared SQLite connection + honker LISTEN infra (splitting later is a two-way door). Schema shape committed (one row per PeerEntry with JSON columns for fingerprints/scopes/resources; one row per EncryptedData blob keyed by provider); exact DDL is an implementation-detail two-way door in the adapter crate. The keypal adapter-factory pattern is intentionally not ported to Rust (runtime column-mapping is a TS affordance; in Rust each adapter is a concrete type, cross-cutting concerns are a shared helper module). Amends ADR-031 (put/delete async refinement, StoreError rename), ADR-033 (concrete adapter shape now specified, two-crate framing collapsed to one), ADR-034 (OQ-36 now resolved), auth.md (IdentityStore section, cache-invalidation summary, OQ-36 reference), config.md (two write paths note), and the OQ-36/OQ-34 entries in open-questions.md. Review fixed 4 criticals (error-type name divergence, duplicate IdentityProvider sketch, upsert/Duplicate ambiguity, 'shape unchanged' contradiction), 7 warnings, 5 suggestions.
status, last_updated, review
| status | last_updated | review |
|---|---|---|
| draft | 2026-06-27 | call/review-call passed 2026-06-23 — registry, protocol, ADR (005/012/014/015/016/017/022/023/024), security, and pattern-consistency checks all conformant; 159 unit/integration tests green; `cargo build`, `cargo clippy -- -D warnings`, `cargo fmt --check`, `cargo test` clean. Call-completion gap (ADR-017 client/adapter surface) addressed 2026-06-26; ADR-029 migration pending. |
alknet-call
Structured RPC over QUIC: operations, request/response, streaming subscriptions, and service discovery. Implements ProtocolHandler on ALPN alknet/call.
Documents
| Document | Status | Description |
|---|---|---|
| call-protocol.md | draft | CallAdapter, EventEnvelope framing, stream model, PendingRequestMap, bidirectional calls |
| operation-registry.md | draft | OperationSpec, Handler, OperationRegistry, AccessControl, service discovery, irpc integration |
| client-and-adapters.md | draft | CallClient (outbound connection opener), from_call / from_jsonschema, OperationAdapter trait, adapter location map, no-env-vars invariant, exchange-of-operations pattern |
Applicable ADRs
| ADR | Title | Relevance |
|---|---|---|
| 001 | ALPN-Based Protocol Dispatch | CallAdapter registers on ALPN alknet/call |
| 002 | ProtocolHandler Trait | CallAdapter implements ProtocolHandler |
| 003 | Crate Decomposition | alknet-call depends on alknet-core and irpc |
| 013 | Rust as Canonical Implementation Language | Adapter traits defined in Rust; TS is reference/browser adaptation |
| 004 | Auth as Shared Core | AuthContext passed to call handlers |
| 005 | irpc as Call Protocol Foundation | irpc provides framing and service dispatch |
| 006 | ALPN String Convention | alknet/call ALPN, one ALPN per connection |
| 007 | BiStream Type Definition | CallAdapter receives Connection, not BiStream |
| 008 | Vault Integration Point | Vault accessed at assembly layer, not on the wire |
| 010 | ALPN Router and Endpoint | Static handler registration |
| 012 | Call Protocol Stream Model | Bidirectional streams, EventEnvelope, ID-based correlation |
| 014 | Secret Material Flow and Capability Injection | Call protocol carries no secret material; capabilities injected at assembly layer |
| 015 | Privilege Model and Authority Context | internal = authority switch not ACL skip; External/Internal visibility; handler identity + scoped env |
| 016 | Abort Cascade for Nested Calls | call.aborted cascades to descendants; default abort-dependents, continue-running opt-in |
| 017 | Call Protocol Client and Adapter Contract | CallClient opens connections; from_call imports remote ops; connection direction independent of call direction |
| 022 | Handler Registration, Provenance, and Composition Authority | Registration bundle carries provenance, composition authority, scoped env, capabilities |
| 023 | Operation Error Schemas | Operations declare domain errors; call.error carries typed details; adapter fidelity |
| 024 | Operation Registry Layering | Curated (static) + session/connection overlays (dynamic); OperationEnv as trait-object integration point; OperationContext.env split into scoped_env (data) and env (dispatch trait) |
| 028 | AccessControl) |
|
| 029 | Peer-Graph Routing Model | Peer-keyed overlays + PeerRef routing; AccessControl-based peer authorization; retires remote_safe/trusted_peer |
| 030 | PeerEntry and Identity.id Decoupling | PeerId source = Identity.id = PeerEntry.peer_id (stable); supersedes ADR-029's UUID source |
| 032 | Forwarded-For Identity | forwarded_for on OperationContext and call.requested; metadata only, never used by AccessControl::check |
| 033 | Storage Boundary and Repo/Adapter Pattern | Core defines repo traits + in-memory defaults; persistence adapters are separate crates |
Relevant Open Questions
| OQ | Title | Status | Relevance |
|---|---|---|---|
| OQ-07 | Call protocol scope within a connection | resolved (ADR-012) | Stream model, multiplexing, scope |
| OQ-13 | Operation path format and routing scope | resolved | /{service}/{op} is the correct design; remote dispatch is a separate layer |
| OQ-14 | Batch operation semantics | resolved | Correlated call.requested events is the correct protocol design |
| OQ-16 | Safe vault operations for call protocol exposure | resolved (ADR-014) | None exposed for now |
| OQ-19 | Session-scoped operation registries | resolved | Agent-written operations overlaid on curated registry via OperationEnv trait layering. Protocol doesn't need changes; OperationEnv must remain a trait. Generalized by ADR-024 to cover connection-scoped overlays. |
| OQ-25 | dissolved (ADR-029) | remote_safe/trusted_peer retired; peer authorization is AccessControl::check(peer_identity) |
|
| OQ-26 | OperationAdapter error type (AdapterError variants) | resolved | DiscoveryFailed, SchemaParse, Transport, Unauthorized, SamePeerCollision; #[non_exhaustive] |
| OQ-27 | from_call re-import trigger | resolved | Auto-re-import on connection establishment; refresh() is a feature addition |
| OQ-28 | from_call namespace collision | resolved | Same-peer collision = error; cross-peer dissolved by ADR-029 (separate sub-overlays) |
| OQ-29 | CallClient TLS client-auth | resolved | Wire quinn client-auth; key-type-aware server cert verification; fingerprint normalization |
| OQ-30 | PeerRef::Any routing policy |
resolved | Insertion-order first-match; richer routing is a feature extension |
| OQ-31 | services/list-peers re-export semantics |
resolved | Opt-in services/list-peers; services/list is "own ops only" |
| OQ-32 | Multi-hop federation | open (feature extension) | One-hop model is the commitment; multi-hop is a feature extension, not a deferral |
| OQ-33 | PeerId — crypto identity vs stable logical id | resolved (ADR-030) | PeerId = Identity.id = PeerEntry.peer_id (stable across key rotation) |
| OQ-34 | Persistent peer registry | resolved (ADR-030+033) | Core trait + in-memory default; persistence adapters are separate crates |
| OQ-35 | dissolved | PeerEntry supports multiple credential paths; ApiKeyEntry is for tokens that ARE the identity |
|
| OQ-37 | X.509 outgoing-only case | resolved (ADR-034) | Three remote roles (public X.509 endpoint, transport relay, hub); PeerEntry asymmetry correct; verifier by PeerEntry presence |
Key Design Principles
- One connection, full access: An
alknet/callconnection gives access to the entire operation registry — calls, subscriptions, batch, schema. - Protocol is symmetric: Both sides can initiate calls. The server calling a client uses the same EventEnvelope format and correlation.
- Stream-agnostic correlation: PendingRequestMap correlates by request ID, not by stream. The protocol works with any stream arrangement.
- Operation registry is layered: The curated layer (
Localprovenance) is static — registered at startup by the CLI binary, immutable for the process lifetime. Session (Session) and imported (FromCalletc.) ops are dynamic overlays at their respective scopes (per-session, per-connection). The registry supports JSON Schema discovery. See ADR-024. - irpc is one dispatch backend: Local operations dispatch directly. irpc service calls (in-process, type-safe) are internal. The call protocol is the external interface.
- Local dispatch only: The operation registry dispatches to local handlers. Remote dispatch (federation, head/worker routing) would be a separate mechanism at a different layer, not a modification to alknet-call's path format.
- No secret material on the wire: The call protocol carries no private keys, API keys, mnemonics, or decrypted credentials. Handlers receive outbound credentials through
OperationContext.capabilities, injected at the assembly layer. See ADR-014. - Abort cascades to descendants:
call.abortedfor a parent request cascades to all non-terminal descendants. Defaultabort-dependents;continue-runningopt-in. See ADR-016. - Internal calls switch authority context, not skip ACL: The
internalflag marks composition-originated calls. ACL runs against the handler's composition authority, not the caller's and not as a blanket skip. Operations have External/Internal visibility. Scoped composition env bounds reachability. See ADR-015, ADR-022. - Provenance determines composition capability: Only
LocalandSessionops can compose. Leaves (FromOpenAPI,FromMCP,FromCall) are forwarding stubs — they don't get composition authority or a scoped env. The assembly layer is the sole grantor of composition authority. See ADR-022. - Connection direction is independent of call direction: Who opens the QUIC connection is a connection-layer concern, not a protocol-layer concern. Both sides can call each other once connected. The
CallAdapteraccepts connections; theCallClientopens them; both produce the sameCallConnectionand dispatch through the same loop. See ADR-017, client-and-adapters.md. - Peer authorization via
AccessControl: A remote peer's call is authorized byAccessControl::check(peer_identity)against the op'sAccessControl— the same mechanism that gates every other call. Noremote_safeflag, notrusted_peerbypass. An op withAccessControl::default()is callable by any peer; an op withrequired_scopesis callable only by peers whoseIdentity.scopessatisfy them; an op withVisibility::Internalis never callable from the wire. See ADR-029. - Adapter trait lives with the types; implementations live with their transport:
OperationAdapteris inalknet-call;from_call/from_jsonschemaare inalknet-call(QUIC / pure parse);from_openapi/from_mcp/to_openapi/to_mcpare inalknet-http(reqwest / axum).alknet-callstays lean — no HTTP client, no HTTP server. See client-and-adapters.md. - No handler reads outbound credentials from any source other than
OperationContext.capabilities(no-env-vars invariant): the credential injection path is vault → assembly layer →Capabilities→HandlerRegistration.capabilities→OperationContext.capabilities→ handler. Downstream consumers'std::env::varreads are unreachable because the assembly layer never callsDefault::default(). See ADR-014, client-and-adapters.md.