Documentation
¶
Overview ¶
Package api implements the HTTP server interface for AWF.
It wires the Huma v2 / chi v5 HTTP adapter and exposes workflow execution endpoints consumed by external callers. The package is an adapter in the "interfaces" layer of the hexagonal architecture: it translates HTTP requests into application service calls and HTTP responses back. No domain logic or infrastructure details reside here—only request parsing, response formatting, middleware wiring, and coordination between the HTTP layer, the ports.WorkflowFacade / ports.WorkflowReader application ports, and the Bridge live-execution metadata store.
Overview ¶
The api package provides a REST API surface for AWF with the following capabilities:
- Workflow discovery and validation (GET /api/workflows, GET /api/workflows/{scope}/{name}, POST /api/workflows/{scope}/{name}/validate)
- Asynchronous workflow execution (POST /api/workflows/{scope}/{name}/run)
- Execution lifecycle management (GET/DELETE /api/executions/{id}, POST /api/executions/{id}/resume)
- Real-time event streaming via Server-Sent Events (GET /api/executions/{id}/events)
- Execution history and statistics (GET /api/history, GET /api/history/stats)
- Auto-generated OpenAPI 3.1 specification at /openapi.{json,yaml}
- Swagger UI at /docs
The package is designed to be embedded inside the CLI (via interfaces/cli) or run standalone. The caller creates a Server with NewServer, calls Start in a goroutine, and calls Shutdown on signal receipt.
Architecture ¶
The api package sits in the interfaces layer. It depends on the application layer only through the domain ports it is wired with: ports.WorkflowFacade (run, resume, list, validate, status, history), ports.WorkflowReader (get, history stats), and the application.SessionRegistry for live session lookup. The Bridge is a small metadata store, not a read port. The package never imports infrastructure packages directly—this invariant is enforced by go-arch-lint.
External HTTP clients
│
▼
┌────────────────────────────────┐
│ chi.Mux │
│ (Logger → Recoverer → │
│ RequestID) │
└───────────────┬────────────────┘
│
▼
┌────────────────────────────────┐
│ huma.API │
│ (schema validation, OpenAPI, │
│ content negotiation, /docs) │
└───────────────┬────────────────┘
│
┌──────────┼──────────────┐
▼ ▼ ▼
WorkflowHandlers ExecutionHandlers SSEHandler HistoryHandlers
│ │ │ │
└──────────┴──────────────┴────────┘
│ │ │
▼ ▼ ▼
ports.WorkflowFacade *Bridge application.SessionRegistry
ports.WorkflowReader (live (live RunSession lookup
(list/get/validate/ exec for SSE + status)
run/resume/history) metadata:
cancel,
List/Get)
Key Types ¶
## Server
Server is the top-level assembly: it owns the chi.Mux, the huma.API instance, the net/http.Server, the shutdown timeout, and the SSE WaitGroup. One Server per process; instantiate via NewServer.
## Bridge
Bridge is a metadata-only store for live (in-flight) executions. It holds NO read or history port: workflow listing/get/validate and history queries route through ports.WorkflowFacade / ports.WorkflowReader directly from the handlers (F108 read-path consolidation). Bridge owns only the in-memory sync.Map of active execution metadata and exposes TrackFacadeSession / GetExecution / CancelExecution / ListExecutions / Shutdown.
Bridge is NOT an anti-corruption read layer and is NOT responsible for executing workflows. All workflow execution (Run and Resume) is routed exclusively through ports.WorkflowFacade, wired via WithFacade and WithRegistryImpl on NewServer. The Bridge entry is created from the returned RunSession so that List/Get/Cancel keep working while the authoritative live session lives in the application.SessionRegistry.
## Facade execution path (F108)
POST /api/workflows/{scope}/{name}/run and POST /api/executions/{id}/resume both require a ports.WorkflowFacade and an application.SessionRegistry to be wired. When either is absent, the handlers return 503 Service Unavailable immediately (a generic message that does not leak internal configuration detail). Genuine not-found stays 404 and request-validation failures stay 422. When both are present, execution is delegated exclusively to facade.Run or facade.Resume. The returned ports.RunSession is:
- Registered in the SessionRegistry synchronously (FR-003: a subscriber connecting on the SSE endpoint right after /run MUST find the session).
- Tracked as lightweight metadata in Bridge.activeExecutions so that List/Get/Cancel keep working (A4 / R5).
The RunSession's own ID() is authoritative: it is the execution ID returned in the HTTP response and the key under which SessionRegistry.Get resolves later.
## Handler families
- WorkflowHandlers (handlers_workflows.go): read-only workflow operations, served directly by ports.WorkflowFacade / ports.WorkflowReader.
- ExecutionHandlers (handlers_executions.go): lifecycle operations on async workflow runs. Run and Resume require a facade and a registry; List/Get/Cancel operate on Bridge live-execution metadata directly (Get overlays the live status snapshot from the registry session when available).
- SSEHandler (sse.go): streams step and workflow transition events to connected clients via Server-Sent Events. Resolves live sessions via the SessionRegistry (SessionLookup), not Bridge metadata.
- HistoryHandlers (handlers_history.go): queries past execution records and aggregate statistics.
Request Lifecycle ¶
1. chi.Mux receives the request and applies middleware in order:
middleware.Logger: structured access log.
middleware.Recoverer: converts panics to 500 responses.
middleware.RequestID: injects X-Request-Id header.
2. huma.API parses the request: validates path/query parameters, deserializes the request body against the registered JSON schema, and populates the typed input struct.
3. The registered handler function is called with the validated input.
- Run/Resume handlers invoke ports.WorkflowFacade and record live metadata in the Bridge; read-only handlers (list/get/validate/history) call ports.WorkflowFacade / ports.WorkflowReader directly. Execution List/Get/Cancel read Bridge metadata.
5. The handler returns a typed output struct or a huma.Error*.
6. huma.API serializes the response body and writes HTTP headers and status.
SSE Event Flow ¶
GET /api/executions/{id}/events establishes a long-lived SSE connection:
- SSEHandler.Stream increments s.sseWG (owned by Server) so Shutdown knows how many streams are active.
- SSEHandler.getSession resolves the live RunSession from the SessionRegistry (SessionLookup). Returns 404 if not found.
- Events are consumed from session.Events() and serialized as SSE frames.
- When the session channel closes (terminal state or session Close), the stream exits cleanly.
- On context cancellation (client disconnect or server shutdown), the goroutine exits cleanly and decrements sseWG.
Error Handling ¶
Handlers return huma.Error* types directly (e.g., huma.Error404NotFound, huma.Error422UnprocessableEntity). Huma serializes these to RFC 7807 problem+json responses. No separate error-mapping middleware is used.
Concurrency Model ¶
## Facade-driven executions
POST /api/workflows/{scope}/{name}/run delegates to ports.WorkflowFacade.Run. The facade owns the execution goroutine and its lifetime; the Bridge only records metadata. The client receives 202 Accepted with an execution ID immediately. Subsequent GET /api/executions/{id} or SSE stream requests observe the running state via the SessionRegistry.
## SSE goroutine lifecycle
Each SSE connection runs in its own goroutine managed by huma/sse. Server.sseWG tracks active SSE goroutines. Server.Shutdown waits on sseWG after calling httpSrv.Shutdown so that in-flight streams can complete before the process exits. The maximum wait is bounded by shutdownTimeout (default 30s, configurable via WithShutdownTimeout).
## Graceful shutdown sequence
- Caller calls Server.Shutdown(ctx).
- context.WithTimeout(ctx, shutdownTimeout) is created.
- httpSrv.Shutdown(shutdownCtx) stops accepting new connections and waits for active HTTP handlers to complete (chi sends context cancellation to handlers).
- SSE goroutines detect ctx.Done() and exit, decrementing sseWG.
- sseWG.Wait() blocks until all SSE goroutines have exited.
- Shutdown returns.
Architectural Invariants ¶
These invariants are enforced by go-arch-lint (NFR-001, NFR-006):
interfaces/api MUST NOT import internal/infrastructure/*. All infrastructure access is mediated by application service ports via Bridge or ports.WorkflowFacade.
All route registration MUST happen inside NewServer, never at package init or in handler constructors. This keeps the full routing table visible in a single function for discoverability.
One huma.API instance per Server. No global huma.API variables.
The Bridge and handler family constructors (NewWorkflowHandlers, NewExecutionHandlers, NewSSEHandler, NewHistoryHandlers) receive their dependencies at construction time; they never fetch from global state.
ExecutionHandlers.Run and ExecutionHandlers.Resume require both a ports.WorkflowFacade and an application.SessionRegistry to be wired (via WithFacade and WithRegistryImpl on NewServer). Without both, these handlers return 503 Service Unavailable immediately — there is no legacy fallback path.
SSE resolves live sessions via SessionLookup (the SessionRegistry wrapped by WithSessionRegistry), NOT via Bridge.activeExecutions. This separation keeps execution ownership with the facade and metadata ownership with Bridge.
The SSE WaitGroup (sseWG) is owned by Server and passed by pointer to NewSSEHandler. Handlers call wg.Add(1) and defer wg.Done() around the stream goroutine lifetime.
Shutdown timeout is configurable only via WithShutdownTimeout; it is never read from CLI flags or environment variables at this layer.
Index ¶
- func ProjectEventToSSEFrame(ev ports.Event) []byte
- func RegisterExecutionRoutes(api huma.API, h *ExecutionHandlers)
- func RegisterHistoryRoutes(api huma.API, h *HistoryHandlers)
- func RegisterRespondRoutes(api huma.API, h *RespondHandler)
- func RegisterSSERoutes(api huma.API, h *SSEHandler)
- func RegisterWorkflowRoutes(api huma.API, h *WorkflowHandlers)
- type ActiveExecution
- type Bridge
- type CancelExecutionInput
- type ExecutionHandlers
- func (h *ExecutionHandlers) Cancel(_ context.Context, in *CancelExecutionInput) (*struct{}, error)
- func (h *ExecutionHandlers) Get(_ context.Context, in *GetExecutionInput) (*ExecutionOutput, error)
- func (h *ExecutionHandlers) List(_ context.Context, _ *struct{}) (*ListExecutionsOutput, error)
- func (h *ExecutionHandlers) Resume(ctx context.Context, in *ResumeExecutionInput) (*RunWorkflowOutput, error)
- func (h *ExecutionHandlers) Run(ctx context.Context, in *RunWorkflowInput) (*RunWorkflowOutput, error)
- func (h *ExecutionHandlers) SetFacade(f ports.WorkflowFacade)
- func (h *ExecutionHandlers) SetSessionRegistry(reg *application.SessionRegistry)
- type ExecutionOutput
- type GetExecutionInput
- type GetWorkflowInput
- type GetWorkflowOutput
- type HistoryEntry
- type HistoryHandlers
- type HistoryListInput
- type HistoryListOutput
- type HistoryStatsOutput
- type ListExecutionsOutput
- type ListWorkflowsOutput
- type Option
- type RespondHandler
- type RespondInput
- type ResumeExecutionInput
- type RunWorkflowInput
- type RunWorkflowOutput
- type SSEHandler
- type Server
- type SessionLookup
- type StreamInput
- type ValidateWorkflowInput
- type ValidateWorkflowOutput
- type WorkflowHandlers
- func (h *WorkflowHandlers) Get(ctx context.Context, in *GetWorkflowInput) (*GetWorkflowOutput, error)
- func (h *WorkflowHandlers) List(ctx context.Context, _ *struct{}) (*ListWorkflowsOutput, error)
- func (h *WorkflowHandlers) Validate(ctx context.Context, in *ValidateWorkflowInput) (*ValidateWorkflowOutput, error)
- type WorkflowSummary
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ProjectEventToSSEFrame ¶
ProjectEventToSSEFrame serializes ev to the raw SSE frame bytes used by the HTTP streaming endpoint and the facade conformance projector. Wire format: "event: <kind>\ndata: <json>\n\n"
func RegisterExecutionRoutes ¶
func RegisterExecutionRoutes(api huma.API, h *ExecutionHandlers)
RegisterExecutionRoutes mounts the execution lifecycle routes on the given Huma API.
func RegisterHistoryRoutes ¶
func RegisterHistoryRoutes(api huma.API, h *HistoryHandlers)
RegisterHistoryRoutes mounts the history list and stats routes on the given Huma API.
func RegisterRespondRoutes ¶
func RegisterRespondRoutes(api huma.API, h *RespondHandler)
RegisterRespondRoutes registers POST /runs/{id}/respond on the given Huma API.
func RegisterSSERoutes ¶
func RegisterSSERoutes(api huma.API, h *SSEHandler)
RegisterSSERoutes registers GET /api/executions/{id}/events on the given Huma API.
func RegisterWorkflowRoutes ¶
func RegisterWorkflowRoutes(api huma.API, h *WorkflowHandlers)
RegisterWorkflowRoutes mounts the three workflow read routes on the given Huma API.
Types ¶
type ActiveExecution ¶
type ActiveExecution struct {
ExecutionID string
WorkflowName string
Ctx context.Context
Cancel context.CancelFunc
ExecutionContext *workflow.ExecutionContext
// StartedAt is stamped when a facade session is tracked. The facade path uses a
// NopRecorder, so the session emits no run.started event to derive a start time from;
// this field is the authoritative start time for facade-tracked executions.
StartedAt time.Time
}
ActiveExecution holds the runtime state of an async workflow execution.
type Bridge ¶
type Bridge struct {
// contains filtered or unexported fields
}
Bridge tracks the runtime metadata of async workflow executions for the HTTP layer.
It no longer owns any read or execution port: workflow listing/get/validate and history queries route through ports.WorkflowFacade / ports.WorkflowReader (F108 read-path consolidation), and execution routes through ports.WorkflowFacade.Run/Resume. Bridge's sole remaining responsibility is the activeExecutions map that backs GET/DELETE /api/executions and graceful shutdown.
func NewBridge ¶
func NewBridge() *Bridge
NewBridge creates an empty Bridge. It takes no dependencies because all workflow and history access is now served by the facade/reader wired on NewServer; the Bridge only holds in-flight execution metadata populated via TrackFacadeSession.
func (*Bridge) CancelExecution ¶
CancelExecution cancels the execution by ID. Returns a descriptive error if not found. Idempotent.
func (*Bridge) GetExecution ¶
func (b *Bridge) GetExecution(id string) (*ActiveExecution, bool)
GetExecution returns the active execution by ID. Returns ok=false if not found.
func (*Bridge) ListExecutions ¶
func (b *Bridge) ListExecutions() []*ActiveExecution
ListExecutions returns all active executions currently in the map. Order is unspecified.
func (*Bridge) Shutdown ¶
func (b *Bridge) Shutdown()
Shutdown cancels every execution that is still tracked in activeExecutions. It must be called after the HTTP server has stopped accepting requests so that no new executions can be started concurrently. Calling Shutdown more than once is safe — context.CancelFunc is idempotent.
func (*Bridge) TrackFacadeSession ¶
func (b *Bridge) TrackFacadeSession(session ports.RunSession, workflowName string) *ActiveExecution
TrackFacadeSession records a metadata entry for a facade-driven execution so the List/Get/Cancel handlers keep working while the live RunSession itself lives in the application.SessionRegistry (A4 / R5). The entry is keyed by the session's own ID() so that GET /api/executions/{id} and SessionRegistry.Get(execID) resolve the same key.
Cancel requests cancellation through CancelWithEvent when available. The facade publishes its terminal event after execution cleanup; legacy sessions use Close. Bridge.Shutdown also invokes Cancel on every tracked entry.
Ctx is a dedicated cancelable context for this ActiveExecution entry. The facade owns the real execution goroutine and its session context; this Ctx is intentionally decoupled from it (ports.RunSession does not expose its internal context). Cancel calls both session cancellation and the context cancel function (so that ae.Ctx.Err() returns context.Canceled after Cancel() — required by M7 contract). The facade owns the execution completion signal.
type CancelExecutionInput ¶
type CancelExecutionInput struct {
ID string `path:"id" doc:"Execution ID to cancel." example:"550e8400-e29b-41d4-a716-446655440000" required:"true"`
}
type ExecutionHandlers ¶
type ExecutionHandlers struct {
// contains filtered or unexported fields
}
ExecutionHandlers exposes execution lifecycle operations via HTTP.
func NewExecutionHandlers ¶
func NewExecutionHandlers(b *Bridge) *ExecutionHandlers
NewExecutionHandlers creates an ExecutionHandlers bound to the given Bridge.
func (*ExecutionHandlers) Cancel ¶
func (h *ExecutionHandlers) Cancel(_ context.Context, in *CancelExecutionInput) (*struct{}, error)
func (*ExecutionHandlers) Get ¶
func (h *ExecutionHandlers) Get(_ context.Context, in *GetExecutionInput) (*ExecutionOutput, error)
func (*ExecutionHandlers) List ¶
func (h *ExecutionHandlers) List(_ context.Context, _ *struct{}) (*ListExecutionsOutput, error)
func (*ExecutionHandlers) Resume ¶
func (h *ExecutionHandlers) Resume(ctx context.Context, in *ResumeExecutionInput) (*RunWorkflowOutput, error)
func (*ExecutionHandlers) Run ¶
func (h *ExecutionHandlers) Run(ctx context.Context, in *RunWorkflowInput) (*RunWorkflowOutput, error)
func (*ExecutionHandlers) SetFacade ¶
func (h *ExecutionHandlers) SetFacade(f ports.WorkflowFacade)
func (*ExecutionHandlers) SetSessionRegistry ¶
func (h *ExecutionHandlers) SetSessionRegistry(reg *application.SessionRegistry)
type ExecutionOutput ¶
type ExecutionOutput struct {
Body struct {
Body executionBody `json:"body"`
}
}
type GetExecutionInput ¶
type GetExecutionInput struct {
ID string `path:"id" doc:"Execution ID." example:"550e8400-e29b-41d4-a716-446655440000" required:"true"`
}
type GetWorkflowInput ¶
type GetWorkflowOutput ¶
type HistoryEntry ¶
type HistoryEntry struct {
ID string `json:"id" doc:"Execution record identifier." example:"rec-abc123"`
WorkflowName string `json:"workflow_name" doc:"Name of the workflow." example:"deploy-prod"`
Status string `json:"status" doc:"Outcome: success, failed, cancelled." example:"success"`
StartedAt time.Time `json:"started_at" doc:"Execution start time." example:"2024-01-15T10:00:00Z"`
CompletedAt time.Time `json:"completed_at" doc:"Execution completion time." example:"2024-01-15T10:05:00Z"`
DurationMs int64 `json:"duration_ms" doc:"Duration in milliseconds." example:"300000"`
}
type HistoryHandlers ¶
type HistoryHandlers struct {
// contains filtered or unexported fields
}
HistoryHandlers exposes execution history query operations via HTTP.
Listing routes through ports.WorkflowFacade.History and statistics through the focused ports.WorkflowReader.HistoryStats — both satisfied by the same application.Adapter — so the HTTP history endpoints share the common facade rather than a legacy Bridge port (F108).
func NewHistoryHandlers ¶
func NewHistoryHandlers(facade ports.WorkflowFacade, reader ports.WorkflowReader) *HistoryHandlers
NewHistoryHandlers creates a HistoryHandlers bound to the facade and reader ports. Either may be nil; the handlers degrade to 503 rather than panicking.
func (*HistoryHandlers) List ¶
func (h *HistoryHandlers) List(ctx context.Context, in *HistoryListInput) (*HistoryListOutput, error)
func (*HistoryHandlers) Stats ¶
func (h *HistoryHandlers) Stats(ctx context.Context, in *HistoryListInput) (*HistoryStatsOutput, error)
type HistoryListInput ¶
type HistoryListInput struct {
Workflow string `query:"workflow" doc:"Filter by workflow name." example:"deploy-prod"`
Status string `query:"status" doc:"Filter by status: success, failed, cancelled." example:"success"`
Since time.Time `query:"since" doc:"Return records after this time (RFC 3339)." example:"2024-01-01T00:00:00Z"`
Until time.Time `query:"until" doc:"Return records before this time (RFC 3339)." example:"2024-02-01T00:00:00Z"`
Limit int `query:"limit" doc:"Maximum number of records to return." example:"50"`
}
type HistoryListOutput ¶
type HistoryListOutput struct {
Body struct {
Body historyListBody `json:"body"`
}
}
type HistoryStatsOutput ¶
type HistoryStatsOutput struct {
Body struct {
Body *workflow.HistoryStats `json:"body"`
}
}
type ListExecutionsOutput ¶
type ListExecutionsOutput struct {
Body struct {
Body listExecutionsBody `json:"body"`
}
}
type ListWorkflowsOutput ¶
type ListWorkflowsOutput struct {
Body struct {
Body listWorkflowsBody `json:"body"`
}
}
type Option ¶
type Option func(*Server)
Option configures a Server on construction.
func WithFacade ¶
func WithFacade(facade ports.WorkflowFacade) Option
WithFacade wires the workflow facade for handlers that need it.
func WithRegistryImpl ¶
func WithRegistryImpl(reg *application.SessionRegistry) Option
WithRegistryImpl wires an application.SessionRegistry into the server. It also creates a sessionLookup adapter and sets it as the SessionLookup for SSE/respond handlers.
func WithSessionRegistry ¶
func WithSessionRegistry(sl SessionLookup) Option
WithSessionRegistry wires a SessionLookup into handlers that need to resolve live RunSessions by ID (SSEHandler and RespondHandler). Without this option those handlers return 404 for every request — no panic, but no streaming either.
func WithShutdownTimeout ¶
WithShutdownTimeout overrides the default 30s graceful shutdown timeout.
func WithWorkflowReader ¶
func WithWorkflowReader(reader ports.WorkflowReader) Option
WithWorkflowReader wires the focused read-only port used by the single-workflow GET and history-stats endpoints. It is typically the same application.Adapter passed to WithFacade. Without it, those two endpoints degrade to 503.
type RespondHandler ¶
type RespondHandler struct {
// contains filtered or unexported fields
}
RespondHandler handles user input submission for running workflows.
func NewRespondHandler ¶
func NewRespondHandler(facade ports.WorkflowFacade) *RespondHandler
NewRespondHandler creates a RespondHandler bound to the given facade.
func (*RespondHandler) Respond ¶
func (h *RespondHandler) Respond(_ context.Context, in *RespondInput) (*struct{}, error)
Respond delegates to the session's Respond method to deliver user input.
func (*RespondHandler) SetSessionLookup ¶
func (h *RespondHandler) SetSessionLookup(sl SessionLookup)
SetSessionLookup wires the session registry into the handler so getSession can resolve live RunSessions by ID. Must be called before the first request is served.
type RespondInput ¶
type RespondInput struct {
ID string `path:"id" doc:"Execution ID." example:"550e8400-e29b-41d4-a716-446655440000" required:"true"`
Body struct {
Response ports.InputResponse `json:"response" doc:"User input response."`
}
}
RespondInput holds the path parameter for the respond endpoint.
type ResumeExecutionInput ¶
type ResumeExecutionInput struct {
ID string `path:"id" doc:"Execution ID to resume." example:"550e8400-e29b-41d4-a716-446655440000" required:"true"`
Body struct {
InputOverrides map[string]any `json:"input_overrides,omitempty" doc:"Input values to override from the original run."`
FromStep string `json:"from_step,omitempty" doc:"Step to resume from: 'current', 'previous', or a named step." example:"build"`
}
}
type RunWorkflowInput ¶
type RunWorkflowInput struct {
Scope string `path:"scope" doc:"Workflow scope (\"local\" or vendor pack name)." example:"local" required:"true"`
Name string `path:"name" doc:"Workflow name." example:"deploy-prod" required:"true"`
Body struct {
Inputs map[string]any `json:"inputs" doc:"Key/value inputs passed to the workflow."`
}
}
type RunWorkflowOutput ¶
type RunWorkflowOutput struct {
Body runWorkflowOutputBody
}
type SSEHandler ¶
type SSEHandler struct {
// contains filtered or unexported fields
}
SSEHandler streams workflow execution events over Server-Sent Events.
func NewSSEHandler ¶
func NewSSEHandler(b *Bridge, wg *sync.WaitGroup) *SSEHandler
NewSSEHandler creates an SSEHandler bound to the given Bridge and WaitGroup.
func (*SSEHandler) SetSessionLookup ¶
func (h *SSEHandler) SetSessionLookup(sl SessionLookup)
SetSessionLookup wires the session registry into the handler so getSession can resolve live RunSessions by ID. Must be called before the first request is served.
func (*SSEHandler) Stream ¶
func (h *SSEHandler) Stream(ctx context.Context, in *StreamInput, send sse.Sender) error
Stream consumes RunSession.Events() and emits typed SSE events. Supports Last-Event-ID header for reconnection with replay from buffered events. Returns huma.Error404NotFound when the execution ID is unknown. Exits cleanly on terminal state or ctx.Done().
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server assembles all handler families into a single HTTP server backed by chi and Huma.
func (*Server) Handler ¶
Handler returns the chi mux for use with httptest.NewServer in integration tests.
type SessionLookup ¶
type SessionLookup interface {
GetSession(id string) (ports.RunSession, bool)
}
SessionLookup is the driven port for resolving a live RunSession by execution ID. It is satisfied by *application.SessionRegistry (wrapped via SessionRegistryLookup). Defined here so the api package has no import dependency on the application package.
type StreamInput ¶
type StreamInput struct {
ID string `path:"id" doc:"Execution ID." example:"550e8400-e29b-41d4-a716-446655440000" required:"true"`
LastEventID string `header:"Last-Event-ID" doc:"Resume from this event sequence; replay buffered events from this seq onward."`
}
StreamInput holds the path parameter and optional reconnection header for the SSE event stream endpoint. LastEventID is parsed from the standard "Last-Event-ID" request header (RFC 8895 §9.1) and used to replay buffered events on reconnect.
type ValidateWorkflowInput ¶
type ValidateWorkflowOutput ¶
type ValidateWorkflowOutput struct {
Body struct {
Body validateWorkflowBody `json:"body"`
}
}
type WorkflowHandlers ¶
type WorkflowHandlers struct {
// contains filtered or unexported fields
}
WorkflowHandlers exposes workflow read operations (list, get, validate) via HTTP.
All operations route through the common application facade rather than legacy Bridge ports (F108 read-path consolidation): list and validate go through ports.WorkflowFacade, and the single-workflow fetch goes through the focused ports.WorkflowReader. Both are satisfied by the same application.Adapter, so every HTTP read shares the one execution core the CLI/TUI/ACP interfaces also drive through.
func NewWorkflowHandlers ¶
func NewWorkflowHandlers(facade ports.WorkflowFacade, reader ports.WorkflowReader) *WorkflowHandlers
NewWorkflowHandlers creates a WorkflowHandlers bound to the facade and reader ports. Either may be nil (e.g. a server constructed without WithFacade/WithWorkflowReader); the handlers degrade to 503 rather than panicking, mirroring the execution handlers.
func (*WorkflowHandlers) Get ¶
func (h *WorkflowHandlers) Get(ctx context.Context, in *GetWorkflowInput) (*GetWorkflowOutput, error)
func (*WorkflowHandlers) List ¶
func (h *WorkflowHandlers) List(ctx context.Context, _ *struct{}) (*ListWorkflowsOutput, error)
func (*WorkflowHandlers) Validate ¶
func (h *WorkflowHandlers) Validate(ctx context.Context, in *ValidateWorkflowInput) (*ValidateWorkflowOutput, error)
type WorkflowSummary ¶
type WorkflowSummary struct {
Name string `json:"name" doc:"Workflow name." example:"deploy-prod"`
Scope string `json:"scope" doc:"Workflow scope (\"local\" or vendor pack name)." example:"local"`
Workflow string `json:"workflow" doc:"Workflow name without scope prefix." example:"deploy-prod"`
Version string `json:"version" doc:"Workflow version." example:"1.0.0"`
Description string `json:"description" doc:"Short description." example:"Deploy to production"`
}
WorkflowSummary is the listing DTO for GET /api/workflows entries. Scope and Workflow are the two components of the canonical URL grammar `/api/workflows/{scope}/{name}`; Name is the display identifier (`scope/workflow` for pack entries, plain name for local/global).