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
@@ -11,20 +11,17 @@ changes)
## Context
> **Port note (scope):** This ADR is ported because it is the decision of
> record for the browser-facing TLS constraint this crate inherits:
> **browsers require X.509** — they cannot present or verify RFC 7250 raw
> Ed25519 keys, so the browser-reachable surface of alkhttp (`http/1.1`,
> `h2`, and the WebSocket upgrade path) must be served from an X.509
> identity (CA-issued via ACME, or operator-provided). The TLS machinery
> itself — `TlsIdentity`, `TlsSetup`, ACME provisioning, the rustls
> server config — is **not implemented in this crate**; alkhttp is
> transport-coupling-free by design (alknet ADR-027's alknet-internal
> sections describe the alknet endpoint layer, which remains an alknet
> concern; see §Port notes at the end of this file). The clauses below
> that matter to alkhttp are the browser constraint and the identity
> modes it implies; the alknet-internal provisioning mechanics are
> retained for provenance and marked as alknet concerns.
**Scope for this crate:** This ADR is the decision of record for the
browser-facing TLS constraint this crate inherits: **browsers require
X.509** — they cannot present or verify RFC 7250 raw Ed25519 keys, so the
browser-reachable surface of alkhttp (`http/1.1`, `h2`, and the WebSocket
upgrade path) must be served from an X.509 identity (CA-issued via ACME,
or operator-provided). The TLS machinery itself — `TlsIdentity`,
`TlsSetup`, ACME provisioning, the rustls server config — is **not
implemented in this crate**; alkhttp is transport-coupling-free by
design, and the TLS provisioning mechanics described below remain an
alknet concern (retained for provenance). The clauses that matter to
alkhttp are the browser constraint and the identity modes it implies.
OQ-12 marked "resolved" identified two TLS identity use cases: RFC 7250
raw Ed25519 keys (default, P2P) and X.509 certs (domain-hosted, browsers).
@@ -333,7 +330,7 @@ in the endpoint layer where it belongs.
- OQ-12 (TLS identity provisioning) — updated by this ADR *(alknet OQ)*
- alknet ADR-010 — multi-connectivity endpoint, feature-gated
transports; the ALPN router and endpoint that owns TLS identity and
dispatch (an alknet decision; not ported to alkhttp — see Port notes)
dispatch (an alknet decision; not ported to alkhttp)
- alknet ADR-004 — auth as shared core (an alknet decision; ported to
alkhttp as alkhttp ADR-004, same number, different scope)
- `docs/architecture/crates/core/endpoint.md` *(alknet doc)* — TLS identity use cases
@@ -344,31 +341,3 @@ in the endpoint layer where it belongs.
requirement load-bearing for this crate
- alkhttp ADR-034 — browsers are not peers; the public X.509 endpoint
role and the hub role in the peer model
## Port notes
- All TLS provisioning mechanics (`TlsIdentity`, `TlsSetup`,
`build_rustls_server_config`, `AcmeState`, the `acme` feature, the
`acme-tls/1` dispatch guard) are **alknet concerns** — they live in the
alknet endpoint/config layer (alknet ADR-010, ADR-001), not in
alkhttp. alkhttp is transport-coupling-free (no TLS, no endpoint, no
accept loop); sections describing them are marked *"(alknet
concern)"* inline and retained for provenance. The clause that is
substantive for alkhttp — **browsers require X.509 for browser-facing
TLS** — is restated under "What alkhttp inherits from this decision."
- `alknet-core` ownership of `Ed25519SecretKey` is historical: the core
types now live in the alkcall crate (vendored there). The decision
text is preserved as written; the wrapper type is an alkcall-owned
type today.
- Reference links rewritten per alkhttp docs conventions: the original
relative sibling-ADR links to alknet ADR-010 and alknet ADR-004 are
textual references above (neither is ported to alkhttp under those
numbers/slug; alkhttp ADR-004 is a different document — auth as
shared core). The `crates/core/*.md` spec links are dropped in
favor of the textual "alknet doc" annotations because the alknet spec
tree is not part of this crate's docs.
- The original ADR-083 is an alknet decision (shared `dispatch` guard
relocation); it is cited textually as "alknet ADR-083" and is not
ported.
- Original title preserved: "TLS Identity Redesign — ACME Integration +
RawKey Decoupling".