sre-triggers

Files (1)

• SKILL.md

SKILL.md (first lines)

# Cron, Webhooks, Events, Forms

## Trigger Declaration

Triggers are declared at the top of a flow file as a global `triggers` table:

```lua
triggers = {
  cron("*/5 * * * *"),
  webhook("/my/hook", {auth="hmac", key="webhook_secret"}),
  event("order.created"),
}
```

Multiple triggers can be declared; each fires the same flow independently.

---

## Cron Triggers

```lua
cron("*/5 * * * *")           -- every 5 minutes
cron("0 9 * * 1-5")           -- 9am Mon-Fri
cron("@hourly")               -- descriptor shorthand
```

- Standard 5-field cron expression (minute hour dom month dow) + descriptors
- Parser: robfig/cron/v3 with UTC timezone
- Behavior: `SkipIfStillRunning` — skips next fire if previous execution is still running
- Recovery chain: `Recover` — panics are caught and logged

**Params injected into flow:**
```lua
params.trigger_type    -- "cron"
params.trigger_id      -- "cr_xxxxxxxx"
params.trigger_name    -- display name
params.scheduled_at    -- RFC3339 scheduled fire time
```

---

## Webhook Triggers

```lua
webhook("/path", {
  auth    = "hmac",          -- "none"|"hmac"|"bearer"
  key     = "vault_key",     -- vault secret key (for hmac/bearer)
  alg     = "sha256",        -- "sha256"|"sha512" (hmac only)
  sig_hdr = "X-Signature",   -- signature header name (hmac only)
  cidrs   = {"10.0.0.0/8"},  -- IP allowlist (optional)
  rps     = 100,             -- per-endpoint rate limit req/s (optional)
})
```

**Security stack** (applied in order): rate limiting → IP/CIDR filter → HMAC verification → execute flow

- HMAC format in header: `sha256=<hex_signature>`
- Constant-time comparison for HMAC
- Global rate limit: 100 req/s burst 50; per-endpoint if `rps` set
- All webhook responses: HTTP 200, errors in body

**Webhook URL:** `{base}/wh{path}` or `{base}/kt/{ns}/{name}/wh/{path}`

**Params injected into flow:** query params + JSON body merged (body wins conflicts), plus:
```lua
params.trigger_type   -- "webhook"
params.trigger_id     -- "wh_xxxxxxxx"
params.trigger_path   -- the webhook path (e.g. "/my/hook")
-- All merged query+body fields available as params.{field_name} (string values)
-- Also set: ctx.params (same merged fields as table) and ctx.req ({method, path, headers, files})
```

---

## Event Triggers

```lua
event("order.created")    -- exact match
event("order.*")          -- wildcard: matches order.created, order.updated
                          -- does NOT match "order" or "orders.created"
```

Pattern matching rules:
- Exact: `"order.created"` matches only `"order.created"`
- Wildcard `"order.*"`: prefix must be followed by `.` then one or more chars
- Pattern `"order.*"` does NOT match `"order"` (no suffix) or `"orders.x"` (wrong prefix)

**Params injected into flow:**
```lua
params.trigger_type    -- "event"
params.trigger_id      -- "ev_xxxxxxxx"
params.event_id        -- UUID of the event
params.event_pattern   -- the pattern that was emitted
params.event_source    -- flow that emitted the event
params.event_payload   -- table of event data
params.event_time      -- RFC3339 timestamp
```

**Emitting events from Lua:**
```lua
sentinel.emit("order.created", {id=123, customer="abc"})
```

Flows can also subscribe to harness-emitted operational events such as:
- `backup.schedule.synced`
- `backup.run.started`
- `backup.run.completed`
- `backup.run.failed`

---

## Form Triggers

Forms wire to flows via `events.yaml`:
```yaml
events:
  "kf.{ns}.{name}.{form}":
    flows:

From ndx-au/sre-init, MIT.

More from ndx-au/sre-init