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
-64
View File
@@ -645,67 +645,3 @@ See [open-questions.md](open-questions.md) for full details.
- `melotic/reqwest-retry-after`
(https://github.com/melotic/reqwest-retry-after) — `RetryAfterMiddleware`
source (MIT, inlined, not a dependency)
## Port notes
Corrections applied during the alknet → alkhttp port, beyond mechanical
crate renames (`alknet-http` → `alkhttp`; `alknet-call`/`alknet-core` →
`alkcall`, with the adapter contract in `alkcall::client`, registry
types in `alkcall::registry`, core in `alkcall::core`):
1. **Gateway is now 6 endpoints.** `/publish` (POST, Pub operations;
request body streamed as newline-delimited JSON, each line one
published chunk) added per alkhttp ADR-068
(`decisions/068-gateway-publish-endpoint.md` — slug assumed; the ADR
file does not exist yet). All "5 fixed endpoints" tables/phrasing
updated to 6; the MCP-gateway exclusion now covers both `/subscribe`
and `/publish` (the "one endpoint the MCP gateway excludes" claim
from the source extended accordingly).
2. **`OperationType::Subscription` renamed `Sub`** (alkcall rename);
`OperationType::Pub` exists (producer→consumer streaming,
`HandlerKind::Sink`, wire event `call.published` — alkcall ADR-046).
The Query/Mutation/Sub detection mapping from OpenAPI is kept, with a
one-line note that Pub ops are not produced by `from_openapi` (no
OpenAPI representation in v1). The `/publish` gateway row is the only
Pub surface in this doc.
3. **ADR cross-reference remapping.** Call-protocol-internal decisions
now live in the alkcall crate and are cited textually (no relative
links across crates): old ADR-017 adapter contract → alkcall ADR-022;
old ADR-022 handler registration → alkcall ADR-018 (§6 mapping
preserved); old ADR-023 error schemas → alkcall ADR-016 (§5 mapping
preserved); old ADR-015 privilege model → alkcall ADR-017; old
ADR-049 streaming handler → alkcall ADR-021; Pub/`HandlerKind::Sink`
→ alkcall ADR-046; `from_jsonschema` provenance → alkcall ADR-027.
alkhttp-owned ADRs keep their numbers and are linked relatively:
014, 036, 041, 042, 045, 047, 051, 066 (ADR-036's port to alkhttp is
assumed — it is an HTTP-surface decision, consistent with the
other gateway/server ADRs).
4. **Old ADR-035 reference (hot-reload pattern) had no verified
mapping.** The source cited alknet ADR-035 (Concrete Persistence
Adapter Shapes) for the `ConfigIdentityProvider` `ArcSwap`
rebuild-and-swap pattern; that ADR has no direct alkcall/alkhttp
counterpart. Replaced with a textual pointer to the alkcall crate's
ADR-006 (AuthContext Structure — documents the
`ArcSwap<DynamicConfig>` reload) and ADR-025 (PeerEntry and
Identity.id Decoupling — introduces `ConfigIdentityProvider`).
Flagged as an inference, not a verified mapping.
5. **Producer/consumer terminology.** Remaining "server"/"client"
wording is deliberately retained where OpenAPI's inherent
client/server directionality is meant (that directionality is a
property of the OpenAPI protocol, not the call protocol) and for the
HTTP server / external HTTP API server (transport roles, not
call-protocol roles). No call-protocol server/client framing remains.
6. **Links.** `../../decisions/` → `decisions/`;
`../../open-questions.md` → `open-questions.md` (sibling, pending
port); `../call/client-and-adapters.md` → textual reference to the
alkcall crate's `docs/architecture/client-and-adapters.md`; the
mono-repo research findings path is kept as a textual absolute path.
`overview.md` and `http-mcp.md` are sibling links to docs pending
port.
7. **WebTransport/h3.** The source document contained no h3/WebTransport
references, so no "out of scope in alkhttp (ADR-069)" replacements
were needed.
8. **Project naming.** "how alknet composes/discover the alknet
operation surface" → "the alk stack" in the Why section prose.
Everything else (decision content, structure, section order,
rationale) is preserved verbatim from the source.