---
id: adapter-from-openapi
name: from_openapi adapter (parse + forwarding handlers)
status: completed
depends_on: [client-http-host]
scope: broad
risk: medium
impact: component
level: implementation
tags: [adapters, phase-3]
---

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

- [x] JSON + YAML + from_str detection ports with tests
- [x] Handler construction: Query/Mutation→Once, Sub→Stream; Pub never produced (v1)
- [x] Forwarding: path params, query params, auth injection from Capabilities, error mapping — unit tested (mock HTTP via local axum server)
- [x] No env-var reads
- [x] `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_<status> 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).