datum-persistence 0.11.3

Event sourcing, durable state, and CQRS persistence for Datum
Documentation
use thiserror::Error;

use crate::{PersistenceId, Revision, SerializerId};

/// Result type used by `datum-persistence`.
pub type PersistenceResult<T> = Result<T, PersistenceError>;

/// Errors produced by persistence operations.
#[derive(Debug, Clone, Error)]
#[non_exhaustive]
pub enum PersistenceError {
    /// A persistence id violates the identity format contract.
    #[error("invalid persistence id: {0}")]
    InvalidPersistenceId(String),

    /// An atomic journal write violates its construction invariants.
    #[error("invalid atomic journal write: {0}")]
    InvalidAtomicWrite(String),

    /// A deterministic request was rejected before storage.
    #[error("persistence operation rejected: {0}")]
    Rejected(String),

    /// A persistence operation failed or its outcome is uncertain.
    #[error("persistence operation failed: {0}")]
    Failure(String),

    /// A value could not be serialized or deserialized.
    #[error("persistence serialization failed: {0}")]
    Serialization(String),

    /// No serializer is registered for a durable serializer id.
    #[error("unknown persistence serializer id {0}")]
    UnknownSerializer(SerializerId),

    /// More than one serializer was registered with the same durable id.
    #[error("duplicate persistence serializer id {0}")]
    DuplicateSerializer(SerializerId),

    /// A storage connection could not be established or was lost.
    #[error("persistence connection failed: {0}")]
    Connection(String),

    /// A durable-state compare-and-set revision did not match.
    #[error(
        "durable-state revision conflict for {persistence_id}: expected {expected}, got {actual}"
    )]
    RevisionConflict {
        /// Durable-state identity whose revision did not match.
        persistence_id: PersistenceId,
        /// Next revision required by the stored value or tombstone.
        expected: Revision,
        /// Revision supplied by the caller.
        actual: Revision,
    },

    /// A durable-state revision cannot advance beyond its numeric range.
    #[error("durable-state revision exhausted for {persistence_id}")]
    RevisionExhausted {
        /// Durable-state identity whose revision reached the maximum value.
        persistence_id: PersistenceId,
    },
}

/// Result of one input [`crate::AtomicWrite`] in a journal append batch.
///
/// Rejection is a deterministic value. An [`Err`](Result::Err) from
/// [`crate::Journal::append`] instead means storage failed or the commit result
/// is uncertain.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AppendOutcome {
    /// The complete atomic write was stored.
    Accepted,
    /// The complete atomic write was refused before storage.
    Rejected {
        /// Backend-provided deterministic rejection explanation.
        reason: String,
    },
}