alkdev/alkhttp
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
63dc4b6d06d61f5c9c6ebe56b284c41c3117c1b2
alkhttp/docs/architecture/open-questions.md
T
glm-5.3-flash 63dc4b6d06 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.
2026-08-28 06:05:45 +00:00

5.7 KiB
Raw Blame History

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, ADR-067
  • 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_alls — 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
  • 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).

OQ-03: from_wss reconnection semantics

  • Origin: ADR-070
  • 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
  • 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 §Auth
OQ-13 Operation path format Resolved: /{service}/{op} is the operation path format (gateway bodies carry it; no direct-call surface) ADR-036, ADR-047
OQ-17 Call protocol client and adapter contract Resolved: OperationAdapter async trait; to_* projections alkcall ADR-022; ADR-017
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
OQ-37 X.509 outgoing-only / three peer roles Resolved: browsers are not peers ADR-034
OQ-39 to_openapi published-spec versioning Resolved: info.version semver tracks the gateway endpoint contract ADR-045
OQ-40 reqwest client config and connection pooling Resolved: ClientWithMiddleware + retry + Retry-After middleware; rebuild-and-swap http-adapters.md §HTTP client
OQ-12 TLS identity provisioning Resolved (alknet): browsers require X.509; provisioning itself is an alknet concern ADR-027; ADR-069

Not carried: OQ-38 (WebTransport standalone relay scope) — moot here; the relay is an alknet concern (ADR-069).

Reference in New Issue View Git Blame Copy Permalink