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
idis 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_atis the same instant, always with six fractional digits andZ.- A type adds one block (
session,objectanditem,objectandchanges, orexecution) and nothing else. expires_atis epoch seconds, the record’screated_atplus the session’sworkflow.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.
sessionis 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_sessionthen givesnull.afterandbeforeare event ids (exclusive) and bound the range;ascendingdefaults tofalse,limitto 100 (1-1000).- The filter runs on the server over each page. A request keeps
reading until it has
limitmatches, the range is exhausted, or it has evaluated 10,000 rows; only that budget can end a page short whilecursoris still live. cursoris opaque and resumes after the last row evaluated. A cursor together withafterorbeforeis 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 withafter: <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 carriesexpires_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.
