datum-persistence 0.11.3

Event sourcing, durable state, and CQRS persistence for Datum
Documentation
//! Byte-oriented event journal storage contract.

use std::pin::Pin;

use futures_core::Stream;

use crate::{
    AppendOutcome, PersistenceError, PersistenceId, PersistenceResult, SequenceNr,
    SerializedPayload, Tag,
};

/// One serialized event as stored by a journal backend.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StoredEvent {
    /// Stable identity of the persistent entity that owns the event.
    pub persistence_id: PersistenceId,
    /// Monotonic sequence number within the persistence id.
    pub sequence_nr: SequenceNr,
    /// Durable event-adapter manifest, separate from serializer manifests.
    pub adapter_manifest: String,
    /// Stable identifier of the writer instance that produced the event.
    pub writer_uuid: String,
    /// Event timestamp as milliseconds since the Unix epoch, 1970-01-01 UTC.
    pub timestamp_ms: i64,
    /// Optional serialized event metadata frame.
    pub metadata: Option<SerializedPayload>,
    /// Serialized event payload frame.
    pub payload: SerializedPayload,
    /// Query tags attached to the adapted stored event.
    pub tags: Vec<Tag>,
}

/// A non-empty, gapless sequence of events committed all-or-nothing.
///
/// Construction validates that every event has the same persistence id and
/// that sequence numbers are strictly ascending without gaps. An append batch
/// may contain multiple atomic writes; the batch as a whole is not atomic.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AtomicWrite {
    events: Vec<StoredEvent>,
}

impl AtomicWrite {
    /// Validates and creates one atomic journal write.
    pub fn new(events: Vec<StoredEvent>) -> PersistenceResult<Self> {
        let Some(first) = events.first() else {
            return Err(PersistenceError::InvalidAtomicWrite(
                "at least one event is required".to_owned(),
            ));
        };

        if let Some(event) = events
            .iter()
            .find(|event| event.persistence_id != first.persistence_id)
        {
            return Err(PersistenceError::InvalidAtomicWrite(format!(
                "event for persistence id {} does not match {}",
                event.persistence_id, first.persistence_id
            )));
        }

        for pair in events.windows(2) {
            let current = pair[0].sequence_nr.as_u64();
            let expected = current.checked_add(1).ok_or_else(|| {
                PersistenceError::InvalidAtomicWrite(format!(
                    "sequence number {current} cannot have a successor"
                ))
            })?;
            let actual = pair[1].sequence_nr.as_u64();
            if actual != expected {
                return Err(PersistenceError::InvalidAtomicWrite(format!(
                    "expected sequence number {expected} after {current}, got {actual}"
                )));
            }
        }

        Ok(Self { events })
    }

    /// Returns the persistence id shared by every event in the write.
    #[must_use]
    pub fn persistence_id(&self) -> &PersistenceId {
        &self.events[0].persistence_id
    }

    /// Returns the validated events in storage order.
    #[must_use]
    pub fn events(&self) -> &[StoredEvent] {
        &self.events
    }

    /// Consumes the write and returns its validated events.
    #[must_use]
    pub fn into_events(self) -> Vec<StoredEvent> {
        self.events
    }
}

/// Inclusive replay selection for one persistence id.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ReplayRange {
    /// Persistence id whose events should be replayed.
    pub persistence_id: PersistenceId,
    /// First sequence number to emit, inclusive.
    pub from: SequenceNr,
    /// Last sequence number to emit, inclusive.
    pub to: SequenceNr,
    /// Maximum number of events to emit.
    pub max: u64,
}

/// Owned asynchronous stream returned by journal replay.
///
/// Individual storage/read failures are emitted as stream items. The stream is
/// `Send` and owns its replay state, so it does not borrow the journal.
pub type EventStream = Pin<Box<dyn Stream<Item = PersistenceResult<StoredEvent>> + Send + 'static>>;

/// Byte-oriented event journal storage provider.
#[async_trait::async_trait]
pub trait Journal: Send + Sync {
    /// Appends one independently atomic write per input item.
    ///
    /// The result must contain exactly one outcome per input write, in input
    /// order. [`AppendOutcome::Rejected`] is deterministic and guarantees that
    /// none of that atomic write was stored. `Err` means storage failure or
    /// uncertainty about whether a commit happened.
    async fn append(&self, writes: Vec<AtomicWrite>) -> PersistenceResult<Vec<AppendOutcome>>;

    /// Appends one atomic write without requiring callers to allocate an input batch.
    ///
    /// Backends with a single-write fast path should override this method. The
    /// default preserves the exact outcome-count contract of [`Self::append`].
    async fn append_one(&self, write: AtomicWrite) -> PersistenceResult<AppendOutcome> {
        let outcomes = self.append(vec![write]).await?;
        let mut outcomes = outcomes.into_iter();
        let outcome = outcomes.next().ok_or_else(|| {
            PersistenceError::Failure("journal returned no outcome for one atomic write".into())
        })?;
        if outcomes.next().is_some() {
            return Err(PersistenceError::Failure(
                "journal returned more than one outcome for one atomic write".into(),
            ));
        }
        Ok(outcome)
    }

    /// Returns the monotonic high watermark for one persistence id.
    ///
    /// The value survives all logical deletes, including delete-to-MAX. The
    /// backend may use `from_hint` for read optimization but must return the
    /// actual watermark; an unknown id returns sequence number zero.
    async fn highest_sequence_nr(
        &self,
        persistence_id: &PersistenceId,
        from_hint: SequenceNr,
    ) -> PersistenceResult<SequenceNr>;

    /// Replays stored, non-deleted events matching an inclusive range.
    ///
    /// Reversed bounds and `max == 0` produce an empty stream.
    async fn replay(&self, range: ReplayRange) -> PersistenceResult<EventStream>;

    /// Logically deletes events currently stored through `inclusive` while
    /// preserving the high watermark.
    ///
    /// Deletion is point-in-time: an event appended after this call completes
    /// remains visible even when its sequence number is at or below `inclusive`
    /// (notably after delete-to-MAX with a preserved watermark). Marker-based
    /// backends must therefore scope their marker to the events present at the
    /// deletion linearization point. [`crate::assert_journal_conformance`] is
    /// the normative executable contract for this behavior.
    async fn delete_to(
        &self,
        persistence_id: &PersistenceId,
        inclusive: SequenceNr,
    ) -> PersistenceResult<()>;
}