016: HTTP Interface Adapter with Huma v2 and SSE Streaming

Status: Accepted Date: 2026-05-17 Issue: F097 Supersedes: N/A Superseded by: N/A

Context#

ADR-001 listed “API (future)” as a planned interface layer alongside CLI. F097 implements that delivery mechanism: a REST/HTTP API that lets external systems (CI pipelines, dashboards, IDE extensions) trigger, monitor, and query AWF workflow executions without shelling out to the CLI.

Two decisions within F097 are architecturally load-bearing beyond the feature itself:

1. HTTP framework selection — introducing Huma v2 + chi v5 as new infrastructure. Huma generates OpenAPI 3.1 schemas automatically from Go types, which locks in how the API contract is expressed and validated for all future endpoints. Replacing it later requires rewriting all handler signatures.

2. Streaming protocol for execution events — workflow executions are long-running (seconds to minutes). External subscribers need real-time step updates. The choice between SSE, WebSockets, or a push-from-application model defines the client integration surface for every future streaming feature.

Candidates#

HTTP Framework#

Streaming Protocol#

Decision#

Framework: Huma v2 + chi v5.

Huma v2 is the only Go library that generates valid OpenAPI 3.1 (not 2.0 or 3.0) directly from Go struct types without a separate code-gen step. Chi’s standard net/http compatibility avoids wrapping the existing request context. AWF’s primary API consumers are developer tooling and CI; an always-in-sync OpenAPI spec eliminates documentation maintenance burden.

Streaming: SSE with 200ms polling of ExecutionContext.GetAllStepStates().

AWF workflow events are unidirectional (server → client). SSE is the standard HTTP mechanism for this pattern. The 200ms cadence matches the existing TUI poll interval (tui/tab_monitoring.go:71: monitoringTickInterval) and satisfies NFR-002 (p95 ≤ 100ms latency at ≤ 50 subscribers). The push-from-ExecutionService alternative was rejected because it would require a new domain port and observer registration pattern — introducing application-layer complexity to solve an interface-layer concern.

Arch-lint scoping: Huma and chi are declared as vendor blocks usable only by interfaces-api, mirroring how bubbletea is scoped to interfaces-tui. This prevents accidental import from domain or application layers.

Consequences#

What becomes easier:

• External systems integrate with AWF without shelling out to the CLI.
• OpenAPI 3.1 spec is always in sync with the implementation; no separate doc maintenance.
• SSE subscribers can use the standard browser EventSource API or curl --no-buffer.
• New endpoints follow the established Huma handler pattern without further architectural decisions.

What becomes harder:

• Replacing Huma v2 requires rewriting all handler signatures and regenerating the OpenAPI spec.
• SSE polling creates O(subscribers) goroutines per active execution; large subscriber counts require monitoring.
• WebSocket upgrades are not possible through the same SSE endpoint; bidirectional communication would require a separate endpoint and a new framework decision.
• Breaking changes to endpoint paths or response shapes require semver major bumps once external consumers build against the OpenAPI contract.

Constitution Compliance#