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§
Sourcefn capabilities(&self) -> SourceCapabilities
fn capabilities(&self) -> SourceCapabilities
Advertise the guarantees and topology implemented by this source.
Sourcefn 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 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.
Sourcefn 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,
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§
Sourcefn capabilities_for_chain(&self, _chain_id: u64) -> SourceCapabilities
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.
Sourcefn 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 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.
Sourcefn 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 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.
Sourcefn 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 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.
Sourcefn 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 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.
Sourcefn 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,
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".