rhei-core 1.5.0

//! [`SyncEngine`] trait — CDC-to-OLAP replication.
//!
//! The production implementation (`CdcSyncEngine` in `rhei-sync`) polls a
//! [`crate::CdcConsumer`], converts events to DML via the sync converter, and
//! applies them to an [`crate::OlapEngine`].

use crate::types::{SyncResult, SyncStatus};

/// Applies CDC events from the OLTP engine to the OLAP engine.
///
/// The sync loop (in `rhei-sync`) calls [`SyncEngine::sync_once`] repeatedly
/// on a configurable interval. A [`crate::SyncMode`] controls whether the OLAP
/// table is kept as a mirror (`Destructive`) or an append-only temporal store
/// (`Temporal` / SCD Type 2).
///
/// # Contract for implementors
///
/// - [`sync_once`](SyncEngine::sync_once) must be idempotent with respect to
///   network/storage failures: a partially-applied cycle must be recoverable by
///   re-running with the same watermark.
/// - [`status`](SyncEngine::status) must be cheap and non-blocking.
pub trait SyncEngine: Send + Sync {
    /// Engine-specific error type returned by all fallible methods.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Poll the CDC log and apply any new events to the OLAP engine.
    ///
    /// Returns a [`SyncResult`] summarising the work done. If there are no new
    /// events, the result will have all counters set to zero and `last_seq =
    /// None`.
    ///
    /// # Errors
    ///
    /// Returns `Err(Self::Error)` if either the CDC consumer or the OLAP engine
    /// encounters an unrecoverable failure.
    fn sync_once(
        &self,
    ) -> impl std::future::Future<Output = Result<SyncResult, Self::Error>> + Send;

    /// Return a snapshot of the current replication state.
    ///
    /// # Errors
    ///
    /// Returns `Err(Self::Error)` if the underlying status query fails.
    fn status(&self) -> impl std::future::Future<Output = Result<SyncStatus, Self::Error>> + Send;
}