datum-persistence 0.11.3

Event sourcing, durable state, and CQRS persistence for Datum
Documentation
//! Durable-state behavior blueprints, effects, recovery, and runtime handles.
//!
//! Unlike event-sourced behaviors, durable-state behaviors do not publish
//! confirmed writes to a `Topic`. This follows Akka's durable-state surface:
//! query backends expose changes, while the command runtime itself has no
//! event-publication channel.

mod effect;
mod runtime;

use std::{marker::PhantomData, sync::Arc};

use datum::{
    RestartSettings,
    actor::{ActorRef, Message},
};

use crate::{
    DurableStateStore, EventAdapter, Journal, PersistenceId, PersistenceResult, SerializerCatalog,
    StateAdapter, Tag,
};

pub use effect::{Effect, ReplyEffect};
pub use runtime::DurableStateMessage;

use runtime::{ChangeEventCodec, StateCodec};

type CommandHandler<C, S> = dyn Fn(&S, C) -> Effect<C, S> + Send + Sync + 'static;
type SignalHandler<S> = dyn Fn(&S, &DurableStateSignal) + Send + Sync + 'static;
type ChangeUpdateHandler<C, S, E> = dyn Fn(&S, &S, &C) -> E + Send + Sync + 'static;
type ChangeDeleteHandler<C, S, E> = dyn Fn(&S, &C) -> E + Send + Sync + 'static;

/// Recovery signals emitted by a durable-state behavior.
///
/// Durable state intentionally has no `PersistFailed` or `PersistRejected`
/// signals. Revision conflicts and write failures enter the behavior failure
/// path and are supervised by [`DurableStateBehavior::on_persist_failure`].
#[derive(Debug)]
#[non_exhaustive]
pub enum DurableStateSignal {
    /// The single durable-state read completed, including for a fresh id.
    RecoveryCompleted,
    /// The durable-state read or state adaptation failed.
    RecoveryFailed(crate::PersistenceError),
}

/// Derives a journal event from each durable-state update or delete.
///
/// The update callback receives previous state, new state, and the command.
/// The delete callback receives previous state and the command, matching
/// Akka's `ChangeEventHandler` inputs.
pub struct ChangeEventHandler<C, S, E> {
    update: Arc<ChangeUpdateHandler<C, S, E>>,
    delete: Arc<ChangeDeleteHandler<C, S, E>>,
}

impl<C, S, E> ChangeEventHandler<C, S, E> {
    /// Creates update and delete change-event callbacks.
    pub fn new<U, D>(update: U, delete: D) -> Self
    where
        U: Fn(&S, &S, &C) -> E + Send + Sync + 'static,
        D: Fn(&S, &C) -> E + Send + Sync + 'static,
    {
        Self {
            update: Arc::new(update),
            delete: Arc::new(delete),
        }
    }
}

/// Immutable, side-effect-free durable-state behavior blueprint.
pub struct DurableStateBehavior<C, S, J = S> {
    pub(crate) persistence_id: PersistenceId,
    pub(crate) empty_state: S,
    pub(crate) command_handler: Arc<CommandHandler<C, S>>,
    pub(crate) state_codec: Option<Arc<dyn StateCodec<S>>>,
    pub(crate) tag: Option<Tag>,
    pub(crate) persist_failure_backoff: Option<RestartSettings>,
    pub(crate) stash_capacity: usize,
    pub(crate) signal_handler: Arc<SignalHandler<S>>,
    pub(crate) change_event_codec: Option<Arc<dyn ChangeEventCodec<C, S>>>,
    pub(crate) change_event_journal: Option<Arc<dyn Journal>>,
    pub(crate) _journal_state: PhantomData<fn() -> J>,
}

impl<C, S> DurableStateBehavior<C, S, S> {
    /// Creates a side-effect-free behavior blueprint.
    ///
    /// No store, journal, actor, or task is touched until [`Self::spawn`]. A
    /// state adapter and serializer catalog must be selected before spawning.
    pub fn new<H>(persistence_id: PersistenceId, empty_state: S, command_handler: H) -> Self
    where
        H: Fn(&S, C) -> Effect<C, S> + Send + Sync + 'static,
    {
        Self::from_handler(persistence_id, empty_state, Arc::new(command_handler))
    }

    /// Creates a blueprint whose handler must return a [`ReplyEffect`].
    pub fn with_enforced_replies<H>(
        persistence_id: PersistenceId,
        empty_state: S,
        command_handler: H,
    ) -> Self
    where
        H: Fn(&S, C) -> ReplyEffect<C, S> + Send + Sync + 'static,
    {
        Self::from_handler(
            persistence_id,
            empty_state,
            Arc::new(move |state, command| command_handler(state, command).into_effect()),
        )
    }

    fn from_handler(
        persistence_id: PersistenceId,
        empty_state: S,
        command_handler: Arc<CommandHandler<C, S>>,
    ) -> Self {
        Self {
            persistence_id,
            empty_state,
            command_handler,
            state_codec: None,
            tag: None,
            persist_failure_backoff: None,
            stash_capacity: 1_024,
            signal_handler: Arc::new(|_, _| {}),
            change_event_codec: None,
            change_event_journal: None,
            _journal_state: PhantomData,
        }
    }
}

impl<C, S, J> DurableStateBehavior<C, S, J> {
    /// Selects the state adapter and serializer catalog, possibly changing `J`.
    #[must_use]
    pub fn with_state_adapter<J2, A>(
        self,
        adapter: A,
        catalog: SerializerCatalog<J2>,
    ) -> DurableStateBehavior<C, S, J2>
    where
        A: StateAdapter<S, J2>,
        S: 'static,
        J2: 'static,
    {
        DurableStateBehavior {
            persistence_id: self.persistence_id,
            empty_state: self.empty_state,
            command_handler: self.command_handler,
            state_codec: Some(Arc::new(runtime::AdaptedStateCodec::new(adapter, catalog))),
            tag: self.tag,
            persist_failure_backoff: self.persist_failure_backoff,
            stash_capacity: self.stash_capacity,
            signal_handler: self.signal_handler,
            change_event_codec: self.change_event_codec,
            change_event_journal: self.change_event_journal,
            _journal_state: PhantomData,
        }
    }

    /// Assigns the query tag written with each upsert.
    #[must_use]
    pub fn with_tag(mut self, tag: Tag) -> Self {
        self.tag = Some(tag);
        self
    }

    /// Restarts with a single-read recovery after durable write failures.
    ///
    /// The delayed backoff uses an actor self-message; the actor does not sleep
    /// inline and remains responsive to [`DurableStateHandle::state`] and stop.
    #[must_use]
    pub fn on_persist_failure(mut self, settings: RestartSettings) -> Self {
        self.persist_failure_backoff = Some(settings);
        self
    }

    /// Sets the bounded manual stash capacity.
    #[must_use]
    pub fn with_stash_capacity(mut self, capacity: usize) -> Self {
        self.stash_capacity = capacity;
        self
    }

    /// Installs a durable-state recovery signal callback.
    #[must_use]
    pub fn on_signal<F>(mut self, handler: F) -> Self
    where
        F: Fn(&S, &DurableStateSignal) + Send + Sync + 'static,
    {
        self.signal_handler = Arc::new(handler);
        self
    }

    /// Derives and serializes an additional journal event for every write.
    ///
    /// The command is cloned before the consuming command handler runs, so this
    /// option alone requires `C: Clone`. Spawn fails if no change-event journal
    /// was supplied with [`Self::with_change_event_journal`].
    #[must_use]
    pub fn with_change_event_handler<E, EJ, A>(
        mut self,
        handler: ChangeEventHandler<C, S, E>,
        adapter: A,
        catalog: SerializerCatalog<EJ>,
    ) -> Self
    where
        C: Clone + Send + 'static,
        S: 'static,
        E: 'static,
        EJ: 'static,
        A: EventAdapter<E, EJ>,
    {
        self.change_event_codec = Some(Arc::new(runtime::AdaptedChangeEventCodec::new(
            handler, adapter, catalog,
        )));
        self
    }

    /// Supplies the journal used by a configured change-event handler.
    ///
    /// The durable-state CAS and journal append are two separate writes. Datum
    /// deliberately makes no cross-store atomicity guarantee: the durable CAS
    /// runs first, then the journal append. Side effects run only if both
    /// succeed; a second-write failure enters persist-failure supervision.
    ///
    /// Change-event journal sequence numbers are allocated from that journal's
    /// actual high watermark, not from the durable-state revision. This keeps a
    /// failed second write from creating a permanent journal gap. The associated
    /// durable-state revision is stored in the event metadata as an eight-byte
    /// big-endian `u64`, with serializer id `u32::MAX` and manifest
    /// `datum-durable-state-change-revision-v1`. Consequently revisions and
    /// change-event sequence numbers normally match, but may diverge after the
    /// explicitly non-atomic CAS/append boundary fails.
    #[must_use]
    pub fn with_change_event_journal(mut self, journal: Arc<dyn Journal>) -> Self {
        self.change_event_journal = Some(journal);
        self
    }
}

impl<C, S, J> DurableStateBehavior<C, S, J>
where
    C: Message,
    S: Clone + Send + Sync + 'static,
    J: 'static,
{
    /// Spawns the Ractor runtime, using `store` for recovery and CAS writes.
    pub async fn spawn(
        self,
        store: Arc<dyn DurableStateStore>,
    ) -> PersistenceResult<DurableStateHandle<C, S>> {
        runtime::spawn(self, store).await
    }

    /// Alias for [`Self::spawn`] emphasizing materialization on Tokio.
    pub async fn run_on(
        self,
        store: Arc<dyn DurableStateStore>,
    ) -> PersistenceResult<DurableStateHandle<C, S>> {
        self.spawn(store).await
    }
}

/// A point-in-time confirmed durable state and revision.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DurableState<S> {
    /// Current confirmed state, or the empty state after a recovered tombstone.
    pub state: S,
    /// Current confirmed or recovered store revision.
    pub revision: crate::Revision,
}

/// Spawned durable-state behavior handle.
pub struct DurableStateHandle<C: Message, S: Send + 'static> {
    pub(crate) control: ActorRef<runtime::DurableStateMessage<C, S>>,
}

impl<C, S> DurableStateHandle<C, S>
where
    C: Message,
    S: Clone + Send + 'static,
{
    /// Returns the behavior's single ordered ingress actor ref.
    ///
    /// `ActorFlow::ask` request builders should wrap commands with
    /// [`DurableStateMessage::command`]. Commands and state queries share this
    /// mailbox, so same-sender enqueue order is FIFO.
    #[must_use]
    pub fn actor_ref(&self) -> &ActorRef<DurableStateMessage<C, S>> {
        &self.control
    }

    /// Sends one command without waiting for persistence.
    pub fn tell(&self, command: C) -> PersistenceResult<()> {
        self.control
            .cast(runtime::DurableStateMessage::command(command))
            .map_err(|error| {
                crate::PersistenceError::Failure(format!(
                    "durable behavior command send failed: {error}"
                ))
            })
    }

    /// Observes confirmed state through the behavior's ordered mailbox.
    ///
    /// All messages enqueued earlier by the same sender have reached their
    /// mailbox handling point first. A write already being handled completes
    /// before this query; during delayed persist-failure backoff the query is
    /// answered immediately ahead of automatically stashed domain commands.
    pub async fn state(&self) -> PersistenceResult<DurableState<S>> {
        let (sender, receiver) = tokio::sync::oneshot::channel();
        self.control
            .cast(runtime::DurableStateMessage::get_state(sender))
            .map_err(|error| {
                crate::PersistenceError::Failure(format!(
                    "durable behavior state query failed: {error}"
                ))
            })?;
        receiver.await.map_err(|_| {
            crate::PersistenceError::Failure(
                "durable behavior stopped before answering state query".into(),
            )
        })
    }

    /// Requests immediate behavior shutdown.
    pub fn stop(&self) {
        self.control.stop(None);
    }
}

impl<C, S> Clone for DurableStateHandle<C, S>
where
    C: Message,
    S: Send + 'static,
{
    fn clone(&self) -> Self {
        Self {
            control: self.control.clone(),
        }
    }
}