Trait TriggerPlugin 

pub trait TriggerPlugin: Send + Sync {
    // Required methods
    fn subscription(&self) -> &TriggerSubscription;
    fn fire(
        &self,
        ctx: TriggerContext<'_>,
        events: &MutationBatch,
    ) -> Result<TriggerOutcome, FnError>;

    // Provided method
    fn on_deferred(
        &self,
        ctx: TriggerContext<'_>,
        events: &MutationBatch,
        _payload: &str,
    ) -> Result<TriggerOutcome, FnError> { ... }
}

A fine-grained mutation trigger.

Required Methods

fn subscription(&self) -> &TriggerSubscription

Subscription describing which events this trigger receives.

fn fire( &self, ctx: TriggerContext<'_>, events: &MutationBatch, ) -> Result<TriggerOutcome, FnError>

Fire the trigger with a batch of matching mutation events.

Threading policy

fire is synchronous; the host wraps it differently depending on the subscription’s FireMode:

• FireMode::Synchronous — invoked inline on the transaction commit path, on a tokio::task::spawn_blocking worker thread. Returning TriggerOutcome::Reject aborts the transaction; long-running work blocks the committer, so keep the body tight.
• FireMode::Async — fires off a separate spawn_blocking task after the transaction commits; cannot reject (the transaction has already landed). Failures are logged but do not roll back.
• FireMode::EventualConsistency — batched via the BackgroundJobProvider machinery; the same blocking-worker contract from crate::traits::background::BackgroundJobProvider::execute applies.

In every mode the body must not call block_on against the host runtime; panics are caught at the dispatcher boundary.

See docs/PLUGIN_THREADING.md for the long-form rationale.

Errors

Returns FnError if the fire cannot complete. For Synchronous triggers this aborts the surrounding transaction.

Provided Methods

fn on_deferred( &self, ctx: TriggerContext<'_>, events: &MutationBatch, _payload: &str, ) -> Result<TriggerOutcome, FnError>

Re-fire after a TriggerOutcome::Defer previously returned.

The host’s deferral queue invokes this with the original payload once the delay has elapsed. The default implementation delegates back to Self::fire with the original MutationBatch — existing trigger plugins keep working without changes. Plugins that need access to the payload (e.g., to resume a long-running aggregation) override this method.

Returning TriggerOutcome::Defer from on_deferred re-queues the item with attempt + 1, capped at the host’s DEFER_MAX_ATTEMPTS.

Errors

Returns FnError when the deferred fire cannot complete. The error is logged at warn and the item is dropped.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors