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.
This commit is contained in:
2026-08-28 13:54:49 +00:00
parent ad975408e7
commit 42239a0af5
10 changed files with 2001 additions and 29 deletions
+29 -7
View File
@@ -1,7 +1,7 @@
---
id: gateway-publish
name: POST /publish endpoint for Pub operations
status: pending
status: completed
depends_on: [gateway-routes]
scope: narrow
risk: medium
@@ -25,11 +25,11 @@ 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
- [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
@@ -43,4 +43,26 @@ SinkHandler over DuplexStream, early-disconnect, error mapping.
## Summary
> Agent fills on completion.
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.