ddd_toolkit_core/
snapshot.rs

1use crate::event_store::StreamRevision;
2use crate::{AggregateRoot, Entity};
3
4/// **English:** Owned aggregate state paired with the last event revision it represents.
5/// No identifier or schema version is added; include validation metadata in `S` when needed.
6///
7/// **日本語:** 集約状態と、その状態が反映する最後のイベントのリビジョンを所有します。
8/// 識別子やスキーマバージョンは追加しません。検証用メタデータは必要に応じて `S` に含めます。
9///
10/// ```rust
11/// use ddd_toolkit_core::{AggregateSnapshot, StreamRevision};
12/// let snapshot = AggregateSnapshot::new(42_u64, StreamRevision::new(3));
13/// assert_eq!(*snapshot.state(), 42);
14/// assert_eq!(snapshot.into_parts(), (42, StreamRevision::new(3)));
15/// ```
16#[derive(Debug, Eq, PartialEq)]
17pub struct AggregateSnapshot<S> {
18    state: S,
19    revision: StreamRevision,
20}
21
22impl<S> AggregateSnapshot<S> {
23    /// **English:** Pairs `state` with `revision` without checking consistency or compatibility.
24    ///
25    /// **日本語:** 整合性や互換性を検証せず、`state` と `revision` を組み合わせます。
26    pub fn new(state: S, revision: StreamRevision) -> Self {
27        Self { state, revision }
28    }
29
30    /// **English:** Borrows the stored aggregate state.
31    ///
32    /// **日本語:** 保存された集約状態を借用します。
33    pub fn state(&self) -> &S {
34        &self.state
35    }
36
37    /// **English:** Returns the last event revision represented by the state.
38    ///
39    /// **日本語:** 状態が反映する最後のイベントのリビジョンを返します。
40    pub fn revision(&self) -> StreamRevision {
41        self.revision
42    }
43
44    /// **English:** Consumes the snapshot, returning state and revision without cloning.
45    ///
46    /// **日本語:** スナップショットを消費し、複製せずに状態とリビジョンを返します。
47    pub fn into_parts(self) -> (S, StreamRevision) {
48        (self.state, self.revision)
49    }
50}
51
52/// **English:** Aggregate-defined snapshot classification used by [`crate::replay_with_optional_snapshot`].
53/// Both `Stale` and `Inapplicable` trigger full replay; an older but usable snapshot may be `Applicable`.
54///
55/// **日本語:** [`crate::replay_with_optional_snapshot`] で使う集約定義のスナップショット分類です。
56/// `Stale` と `Inapplicable` は全件再生を選択します。古くても利用可能なら `Applicable` にできます。
57#[derive(Clone, Copy, Debug, Eq, PartialEq)]
58pub enum SnapshotUse {
59    /// **English:** Restore this snapshot and replay only later events.
60    ///
61    /// **日本語:** このスナップショットを復元し、後続イベントのみ再生します。
62    Applicable,
63    /// **English:** Reject this snapshot as stale and replay the complete history.
64    ///
65    /// **日本語:** 古いスナップショットとして採用せず、完全な履歴を再生します。
66    Stale,
67    /// **English:** Reject this snapshot as incompatible and replay the complete history.
68    ///
69    /// **日本語:** 互換性のないスナップショットとして採用せず、完全な履歴を再生します。
70    Inapplicable,
71}
72
73/// **English:** Snapshot lookup failure, distinct from a missing snapshot.
74///
75/// **日本語:** スナップショットの検索失敗です。スナップショットの不在とは区別されます。
76#[derive(Debug, Eq, PartialEq)]
77pub enum SnapshotLoadError<E> {
78    /// **English:** Error reported by the storage adapter.
79    ///
80    /// **日本語:** ストレージアダプターが報告したエラーです。
81    Adapter(E),
82}
83
84/// **English:** Failure to persist a snapshot.
85///
86/// **日本語:** スナップショットの永続化失敗です。
87#[derive(Debug, Eq, PartialEq)]
88pub enum SnapshotSaveError<E> {
89    /// **English:** Storage adapter error during saving.
90    ///
91    /// **日本語:** 保存時のストレージアダプターエラーです。
92    Adapter(E),
93}
94
95/// **English:** Synchronous storage boundary for snapshots indexed by aggregate identifier.
96/// Implementations define replacement policy, durability, synchronization, and panic conditions.
97/// Saving a snapshot does not itself append events or validate the snapshot against an event stream.
98///
99/// **日本語:** 集約識別子をキーとするスナップショットの同期ストレージ境界です。
100/// 置換方針、永続性、同期、パニック条件は実装が定めます。
101/// 保存自体はイベント追加やイベントストリームに対するスナップショットの検証を行いません。
102pub trait SnapshotStore {
103    /// **English:** Aggregate defining the snapshot lookup identifier.
104    ///
105    /// **日本語:** スナップショット検索の識別子を定める集約です。
106    type Aggregate: AggregateRoot;
107    /// **English:** State representation stored in each snapshot.
108    ///
109    /// **日本語:** 各スナップショットに保存する状態の表現です。
110    type State;
111    /// **English:** Adapter-specific persistence error.
112    ///
113    /// **日本語:** アダプター固有の永続化エラーです。
114    type Error;
115
116    /// **English:** Loads a snapshot for `id`; `Ok(None)` means none is available.
117    /// Storage failures use [`SnapshotLoadError::Adapter`] rather than the absence result.
118    ///
119    /// **日本語:** `id` のスナップショットを読み込みます。`Ok(None)` は不在を表します。
120    /// ストレージ障害は不在ではなく [`SnapshotLoadError::Adapter`] で返します。
121    fn load(
122        &self,
123        id: &<Self::Aggregate as Entity>::Id,
124    ) -> Result<Option<AggregateSnapshot<Self::State>>, SnapshotLoadError<Self::Error>>;
125
126    /// **English:** Consumes and saves `snapshot` for `id`, returning an adapter error on failure.
127    /// The snapshot is not returned on error; replacement and retry behavior depend on the adapter.
128    ///
129    /// **日本語:** `id` に対して `snapshot` を消費して保存し、失敗時はアダプターエラーを返します。
130    /// エラー時にスナップショットは返されません。置換や再試行の挙動はアダプターに依存します。
131    fn save(
132        &mut self,
133        id: &<Self::Aggregate as Entity>::Id,
134        snapshot: AggregateSnapshot<Self::State>,
135    ) -> Result<(), SnapshotSaveError<Self::Error>>;
136}
ddd_toolkit_core/snapshot.rs

ddd_toolkit_core/
snapshot.rs
