glm-5.3-flash
63dc4b6d06
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.
98 lines
5.7 KiB
Markdown
98 lines
5.7 KiB
Markdown
# Open Questions
|
|
|
|
Centralized tracker. Format follows the SDD process
|
|
(`docs/sdd_process.md` §Open Questions Format). Ported alknet OQs that
|
|
resolved before the extraction are recorded in the resolved section
|
|
with their resolutions; new alkhttp OQs start at OQ-01.
|
|
|
|
## Status legend
|
|
|
|
`open` | `resolved` | `deferred(scope)` | `partially resolved`
|
|
|
|
## Open
|
|
|
|
### OQ-01: WS ↔ byte-stream adaptation semantics
|
|
|
|
- **Origin**: [websocket.md](websocket.md), [ADR-067](decisions/067-websocket-carries-channels.md)
|
|
- **Status**: open
|
|
- **Priority**: high
|
|
- **Question**: The channels demux consumes bytes (`read_exact` on the
|
|
8-byte header + payload); the mux writes chunks as contiguous byte
|
|
sequences. A WebSocket is message-oriented. The adapter's contract
|
|
needs nailing down before implementation:
|
|
(a) inbound buffer bound (the alknet-tty precedent — bounded mpsc
|
|
with `try_send` → `Full` → `Pending` backpressure, and the single-
|
|
drainer ordered-write pattern from `pump_session` — is the working
|
|
reference; bound value to lock during implementation);
|
|
(b) write-side chunk boundary parsing (verified against alkcall
|
|
source: the mux emits one mpsc payload per chunk, but a logical
|
|
write above the mux — e.g. channel 0's `write_frame`, which issues
|
|
prefix and body as separate `write_all`s — can surface as multiple
|
|
chunks; the adapter must parse outgoing chunk headers rather than
|
|
assume write-per-chunk; also confirm the WS-message cap policy for
|
|
chunks up to `MAX_CHUNK_LEN` = 16 MiB — split across messages, and
|
|
what the practical cap is for browser stacks);
|
|
(c) flush mapping (`AsyncWrite::flush` → WS message emission point);
|
|
(d) close mapping (WS close code → transport EOF → REQ-CH-02
|
|
teardown; `AsyncWrite::shutdown` maps to the zero-length EOF
|
|
sentinel (REQ-CH-01) then a WS Close frame — confirm this ordering
|
|
against the mux's pump-exit behavior).
|
|
- **Blocked on**: nothing (the spike resolved the factual
|
|
sub-questions; the remaining items are implementation decisions to
|
|
lock during the WS adapter task)
|
|
|
|
### OQ-02: `/publish` body framing details
|
|
|
|
- **Origin**: [ADR-068](decisions/068-gateway-publish-endpoint.md)
|
|
- **Status**: open
|
|
- **Priority**: medium
|
|
- **Resolution**: (pending)
|
|
- **Question**: The exact first-line convention for naming the target
|
|
operation (first line `{operation, chunk}` vs `?operation=` query
|
|
parameter vs required header), and where a terminal error envelope
|
|
lives (final NDJSON line of a JSON error object vs plain HTTP status
|
|
with JSON body). Must settle before the gateway contract's
|
|
`info.version` bumps ([ADR-045](decisions/045-to-openapi-gateway-spec-versioning.md)).
|
|
|
|
### OQ-03: `from_wss` reconnection semantics
|
|
|
|
- **Origin**: [ADR-070](decisions/070-from-wss-consumer-adapter.md)
|
|
- **Status**: open
|
|
- **Priority**: medium
|
|
- **Resolution**: (pending)
|
|
- **Question**: On a dropped WSS connection, does `from_wss`
|
|
auto-reconnect + re-discover (`services/list`) + reconcile imported
|
|
registrations, or does v1 surface call failures (`INTERNAL`,
|
|
retryable) and leave the policy to the assembly layer? The v1
|
|
default (fail with retryable errors) is documented in ADR-070; the
|
|
question is whether a built-in policy is ever warranted.
|
|
|
|
### OQ-04: Browser client library ownership
|
|
|
|
- **Origin**: [websocket.md](websocket.md)
|
|
- **Status**: open
|
|
- **Priority**: low
|
|
- **Blocked on**: a concrete browser consumer (the alk UI) needing the
|
|
JS/TS client for channels-over-WS. The framing contract is the
|
|
alkcall BAST document (`chunk-header.bast.json`); the client library
|
|
lives outside this crate. Deferred(scope: browser UI work).
|
|
|
|
## Resolved (ported)
|
|
|
|
Resolutions inherited from the alknet architecture; recorded here for
|
|
reference. Full rationale in the alknet mono-repo's open-questions.md
|
|
and the cited ADRs.
|
|
|
|
| OQ (alknet) | Title | Resolution | Where it lives now |
|
|
|-------------|-------|------------|--------------------|
|
|
| OQ-11 | Handler-level auth resolution observability | Resolved: resolved identity stored on `Connection` via `set_identity` | alkcall core; [http-server.md](http-server.md) §Auth |
|
|
| OQ-13 | Operation path format | Resolved: `/{service}/{op}` is the operation path format (gateway bodies carry it; no direct-call surface) | [ADR-036](decisions/036-http-to-call-operation-mapping.md), [ADR-047](decisions/047-remove-direct-call-http-surface.md) |
|
|
| OQ-17 | Call protocol client and adapter contract | Resolved: `OperationAdapter` async trait; `to_*` projections | alkcall ADR-022; [ADR-017](decisions/017-call-protocol-client-and-adapter-contract.md) |
|
|
| OQ-24 / OQ-26 | Operation error schemas / `AdapterError` variants | Resolved: protocol/operation codes distinct; `HTTP_<status>` prefix; `AdapterError` `#[non_exhaustive]` | alkcall ADR-016; [ADR-023](decisions/023-operation-error-schemas.md) |
|
|
| OQ-37 | X.509 outgoing-only / three peer roles | Resolved: browsers are not peers | [ADR-034](decisions/034-outgoing-only-x509-and-three-peer-roles.md) |
|
|
| OQ-39 | `to_openapi` published-spec versioning | Resolved: `info.version` semver tracks the gateway endpoint contract | [ADR-045](decisions/045-to-openapi-gateway-spec-versioning.md) |
|
|
| OQ-40 | reqwest client config and connection pooling | Resolved: `ClientWithMiddleware` + retry + Retry-After middleware; rebuild-and-swap | [http-adapters.md](http-adapters.md) §HTTP client |
|
|
| OQ-12 | TLS identity provisioning | Resolved (alknet): browsers require X.509; provisioning itself is an alknet concern | [ADR-027](decisions/027-tls-identity-redesign-acme-rawkey-decoupling.md); [ADR-069](decisions/069-webtransport-out-of-scope.md) |
|
|
|
|
Not carried: OQ-38 (WebTransport standalone relay scope) — moot here;
|
|
the relay is an alknet concern ([ADR-069](decisions/069-webtransport-out-of-scope.md)). |