roboto.domain.platform_events.catalog

Module Contents

roboto.domain.platform_events.catalog.DEFAULT_PLATFORM_EVENT_CATALOG

The catalog of every PlatformEventType, used wherever a caller does not supply its own (envelope payload binding, trigger validation, evaluation).

roboto.domain.platform_events.catalog.ENVELOPE_ROOT = 'envelope'

its id, source, subject, type, time, and org. Reserved: no event type may expose it as an entity root.

Type:

Namespace root served from the platform event’s own envelope

roboto.domain.platform_events.catalog.OncePerProjection

Projects a PlatformEvent onto the token string that identifies what the trigger fires once per (e.g. the dataset id for once_per=dataset).

A projection reads the event payload and nothing else: one event in, one string out, with no lookup against platform state. A once_per value can only name what the event itself already identifies, so there is no “once per file in the dataset this event is about”. once_per only collapses repeats; it never fans one event out into several runs, and a trigger dispatches each of its targets at most once per event.

class roboto.domain.platform_events.catalog.PlatformEventCatalog(descriptors)

Descriptors for platform event types, looked up by type.

Everything that varies by event type — payload model, exposed roots, default root, dedup projections — hangs off the PlatformEventDescriptor objects registered here. DEFAULT_PLATFORM_EVENT_CATALOG registers every member of PlatformEventType; a caller may build a catalog over a subset.

Parameters:

descriptors (collections.abc.Iterable[PlatformEventDescriptor])

descriptor(event_type)

Return the descriptor for event_type.

Raises:

ValueError – No descriptor is registered for event_type.

Parameters:

event_type (roboto.domain.platform_events.events.PlatformEventType)

Return type:

PlatformEventDescriptor

exposed_roots(event_type)

Return the namespace roots event_type exposes.

Raises:

ValueError – No descriptor is registered for event_type.

Parameters:

event_type (roboto.domain.platform_events.events.PlatformEventType)

Return type:

frozenset[str]

namespace_roots()

Return the union of every registered event type’s exposed roots.

Return type:

frozenset[str]

subscribable_types()

Return the event types a trigger may subscribe to.

Return type:

frozenset[roboto.domain.platform_events.events.PlatformEventType]

class roboto.domain.platform_events.catalog.PlatformEventDescriptor

Everything the trigger system knows about one platform event type.

Immutable. Carries the payload model the envelope validates against, the namespace roots the event exposes to conditions and target templates, the default root unqualified condition fields bind to, the entity the event is about, and the OncePer values the event supports (as projections from an event to its dedup token value).

Every once_per value is declared as an OncePerProjection, a pure function of the event payload, so a descriptor can only offer what the payload itself names. No descriptor can resolve one event into several subjects, which is what holds dispatch at one per target per event.

default_root: str

Root that unqualified condition fields bind to. Always one of exposed_roots.

event_type: roboto.domain.platform_events.events.PlatformEventType

The event type this descriptor describes.

exposed_roots: frozenset[str]

Namespace roots (dataset, file, changed, …) this event exposes.

idempotency_token(event, once_per)

Return the dedup token for event at once_per.

Two events that project onto the same token dispatch the same target of the same trigger at most once.

Parameters:

• event (roboto.domain.platform_events.events.PlatformEvent) – The event to project. Must be of this descriptor’s type.

• once_per (roboto.domain.platform_events.once_per.OncePer) – What the trigger fires once per.

Raises:

ValueError – event is of a different type, or once_per is not supported by this event type.

Return type:

str

once_per_projections: collections.abc.Mapping[roboto.domain.platform_events.once_per.OncePer, OncePerProjection]

Supported once_per values, each mapped to the projection that yields its token. Key presence defines legality; every event supports OncePer.Occurrence.

payload_model: type[pydantic.BaseModel]

Model of PlatformEvent.data for this event type.

subject(event)

Return the roboto:// URI of the entity event is about.

Raises:

ValueError – event is not of this descriptor’s event type.

Parameters:

event (roboto.domain.platform_events.events.PlatformEvent)

Return type:

roboto.uri.RobotoUri

subject_type: roboto.uri.RobotoUriType

The kind of entity this event is about — its CloudEvents subject. The payload carries that entity’s id under {subject_type}_id; everything else in it is context around the entity: the upload transaction a file arrived in, the files added to a session, the applied changeset.

subscribable: bool = True

Whether a trigger may name this type in an EventSubscription. False for occurrences delivered to a single trigger rather than broadcast to subscribers — the schedule tick — which still carry a descriptor so their tokens and namespaces are built the same way.

property supported_once_per: frozenset[roboto.domain.platform_events.once_per.OncePer]

The OncePer values this event type supports.

Return type:

frozenset[roboto.domain.platform_events.once_per.OncePer]

supports_once_per(once_per)

Return whether once_per is legal for this event type.

Parameters:

once_per (roboto.domain.platform_events.once_per.OncePer)

Return type:

bool

roboto.domain.platform_events.catalog.RESERVED_ROOTS

Roots the evaluation namespace serves itself. A descriptor claiming one would be silently shadowed by the envelope or the trigger, so construction rejects it.

roboto.domain.platform_events.catalog.TRIGGER_ROOT = 'trigger'

Namespace root describing the trigger being evaluated. Reserved for the consumer; no event type may expose it as an entity root.

roboto.domain.platform_events.catalog.event_catalog_manifest(catalog=DEFAULT_PLATFORM_EVENT_CATALOG)

The catalog as the web UI’s TypeScript mirror reads it: per event type, its roots, default root, supported grains, subject type, and whether a trigger may subscribe.

event_catalog.json in this package is this function’s output, written by scripts/gen_trigger_manifests.py and drift-checked by a test on each side.

Parameters:

catalog (PlatformEventCatalog)

Return type:

dict[str, Any]