BoscaDeveloper Documentation

Messaging & Events

PubSubService, domain events, @JobEvent, event dispatch, deduplication, job queues, and @JobDefinition executors.

Overview

  1. Domain Events — dispatched from services after writes, trigger job enqueuing and pub-sub publishing.
  2. PubSubService — real-time publish/subscribe for inter-process notification and GraphQL subscriptions.
  3. Job Queues — durable, at-least-once background job processing.

Defining Events

Events are @Serializable classes annotated with @JobEvent:

kotlin
@JobEvent ParameterPurpose
jobsJob classes to enqueue when dispatched
pubsubChannelChannel 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.

kotlin

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:

kotlin

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:

kotlin

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

kotlin

Full Event Flow

The complete lifecycle:

Event flow