rhei-core 1.5.0

//! [`CdcConsumer`] trait — polling interface for CDC event streams.
//!
//! The default implementation in `rhei-oltp-rusqlite` reads from the
//! `_rhei_cdc_log` SQLite table populated by triggers. Alternative backends
//! (e.g., WAL-based or RocksDB-backed) implement this same trait.

use crate::types::CdcEvent;

/// Consumes CDC (Change Data Capture) events from the OLTP engine.
///
/// The default implementation uses trigger-based CDC with a `_rhei_cdc_log`
/// table. Future implementations may use WAL-based approaches.
///
/// # Contract for implementors
///
/// - [`poll`](CdcConsumer::poll) must return events in ascending
///   [`CdcEvent::seq`] order.
/// - [`prune`](CdcConsumer::prune) must be idempotent: pruning an already-
///   pruned range must not error.
/// - All methods must be `Send` so they can be called from async tasks.
pub trait CdcConsumer: Send + Sync {
    /// Engine-specific error type returned by all fallible methods.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Poll for new CDC events after the given sequence number.
    ///
    /// Returns at most `limit` events ordered by ascending [`CdcEvent::seq`].
    /// Pass `after_seq = None` to start from the very beginning of the log.
    ///
    /// # Errors
    ///
    /// Returns `Err(Self::Error)` if the underlying storage is unavailable or
    /// returns a malformed event.
    fn poll(
        &self,
        after_seq: Option<i64>,
        limit: u32,
    ) -> impl std::future::Future<Output = Result<Vec<CdcEvent>, Self::Error>> + Send;

    /// Return the highest [`CdcEvent::seq`] currently in the CDC log, or
    /// `None` if the log is empty.
    ///
    /// # Errors
    ///
    /// Returns `Err(Self::Error)` if the storage query fails.
    fn latest_seq(
        &self,
    ) -> impl std::future::Future<Output = Result<Option<i64>, Self::Error>> + Send;

    /// Delete CDC events with `seq <= up_to_seq` from the log.
    ///
    /// Called by the sync engine after events have been successfully applied to
    /// the OLAP backend. Returns the number of events deleted.
    ///
    /// # Errors
    ///
    /// Returns `Err(Self::Error)` if the delete operation fails.
    fn prune(
        &self,
        up_to_seq: i64,
    ) -> impl std::future::Future<Output = Result<u64, Self::Error>> + Send;
}