alkhttp/tasks/gateway/publish.md at v0.1.0

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

2.7 KiB

Raw Permalink Blame History

id, name, status, depends_on, scope, risk, impact, level, tags

name

status

depends_on

scope

risk

impact

level

Description

Implement POST /publish per ADR-068: NDJSON request body (each line = one published chunk) dispatched through invoke_sink() (alkcall ADR-046); handler's final ResponseEnvelope → 200 JSON or mapped error status. Resolve OQ-02 during this task: first line carries { "operation": "/{service}/{op}", "chunk": {...} } (subsequent lines chunk-only); terminal errors are plain HTTP status + JSON body (not an NDJSON line). Client disconnect drops the body stream → sink cancelled (PublishStream sees EOF). Non-Pub target → 400 INVALID_OPERATION_TYPE. Tests: multi-chunk publish round-trip against a SinkHandler over DuplexStream, early-disconnect, error mapping.

Acceptance Criteria

/publish wired; OQ-02 convention implemented and documented in ADR-068
Sink round-trip test (3+ chunks → final envelope)
Disconnect mid-stream cancels the handler (no hang)
to_openapi gateway doc gains /publish; gateway info.version minor bump
cargo test passes

References

docs/architecture/decisions/068-gateway-publish-endpoint.md
docs/architecture/open-questions.md (OQ-02)
alkcall ADR-046 (Pub/invoke_sink/PublishStream)

Notes

Agent fills during implementation.

Summary

Implemented POST /publish per ADR-068 with the OQ-02 resolution:

GatewayDispatch::invoke_sink added (root context internal:false / forwarded_for:None, unbounded — the sink is client-paced) delegating to OperationRegistry::invoke_sink (alkcall ADR-046).
publish_handler: NDJSON body -> chunks; first line carries {"operation": "...", "chunk": {...}} (OQ-02 resolution), subsequent lines chunk-only. Pre-dispatch checks ordered: internal/unknown -> 404, ACL -> 401/403, non-Pub -> 400 INVALID_OPERATION_TYPE. Chunk-stream errors -> INVALID_INPUT chunk items (handler-visible). Final envelope -> 200 JSON or standard error mapping.
OQ-02 resolved in open-questions.md + ADR-068 updated: first-line convention (no query param — rejected as a second naming source); terminal errors are plain HTTP status + JSON, not NDJSON lines.
Disconnect semantics: the request future is dropped on client disconnect, cancelling invoke_sink — the handler's PublishStream sees EOF (structural; socket-level test lands with infra-integration-suite).

11 tests: 3-chunk sink round-trip with collected-chunks verification, internal 404, ACL 401/403, non-Pub 400, unknown 404, missing-operation 400, empty-body 400, invalid-later-line handler-visible error, error envelope -> mapped HTTP status.

2.7 KiB Raw Permalink Blame History