lifecyclegateway

Overview ¶

Package lifecyclegateway — Discoverable + Gateway + factory.

Package lifecyclegateway exposes the pkg/lifecycle.Manager's read + operator-mutation surface over HTTP and WebSocket. ADR-047 PR 3. The endpoints are deliberately framework-shape — every app's lifecycle-managed workflow types (drone missions, sensor lifecycles, manufacturing batches, scenario executions, API request lifecycles) become uniformly inspectable + operator- patchable through one gateway component.

Wiring contract:

• The component reads Dependencies.LifecycleManager. Apps that declare no lifecycle-managed entity types simply don't run this gateway; apps that DO run it pass the same Manager into Dependencies that the rule processor consumes for lifecycle_* actions + $entity.lifecycle.* substitutions.
• RegisterHTTPHandlers mounts the routes under the configured PathPrefix (default "/workflows"). Each app deployment chooses where in its gateway placement to mount this — there's no hardcoded port or standalone binary.

Endpoint surface (ADR-047 line 305-315):

• GET {prefix} → list registered workflow types + instance counts
• GET {prefix}/{type} → list instances (Phase/Active/Match/Limit/Offset query params)
• GET {prefix}/{type}/{id} → get full instance state
• GET {prefix}/{type}/{id}/history → phase transition history (KV revision replay)
• GET {prefix}/{type}/{id}/children → child instance summaries
• POST {prefix}/{type}/{id}/state → operator patch (validates lifecycle:"operator_writable")
• POST {prefix}/{type}/{id}/transition → operator-initiated transition (validates transitions table)
• GET {prefix}/{type}?stream=true (websocket) → live updates via Manager.Watch

All endpoints loud-fail on missing manager / unknown workflow / unknown entity rather than silently returning empty results. Error responses use a uniform JSON envelope {"error": "..."} so operator dashboards can render the underlying cause without per-endpoint parsing.

Scaling cliffs documented at ADR-047 § "Scaling cliff (operator guidance)" apply to the gateway's List/Watch/History/Children paths since they are direct Manager pass-throughs. Operators observing dashboard latency at high cardinality should file a bottleneck issue per the ADR's v2 secondary-index upgrade path.

Package lifecyclegateway — HTTP + WebSocket handlers.

Single catch-all `serveHTTP` dispatches by trimmed path + method. Path-tree shape (ADR-047 § Operator API):

{root}                                  GET   → list workflow types + counts
{root}/{type}                           GET   → list instances (query params for filters) — or WS upgrade when ?stream=true
{root}/{type}/{id}                      GET   → instance state
{root}/{type}/{id}/history              GET   → phase-transition history
{root}/{type}/{id}/children             GET   → child instances
{root}/{type}/{id}/state                POST  → operator patch
{root}/{type}/{id}/transition           POST  → operator transition

Error model: every non-2xx response is `{"error": "..."}` so operator dashboards parse one envelope. The mapping from pkg/lifecycle errors → HTTP status is centralized in `errorToStatus`. Workflow-not-registered + entity-not-found map to 404; field-not-operator-writable + invalid-transition + terminal-phase map to 400 (client must fix); retries-exhausted maps to 409 (race with another writer); anything else 500.

Package lifecyclegateway — OpenAPI spec.

The lifecycle-gateway implements gateway.OpenAPIProvider so the operator-facing endpoints show up in the framework's auto- generated OpenAPI surface (specs/openapi.v3.yaml). Matches the pattern from gateway/graph-gateway/openapi.go.

Path templates use literal "{prefix}/{type}/{id}" placeholders — the actual path prefix is operator-configurable per deployment, so the spec advertises the shape, not the bound paths.