datum-persistence 0.11.3

Event sourcing, durable state, and CQRS persistence for Datum
Documentation
use datum::ReplyPort;

use crate::Revision;

type SideEffect<S> = dyn FnOnce(&S, Revision) + Send + 'static;

pub(crate) enum MainEffect<C, S> {
    Persist(S),
    Delete,
    None,
    Unhandled,
    Stash(C),
}

pub(crate) enum ChainedEffect<S> {
    Run(Box<SideEffect<S>>),
    Stop,
    UnstashAll,
}

/// A command decision for a [`DurableStateBehavior`](super::DurableStateBehavior).
///
/// Durable-state effects are deliberately synchronous. Akka durable state has
/// no `Effect.async`, so Datum does not add an `async_effect` extension here.
/// Storage I/O remains asynchronous inside the materialized runtime.
#[must_use]
pub struct Effect<C, S> {
    pub(crate) main: MainEffect<C, S>,
    pub(crate) chained: Vec<ChainedEffect<S>>,
}

impl<C, S> Effect<C, S> {
    /// Replaces the durable state using the next CAS revision.
    pub fn persist(new_state: S) -> Self {
        Self {
            main: MainEffect::Persist(new_state),
            chained: Vec::new(),
        }
    }

    /// Deletes the durable state using the next CAS revision.
    ///
    /// A successful delete installs the behavior's empty state in memory while
    /// the store retains a revision-advancing tombstone.
    pub fn delete() -> Self {
        Self {
            main: MainEffect::Delete,
            chained: Vec::new(),
        }
    }

    /// Handles the command without changing durable state.
    pub fn none() -> Self {
        Self {
            main: MainEffect::None,
            chained: Vec::new(),
        }
    }

    /// Marks the command unhandled without changing durable state.
    pub fn unhandled() -> Self {
        Self {
            main: MainEffect::Unhandled,
            chained: Vec::new(),
        }
    }

    /// Stops the behavior after processing this command.
    pub fn stop() -> Self {
        Self::none().then_stop()
    }

    /// Places an owned command in the bounded in-memory manual stash.
    ///
    /// Commands are passed explicitly because Datum command handlers consume
    /// commands, allowing them to own non-cloneable one-shot reply ports.
    pub fn stash(command: C) -> Self {
        Self {
            main: MainEffect::Stash(command),
            chained: Vec::new(),
        }
    }

    /// Starts draining the commands that are manually stashed at this point.
    pub fn unstash_all() -> Self {
        Self::none().then_unstash_all()
    }

    /// Replies after a successful no-persist effect.
    pub fn reply<R>(reply_to: ReplyPort<R>, reply: R) -> ReplyEffect<C, S>
    where
        R: Send + 'static,
    {
        Self::none().then_reply(reply_to, move |_| reply)
    }

    /// Explicitly chooses not to reply in an enforced-replies handler.
    pub fn no_reply() -> ReplyEffect<C, S> {
        Self::none().then_no_reply()
    }

    /// Runs a callback with the confirmed resulting state.
    pub fn then_run<F>(mut self, callback: F) -> Self
    where
        F: FnOnce(&S) + Send + 'static,
    {
        self.chained
            .push(ChainedEffect::Run(Box::new(move |state, _revision| {
                callback(state)
            })));
        self
    }

    /// Runs a callback with the confirmed resulting state and revision.
    pub fn then_run_with_revision<F>(mut self, callback: F) -> Self
    where
        F: FnOnce(&S, Revision) + Send + 'static,
    {
        self.chained.push(ChainedEffect::Run(Box::new(callback)));
        self
    }

    /// Stops the behavior after all earlier side effects have run.
    pub fn then_stop(mut self) -> Self {
        self.chained.push(ChainedEffect::Stop);
        self
    }

    /// Starts a bounded drain of the current manual stash.
    pub fn then_unstash_all(mut self) -> Self {
        self.chained.push(ChainedEffect::UnstashAll);
        self
    }

    /// Sends a reply computed from the confirmed resulting state.
    pub fn then_reply<R, F>(mut self, reply_to: ReplyPort<R>, reply: F) -> ReplyEffect<C, S>
    where
        R: Send + 'static,
        F: FnOnce(&S) -> R + Send + 'static,
    {
        self.chained
            .push(ChainedEffect::Run(Box::new(move |state, _revision| {
                let _ = reply_to.send(reply(state));
            })));
        ReplyEffect(self)
    }

    /// Sends a reply computed from the confirmed state and revision.
    pub fn then_reply_with_revision<R, F>(
        mut self,
        reply_to: ReplyPort<R>,
        reply: F,
    ) -> ReplyEffect<C, S>
    where
        R: Send + 'static,
        F: FnOnce(&S, Revision) -> R + Send + 'static,
    {
        self.chained
            .push(ChainedEffect::Run(Box::new(move |state, revision| {
                let _ = reply_to.send(reply(state, revision));
            })));
        ReplyEffect(self)
    }

    /// Explicitly records that this command will not reply.
    pub fn then_no_reply(self) -> ReplyEffect<C, S> {
        ReplyEffect(self)
    }
}

/// An effect that statically records a reply or explicit no-reply decision.
#[must_use]
pub struct ReplyEffect<C, S>(Effect<C, S>);

impl<C, S> ReplyEffect<C, S> {
    /// Runs a callback while preserving reply enforcement.
    pub fn then_run<F>(self, callback: F) -> Self
    where
        F: FnOnce(&S) + Send + 'static,
    {
        Self(self.0.then_run(callback))
    }

    /// Runs a callback with state and revision while preserving reply enforcement.
    pub fn then_run_with_revision<F>(self, callback: F) -> Self
    where
        F: FnOnce(&S, Revision) + Send + 'static,
    {
        Self(self.0.then_run_with_revision(callback))
    }

    /// Stops the behavior after all earlier side effects have run.
    pub fn then_stop(self) -> Self {
        Self(self.0.then_stop())
    }

    /// Starts a bounded drain of the current manual stash.
    pub fn then_unstash_all(self) -> Self {
        Self(self.0.then_unstash_all())
    }

    pub(crate) fn into_effect(self) -> Effect<C, S> {
        self.0
    }
}