alkdev/alkhttp
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
320ea87b08a153a63903f4c01dbe362a4307634f
alkhttp/docs/architecture/open-questions.md
T
glm-5.3-flash 320ea87b08 docs: port architecture specs and ADRs from alknet-http; write new alkhttp ADRs 067-070 
Phase 1 (SDD) — architecture documentation:

Ported specs (adapted for alkcall, producer/consumer terms, 6-endpoint
gateway, channels-over-WS, Sub/Pub operation types):
- overview.md, http-server.md, http-adapters.md, http-mcp.md
- README.md index (rewritten for alkhttp)

New ADRs:
- 067: WebSocket carries the channels protocol (8-byte chunk demux,
  channel 0 = alk/call, upgrade path /alk/channels)
- 068: gateway /publish endpoint for Pub operations (NDJSON body)
- 069: WebTransport out of scope in alkhttp (alknet concern)
- 070: from_wss consumer adapter (wss feature, tokio-tungstenite)

Ported ADRs (25, same numbers, port notes + amendments where the
extraction changed facts): 001-004, 010, 014, 015, 017, 022, 023, 027,
034, 036, 037, 039, 041, 042, 044, 045, 046, 047, 048, 049, 051, 066.

websocket.md rewritten for the channels session; open-questions.md
seeded (OQ-01 WS byte-stream adapter, OQ-02 /publish framing,
OQ-03 from_wss reconnect, OQ-04 browser client ownership).

Verified: cargo test, clippy -D warnings, fmt, doc --no-deps.
2026-08-27 14:19:24 +00:00

5.1 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 (bounded channel between the WS read task and the AsyncRead half — what bound, what policy on overflow); (b) write-side chunk completeness (the adapter assumes the mux emits each chunk as one contiguous write_all — verify against alkcall's MuxRunner and codify, or add an internal chunking layer); (c) flush mapping (AsyncWrite::flush → WS message emission point); (d) close mapping (WS close code → transport EOF → REQ-CH-02 teardown; and does AsyncWrite::shutdown map to a WS Close frame or to a zero-length chunk sentinel?).
  • Blocked on: nothing (implementation-blocking, not decision-blocking — resolve during implementation of the WS adapter)

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