Module serve 

Available on crate feature serve only.

faucet serve — HTTP control plane (#127). Runs pipeline configs submitted over HTTP, reusing executor::run_expanded. Feature-gated on serve; structured like cli/src/schedule/. See docs/superpowers/specs/2026-05-30-faucet-serve-design.md.

Re-exports

pub use config::ServeConfig;

Modules

auth

Bearer-token authentication for /v1/*. Constant-time comparison via subtle; the Authorization header is the only accepted credential.

cluster

Clustered execution (#197, Mode A): when --cluster is set, every instance runs a claim loop that pulls Pending runs from the shared SQL history DB, so submissions pull-balance across instances and a crashed instance’s runs are re-run by a survivor. Inert unless enabled.

config

ServeConfig — the validated, runtime-ready server configuration built from ServeArgs. The no-auth gate lives here so an unauthenticated server can never start silently.

error

HTTP-facing error type. Every fallible serve handler returns ServeError, which renders to a JSON ApiError body with the right status code.

handlers

serve HTTP handlers.

history

Run-history storage. The trait is defined in full now; the in-memory backend lives in memory.rs, and the feature-gated SQL backends (postgres.rs / sqlite.rs, sharing sql.rs) wrap themselves in fallback.rs so an unreachable backend degrades to in-memory rather than refusing to start. See spec §11 + §20.

idempotency

Stable content fingerprint for idempotency replay-vs-conflict detection. A key replayed with the same merged config returns the existing run; reused with a different config is a 409. The hash is order-independent for object keys (canonical JSON) and stable across process restarts (sha256), so the Phase 5 SQL backends can store and compare it unchanged.

load

Turn a submitted config body into expanded nodes, applying the workspace --default-config base. Mirrors PipelineConfig::from_path_async but merges a base Value and uses from_value. All ${env}/${file}/${secret} and ${vault:…}-style directives resolve against the server’s environment and credentials (the documented privilege surface — spec §13).

logs

Per-run log capture for SSE streaming (GET /v1/runs/{id}/logs, spec §12).

metrics

faucet_serve_* request metrics. The path label is the matched route template (/v1/runs/{id}), never the raw path — cardinality safety.

observability

serve-owned observability: install the Prometheus recorder (returning a render handle for the /metrics route) and a tracing subscriber whose fmt layer routes through the secret-redacting writer and whose RunLogLayer feeds the per-run SSE log buffers. Both are process-global and set-once; a second install in the same process is tolerated (returns no handle / leaves the existing subscriber). The returned LogHub is shared with ServerState so the /logs handler reads the same buffers the layer writes.

registry

In-flight run registry. Tracks per-run cancellation tokens and the queue / in-flight counters that drive backpressure (429), the faucet_serve_runs_* gauges, /readyz, and the shutdown drain. A “queued” run is one that has been spawned but has not yet acquired an execution permit.

runner

The run lifecycle: validate + queue a submission (submit), then run it under a permit. A cancel / timeout / shutdown trigger cooperatively cancels the pipeline (so a buffered sink flushes at its next page boundary, #146 H16) and grants a bounded flush grace before hard-dropping it; the task then finalizes an authoritative terminal status. See spec §7 + §20.

server

axum router assembly and the bind / graceful-shutdown serve loop.

state

Shared, cheaply-cloneable server state handed to every handler via axum::extract::State. Holds auth, the Prometheus render handle, the server-wide shutdown token, the run registry, the execution semaphore, the run-history backend, and the --default-config merge base.

triggerstriggers

Event-driven pipeline triggers for faucet serve (#196).

ui_assetsserve-ui

Embedded web-console assets (serve-ui feature). The static shell is PUBLIC; all data stays behind the bearer-gated /v1 API. Assets are embedded at compile time from src/serve/ui/ via rust-embed.

Functions

run_server

Boot the HTTP control plane and serve until SIGTERM/SIGINT.