feat: server foundation (phase 1 core) — state, auth, healthz/decoy, gateway dispatch, HttpAdapter

Tasks completed: server-core-types, server-auth, server-healthz-decoy,
gateway-dispatch, server-adapter (5 of 17).

- src/server/state.rs: DecoyConfig + RouterState (alkcall type paths,
  6-endpoint reserved-path docs)
- src/server/auth.rs: bearer middleware + ResolvedIdentity extractor
  (10 tests: missing/malformed/basic/failed-resolution matrix)
- src/server/healthz.rs + decoy.rs: raw healthz; nginx-style 404,
  static site (path-traversal guarded), redirect decoys
- src/gateway/dispatch.rs: GatewayDispatch invoke/invoke_streaming
  (internal:false, forwarded_for:None, bounded deadline) +
  src/gateway/error.rs: CallError→HTTP status mapping (HTTP_<status>
  passthrough, retryable→Retry-After)
- src/server/adapter.rs: HttpAdapter ProtocolHandler — accept_bi →
  BiStream → TokioIo → hyper auto builder (h2 CONNECT enabled);
  integration tests over DuplexStream (request/response cycle, healthz,
  decoy 404)

Verified: cargo test (46 lib tests), clippy -D warnings, fmt,
test --all-features.
This commit is contained in:
2026-08-28 07:35:02 +00:00
parent a85500d3d9
commit d070e548ad
15 changed files with 1669 additions and 31 deletions
+11 -6
View File
@@ -1,7 +1,7 @@
---
id: gateway-dispatch
name: GatewayDispatch — shared dispatch spine (invoke + streaming)
status: pending
status: completed
depends_on: [server-core-types]
scope: moderate
risk: medium
@@ -27,10 +27,10 @@ FORBIDDEN→401/403, INVALID_INPUT→422, TIMEOUT→504, INTERNAL→500,
## Acceptance Criteria
- [ ] `invoke()` + `invoke_streaming()` ported against alkcall dispatch
- [ ] Error mapping table ported with unit tests per row
- [ ] Internal ops → 404 before ACL; ACL failure → 401/403 distinction preserved
- [ ] `cargo test` passes
- [x] `invoke()` + `invoke_streaming()` ported against alkcall dispatch
- [x] Error mapping table ported with unit tests per row
- [x] Internal ops → 404 before ACL; ACL failure → 401/403 distinction preserved
- [x] `cargo test` passes
## References
@@ -44,4 +44,9 @@ FORBIDDEN→401/403, INVALID_INPUT→422, TIMEOUT→504, INTERNAL→500,
## Summary
> Agent fills on completion.
Ported `src/gateway/dispatch.rs` (GatewayDispatch: invoke +
invoke_streaming, root OperationContext construction with
internal:false / forwarded_for:None, deadline bounded for once-ops) and
`src/gateway/error.rs` (CallError→HTTP mapping per row, HTTP_<status>
passthrough, retryable→Retry-After). Tests adapted to alkcall's
`ResponseEnvelope.result: Result<Value, CallError>` shape.
+13 -7
View File
@@ -1,7 +1,7 @@
---
id: server-adapter
name: HttpAdapter — ProtocolHandler with hyper over BiStream
status: pending
status: completed
depends_on: [server-core-types, server-auth, server-healthz-decoy]
scope: moderate
risk: medium
@@ -24,11 +24,11 @@ the axum `Router` (built once at construction, `with_decoy` /
## Acceptance Criteria
- [ ] `HttpAdapter::new/h2/for_alpn` + `with_decoy` + `with_extra_routes` ported
- [ ] `ProtocolHandler` impl drives hyper over the BiStream; returns on connection close
- [ ] Router merges extra routes; default surface wins collisions
- [ ] Integration test: full HTTP request/response cycle over `tokio::io::DuplexStream``Connection::from_bidi` → adapter
- [ ] `cargo test` passes; feature gates `h2`/`http1` both compile
- [x] `HttpAdapter::new/h2/for_alpn` + `with_decoy` + `with_extra_routes` ported
- [x] `ProtocolHandler` impl drives hyper over the BiStream; returns on connection close
- [x] Router merges extra routes; default surface wins collisions
- [x] Integration test: full HTTP request/response cycle over `tokio::io::DuplexStream``Connection::from_bidi` → adapter
- [x] `cargo test` passes; feature gates `h2`/`http1` both compile
## References
@@ -42,4 +42,10 @@ the axum `Router` (built once at construction, `with_decoy` /
## Summary
> Agent fills on completion.
Ported `src/server/adapter.rs`: HttpAdapter (ProtocolHandler for
h2/http1.1), accept_bi→BiStream→TokioIo→hyper auto builder with
h2 connect-protocol enabled, with_decoy/with_extra_routes builders,
RESERVED_PATHS + WS_UPGRADE_PATH constants (WS handler wired in the
websocket task). Integration tests: full request/response cycle,
healthz, decoy 404 — all over tokio DuplexStream → Connection::from_bidi
→ ProtocolHandler::handle.
+11 -6
View File
@@ -1,7 +1,7 @@
---
id: server-auth
name: Bearer auth middleware and identity extraction
status: pending
status: completed
depends_on: [server-core-types]
scope: narrow
risk: low
@@ -23,10 +23,10 @@ static identity provider.
## Acceptance Criteria
- [ ] Middleware ports with tests (missing header, malformed, valid token, unknown token)
- [ ] `set_identity` observability path documented for the WS route's use
- [ ] No env-var reads anywhere (no-env-vars invariant)
- [ ] `cargo test` passes
- [x] Middleware ports with tests (missing header, malformed, valid token, unknown token)
- [x] `set_identity` observability path documented for the WS route's use
- [x] No env-var reads anywhere (no-env-vars invariant)
- [x] `cargo test` passes
## References
@@ -39,4 +39,9 @@ static identity provider.
## Summary
> Agent fills on completion.
Ported `src/server/auth.rs`: `bearer_auth_middleware`,
`extract_bearer_identity`, `ResolvedIdentity` extractor — resolution
semantics preserved (no header/malformed/failed resolution → None;
routes decide 401 vs anonymous). 10 unit tests covering the matrix.
alkcall type paths. The WS route's `set_identity` observability is
documented in the module doc of adapter.rs.
+11 -6
View File
@@ -1,7 +1,7 @@
---
id: server-core-types
name: Shared server state, config, and error types
status: pending
status: completed
depends_on: []
scope: narrow
risk: low
@@ -21,10 +21,10 @@ module skeleton for `src/server/`. Ported from
## Acceptance Criteria
- [ ] `DecoyConfig`, `RouterState` ported with the 6-endpoint reserved-path doc comments
- [ ] `alkcall::core::auth::IdentityProvider` / `alkcall::registry::registration::OperationRegistry` type paths correct
- [ ] No comments in code (project convention); doc comments on public API only
- [ ] `cargo clippy --all-targets -- -D warnings` clean
- [x] `DecoyConfig`, `RouterState` ported with the 6-endpoint reserved-path doc comments
- [x] `alkcall::core::auth::IdentityProvider` / `alkcall::registry::registration::OperationRegistry` type paths correct
- [x] No comments in code (project convention); doc comments on public API only
- [x] `cargo clippy --all-targets -- -D warnings` clean
## References
@@ -37,4 +37,9 @@ module skeleton for `src/server/`. Ported from
## Summary
> Agent fills on completion.
Implemented `src/server/state.rs`: `DecoyConfig` (NotFound/StaticSite/
Redirect), `RouterState` with axum `FromRef` impls, module skeleton for
`src/server/`. Adapted to alkcall type paths
(`alkcall::core::auth::IdentityProvider`,
`alkcall::registry::registration::OperationRegistry`). Reserved-path
doc comments updated to the 6-endpoint gateway + `/alk/channels`.
+10 -6
View File
@@ -1,7 +1,7 @@
---
id: server-healthz-decoy
name: /healthz raw route and stealth decoy fallback
status: pending
status: completed
depends_on: [server-core-types]
scope: narrow
risk: low
@@ -20,10 +20,10 @@ Tests: healthz responds without auth; decoy serves all three configs.
## Acceptance Criteria
- [ ] `/healthz` returns 200 text/plain without auth
- [ ] Decoy fallback for unmatched paths per DecoyConfig (404/static/redirect)
- [ ] Reserved paths (6 gateway + /healthz + /openapi.json + /mcp + /alk/channels) never hit the decoy
- [ ] `cargo test` passes
- [x] `/healthz` returns 200 text/plain without auth
- [x] Decoy fallback for unmatched paths per DecoyConfig (404/static/redirect)
- [x] Reserved paths (6 gateway + /healthz + /openapi.json + /mcp + /alk/channels) never hit the decoy
- [x] `cargo test` passes
## References
@@ -36,4 +36,8 @@ Tests: healthz responds without auth; decoy serves all three configs.
## Summary
> Agent fills on completion.
Ported `src/server/healthz.rs` (raw 200 "ok", no auth) and
`src/server/decoy.rs` (fake nginx 404 / static site with path-traversal
guard / redirect). Reserved-path protection is enforced in
`HttpAdapter`'s router (gateway routes take precedence; decoy is the
fallback). Tests: 7 decoy + 2 healthz.