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

ddd_toolkit_core/
async_transactional_outbox.rs
