Struct SubscriptionBuilder 

pub struct SubscriptionBuilder<E: Executor> { /* private fields */ }

Builder for creating event subscriptions.

Created via [Projection::subscription], this builder configures a continuous event processing subscription with retry logic, routing key filtering, and graceful shutdown support.

Example

let subscription = projection
    .subscription()
    .routing_key("accounts")
    .chunk_size(100)
    .retry(5)
    .delay(Duration::from_secs(10))
    .start(&executor)
    .await?;

// Later, gracefully shutdown
subscription.shutdown().await?;

Implementations

impl<E: Executor + 'static> SubscriptionBuilder<E>

pub fn new(key: impl Into<String>) -> Self

Creates a new projection with the given key.

The key is used as the subscription identifier for cursor tracking.

pub fn safety_check(self) -> Self

Enables safety checks for unhandled events.

When enabled, processing fails if an event is encountered without a handler.

pub fn handler<H: Handler<E> + 'static>(self, h: H) -> Self

Registers an event handler with this subscription.

Panics

Panics if a handler for the same event type is already registered.

pub fn skip<EV: AggregatorEvent + Send + Sync + 'static>(self) -> Self

Registers a skip handler for an event type.

Events of this type will be acknowledged but not processed.

Panics

Panics if a handler for the same event type is already registered.

pub fn data<D: Send + Sync + 'static>(self, v: D) -> Self

Adds shared data to the subscription context.

Data added here is accessible in handlers via the context.

pub fn accept_failure(self) -> Self

Allows the subscription to continue after handler failures.

By default, subscriptions stop on the first error. With this flag, errors are logged but processing continues.

pub fn chunk_size(self, v: u16) -> Self

Sets the number of events to process per batch.

Default is 300.

pub fn delay(self, v: Duration) -> Self

Sets a delay before starting the subscription.

Useful for staggering subscription starts in multi-node deployments.

pub fn routing_key(self, v: impl Into<String>) -> Self

Filters events by routing key.

Only events with the matching routing key will be processed.

pub fn retry(self, v: u8) -> Self

Sets the maximum number of retries on failure.

Uses exponential backoff. Default is 30.

pub fn all(self) -> Self

Processes all events regardless of routing key.

pub fn aggregator<A: Aggregator>(self, id: impl Into<String>) -> Self

Adds a related aggregate to process events from.

pub async fn unretry_start(self, executor: &E) -> Result<Subscription>

where E: Clone,

Starts the subscription without retry logic.

Equivalent to calling start() with retries disabled.

pub async fn start(self, executor: &E) -> Result<Subscription>

where E: Clone,

Starts a continuous background subscription.

Returns a Subscription handle that can be used for graceful shutdown. The subscription runs in a spawned tokio task and polls for new events.

pub async fn unretry_execute(self, executor: &E) -> Result<()>

Executes the subscription once without retry logic.

Processes all pending events and returns. Does not poll for new events.

pub async fn execute(&self, executor: &E) -> Result<()>

Executes the subscription once, processing all pending events.

Unlike start(), this does not run continuously. It processes all currently pending events and returns.