datum-persistence 0.11.3

Event sourcing, durable state, and CQRS persistence for Datum
Documentation
//! Fenced projection cursor and management storage.

use std::{
    collections::HashMap,
    sync::{Arc, Mutex, MutexGuard},
};

use super::{CursorPosition, ProjectionCursor, ProjectionError, ProjectionId, ProjectionResult};

/// Monotonic ownership generation for one [`ProjectionId`].
///
/// Generation zero represents an unclaimed key. Every successful
/// [`ProjectionOffsetStore::claim`] increments the durable value and returns a
/// non-zero generation. A store must never wrap the value.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ProjectionGeneration(u64);

impl ProjectionGeneration {
    /// Creates a generation from its durable numeric representation.
    #[must_use]
    pub const fn new(value: u64) -> Self {
        Self(value)
    }

    /// Returns the durable numeric representation.
    #[must_use]
    pub const fn as_u64(self) -> u64 {
        self.0
    }
}

/// Durable cursor store with generation fencing and position CAS.
///
/// `claim`, `save`, and `clear` must linearize independently for each
/// [`ProjectionId`]. A save succeeds only when both its generation is current
/// and its expected position equals the position currently stored (`None`
/// means no cursor). Generation loss and CAS conflicts are deterministic fatal
/// errors; storage I/O and uncertain outcomes are restartable.
///
/// The paused management flag is logically independent from the cursor.
/// [`Self::clear`] removes only the cursor and must retain the management row.
#[async_trait::async_trait]
pub trait ProjectionOffsetStore: Send + Sync {
    /// Validates that this store can participate in exactly-once delivery.
    ///
    /// Exactly-once builders must call this during spawn, before claiming a
    /// generation or materializing a source. The default rejects the mode:
    /// stores must opt in only when they can commit handler writes and the
    /// cursor in one transaction.
    fn validate_exactly_once(&self) -> ProjectionResult<()> {
        Err(ProjectionError::invalid_config(
            "delivery_semantics",
            "exactly-once requires a transactional projection offset store",
        ))
    }

    /// Atomically increments and returns the owner generation for `projection_id`.
    async fn claim(&self, projection_id: &ProjectionId) -> ProjectionResult<ProjectionGeneration>;

    /// Loads the current provider-complete cursor, if one has been saved.
    async fn load(
        &self,
        projection_id: &ProjectionId,
    ) -> ProjectionResult<Option<ProjectionCursor>>;

    /// Saves a cursor under generation fencing and expected-position CAS.
    ///
    /// `expected_position` is the position returned by the caller's previous
    /// load/save, or `None` when the caller expects no cursor. Comparing the
    /// position rather than only checking generation prevents stale
    /// same-generation work from overwriting a management clear/update.
    async fn save(
        &self,
        projection_id: &ProjectionId,
        generation: ProjectionGeneration,
        expected_position: Option<&CursorPosition>,
        cursor: ProjectionCursor,
    ) -> ProjectionResult<()>;

    /// Removes the cursor under generation fencing.
    ///
    /// The ownership generation and paused management row remain present. A
    /// stale generation must be rejected.
    async fn clear(
        &self,
        projection_id: &ProjectionId,
        generation: ProjectionGeneration,
    ) -> ProjectionResult<()>;

    /// Loads the persistent paused flag. An unknown management row is not paused.
    async fn load_paused(&self, projection_id: &ProjectionId) -> ProjectionResult<bool>;

    /// Persists the paused flag independently of cursor state.
    async fn set_paused(&self, projection_id: &ProjectionId, paused: bool) -> ProjectionResult<()>;

    /// Returns the PostgreSQL transactional extension when this is that store.
    ///
    /// This hidden default keeps third-party offset-store implementations
    /// source-compatible while allowing the exactly-once runtime to reject a
    /// non-PostgreSQL store before processing any envelope.
    #[cfg(feature = "postgres")]
    #[doc(hidden)]
    fn postgres_store(&self) -> Option<&super::PostgresProjectionOffsetStore> {
        None
    }
}

#[derive(Debug, Default)]
struct MemoryOffsetEntry {
    generation: ProjectionGeneration,
    cursor: Option<ProjectionCursor>,
}

#[derive(Debug, Default)]
struct MemoryOffsetState {
    offsets: HashMap<ProjectionId, MemoryOffsetEntry>,
    management: HashMap<ProjectionId, bool>,
}

/// Always-compiled in-memory semantic reference offset store.
///
/// Clones share one in-process state. Every operation is linearized by a
/// short-lived mutex, making this backend the correctness oracle for
/// [`super::testkit::assert_projection_offset_store_semantic_conformance`].
///
/// This backend is intentionally not durable. Dropping every clone loses
/// cursor, generation, and management state, so it cannot establish
/// process-restart equivalence and must not run the durable conformance suite.
#[derive(Debug, Clone, Default)]
pub struct MemoryProjectionOffsetStore {
    state: Arc<Mutex<MemoryOffsetState>>,
}

impl MemoryProjectionOffsetStore {
    /// Creates an empty in-memory projection offset store.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }
}

#[async_trait::async_trait]
impl ProjectionOffsetStore for MemoryProjectionOffsetStore {
    async fn claim(&self, projection_id: &ProjectionId) -> ProjectionResult<ProjectionGeneration> {
        projection_id.validate()?;
        let mut state = lock(&self.state)?;
        let entry = state.offsets.entry(projection_id.clone()).or_default();
        let next = entry.generation.as_u64().checked_add(1).ok_or_else(|| {
            ProjectionError::GenerationExhausted {
                projection_id: projection_id.clone(),
            }
        })?;
        entry.generation = ProjectionGeneration::new(next);
        Ok(entry.generation)
    }

    async fn load(
        &self,
        projection_id: &ProjectionId,
    ) -> ProjectionResult<Option<ProjectionCursor>> {
        projection_id.validate()?;
        let state = lock(&self.state)?;
        Ok(state
            .offsets
            .get(projection_id)
            .and_then(|entry| entry.cursor.clone()))
    }

    async fn save(
        &self,
        projection_id: &ProjectionId,
        generation: ProjectionGeneration,
        expected_position: Option<&CursorPosition>,
        cursor: ProjectionCursor,
    ) -> ProjectionResult<()> {
        projection_id.validate()?;
        let mut state = lock(&self.state)?;
        let entry = state.offsets.get_mut(projection_id);
        validate_generation(projection_id, generation, entry.as_deref())?;

        let entry = entry.expect("validated claimed generation has an entry");
        let actual_position = entry.cursor.as_ref().map(ProjectionCursor::position);
        if actual_position != expected_position {
            return Err(ProjectionError::UnexpectedPosition {
                projection_id: projection_id.clone(),
                expected: expected_position.map(ToString::to_string),
                actual: actual_position.map(ToString::to_string),
            });
        }
        entry.cursor = Some(cursor);
        Ok(())
    }

    async fn clear(
        &self,
        projection_id: &ProjectionId,
        generation: ProjectionGeneration,
    ) -> ProjectionResult<()> {
        projection_id.validate()?;
        let mut state = lock(&self.state)?;
        let entry = state.offsets.get_mut(projection_id);
        validate_generation(projection_id, generation, entry.as_deref())?;
        entry
            .expect("validated claimed generation has an entry")
            .cursor = None;
        Ok(())
    }

    async fn load_paused(&self, projection_id: &ProjectionId) -> ProjectionResult<bool> {
        projection_id.validate()?;
        let state = lock(&self.state)?;
        Ok(state
            .management
            .get(projection_id)
            .copied()
            .unwrap_or(false))
    }

    async fn set_paused(&self, projection_id: &ProjectionId, paused: bool) -> ProjectionResult<()> {
        projection_id.validate()?;
        let mut state = lock(&self.state)?;
        state.management.insert(projection_id.clone(), paused);
        Ok(())
    }
}

fn validate_generation(
    projection_id: &ProjectionId,
    attempted: ProjectionGeneration,
    entry: Option<&MemoryOffsetEntry>,
) -> ProjectionResult<()> {
    let current = entry.map_or(ProjectionGeneration::default(), |entry| entry.generation);
    if attempted != current || attempted == ProjectionGeneration::default() {
        return Err(ProjectionError::Fenced {
            projection_id: projection_id.clone(),
            attempted_generation: attempted.as_u64(),
            current_generation: current.as_u64(),
        });
    }
    Ok(())
}

fn lock(state: &Mutex<MemoryOffsetState>) -> ProjectionResult<MutexGuard<'_, MemoryOffsetState>> {
    state
        .lock()
        .map_err(|_| ProjectionError::OffsetStore("in-memory offset-store lock poisoned".into()))
}