Bump the alkcall dependency to 0.2 (with the gateway feature) and
converge on the promoted shared pieces:
- The local dispatch spine (gateway/dispatch.rs, 721 lines) is deleted;
GatewayDispatch, schema_disclosure_denial, and DEFAULT_DEADLINE are
re-exported from alkcall::gateway (alkcall ADR-048). The 30 s default
deadline preserves the previous behavior exactly.
- gateway/schema_cache.rs (PublishSchemaCache) is deleted: alkcall CF-003
compiles publish_schema at registration time and exposes
OperationRegistry::publish_validator; the /publish chunk stream
resolves against it. Un-compilable schemas are now rejected at
registration, so the two end-to-end fail-closed tests were reworked
into a registration-rejection test (a stronger guarantee).
- schema_disclosure_denial consumers (to_mcp, routes) use alkcall's
promoted implementation; the alkhttp-local copy is gone (ADR-071
updated: the guard stays as defense-in-depth, the implementation no
longer forks).
- CF-001: from_wss drop monitor and the WS overlay tests use
CallError::connection_closed; the review-001-ws-eof-signal race tests
now assert retryable CONNECTION_CLOSED on both resolution paths (the
tolerated non-retryable INTERNAL write-failure outcome is gone).
- Added CHANGELOG.md (Keep a Changelog), Unreleased section records the
bump and convergence.
Verification: cargo test default 453 ok, wss 470 ok, mcp 526 ok,
all-features 575 ok; clippy -D warnings clean (default + all-features,
all-targets); fmt clean; cargo doc warning-free.
Net: -1093 lines.
Decision: advertise == enforce. The key allowlist (OAI-02) stays as the
first gate with its established unknown-key message; a compiled leaf
validator now runs second, so required/type/enum/pattern/bounds
violations surface as INVALID_INPUT 422 naming the keyword — not as
upstream round-trips.
- new src/adapters/input_validation.rs: CompiledInputSchema compiles an
op's input_schema once at import with the jsonschema crate (same
2020-12 dialect publish_schema uses) and validates peer input at call
time; the compile-time copy is hardened closed-by-default
(additionalProperties: false injected when absent) so the validator
reproduces the allowlist's unknown-key semantics; explicit
additionalProperties:true catch-all and schema values are preserved;
the original spec value is never mutated
- from_openapi/from_jsonschema import(): compile per registration,
capture the validator in the handler closure (re-import recompiles —
the closure capture is the invalidation story); a non-compilable
input schema fails import loudly (AdapterError::SchemaParse naming
the operation), matching the publish_schema fail-closed precedent
- from_openapi generated input schemas now carry
additionalProperties:false explicitly, so the /schema advert states
the enforced rule and external schema-driven validators reach the
same verdicts
- forward/forward_stream/build_request gain an
Option<&CompiledInputSchema> parameter; enforcement runs after the
allowlist
- round-trip test (review 002 Test-gap 10): the /schema-exported
input_schema is compiled with the same validator and driven against
build_request over a 10-input violation matrix — accept-sets exactly
equal in both directions; the chain-test that lets advertise/enforce
drift surface as a CI failure
- ADR-066: new decision section (advertise==enforce) with the trust-
boundary reasoning and the rejected option (b) rationale
- module + enforce_input_schema docs updated to the two-gate shape
cargo test --all-features 596 pass; clippy --all-features/-D warnings,
fmt, doc gates clean.
docs(tasks): mark review-002-fu-oai18-decision done
- forward_stream build-error arm (forward.rs): wire-level test asserts
one INVALID_INPUT envelope then stream end with zero upstream
contact (a panicking responder counts as the contact guard), plus
the from_jsonschema integration mirror (undeclared key + non-scalar
placeholder, each naming its rejection source)
- PEM read-failure arms (http_client.rs): nonexistent CA path →
CaBundleRead (sync new), nonexistent client-cert path → ClientCertRead
(async reload, prior generation retained)
- Over-cap poll_write rejection leg (byte_adapter.rs): cap+1 write →
InvalidData naming the cap; stream stays usable for an at-cap write
afterwards
- SSE parser edges: CRLF split across feed chunks frames one line;
invalid-UTF8 data lines drop without killing the frame stream
- from_value structural rejects: non-object doc, missing `info`,
missing `paths`, non-object `paths` each name the member
- Connection-failure arms: accept-path ConnectionClosed →
HandlerError::ConnectionClosed via stream_error_to_handler; read-pump
demux-gone break ends the pump when the byte-stream side is dropped
- Delete the caller-less `impl Default for WsTimeouts` (the extension
is constructed explicitly)
cargo llvm-cov --all-features: all named arms covered; TOTAL regions
94.18% (was 93.86%), lines 96.04% (was 95.77%); http_client.rs
86.56% lines (was 81.72%).
docs(tasks): mark review-002-fu-stream-error-coverage done
- dispatch.rs: qualify [invoke]/[invoke_streaming] as
[GatewayDispatch::invoke]/[::invoke_streaming] (module-level docs
need the type-qualified path)
- byte_adapter.rs: drop redundant explicit link targets for
DEFAULT_WS_WRITE_TIMEOUT / DEFAULT_WS_IDLE_TIMEOUT (already
re-exported at crate::websocket)
- from_wss.rs, byte_adapter.rs: backtick WssSession::drop and the
private WsFraming (all-features-only link errors, same class)
- Ws pump/timeout module docs spot-checked against WS-13/18/17 impls:
no drift found
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps now exits clean both
default-features and --all-features.
docs(tasks): mark review-002-fu-doc-warnings done
The bracketed planning task's five candidates, re-validated against
the post-bulk tree (0a932e5, all 23 bulk tasks done, 446/568 green):
1. OAI-18 -> review-002-fu-oai18-decision: still key-allowlist-only;
bulk blockers (yaml/path-item) both landed. Task records the
enforce-vs-scope-the-advert decision framework from review 002.
2. CON-08/CON-09 close() lever: deferred still (documented v1
contracts unchanged, no consumer pressure) — not tasked.
3. Cross-crate: CF-001..004 all open in alkcall, no alkhttp-side task;
PRJ-16 guard already documents its defense-in-depth re-scope
disposition (no work when CF-004 lands).
4. Stale-comment sweep: mostly absorbed by the bulk (SRV-11 comment
rewritten in-fix); residue = 3 cargo-doc warnings + WsTimeouts
redundant Default -> review-002-fu-doc-warnings.
5. ADR-045 version audit: clean (1.4.0 + annotations + test pin).
Post-bulk coverage re-pass (95.89% regions, bulk's new code fully
covered: PRJ-16 guard, body cap, router reorder, batch cap, WS
knobs, OAI-11 node budget all exercised) surfaced one unanticipated
residue -> review-002-fu-stream-error-coverage (forward_stream
build-error arm never exercised on a Sub op; PEM read-failure arms;
over-cap poll_write; SSE split-CRLF edge; from_value structural
rejects; WsTimeouts Default).
Bracketed pass itself marked completed (planning consumed).
taskgraph: 69 valid, no cycles; 3 pending.
- build_error_schemas: default/wildcard response keys dropped with a
warn instead of emitting a dead HTTP_0 ErrorDefinition — /search
never advertises a code that can't match (the runtime mapper already
synthesizes HTTP_<actual> for unmapped statuses)
- check_parameter_style: non-default style/explode parameter forms
(spaceDelimited, pipeDelimited, deepObject, form+explode:false,
simple+explode:true) fail import with a feature-naming SchemaParse;
wire-equivalent defaults (form, simple) import unchanged — no more
silent "[1,2]" array mis-serialization
- servers overrides rejected at import at all three levels (document,
path, operation) — the adapter pins one base_url at assembly time
- trace-only paths: skip is now logged (warn naming path + methods),
documented-as-inert instead of silent
- detect_op_type + build_output_schema sweep 2XX/default keys for
text/event-stream — a default-declared SSE stream classifies as Sub
instead of returning one giant text body
Tests: 11 new (error-drop, style rejections + default accept, servers
3-level rejections + baseline, trace skip, SSE default/2XX detection).
Verified: cargo test (299), --all-features (370 + suites), clippy
--all-targets -D warnings (default + all-features), fmt --check.
Tasks: review-001-openapi-loud-degradation
- new gateway::schema_cache — PublishSchemaCache: compile the op's
publish_schema once per registration (value-keyed invalidation for
hot reload), cache compile failures (logged once at error level,
never retried per request)
- /publish compile failure is now fail-closed: the chunk stream
terminates with INTERNAL (500), the error text stays in the log
(no schema internals on the wire) — the per-request warn-and-skip
unvalidated ingest path is removed
- schema resolution is lazy (first chunk poll, after invoke_sink's
404/403/422 pre-checks — GW-11 order preserved) and keyed by schema
value, so re-registration/hot reload is picked up (test)
- NdjsonChunkStream: first Err item is terminal (done + stream end),
mirroring the wire pump's send(Err) + break — Ok chunks can never
follow an error on the HTTP path either (found by spy-handler test)
Verified: cargo test (308), cargo test --all-features, clippy
--all-targets -D warnings (default + all-features), fmt --check.
Tasks: review-001-publish-schema-validation-robust
Found in the sweep of completed review-001 remediation:
- /publish schema validation fails open on compile error + recompiles
per request (remediation-introduced, routes.rs:254-268)
- OAI-06 loud-degradation unblocked and still open (HTTP_0 marker)
- HY-06 ExponentialBackoff in public API + COV-02 mTLS success path
both unblocked post client-config rework
- HY-02/04/11 publish-prep docs gate (104 missing-docs warnings
re-measured)
Also flagged, not tasked here: WS-12 (alkcall demux 4 GiB discard
alloc) was never actually filed in alkcall's consumer-findings-ledger —
only CF-001 is there. File it when next touching alkcall.
taskgraph: validate clean (42), no cycles
Record the v1 cut for browser-opened data channels over WS (review-001
WS-03): the design (ADR-067) stands; only the wiring is deferred.
- open-questions.md: add OQ-05 (deferred(scope: v1 cut)) with gap
detail and deferred scope
- ADR-067: dated status amendment + v1-cut note at the data-channel
step; References point to OQ-05
- ADR-048: dated reconciliation note — overlay bidirectionality is
decided design, not a v1 implementation commitment
- websocket.md: status notes on §"Data channels for browsers" and
upgrade step 7
- task review-001-ws-data-channel-decision: completed, Summary filled
Verification: taskgraph validate (38 tasks OK); cargo doc --no-deps
(pre-existing warnings only).
- build_request takes the op's input_schema and rejects undeclared
input keys (INVALID_INPUT) before any outbound request is built;
explicit `additionalProperties: true` opts into catch-all input;
non-object inputs rejected (OAI-02)
- in: header parameters are stamped `wire: header` in the generated
input schema and sent as upstream request headers, not query params;
in: cookie fails import with a clear error (OAI-03)
- a spec parameter named `body` is rejected at import unconditionally
(OAI-07)
- FromJsonSchema::new returns Result and validates method/path template/
base_url at construction; registered visibility forced to Internal
like from_openapi; module doc corrected (OAI-09)
Verified: cargo test, cargo test --all-features, clippy (both feature
sets, -D warnings), cargo fmt --check
- index components/parameters + requestBodies in OpenAPISpec; resolve
bare $ref parameter and requestBody entries through the cycle-guarded
resolver; unresolvable refs abort spec parse loudly
- reject path placeholders with no matching input-schema property at
registration (no more silently percent-encoded literal placeholders)
- reject duplicate operationIds and path+method routes in one import
batch instead of silent last-write-wins registration
- also reject a parameter named 'body' shadowed by requestBody (OAI-07
adjacency, same code path)
Verified: cargo test (243), --all-features (322), clippy -D warnings
(default + all-features), fmt --check, doc --no-deps
Add tests for the /mcp body cap and complete the task file.
- oversized POST /mcp with declared Content-Length > 8 MiB -> 413
before any body read
- oversized chunked POST /mcp -> 413 (counting-stream cut mid-body;
rmcp maps body errors to 500, so the middleware sources the status)
- normal-size initialize round-trip unchanged
- task file: status completed, Summary filled
Verified: cargo test (219), cargo test --features mcp --lib (257),
cargo test --all-features (269 + integration), clippy default and
--all-features (-D warnings), cargo fmt --check.
Replace per-chunk parse_sse_frames with SseParser holding raw bytes
across chunks: reassembles frames split at TCP boundaries (the review's
silently-losing case), decodes UTF-8 per complete line so multi-byte
chars split across chunks survive, caps the buffer at 1 MiB
(SSE_EVENT_BUFFER_CAP) and dispatches a pending event at EOF.
forward_stream threads the parser through its unfold state and emits a
terminal error envelope on cap overflow. Existing single-chunk SSE test
assertions preserved; added multi-chunk, split-UTF-8, EOF-dispatch, and
cap tests.
Verified: cargo test (219 pass), clippy -D warnings, fmt --check.
- apply bearer_auth_middleware route_layer AFTER the extra_routes merge,
so assembly-layer custom routes resolve the bearer token by default
(ADR-046 §4); per-route opt-out via the route's own layer remains
- enforce RESERVED_PATHS per-method at build time: a probe MethodRouter
occupied on all methods is pre-merged against extras, so a custom
POST /search panics like a same-method overlap (ADR-046 §3)
- tests: auth resolves through an extra route; an extra route with its
own layer opts out; reserved-path merge panics; non-reserved
different-method merge stays legal; MCP bearer-gate test stays green
- ADR-046 §3: one sentence restating the per-method rejection rule
Verification: cargo test (215) ok, cargo test --all-features (260 +
integration) ok, clippy -D warnings (default + all-features) ok,
cargo fmt --check ok.
- GW-01: /publish validates every NDJSON chunk against the op's
publish_schema (incl. the first-line chunk) via NdjsonChunkStream —
terminal Err(INVALID_INPUT)/422 on violation, matching the wire
dispatcher's per-chunk contract. Route-level fix; the alkcall spine
was explored and rejected (wire validation is pump-side by design).
- GW-06: the body is streamed, not buffered — Body::into_data_stream()
-> newline-framed BufferedLines -> lazily parsed chunk stream.
ADR-068 documents the streamed semantics and the 2 MiB per-line cap.
- GW-08: /batch capped at 100 operations (INVALID_INPUT 400).
- GW-09: internal-op batch entries now carry generated UUID request ids.
- GW-10: first publish line missing `chunk` is rejected INVALID_INPUT.
- GW-11: redundant /publish pre-checks removed; enforcement rides on
invoke_sink via the shared dispatch spine.
- HY-13: the vacuous stub test was replaced by a body-cut-short test.
- Adjacent: INVALID_OPERATION_TYPE now maps 422 (with identity) / 401
(without) in error.rs — the route relies on the shared mapper since
the pre-checks are gone (GW-03's finding; was a 500 fall-through).
Verification: cargo test 211 passed; cargo clippy --all-targets -- -D
warnings clean; cargo fmt --check clean.
resolve_refs_recursive recursed with no cycle detection and no depth
budget; a self-referential OpenAPI component stack-overflowed and
aborted the process (uncatchable, kills import()).
- add branch-scoped visited set on the JSON-pointer ref path: a ref
re-entering its own expansion chain errors cleanly with
AdapterError::SchemaParse naming the offending ref (OAI-01)
- add depth budget (MAX_REF_RESOLUTION_DEPTH = 64) bounding $ref hop
chains and schema nesting height; over-deep specs error cleanly
instead of exhausting the stack (OAI-01)
- clean loud error over depth-limited expansion: recursive schemas
(trees, linked lists, cursor pagination) fail import rather than
expand unboundedly
- shared refs to a common schema (diamond/repeated) still resolve —
visited set is branch-scoped, not global
- OAI-08: replace the two guarded expects in from_value
("paths is object", "schemas is object") with if-let paths
Verification: cargo test 188 passed / 0 failed; clippy
--all-targets -D warnings clean; fmt --check clean
21 review-001 tasks across server/adapters/client/gateway/websocket/infra,
chunked from the 7-unit remediation plan in
docs/reviews/001-initial-implementation-review.md.
- Scope split by mechanism, not one-per-finding: 15 tasks in generation 1
(parallelizable), 6 sequenced after their file-sharing precursors
- Deliberately deferred until dependent fixes land: projection/doc
fidelity partial (Unit 6 beyond dependency hygiene), coverage backfills
(COV-01..07 via in-task acceptance for forward.rs), and per-finding
minors (OAI-06/07, HY-02/04/06/10/11, CON-08)
- Cross-crate WS-12 (alkcall demux 4 GiB discard alloc) noted for filing
in alkcall, not here
taskgraph: validate clean, no cycles, 6 generations
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.
Ported the alknet-http overlay verification to the channels-over-WS
session (tests/ws_overlay_ops.rs, test-support feature, 8 tests):
- overlay mechanism: browser-registered ops land in the connection's
Layer 2 overlay (register_imported), exposed via overlay_env() —
no PeerIds (browsers are not peers); PeerRef::Specific to a browser
id routes to nothing (NOT_FOUND)
- hub→browser call through compose_root_env's attached overlay
- AccessControl on browser ops gates hub calls (scope match allows,
missing scope FORBIDDEN)
- overlay dies with the connection; no leak between connections;
in-flight calls to browser ops resolve on close
- wire-level: 10 interleaved concurrent calls across two WS sessions
— no cross-correlation, no deadlock; disconnect mid-call resolves
and a fresh session works (no listener wedge)
byte_adapter: read_eof Notify now gated to the wss feature (its only
consumer is from_wss) so a test-support-only build is warning-free.
Verified: cargo test (182 lib), --all-features (227 lib + 5 MCP + 8
overlay + 10 WS integration), clippy -D warnings (default,
test-support, all-features), fmt.
glm-5.3-flash