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:
@@ -130,10 +130,11 @@ Once published, the gateway endpoint set (5 endpoints) and the
|
||||
request/response shapes are a compatibility contract (ADR-017
|
||||
Consequences). Adding endpoints is additive (non-breaking); removing or
|
||||
renaming is a one-way door. The initial 5-endpoint set is the published
|
||||
contract. The versioning strategy for the generated doc is tracked as
|
||||
OQ-39 (same as the per-operation-paths versioning question — the
|
||||
gateway pattern doesn't eliminate the versioning concern, it simplifies
|
||||
it to 5 stable endpoints instead of a per-operation surface).
|
||||
contract. The versioning strategy for the generated doc was tracked as
|
||||
OQ-39 (now **resolved by [ADR-045](045-to-openapi-gateway-spec-versioning.md)**:
|
||||
`info.version` semver tracks the gateway endpoint contract, not the
|
||||
operation set) — the gateway pattern simplifies versioning to 5 stable
|
||||
endpoints instead of a per-operation surface.
|
||||
|
||||
### 5. A traditional per-operation-paths projection is additive, not replacement
|
||||
|
||||
@@ -244,5 +245,6 @@ require it for the common case.
|
||||
pattern for `to_mcp` (4 tools; `subscribe` excluded because MCP tool
|
||||
calls are request/response)
|
||||
- OQ-39 — `to_openapi` published-spec versioning (simplified by the
|
||||
gateway pattern to 5 stable endpoints)
|
||||
gateway pattern to 5 stable endpoints; **resolved by
|
||||
[ADR-045](045-to-openapi-gateway-spec-versioning.md)**)
|
||||
- `crates/http/http-adapters.md` — the spec that implements the gateway
|
||||
Reference in New Issue
Block a user