roboto.domain.platform_events.catalog
Module Contents
DATASET_ROOT
Namespace root naming a dataset. An event exposing it is about a dataset or about something within one, so a consumer may reach that dataset’s files from the event.
DEFAULT_PLATFORM_EVENT_CATALOG
The catalog of every PlatformEventType, used wherever a caller does not supply its own (envelope payload binding, trigger validation, evaluation).
ENVELOPE_ROOT
Namespace root served from the platform event’s own envelope: its id, source, subject, type, time, and org, plus the payload as published under data. Reserved: no event type may expose it as an entity root.
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.
PlatformEventCatalog
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.PlatformEventCatalog.descriptor()
Return the descriptor for event_type.
Parameters
Raises
ValueErrorNo descriptor is registered for event_type.
Return type
PlatformEventCatalog.exposed_roots()
Return the namespace roots event_type exposes.
Parameters
Raises
ValueErrorNo descriptor is registered for event_type.
Return type
PlatformEventCatalog.namespace_roots()
Return the union of every registered event type’s exposed roots.
Return type
PlatformEventCatalog.subscribable_types()
Return the event types a trigger may subscribe to.
Return type
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.
Attributes
PlatformEventDescriptor.default_root
Root that unqualified condition fields bind to. Always one of exposed_roots.
PlatformEventDescriptor.event_type
The event type this descriptor describes.
PlatformEventDescriptor.exposed_roots
Namespace roots (dataset, file, changed, …) this event exposes.
PlatformEventDescriptor.idempotency_token()
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
The event to project. Must be of this descriptor’s type.
What the trigger fires once per.
Raises
ValueErrorevent is of a different type, or once_per is not supported by this event type.
Return type
Attributes
PlatformEventDescriptor.once_per_projections
once_per_projections collections.Supported once_per values, each mapped to the projection that yields its token. Key presence defines legality; every event supports OncePer.Occurrence.
PlatformEventDescriptor.payload_model
Model of PlatformEvent.data for this event type.
PlatformEventDescriptor.subject()
Return the roboto:// URI of the entity event is about.
Parameters
Raises
ValueErrorevent is not of this descriptor’s event type.
Return type
Attributes
PlatformEventDescriptor.subject_type
The kind of entity this event is about — its CloudEvents subject. The payload carries that entity’s id under {subject_type}_id, and may say more about it, such as the version a file was at. The rest is context around the entity: the upload transaction a file arrived in, or the applied changeset.
PlatformEventDescriptor.subscribable
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.
Properties
PlatformEventDescriptor.supported_once_per
The OncePer values this event type supports.
PlatformEventDescriptor.supports_once_per()
Return whether once_per is legal for this event type.
Parameters
Return type
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.
TRIGGER_ROOT
Namespace root describing the trigger being evaluated. Reserved for the consumer; no event type may expose it as an entity root.
event_catalog_manifest()
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 PlatformEventCatalogReturn type