docs(http): draft alknet-http architecture specs and ADRs 036-039
First speccing pass for alknet-http (HTTP interface crate: h2/http1.1/h3 server + from_openapi/to_openapi/from_mcp/to_mcp adapters). Specs (crates/http/): - README.md, overview.md — crate index, two-roles-in-one-crate framing, adapter location map, feature gates (h3, mcp), no-env-vars invariant - http-server.md — HttpAdapter for h2/http1.1, axum over QUIC stream, Bearer auth, SSE projection for subscriptions, /healthz, stealth decoy - http-adapters.md — from_openapi (reqwest) and to_openapi (projection), error fidelity (HTTP_<status> per ADR-023), type definitions - http-mcp.md — from_mcp/to_mcp (feature-gated), streamable-HTTP-only - webtransport.md — h3/WebTransport handler, browser streaming path, HTTP/3 request vs WebTransport session distinguished at framing layer ADRs: - ADR-036 HTTP-to-Call Operation Mapping (Proposed) — direct path mapping; to_openapi is projection, not router (the load-bearing one-way door from Phase 0 DH-3) - ADR-037 MCP Stdio Transport Exclusion (Proposed) — streamable HTTP only; stdio is not built (RCE-vector security position) - ADR-038 HTTP/3 and WebTransport as First-Class HTTP Transports (Proposed) — corrects the Phase 0 DH-2 deferral framing; h3 is in scope, not deferred, per ADR-009 §'What this framework is NOT' - ADR-039 HTTP Server and Client Host Colocated in alknet-http (Proposed) — one crate for server + client host (shared HTTP deps, shared operation-spec->HTTP mapping) - ADR-003 Amendment 1 — clarifies alknet-call is a protocol-foundation crate (the alknet-http -> alknet-call dependency edge) Open questions (OQ-38, OQ-39, OQ-40 added under 'Theme: alknet-http'): - OQ-38 WebTransport relay-as-proxy scope (genuine scope question, not a deferral — the decision is made when the use case becomes concrete) - OQ-39 to_openapi published-spec versioning (one-way after first publication) - OQ-40 reqwest client config and connection pooling (two-way-door) Architecture README and overview updated with doc table, ADR table (036-039), current-state note, and crate graph (alknet-http -> alknet-call edge). Reviewed by architecture-reviewer subagent: 3 critical, 4 warning, 5 suggestion issues found and fixed (missing ADR-039, WebTransport stream routing conflation, undefined types, stale OQ-37 deferral language, README OQ table completeness, Bearer-only attribution, cross-references, ADR-038 ALPN quote, feature-gate placeholder, MCP temporal language).
This commit is contained in:
@@ -72,4 +72,31 @@ alknet-napi is a thin projection layer — it exposes the Rust call protocol cli
|
||||
- ADR-001: ALPN-based protocol dispatch
|
||||
- ADR-002: ProtocolHandler trait
|
||||
- ADR-004: Auth as shared core (IdentityProvider)
|
||||
- ADR-005: irpc as call protocol foundation
|
||||
- ADR-005: irpc as call protocol foundation
|
||||
|
||||
## Amendments
|
||||
|
||||
### Amendment 1 (2026-06-29): `alknet-call` is a protocol-foundation crate
|
||||
|
||||
The Decision table lists `alknet-call` as a handler crate that "depends
|
||||
on alknet-core, irpc." The dependency-flow diagram and the "No handler
|
||||
crate depends on another handler crate" rule were written before
|
||||
`alknet-http` (which implements `from_openapi`/`from_mcp`/`to_openapi`/
|
||||
`to_mcp` and therefore needs `alknet-call`'s `OperationSpec`, `Handler`,
|
||||
`HandlerRegistration`, and `OperationAdapter` trait) was specced.
|
||||
|
||||
**Clarification:** `alknet-call` is both a handler crate (it implements
|
||||
`ProtocolHandler` on ALPN `alknet/call`) *and* the protocol-foundation
|
||||
crate that `alknet-agent`, `alknet-napi`, and `alknet-http` consume for
|
||||
the operation registry, adapter contract, and call client. The "no
|
||||
handler crate depends on another handler crate" rule applies to peer
|
||||
handler crates (e.g., `alknet-http` does not depend on `alknet-ssh`);
|
||||
`alknet-call` is a protocol-foundation crate in the same spirit that
|
||||
`alknet-core` is, just at a different layer (operations/RPC vs.
|
||||
transport/auth/config).
|
||||
|
||||
`alknet-http` depending on `alknet-call` is "HTTP uses the call protocol
|
||||
types," not "HTTP depends on SSH." This is within the spirit of this
|
||||
ADR's decomposition. The `alknet-call` → `alknet-http` edge is recorded
|
||||
in the `alknet-http` spec (`crates/http/overview.md`) and in the adapter
|
||||
location map (`crates/call/client-and-adapters.md`).
|
||||
Reference in New Issue
Block a user