Skip to main content

SourceProvider

Trait SourceProvider 

Source
pub trait SourceProvider<Envelope>:
    Send
    + Sync
    + 'static {
    // Required methods
    fn manifest(&self) -> &ProviderManifest;
    fn source_from<'life0, 'life1, 'async_trait>(
        &'life0 self,
        cursor: Option<&'life1 ProjectionCursor>,
        mode: QueryMode,
    ) -> Pin<Box<dyn Future<Output = ProjectionResult<ProjectionSource<Envelope>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn extract_cursor(
        &self,
        envelope: &Envelope,
    ) -> ProjectionResult<ProjectionCursor>;
    fn compare_positions(
        &self,
        left: &CursorPosition,
        right: &CursorPosition,
    ) -> ProjectionResult<Ordering>;

    // Provided methods
    fn validate_projection_id(
        &self,
        _projection_id: &ProjectionId,
    ) -> ProjectionResult<()> { ... }
    fn resume_allows(
        &self,
        cursor: &ProjectionCursor,
        envelope: &Envelope,
    ) -> ProjectionResult<bool> { ... }
}
Expand description

Factory for provider-complete, restartable projection sources.

Self::source_from must materialize a new source every time it is invoked. Returning a reused stream or a clone sharing one underlying query cursor violates the projection restart contract.

Delivery guarantees apply only to envelopes emitted by the provider. They cannot repair source-side omissions: PostgreSQL live tag/slice queries can permanently skip events committed by transactions open longer than their configured visibility lag, Cassandra can commit a journal row while losing its non-atomic tag-index row until external repair, and durable-state change sources may coalesce rapid revisions to the latest revision per id.

Required Methods§

Source

fn manifest(&self) -> &ProviderManifest

Returns the stable durable identity of this provider and cursor format.

Source

fn source_from<'life0, 'life1, 'async_trait>( &'life0 self, cursor: Option<&'life1 ProjectionCursor>, mode: QueryMode, ) -> Pin<Box<dyn Future<Output = ProjectionResult<ProjectionSource<Envelope>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Materializes a fresh source beginning at cursor.

Inclusive-resume implementations should begin at the cursor position; the runtime’s demand-side resume filter removes already consumed boundary events before they reach the handler.

Source

fn extract_cursor( &self, envelope: &Envelope, ) -> ProjectionResult<ProjectionCursor>

Extracts the complete durable cursor after processing envelope.

For an inclusive position shared by multiple persistence ids, the returned boundary should contain the identity represented by this envelope. The runtime merges identities at equal positions.

Source

fn compare_positions( &self, left: &CursorPosition, right: &CursorPosition, ) -> ProjectionResult<Ordering>

Compares two opaque provider positions in source order.

Implementations must not use lexical ordering unless their stable position codec is explicitly lexicographically sortable.

Provided Methods§

Source

fn validate_projection_id( &self, _projection_id: &ProjectionId, ) -> ProjectionResult<()>

Validates that this provider may run under projection_id.

The projection runtime invokes this side-effect-free hook during spawn validation, before the provider is materialized or an offset-store generation is claimed. Most providers accept any valid projection id, so the default preserves that behavior. Providers whose durable source identity requires a particular instance key can override the hook and return a fatal ProjectionError::InvalidConfig.

Source

fn resume_allows( &self, cursor: &ProjectionCursor, envelope: &Envelope, ) -> ProjectionResult<bool>

Decides whether envelope is after the already-consumed resume cursor.

Providers may override this for backend-specific inclusive-resume rules. The default drops earlier positions, accepts later positions, and at an equal position checks the emitted envelope’s own boundary identity. A scalar cursor with no boundary identity treats equality as consumed. An equal-position cursor containing multiple identities is rejected as ambiguous: Self::extract_cursor must identify the one (persistence_id, sequence_nr) represented by this envelope, rather than returning a cumulative boundary set.

Dyn Compatibility§

This trait is dyn compatible.

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

Implementors§