Messaging & Events
PubSubService, domain events, @JobEvent, event dispatch, deduplication, job queues, and @JobDefinition executors.
Overview
- Domain Events — dispatched from services after writes, trigger job enqueuing and pub-sub publishing.
- PubSubService — real-time publish/subscribe for inter-process notification and GraphQL subscriptions.
- Job Queues — durable, at-least-once background job processing.
Defining Events
Events are @Serializable classes annotated with @JobEvent:
| @JobEvent Parameter | Purpose |
|---|---|
jobs | Job classes to enqueue when dispatched |
pubsubChannel | Channel to publish to (empty = no publish) |
Dispatching Events
KSP generates a dispatch() extension. Job queues defer enqueueing while a transaction is active until commit. Pub/sub publication happens immediately during dispatch.
Dispatch directly inside the transaction. Job enqueueing already waits for commit. Subscribers should treat pub/sub messages as notifications and apply the normal read permissions when fetching data.
Event Deduplication
Within an event-manager context, deferredEvents {} captures events and flushes them on scope exit. Events of the same class and identityKey() collapse to the last occurrence. Event types must override the default key to deduplicate separate instances. Scope-exit flushing is separate from transaction commit timing:
Job Executors
The following excerpt uses the collection indexing executor and its named transformation provider. A job executor extends AbstractJobExecutor<T> and is annotated with @JobDefinition:
The queue in @JobDefinition is a DI provider name, such as JobQueueNames.contentJobQueue. Register the generated executor provider in the runner that handles the job. At-least-once delivery means executors must handle redelivery without duplicating completed effects.
Job payload
Full Event Flow
The complete lifecycle: