Files

T

glm-5.3-flash 42239a0af5 feat(gateway,adapters): /publish endpoint (ADR-068) + to_openapi 6-endpoint projection

gateway-publish:
- GatewayDispatch::invoke_sink (internal:false, forwarded_for:None)
- POST /publish: NDJSON body, first line {operation, chunk} (OQ-02
  resolved: first-line convention; terminal errors = plain HTTP status
  + JSON body, not NDJSON lines); 404 internal/unknown, 401/403 ACL,
  400 INVALID_OPERATION_TYPE for non-Pub
- ADR-068 + open-questions.md updated with the OQ-02 resolution

adapter-to-openapi:
- src/adapters/openapi_spec.rs: OpenAPISpec model (JSON/YAML/from_str
  JSON-first per ADR-051, $ref resolution) shared by from/to_openapi
- src/adapters/to_openapi.rs: 6-endpoint projection, info.version
  1.0.0 -> 1.1.0 (minor: /publish addition per ADR-045), /publish
  NDJSON doc with 400 oneOf (INVALID_INPUT + INVALID_OPERATION_TYPE),
  ADR-023 error fidelity (protocol statuses, HTTP_<status> passthrough,
  internal-op exclusion)
- GET /openapi.json wired into HttpAdapter's router (bearer-auth layer)

Verified: cargo test (136 lib), test --all-features (136+10 WS),
clippy -D warnings (both), fmt. Doc validates against openapiv3.

2026-08-28 13:54:49 +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: 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).

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.7 KiB Raw Blame History