feat(infra): full-surface integration suite + docs sync + publish prep

Full-surface integration suite (tests/full_surface.rs, mcp feature):
- one HttpAdapter over real TCP (ProtocolHandler::handle path) serving
  gateway endpoints, /openapi.json, /mcp, and the WS channels session
- gateway: search/schema/call/subscribe/batch/publish presence,
  envelope shapes, error fidelity end-to-end
- from_openapi import -> Internal-by-default invisible from the wire ->
  External facade composes it via env.invoke -> upstream HTTP API
  called end-to-end (ADR-015 composition model exercised)
- to_openapi 6-path doc validated against openapiv3 over the wire
- to_mcp: MCP client connects to /mcp on the served adapter, lists the
  4 gateway tools, search returns ACL-filtered ops (Sub excluded)

Production fix: the WS upgrade route was reserved but never wired into
HttpAdapter's router (the ws-upgrade-session tests built their own
router). Now wired with ws_bearer_auth (401 without a resolvable
token) around ws_upgrade_handler.

Docs sync: all 28 'Port notes' sections/blockquotes stripped from
ported ADRs/specs; OQ-01/OQ-02 statuses corrected to resolved in
overview.md, websocket.md, and the README table (open-questions.md was
already current).

Publish prep: cargo publish --dry-run --allow-dirty succeeds;
cargo doc --no-deps warning-free (ADR link targets fixed); feature
combinations (default / test-support / mcp / wss / all) compile
warning-free under clippy -D warnings.

Verified: cargo test (182 lib default), --all-features (227 lib + 29
integration), clippy -D warnings x3 feature sets, fmt, doc,
publish --dry-run.
This commit is contained in:
2026-08-28 16:07:56 +00:00
parent bc99ec7188
commit 4a825d33e7
41 changed files with 700 additions and 1035 deletions
@@ -306,46 +306,3 @@ to `to_openapi` or its versioning.
unchanged; it moves from the HTTP path to the `/call` request body
- `docs/architecture/http-server.md` — this crate's spec whose router
surface this ADR narrows to the gateway endpoints
## Port notes
- Renames: "alknet-http" → alkhttp throughout (crate name, shipped-vs-
specced status, threat-model and default-contract references).
- **Gateway endpoint count (extension note, never silently rewritten):**
the original decision text says "the 5 fixed gateway endpoints"
(`/search`, `/schema`, `/call`, `/batch`, `/subscribe`) throughout.
In alkhttp, alkcall ADR-046 (`Pub` operation type) motivated a sixth
gateway endpoint, `/publish` (producer→consumer streaming; newline-
delimited JSON request body; final `ResponseEnvelope` as the HTTP
response), recorded in this crate's ADR-068. A block-quote extension
note at the top of §Decision states the 6-endpoint contract and marks
the "5 endpoints" phrasing below it as retained decision history;
the original text is otherwise verbatim. The stealth-decoy clause §3
retains the original 5-path enumeration for the same reason.
- **`Subscription``Sub`** (§2's method-mapping sentence; alkcall
rename of the `OperationType` value).
- **Producer/consumer terminology**: §3 abort-cascade bullet "An HTTP
client disconnecting mid-`/subscribe`" → "An HTTP consumer
disconnecting mid-`/subscribe`" (call-protocol role framing; the
abort-cascade citation is alkcall ADR-020). HTTP server/client
phrasing elsewhere is HTTP-inherent and untouched (`HttpAdapter`
serves; HTTP clients call).
- **Cross-refs**: `../../decisions/...``decisions/...`. ADR-036 and
ADR-042 are ported to this crate under their alknet numbers/slugs and
linked (`decisions/036-http-to-call-operation-mapping.md`,
`decisions/042-openapi-gateway-pattern.md`); ADR-044/045/046 are
ported under the same numbers and linked directly. The source's
alknet ADR-023 (error schemas) citation is remapped textually to the
alkcall crate's ADR-016 (`decisions/016-operation-error-schemas.md`);
the alknet ADR-016 (abort cascade) citation is remapped to alkcall
ADR-020. The new-ADR link `decisions/068-gateway-publish-endpoint.md`
uses the alkhttp slug for ADR-068 (the alknet ADR-068 is an unrelated
hub decision and is not referenced here).
- `crates/http/http-server.md``docs/architecture/http-server.md`
(this crate's docs/architecture/).
- No frontmatter in the source; status kept as Proposed.
- No decision content changed — the sole-invoke-path decision, the
method-semantics move, the "what survives" list, the custom-routes
escape hatch, the `to_openapi` unchanged clause, and the
consequences/assumptions are verbatim from the alknet ADR modulo the
renames and the logged six-endpoint extension note.