Skip to main content
A session’s stream is an append-only log of what happened in it: one record per change, in id order. It is stored in blobhub-workflow-session-stream (partition session_id, sort key id), read with list_session_events and get_session_event, pushed to WebSocket connections through listener/add, and acted on by declared listeners. Producers append to the stream. The router matches each new record against the session’s listeners, and a read returns the same records by id. Both use one filter. An execution’s own flow.* and processor.* events are kept apart, in the execution log.

Record

  • id is sixteen lowercase hex digits of microseconds since the Unix epoch, a dash, and eight lowercase Crockford base-32 characters. Ids sort in the order they were issued; one producer never issues two out of order.
  • created_at is the same instant, always with six fractional digits and Z.
  • A type adds one block (session, object and item, object and changes, or execution) and nothing else.
  • expires_at is epoch seconds, the record’s created_at plus the session’s workflow.session_event_retention_days; it is absent when that limit is unlimited.

Source

{kind, user_id?, execution_id?, processor_id?, listener?, client?, depth}; depth is always present.

Client

client is a string of 1-64 characters that a write command (and the four writing logic.code verbs, upload_session_object, delete_session_object, post_session_thread_item and apply_session_graph_mutations) accepts and echoes. An execution’s execution.started and execution.ended never carry the execution’s client, so a client that excludes its own writes still sees the run it started end. A thread item posted with a client stores it: the item in a thread listing, in get_session_thread_item and in the event’s item block all carry the same value as source.client.

Types

An execution’s flow.* and processor.* events live in the execution log (blobhub-workflow-execution-log, read with list_execution_events), not on the stream. One example for each family of block:

Reading

list_session_events {session, filter?, after?, before?, ascending?, limit?, cursor?, include_session?} returns {events, cursor, session?}; get_session_event returns {event}. See List Session Events.
  • session is an id or an alias and must belong to the route’s revision. A deleted session is still served by id while its stream lasts; include_session then gives null.
  • after and before are event ids (exclusive) and bound the range; ascending defaults to false, limit to 100 (1-1000).
  • The filter runs on the server over each page. A request keeps reading until it has limit matches, the range is exhausted, or it has evaluated 10,000 rows; only that budget can end a page short while cursor is still live.
  • cursor is opaque and resumes after the last row evaluated. A cursor together with after or before is refused.

Settle time

An event’s id is minted just before its row is written, so a row can commit after a row with a larger id. Every append is bounded, so an event is visible to a read at most N = 60 seconds after the timestamp in its id, and every listing reads consistently. A client that follows the stream with after: <last id> can therefore skip a late row. To follow it without a gap, re-read from the boundary id of a timestamp a minute older than the last event seen (the recipe below) and drop the ids already held.

Boundary ids

To start at a timestamp, convert it to the id that sorts before every event of that microsecond: the microseconds since the epoch as sixteen lowercase hex digits, then a dash (f"{micros:016x}-"). Pass it as after (events from that instant on, since every id of the microsecond sorts after it) or as before.

Retention

Each record carries expires_at (see Record): its created_at plus the session’s workflow.session_event_retention_days. The default is 30 days and the limit can be raised to 365; set to null it keeps records forever, and then expires_at is absent. A session.deleted record outlives the purge of the session and is kept 24 hours. Limits says how a limit is read and changed.