Skip to main content

EventSource

Trait EventSource 

Source
pub trait EventSource:
    Send
    + Sync
    + 'static {
    // Required methods
    fn capabilities(&self) -> SourceCapabilities;
    fn next_delivery<'life0, 'life1, 'async_trait>(
        &'life0 self,
        request: DeliveryRequest<'life1>,
    ) -> Pin<Box<dyn Future<Output = Result<Option<Delivery>, EventSourceError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             Self: 'async_trait;
    fn acknowledge<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        chain_id: u64,
        acknowledgement: &'life1 Acknowledge,
        committed_cursor: &'life2 Cursor,
    ) -> Pin<Box<dyn Future<Output = Result<(), EventSourceError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             Self: 'async_trait;

    // Provided methods
    fn capabilities_for_chain(&self, _chain_id: u64) -> SourceCapabilities { ... }
    fn prepare_desired_state<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _preparation_id: PreparationId,
        _desired_state: &'life1 ApplyDesiredState,
        _acknowledged_cursor: Option<&'life2 Cursor>,
    ) -> Pin<Box<dyn Future<Output = Result<Option<Cursor>, EventSourceError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             Self: 'async_trait { ... }
    fn activate_desired_state<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _preparation_id: PreparationId,
        _desired_state: &'life1 ApplyDesiredState,
        _acknowledged_cursor: Option<&'life2 Cursor>,
    ) -> Pin<Box<dyn Future<Output = Result<(), EventSourceError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             Self: 'async_trait { ... }
    fn abort_desired_state<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _preparation_id: PreparationId,
        _desired_state: &'life1 ApplyDesiredState,
    ) -> Pin<Box<dyn Future<Output = Result<(), EventSourceError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             Self: 'async_trait { ... }
    fn release_session<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _session_id: &'life1 str,
        _chain_id: u64,
    ) -> Pin<Box<dyn Future<Output = Result<(), EventSourceError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             Self: 'async_trait { ... }
    fn wait_for_update<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _request: DeliveryRequest<'life1>,
    ) -> Pin<Box<dyn Future<Output = Result<(), EventSourceError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             Self: 'async_trait { ... }
}
Expand description

Provider-neutral source boundary used by the durable event service.

§Cancellation and failure atomicity

The service applies deadlines by dropping these async futures. Every method must therefore be cancellation-safe as well as failure-atomic: if its future is dropped or returns Err, a retry with the same durable inputs must remain valid and must not observe a partially published transition. Implementations may stage idempotent work behind a preparation or delivery token, but must bound and eventually release such work. Durable service state, not an in-memory source task, is the authority after restart.

Required Methods§

Source

fn capabilities(&self) -> SourceCapabilities

Advertise the guarantees and topology implemented by this source.

Source

fn next_delivery<'life0, 'life1, 'async_trait>( &'life0 self, request: DeliveryRequest<'life1>, ) -> Pin<Box<dyn Future<Output = Result<Option<Delivery>, EventSourceError>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Produce the next delivery after the durable cursor, or None when caught up.

Implementations must inspect DeliveryRequest::required_reorg_anchor. Returning None or a typed unsupported error is valid when the source cannot yet certify it; returning output that skips it is a contract violation and will be rejected before outbox persistence.

Cancellation or Err must not advance the acknowledged source cursor. Repeating the call with the same inputs must return the same pending token and payload, or reconstruct an equivalent delivery without skipping data. Provider reads performed before cancellation are observations only.

§Errors

Returns EventSourceError for invalid/unsupported requests, resource exhaustion, source unavailability, or an internal continuity failure.

Source

fn acknowledge<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, chain_id: u64, acknowledgement: &'life1 Acknowledge, committed_cursor: &'life2 Cursor, ) -> Pin<Box<dyn Future<Output = Result<(), EventSourceError>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Reconcile provider-local state after the service has already committed runtime ingestion and its durable cursor.

This is a post-commit hook, not a transaction participant. It must be idempotent by delivery token/sequence and treat committed_cursor as the authority. Cancellation or Err cannot roll back the service commit; a retry (including after restart with no pending in-memory delivery) must converge provider-local state to that committed cursor without replaying side effects or rejecting an already-applied acknowledgement.

§Errors

Returns EventSourceError when provider-local reconciliation cannot currently converge to the already committed cursor. The error cannot roll back service authority.

Provided Methods§

Source

fn capabilities_for_chain(&self, _chain_id: u64) -> SourceCapabilities

Advertise guarantees for a particular chain. Multi-chain sources should override this; single-capability sources retain the legacy behavior.

Source

fn prepare_desired_state<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _preparation_id: PreparationId, _desired_state: &'life1 ApplyDesiredState, _acknowledged_cursor: Option<&'life2 Cursor>, ) -> Pin<Box<dyn Future<Output = Result<Option<Cursor>, EventSourceError>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Validate and fully prepare a desired state before it becomes durable.

A source that establishes a provider-native activation boundary may return the corresponding portable cursor. The service persists that cursor in the activation barrier, so acknowledging the barrier cannot rewind a newly prepared source (for example, from archive head to genesis). Sources without a prepared boundary return None.

Cancellation or Err must leave the active revision unchanged. Any staged candidate must remain safely retryable by preparation_id or removable by EventSource::abort_desired_state.

§Errors

Returns EventSourceError when the desired state is invalid or unsupported, resources are exhausted, the provider is unavailable, or preparation cannot complete atomically.

Source

fn activate_desired_state<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _preparation_id: PreparationId, _desired_state: &'life1 ApplyDesiredState, _acknowledged_cursor: Option<&'life2 Cursor>, ) -> Pin<Box<dyn Future<Output = Result<(), EventSourceError>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Activate a previously prepared desired state after its durable commit.

Cancellation or Err must not expose a partially activated revision; the previous active source must remain usable and the candidate must remain retryable or abortable.

§Errors

Returns EventSourceError when the prepared candidate is missing or inconsistent, resources are unavailable, or activation cannot complete atomically.

Source

fn abort_desired_state<'life0, 'life1, 'async_trait>( &'life0 self, _preparation_id: PreparationId, _desired_state: &'life1 ApplyDesiredState, ) -> Pin<Box<dyn Future<Output = Result<(), EventSourceError>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Discard a prepared desired state when its durable commit fails.

This operation must be idempotent. Cancellation or Err must leave a later abort retry able to finish cleanup without losing the active source.

§Errors

Returns EventSourceError when cleanup cannot currently complete. Implementations must leave the same abort safely retryable.

Source

fn release_session<'life0, 'life1, 'async_trait>( &'life0 self, _session_id: &'life1 str, _chain_id: u64, ) -> Pin<Box<dyn Future<Output = Result<(), EventSourceError>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Release all process-local state for a stream that owned this durable session. The service invokes this at most once for each successfully negotiated lease, after it stops using every other source method.

Implementations must be idempotent and cancellation-safe. An error or cancellation at EventService::with_source_operation_timeout may mean cleanup is partial. In either case the service retains the lease (fail closed), so another generation cannot overlap it; a service restart is needed to recover that session identity.

§Errors

Returns EventSourceError when process-local session cleanup cannot complete. The service then retains the lease to prevent overlap.

Source

fn wait_for_update<'life0, 'life1, 'async_trait>( &'life0 self, _request: DeliveryRequest<'life1>, ) -> Pin<Box<dyn Future<Output = Result<(), EventSourceError>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Wait until the source reports that a newer archive height may be available. Providers without a push signal can retain the default; EventService always keeps its polling interval as a fallback. The request is identical to the one used for delivery production, so a push source can wait for a required reorg anchor instead of waking on a newer but insufficient source hint. This future is observational: cancellation or Err must not consume a unique wakeup needed for correctness, because polling remains authoritative.

§Errors

Returns EventSourceError when the wakeup request is invalid or the source cannot observe updates. Failure must not consume correctness state.

Dyn Compatibility§

This trait is dyn compatible.

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

Implementors§