docs(http): resolve OQ-39; add ADRs 045-047; record pubsub prior art for WS path

OQ-39 (to_openapi published-spec versioning) resolved by ADR-045:
info.version semver tracks the gateway endpoint contract, not the
operation set — per-caller operations discovered via /search do not
bump the version. The gateway pattern (ADR-042) dissolved most of the
original churn concern.

ADR-046: assembly-layer custom HTTP routes on HttpAdapter. The HTTP
router had no documented extension point for deployment-specific
endpoints (e.g., an OAI-compatible proxy at /v1/chat/completions). Adds
extra_routes: Option<Router> at construction; raw HTTP, not operations;
default surface takes precedence on collision. The mechanism is the
one-way door; specific routes are two-way.

ADR-047: remove the direct-call POST /{service}/{op} HTTP surface. The
gateway /call is the sole invoke path — the simplified contract is a
few fixed endpoints, not a per-operation REST tree. The direct-call
surface re-introduced the 'dump the full API regardless of privs'
failure mode at the HTTP level that the gateway /search was built to
escape. ADR-036's routing decision is superseded; its non-routing
clauses (SSE, Bearer auth, /healthz, stealth, error mapping) survive.
A deployment wanting a REST-like per-operation surface builds it as a
custom route projection (ADR-046).

ADR-044 updated with the tradeoff framing (WSS is the right tool for
the call-protocol-from-browser case; WebTransport is the right tool for
the generalized ALPN-stream-proxy case we don't have yet — coexist, not
migrate) and the @alkdev/pubsub concrete prior art (the EventEnvelope
{type,id,payload} the call protocol was derived from already has a
working WebSocket client/server; the sync is a small adjustment, not a
from-scratch build).

call-protocol.md references the pubsub lineage for the
transport-agnosticism claim.
This commit is contained in:
2026-06-30 09:49:25 +00:00
parent 3327d585da
commit 2a6e4c371a
14 changed files with 1082 additions and 129 deletions

View File

@@ -59,13 +59,13 @@ enabled. It serves two things on a single `h3` connection:
1. **HTTP/3 requests** — the standard HTTP/3 over QUIC framing. An
HTTP/3 request is dispatched through the same axum `Router` as `h2`/
`http/1.1` requests (ADR-036 — the HTTP path IS the operation path
on the direct-call surface; ADR-042 — the gateway endpoints). From
the axum router's perspective, an HTTP/3 request is just
another HTTP request; the framing difference is handled below the
router. The HTTP/3 request path is the **one-directional projection**
(client→server calls only — HTTP is request/response; see
[http-server.md](http-server.md) §"One-directional projection").
`http/1.1` requests (ADR-042 + ADR-047 — the gateway endpoints are
the sole invoke path; the direct-call `POST /{service}/{op}` surface
was removed). From the axum router's perspective, an HTTP/3 request
is just another HTTP request; the framing difference is handled
below the router. The HTTP/3 request path is the **one-directional
projection** (client→server calls only — HTTP is request/response;
see [http-server.md](http-server.md) §"One-directional projection").
2. **WebTransport sessions** — the **bidirectional** path. WebTransport
is a transport substrate that carries ALPN protocols as
bidirectional streams (ADR-043), not a browser→hub one-way path. A