alkhttp/docs/architecture/open-questions.md

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: resolved (POC ws-byte-adapter; validated end-to-end — see the task's Summary in tasks/websocket/byte-adapter.md)
• Priority: high
• Resolution: The adapter treats the WS message stream as a byte stream in both directions; the 8-byte chunk header is the only framing. Inbound: WS read task → bounded mpsc (64 slots; backpressure = send awaiting capacity, applying TCP-level backpressure to the socket) → AsyncRead drains; channel close = EOF. Outbound: a writer task parses 8-byte chunk headers out of the pending byte buffer (live- confirmed: a single response frame arrives as TWO chunks — write_frame's prefix and body surface as separate mux payloads) and emits one WS message per chunk, splitting at a 1 MiB WS_MESSAGE_CAP (receiver's boundary is the chunk header, not the message). Flush is a no-op (writes queue; the writer task emits independently). Close: WS close → read EOF → REQ-CH-02 teardown; shutdown closes the write channel (mux pumps emit zero-length sentinels on sender drop). Client-side consequence: chunk ≠ frame — channel-0 consumers reassemble length-prefixed frames from the byte stream; and the dispatcher reads operationId from the request payload.
• Cross-references: ADR-067, websocket.md, tasks/websocket/byte-adapter.md

OQ-02: /publish body framing details

• Origin: ADR-068
• Status: resolved (implementation: gateway-publish task, 2026-08-28)
• Priority: medium
• Resolution: First line of the NDJSON body carries { "operation": "/{service}/{op}", "chunk": {...} }; subsequent lines are chunk values only. Terminal errors are plain HTTP status + JSON body (NOT an NDJSON line) — consistent with every other gateway endpoint's error surface. A ?operation= query parameter was considered and rejected: it duplicates the first-line field and adds a second way to name the op (two sources of truth) for no curl-ability gain. The first-line convention is the single naming point. Implemented in src/gateway/routes.rs::publish_handler.

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).

OQ-05: Browser-opened data channels over WS — v1 cut

• Origin: review-001 finding WS-03 (docs/reviews/001-initial-implementation-review.md), ADR-067, ADR-048
• Status: deferred(scope: v1 cut — no browser consumer yet; reopened when one lands)
• Priority: medium
• Question: ADR-067 §"Data channels for browsers" promises browser-opened data channels (open ops on channel 0 → chunk demultiplexing of channels 1..N), and ADR-048's bidirectionality promise leans on the same connection-local machinery. The v1 implementation wires channel 0 only (install_channel_zero + Dispatcher::run_loop_single_stream, src/websocket/upgrade.rs); no ChannelCore/register_openable/ChannelOperations path exists for a browser to open a data channel (grep-verified, review-001). The design is decided (ADR-067: the browser opens data channels exactly as any channels consumer — nothing new to design); what is deferred is the wiring: passing the deployment's openable-ALPN registrations and ChannelLifecyclePolicy through the WS upgrade path, plus a browser-opened-channel end-to-end test.
• Resolution: (pending — v1 cut recorded 2026-08-29 in ADR-067 and ADR-048; the recently landed WS robustness work — idle-read timeout, session caps/eviction, pump consolidation — is the foundation the deferred work builds on)
• Cross-references: ADR-067, ADR-048, websocket.md, tasks/websocket/review-001-ws-data-channel-decision.md

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).