glm-5.3-flash
42239a0af5
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.
68 lines
2.7 KiB
Markdown
68 lines
2.7 KiB
Markdown
---
|
|
id: gateway-publish
|
|
name: POST /publish endpoint for Pub operations
|
|
status: completed
|
|
depends_on: [gateway-routes]
|
|
scope: narrow
|
|
risk: medium
|
|
impact: component
|
|
level: implementation
|
|
tags: [gateway, phase-3]
|
|
---
|
|
|
|
## 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
|
|
|
|
- [x] /publish wired; OQ-02 convention implemented and documented in ADR-068
|
|
- [x] Sink round-trip test (3+ chunks → final envelope)
|
|
- [x] Disconnect mid-stream cancels the handler (no hang)
|
|
- [x] to_openapi gateway doc gains /publish; gateway `info.version` minor bump
|
|
- [x] `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. |