Module triggers 

Available on crate features serve and triggers only.

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

A static --triggers <file> defines watchers (object-arrival / webhook / queue-depth) that, on fire, enqueue a run via crate::serve::runner::submit — reusing the whole queue/executor/idempotency pipeline. Pure decision logic (spec validation, ${trigger.*} substitution, cursors, edge detection) is separated from the IO shell (watchers, fire path, webhook route).

Re-exports

pub use compiled::CompiledTriggers as Compiled;

Modules

compiled

Validated form of a TriggersFile. compile surfaces every problem at startup (unique names, webhook-path collisions, resolvable pipeline ref, interval/threshold bounds, missing backend feature) so a watcher never fails mid-run from a config mistake. Pure (no IO except reading a path’s existence, which is done by the caller; here we only validate shapes).

context

The fired event (TriggerEvent) and pure derivations from it: ${trigger.*} text substitution, the deterministic idempotency key, and the auto run-labels. No IO.

enqueue

The single choke point all trigger fires funnel through. build_submit_request is pure (text + event → SubmitRequest); fire resolves the pipeline ref, substitutes, submits via the existing runner, and maps the outcome.

health

Per-watcher health, shared with /readyz. A TriggersHandle is an Arc-backed, cheaply-cloneable handle stored in ServerState (mirrors ClusterHandle).

metrics

faucet_serve_trigger_* metrics. Low-cardinality labels only (trigger name, type). Mirrors crate::schedule::metrics.

object_arrivaltriggers-object-store

object_arrival trigger: incremental S3/GCS prefix listing. The pure Cursor decides which listed objects are new; the watcher (Task 13) does IO.

queue_depthtriggers-kafka or triggers-redis

queue_depth trigger: poll a queue’s depth and fire edge-triggered (once per rising crossing of threshold, suppressed until it drains). The Edge is pure; DepthProbe is the IO seam (Redis/Kafka impls + a fake in tests).

spec

Serde config types for the --triggers file. Pure data + JsonSchema; no IO. Validation lives in compiled.rs.

watcher

The Watcher trait + the supervised polling loop. A watcher never dies on a transient error: it records health, backs off, and retries until shutdown.

webhook

POST/PUT /v1/triggers/{name} — the webhook trigger endpoint. Looks the name up in the TriggersHandle webhook table, checks the method allowlist, applies a leading-edge debounce (coalesce fires that arrive within debounce_secs of the last accepted fire), builds a TriggerEvent::Webhook, and fires. Bearer auth is inherited from the /v1 route_layer.

Functions

load_triggers

Load + validate a triggers file. Surfaces a clear CliError::Serve on any parse/validation failure (fail-fast at startup).

spawn_watchers

Spawn supervised watcher tasks for every enabled polling trigger. Webhook triggers need no task (they are served by the route). Returns the join handles (the caller aborts them on shutdown, like the maintenance/lease loops).