ddd_toolkit_core/
async_transactional_outbox.rs

1#![allow(clippy::type_complexity)]
2
3use crate::{
4    AggregateRoot, AppendError, AppendResult, ExpectedRevision, OutboxClaim, OutboxMessageId,
5};
6use std::future::Future;
7use std::pin::Pin;
8
9/// **English:**<br>
10/// Asynchronous boundary for saving aggregates and staging events for delivery.
11///
12/// Operations return boxed `Send` futures without choosing an executor. The adapter supplies
13/// transactions, durability, concurrent claim coordination, ordering, leases, and panic behavior.
14/// Neither errors nor cancellation imply rollback; implementations must document retry safety.
15/// Claims and acknowledgements are separate operations, not an exactly-once delivery mechanism.
16/// Implementations may perform work before returning a future as well as while polling it.
17///
18/// **日本語:**<br>
19/// 集約の保存と配信イベントの登録を行う非同期境界です。
20///
21/// 操作は実行器を選ばず、ボックス化された `Send` Future を返します。トランザクション、
22/// 永続性、並行取得の調整、順序、リース、パニック時の挙動はアダプターが提供します。
23/// エラーやキャンセルはロールバックを意味せず、実装は再試行の安全性を文書化する必要があります。
24/// 取得と確認応答は別操作であり、厳密に一度だけ配信する機構ではありません。
25/// 実装はポーリング中だけでなく、Future を返す前にも処理を行う場合があります。
26pub trait AsyncTransactionalOutbox {
27    /// **English:**<br>
28    /// Aggregate borrowed during saving; `Sync` permits sharing its reference across threads.
29    ///
30    /// **日本語:**<br>
31    /// 保存時に借用する集約です。`Sync` により参照をスレッド間で共有できます。
32    type Aggregate: AggregateRoot + Sync;
33    /// **English:**<br>
34    /// Adapter failure transferable in the future's result.
35    ///
36    /// **日本語:**<br>
37    /// Future の結果としてスレッド間で受け渡せるアダプター障害です。
38    type Error: Send;
39
40    /// **English:**<br>
41    /// Borrows `aggregate` and takes ownership of `events` for saving and enqueueing
42    /// under `expected`. The future returns the final revision or [`AppendError`] for an empty
43    /// batch, conflict, revision exhaustion, or adapter failure. The batch is not returned on
44    /// failure. This signature does not pull pending events from the aggregate; transaction scope
45    /// and partial-write behavior are defined by the adapter.
46    ///
47    /// **日本語:**<br>
48    /// `aggregate` を借用し、`events` の所有権を受け取り、`expected` を条件に保存・登録します。
49    /// Future は最終リビジョン、または空バッチ、競合、リビジョン枯渇、アダプター障害を示す
50    /// [`AppendError`] を返します。失敗時にバッチは返されません。このシグネチャは集約から
51    /// 保留イベントを取り出しません。トランザクション範囲と部分書き込みの挙動はアダプターが定めます。
52    fn save_and_enqueue<'a>(
53        &'a mut self,
54        aggregate: &'a Self::Aggregate,
55        expected: ExpectedRevision,
56        events: Vec<<Self::Aggregate as AggregateRoot>::Event>,
57    ) -> Pin<Box<dyn Future<Output = Result<AppendResult, AppendError<Self::Error>>> + Send + 'a>>;
58
59    /// **English:**<br>
60    /// Returns a future claiming an available message as an owned [`OutboxClaim`].
61    /// `Ok(None)` means none is available to this call; `Self::Error` reports adapter failure.
62    /// Reservation duration and redelivery after cancellation follow the adapter's policy.
63    ///
64    /// **日本語:**<br>
65    /// 利用可能なメッセージを所有された [`OutboxClaim`] として取得する Future を返します。
66    /// `Ok(None)` はこの呼び出しで取得可能なものがないこと、`Self::Error` は障害を表します。
67    /// 予約期間とキャンセル後の再配信はアダプターの方針に従います。
68    fn claim<'a>(
69        &'a mut self,
70    ) -> Pin<
71        Box<
72            dyn Future<
73                    Output = Result<
74                        Option<OutboxClaim<<Self::Aggregate as AggregateRoot>::Event>>,
75                        Self::Error,
76                    >,
77                > + Send
78                + 'a,
79        >,
80    >;
81
82    /// **English:**<br>
83    /// Borrows `message_id` and returns a future reporting completed handling.
84    /// The result is `Ok(())` or an adapter error. Unknown IDs, repeated acknowledgements,
85    /// retention, and cancellation effects are adapter-defined; no claim token is required here.
86    ///
87    /// **日本語:**<br>
88    /// `message_id` を借用し、処理完了を通知する Future を返します。
89    /// 結果は `Ok(())` またはアダプターエラーです。未知の識別子、確認応答の繰り返し、
90    /// 保持、キャンセルの効果はアダプターが定めます。ここでは取得トークンを要求しません。
91    fn acknowledge<'a>(
92        &'a mut self,
93        message_id: &'a OutboxMessageId,
94    ) -> Pin<Box<dyn Future<Output = Result<(), Self::Error>> + Send + 'a>>;
95}
ddd_toolkit_core/async_transactional_outbox.rs

ddd_toolkit_core/
async_transactional_outbox.rs
