docs: implementation plan (TTY precedents folded in); task decomposition (17 tasks)
Plan updated with the alknet-tty findings: the drainer pattern (single ordered writer) makes outbound chunk-boundary parsing sound; TestStdinSink's try_send→Full→Pending is the inbound backpressure precedent; OQ-01(a) now cites the reference. Task graph (taskgraph-validated, 17 tasks, 6 generations, no cycles): - tasks/server/: core-types, auth, healthz-decoy, adapter - tasks/gateway/: dispatch, routes, publish - tasks/websocket/: byte-adapter (research POC), upgrade-session, overlay-ops - tasks/adapters/: from-openapi, from-jsonschema, to-openapi, from-wss, mcp - tasks/client/: http-host - tasks/infra/: integration-suite (phase 4) Critical path runs through server core → adapter → WS session → overlay tests → integration suite. High-risk tasks are the three WS tasks, de-risked by the ws-byte-adapter POC blocking upgrade-session.
This commit is contained in:
@@ -0,0 +1,42 @@
|
||||
---
|
||||
id: adapter-from-jsonschema
|
||||
name: from_jsonschema single-endpoint adapter
|
||||
status: pending
|
||||
depends_on: [client-http-host]
|
||||
scope: narrow
|
||||
risk: low
|
||||
impact: component
|
||||
level: implementation
|
||||
tags: [adapters, phase-3]
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Port `adapters/from_jsonschema.rs` from
|
||||
`/workspace/@alkdev/alknet/crates/alknet-http/src/adapters/from_jsonschema.rs`
|
||||
per ADR-066: caller supplies OperationSpec + HttpServiceConfig + path
|
||||
template + method; one HandlerRegistration with a reqwest forwarding
|
||||
handler (same shape as from_openapi's), FromJsonSchema provenance
|
||||
(leaf, Internal default). Sub op type → StreamingHandler expecting
|
||||
text/event-stream. Shares the forwarding-handler code path with
|
||||
from_openapi.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Adapter ported; one registration per call, correct provenance
|
||||
- [ ] Forwarding round-trip test against a local mock server
|
||||
- [ ] `cargo test` passes
|
||||
|
||||
## References
|
||||
|
||||
- docs/architecture/decisions/066-from-jsonschema-as-http-adapter.md
|
||||
- docs/architecture/http-adapters.md (§from_jsonschema)
|
||||
- alkcall ADR-027 (FromJsonSchema provenance)
|
||||
|
||||
## Notes
|
||||
|
||||
> Agent fills during implementation.
|
||||
|
||||
## Summary
|
||||
|
||||
> Agent fills on completion.
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
id: adapter-from-openapi
|
||||
name: from_openapi adapter (parse + forwarding handlers)
|
||||
status: pending
|
||||
depends_on: [client-http-host]
|
||||
scope: broad
|
||||
risk: medium
|
||||
impact: component
|
||||
level: implementation
|
||||
tags: [adapters, phase-3]
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Port `adapters/from_openapi.rs` (~2k lines, the largest port) from
|
||||
`/workspace/@alkdev/alknet/crates/alknet-http/src/adapters/from_openapi.rs`:
|
||||
OpenAPISpec (from_json/from_yaml/from_str JSON-first per ADR-051,
|
||||
from_value), $ref resolution, HttpServiceConfig, per-op
|
||||
HandlerRegistration construction (Internal by default, FromOpenAPI
|
||||
leaf provenance), forwarding handlers (path-template substitution,
|
||||
query params, auth header from capabilities, content-type branching),
|
||||
SSE→StreamingHandler for Sub ops (HandlerKind::Stream), error fidelity
|
||||
(`HTTP_<status>` codes). Type paths move to alkcall::client (adapter
|
||||
contract) and alkcall::registry.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] JSON + YAML + from_str detection ports with tests
|
||||
- [ ] Handler construction: Query/Mutation→Once, Sub→Stream; Pub never produced (v1)
|
||||
- [ ] Forwarding: path params, query params, auth injection from Capabilities, error mapping — unit tested (mock HTTP via local axum server)
|
||||
- [ ] No env-var reads
|
||||
- [ ] `cargo test` passes
|
||||
|
||||
## References
|
||||
|
||||
- docs/architecture/http-adapters.md (§from_openapi, §Forwarding handler, §Error Fidelity)
|
||||
- docs/architecture/decisions/023-operation-error-schemas.md, 051-yaml-input-for-from-openapi.md
|
||||
- Old source: `/workspace/@alkdev/alknet/crates/alknet-http/src/adapters/from_openapi.rs`
|
||||
|
||||
## Notes
|
||||
|
||||
> Agent fills during implementation. Largest single port — consider
|
||||
> splitting internally (parse half / handler half) if review flags it.
|
||||
|
||||
## Summary
|
||||
|
||||
> Agent fills on completion.
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
id: adapter-from-wss
|
||||
name: from_wss consumer adapter (wss feature)
|
||||
status: pending
|
||||
depends_on: [ws-byte-adapter, ws-upgrade-session]
|
||||
scope: moderate
|
||||
risk: high
|
||||
impact: component
|
||||
level: implementation
|
||||
tags: [adapters, phase-3]
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Implement `from_wss` per ADR-070 behind the `wss` feature
|
||||
(tokio-tungstenite): dial wss:// endpoint → adapt the WS stream with
|
||||
the shared byte-adapter → `Connection::from_bidi(_, b"alk/channels")` →
|
||||
consumer half (alkcall ChannelClient machinery: channel 0 install +
|
||||
client dispatch loop) → services/list + services/schema → one
|
||||
forwarding HandlerRegistration per discovered op (FromCall provenance,
|
||||
leaf, Internal default). Forwarding: serialize input → call.requested
|
||||
frame on channel 0 → correlate by id. Bearer token from Capabilities
|
||||
(no-env-vars). Reconnect policy: v1 = drop → retryable failures
|
||||
(OQ-03 disposition).
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Adapter behind `wss` feature; base crate compiles without it
|
||||
- [ ] Round-trip test: from_wss consumer ↔ ws-upgrade-session server (both halves of the adapter exercised together)
|
||||
- [ ] Discovered ops invoke correctly; identity/ACL enforced end-to-end
|
||||
- [ ] Connection drop → in-flight calls fail retryable, no hang
|
||||
- [ ] Credentials flow from Capabilities only (no env-var reads)
|
||||
- [ ] `cargo test --all-features` passes
|
||||
|
||||
## References
|
||||
|
||||
- docs/architecture/decisions/070-from-wss-consumer-adapter.md
|
||||
- docs/architecture/websocket.md (§The consumer-side mirror)
|
||||
- alkcall ADR-028 (from_call pattern), ADR-043 (ChannelClient)
|
||||
|
||||
## Notes
|
||||
|
||||
> Agent fills during implementation.
|
||||
|
||||
## Summary
|
||||
|
||||
> Agent fills on completion.
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
id: adapter-mcp
|
||||
name: from_mcp + to_mcp (mcp feature)
|
||||
status: pending
|
||||
depends_on: [client-http-host, gateway-routes]
|
||||
scope: broad
|
||||
risk: medium
|
||||
impact: component
|
||||
level: implementation
|
||||
tags: [adapters, mcp, phase-3]
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Port both MCP adapters from
|
||||
`/workspace/@alkdev/alknet/crates/alknet-http/src/adapters/{from_mcp/`,
|
||||
`to_mcp.rs}` behind the `mcp` feature (rmcp, streamable HTTP only —
|
||||
ADR-037). from_mcp: tools/list discovery, per-tool HandlerRegistration
|
||||
(Mutation, HandlerKind::Once, FromMCP leaf), structuredContent-preferred
|
||||
output handling, ContentBlock-union fallback, isError→CallError.
|
||||
to_mcp: 4 fixed gateway tools (search/schema/call/batch — Sub AND Pub
|
||||
excluded), StreamableHttpService into axum under /mcp with bearer
|
||||
middleware. Shared dispatch spine with to_openapi via GatewayDispatch.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Both adapters behind `mcp`; default features compile without rmcp
|
||||
- [ ] from_mcp round-trip against a mock MCP server (tools/list, tools/call, structured + content-block outputs)
|
||||
- [ ] to_mcp: 4 tools listed; call dispatch filtered by ACL; Pub/Sub ops excluded
|
||||
- [ ] stdio transport not present anywhere (dependency audit)
|
||||
- [ ] `cargo test --all-features` passes
|
||||
|
||||
## References
|
||||
|
||||
- docs/architecture/http-mcp.md
|
||||
- docs/architecture/decisions/037-mcp-stdio-transport-exclusion.md, 041-mcp-tool-gateway-pattern.md
|
||||
- Old source: `/workspace/@alkdev/alknet/crates/alknet-http/src/adapters/from_mcp/`, `to_mcp.rs`, `tests/from_mcp_integration.rs`
|
||||
|
||||
## Notes
|
||||
|
||||
> Agent fills during implementation.
|
||||
|
||||
## Summary
|
||||
|
||||
> Agent fills on completion.
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
id: adapter-to-openapi
|
||||
name: to_openapi projection (6-endpoint gateway doc)
|
||||
status: pending
|
||||
depends_on: [gateway-routes]
|
||||
scope: moderate
|
||||
risk: low
|
||||
impact: component
|
||||
level: implementation
|
||||
tags: [adapters, phase-3]
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Port `adapters/to_openapi.rs` from
|
||||
`/workspace/@alkdev/alknet/crates/alknet-http/src/adapters/to_openapi.rs`:
|
||||
generate the OpenAPI doc describing the 6 fixed gateway endpoints
|
||||
(search/schema/call/batch/subscribe + publish), per-caller surface
|
||||
discovered via /search (not preloaded), `info.version` semver tracking
|
||||
the gateway contract (ADR-045; minor = /publish addition), error
|
||||
schemas projected per ADR-023. Wire `GET /openapi.json` in the server
|
||||
router. Pub ops excluded from /subscribe's tool description but listed
|
||||
in /search; /publish documents the NDJSON body per OQ-02's resolution.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Projection ported; 6-endpoint doc with correct versioning
|
||||
- [ ] /openapi.json serves it (integration test)
|
||||
- [ ] Doc validates against openapiv3 parsing
|
||||
- [ ] `cargo test` passes
|
||||
|
||||
## References
|
||||
|
||||
- docs/architecture/http-adapters.md (§to_openapi)
|
||||
- docs/architecture/decisions/042-openapi-gateway-pattern.md, 045-to-openapi-gateway-spec-versioning.md, 068-gateway-publish-endpoint.md
|
||||
- Old source: `/workspace/@alkdev/alknet/crates/alknet-http/src/adapters/to_openapi.rs`
|
||||
|
||||
## Notes
|
||||
|
||||
> Agent fills during implementation.
|
||||
|
||||
## Summary
|
||||
|
||||
> Agent fills on completion.
|
||||
Reference in New Issue
Block a user