Files

T

glm-5.3-flash a85500d3d9 docs: ws-byte-adapter POC complete (GO) — resolve OQ-01, update framing facts

POC at /workspace/ws-byte-adapter-poc/ (not on main), all tests green:
- call round-trip over axum WS ↔ adapter ↔ ChannelsAdapter ↔ channel-0
  Dispatcher (published alkcall API only, no forks)
- 3 MiB payload splits across 1 MiB WS messages, byte-intact reassembly
- 20 interleaved calls reassemble without corruption/cross-correlation

Findings merged:
- OQ-01 resolved: byte-stream both directions, bounded mpsc (64 slots)
  inbound, outbound chunk-header parsing (frame-as-two-chunks
  live-confirmed), 1 MiB message cap with split, flush no-op, close →
  EOF → REQ-CH-02
- websocket.md: chunk ≠ frame on channel 0 (frame reassembly required);
  operationId is the request payload key
- task ws-byte-adapter → completed with full Summary; ws-upgrade-session
  unblocks

2026-08-28 07:14:32 +00:00

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

5.5 KiB Raw Blame History