---
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.