alkhttp/tasks/adapters/from-openapi.md at 21e19abb60677ba9f307a707842efe078388e788

Files

T

glm-5.3-flash 7be91987ca feat(adapters): from_openapi adapter (parse + forwarding handlers)

Ported FromOpenAPI on the pre-staged foundations:
- openapi_spec.rs (from_json/from_yaml/from_str JSON-first per ADR-051,
  $ref resolution) — already shared with to_openapi
- forward.rs shared forwarding core (build_request/forward/
  forward_stream/parse_sse_frames) — already shared with from_jsonschema

New in this port:
- FromOpenAPI adapter: op-id normalization (declared or
  {method}_{path}), op-type detection (GET->Query, else Mutation;
  200/201 text/event-stream -> Sub), input schema from parameters +
  requestBody 'body', error schemas as HTTP_<status> (ADR-023),
  Internal visibility + FromOpenAPI provenance (ADR-015/022),
  Query/Mutation -> Once, Sub -> Stream (Pub never produced, v1)
- 47 in-module tests: wire-level integration over real TCP
  (echo + capturing servers), bearer/api-key/basic credential
  injection from Capabilities (ADR-014 no-env-vars), SSE streaming,
  YAML + from_str + ADR-051 yes-string guards
- removed dead_code allows from openapi_spec.rs (now consumed)

Verified: cargo test (182 lib), test --all-features (182+10 WS),
clippy -D warnings (both), fmt.

2026-08-28 14:04:48 +00:00

3.1 KiB

Raw Blame History

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

name

status

depends_on

scope

risk

impact

level

Description

Port adapters/from_openapi.rs (~2k lines, the largest port) from /workspace/@alkdev/alknet/crates/alknet-http/src/adapters/from_openapi.rs: OpenAPISpec (from_json/from_yaml/from_str JSON-first per ADR-051, from_value), $ref resolution, HttpServiceConfig, per-op HandlerRegistration construction (Internal by default, FromOpenAPI leaf provenance), forwarding handlers (path-template substitution, query params, auth header from capabilities, content-type branching), SSE→StreamingHandler for Sub ops (HandlerKind::Stream), error fidelity (HTTP_<status> codes). Type paths move to alkcall::client (adapter contract) and alkcall::registry.

Acceptance Criteria

JSON + YAML + from_str detection ports with tests
Handler construction: Query/Mutation→Once, Sub→Stream; Pub never produced (v1)
Forwarding: path params, query params, auth injection from Capabilities, error mapping — unit tested (mock HTTP via local axum server)
No env-var reads
cargo test passes

References

docs/architecture/http-adapters.md (§from_openapi, §Forwarding handler, §Error Fidelity)
docs/architecture/decisions/023-operation-error-schemas.md, 051-yaml-input-for-from-openapi.md
Old source: /workspace/@alkdev/alknet/crates/alknet-http/src/adapters/from_openapi.rs

Notes

Agent fills during implementation. Largest single port — consider splitting internally (parse half / handler half) if review flags it.

Summary

Ported from_openapi — much smaller than the original 2k lines because the parse half was pre-staged in openapi_spec.rs (from_json / from_yaml / from_str JSON-first per ADR-051, $ref resolution) during the to_openapi task, and the forwarding half lives in the shared forward.rs core (build_request / forward / forward_stream / parse_sse_frames) from the from_jsonschema task:

src/adapters/from_openapi.rs: FromOpenAPI adapter — operation-id normalization (declared or {method}_{path}), op-type detection (GET→Query, else Mutation; 200/201 text/event-stream→Sub), input schema from parameters + requestBody["body"], output schema from 200/201, error schemas as HTTP_ definitions (ADR-023), per-op HandlerRegistration with Internal visibility, FromOpenAPI provenance, composition_authority: None, scoped_env: None (ADR-015/022). Query/Mutation→HandlerKind::Once, Sub→ HandlerKind::Stream (Pub never produced, v1).
Wire-level integration tests over real TCP: echo server (JSON/text/SSE/404/500) + capturing server (method/path/query/ headers/body assertions), covering bearer/api-key/basic credential injection from Capabilities, path+query split, NDJSON... — 47 tests in-module (import shape, YAML + from_str + ADR-051 yes-string guards, SSE streaming, error fidelity, no-env-vars).
resolve_ref / resolve_refs_recursive dead_code allows removed from openapi_spec.rs — now consumed.

182 lib tests green (was 135).

3.1 KiB Raw Blame History