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.
65 lines
2.5 KiB
Markdown
65 lines
2.5 KiB
Markdown
---
|
|
id: adapter-to-openapi
|
|
name: to_openapi projection (6-endpoint gateway doc)
|
|
status: completed
|
|
depends_on: [gateway-routes]
|
|
scope: moderate
|
|
risk: low
|
|
impact: component
|
|
level: implementation
|
|
tags: [adapters, phase-3]
|
|
---
|
|
|
|
## Description
|
|
|
|
Port `adapters/to_openapi.rs` from
|
|
`/workspace/@alkdev/alknet/crates/alknet-http/src/adapters/to_openapi.rs`:
|
|
generate the OpenAPI doc describing the 6 fixed gateway endpoints
|
|
(search/schema/call/batch/subscribe + publish), per-caller surface
|
|
discovered via /search (not preloaded), `info.version` semver tracking
|
|
the gateway contract (ADR-045; minor = /publish addition), error
|
|
schemas projected per ADR-023. Wire `GET /openapi.json` in the server
|
|
router. Pub ops excluded from /subscribe's tool description but listed
|
|
in /search; /publish documents the NDJSON body per OQ-02's resolution.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [x] Projection ported; 6-endpoint doc with correct versioning
|
|
- [x] /openapi.json serves it (integration test)
|
|
- [x] Doc validates against openapiv3 parsing
|
|
- [x] `cargo test` passes
|
|
|
|
## References
|
|
|
|
- docs/architecture/http-adapters.md (§to_openapi)
|
|
- docs/architecture/decisions/042-openapi-gateway-pattern.md, 045-to-openapi-gateway-spec-versioning.md, 068-gateway-publish-endpoint.md
|
|
- Old source: `/workspace/@alkdev/alknet/crates/alknet-http/src/adapters/to_openapi.rs`
|
|
|
|
## Notes
|
|
|
|
> Agent fills during implementation.
|
|
|
|
## Summary
|
|
|
|
Ported `src/adapters/to_openapi.rs` (6-endpoint gateway doc) plus the
|
|
shared `OpenAPISpec` model it produces:
|
|
|
|
- `src/adapters/openapi_spec.rs`: OpenAPISpec — from_json / from_yaml /
|
|
from_str (JSON-first per ADR-051, yaml_serde 0.10.x YAML 1.2),
|
|
from_value, $ref resolution (resolve_ref / resolve_refs_recursive,
|
|
pre-staged for the from_openapi port). Shared by from_openapi
|
|
(consume) and to_openapi (produce).
|
|
- `src/adapters/to_openapi.rs`: pure projection emitting the fixed
|
|
6-endpoint doc (search/schema/call/batch/subscribe + publish per
|
|
ADR-068). info.version bumped 1.0.0 -> 1.1.0 (ADR-045 minor bump:
|
|
/publish addition). /publish documents the NDJSON body per OQ-02's
|
|
resolution (operation+chunk first line), 400 oneOf covers
|
|
INVALID_INPUT + INVALID_OPERATION_TYPE. Error schemas projected per
|
|
ADR-023 (protocol statuses, HTTP_<status> passthrough, oneOf merge,
|
|
internal-op exclusion).
|
|
- `GET /openapi.json` wired into HttpAdapter's router under the
|
|
bearer-auth layer (serves spec.raw as JSON).
|
|
|
|
21 tests incl. doc-validates-against-openapiv3 + full /openapi.json
|
|
serving test over DuplexStream asserting /publish + 1.1.0 + 6 paths.
|
|
136 lib tests green. |