Reacting to Events

1. Two runs act on the same state at once.
2. An event lands while a run is busy and is never seen.
3. A run’s own writes wake it again.
4. A burst of writes starts a burst of runs.
5. A cursor kept somewhere drifts from the truth.

What a run can count on

• It is woken, not fed. An event says something changed here. A run reads the current state and acts on it; the batch tells it where to look (which aliases, items and executions) and is not the state. Two hundred writes to one alias are one entry with distinct_by.
• One lane runs one run at a time. concurrency divides a listener’s events in a session into lanes: serial has one lane and keyed one per key value, each with at most one run in flight. parallel runs up to max_parallel at once and waits when its slots are full (below).
• A matching event reaches a run at least once, unless its batch is consumed without one. Delivery is at least once: a rare event reaches two runs, an event that commits late can arrive in a later batch than events with larger ids, and batches are not globally ordered. A declared retry delivers a failed run’s batch again (below). A listener takes effect up to about ten seconds after it is saved, and events routed before then are not delivered to it. A batch that is skipped (depth, session_not_open, unmatched or throttled), ends in access_error, or comes due while the listener is switched off in the session is consumed and never runs; every one but the switched-off batch leaves an outcome that says why. A reconcile catches up on the next batch.
• It keeps no cursor. The platform holds the listener’s position in the stream. A run that wants more than its batch reads the stream itself with list_session_events; batch.first_id and batch.last_id are ids it can pass as after or before.
• It is not woken by itself. Everything the run writes, and the run’s own execution.ended, carries the listener as source.listener and never matches it.
• It is bounded. A burst becomes one batch per window, up to max_events entries; a chain of listeners stops at workflow.listener_chain_depth; fires are throttled at workflow.listener_fires_per_minute. See Limits.

Concurrency

What you write

• a cursor, since the platform holds the position;
• a lease, since a serial or keyed lane never has two runs in flight;
• a sleep-and-poll loop, since the listener wakes the run;
• an item posted to remember that an event was seen, since a repeated event is reconciled to the same result.

When a run fails

1. The execution’s status. list_executions {session_id, listener} lists the runs a listener started. A run that was started and then failed has the outcome success, since the action was accepted; its own status is the result.
2. The outcome on the listener’s state in the session, read with list_session_listeners: invocation_error when the action or its template failed, refused when a limit refused it. A retry’s outcome carries retry, which says which repeat it is (outcomes).
3. A receipt, when the listener declares one: a thread item with the outcome’s status, posted for success, invocation_error, refused and throttled.

One writer per alias

A clock

{
  "command": "create_schedule",
  "alias": "ops-clock",
  "repeat": "recurring_cron",
  "cron_expression": "0/15 * * * ? *",
  "timezone": "UTC",
  "invocation_target_type": "object",
  "invocation_target": {
    "target": {"blob": "${blob_id}", "revision": "${revision_id}", "session": "${session_id}"},
    "alias": "ops/clock",
    "value": {"type": "text", "text": "tick"}
  }
}

{"types": ["object.written", "thread.item_posted"], "aliases": ["tickets/**", "ops/clock"]}

Use cases