1use std::{collections::BTreeSet, fmt};
21
22use schemars::JsonSchema;
23use serde::{Deserialize, Deserializer, Serialize, de};
24use thiserror::Error;
25
26use crate::{
27 AttemptId, DeliveryId, DestinationId, Digest, EventId, Failure, FencingEpoch, JournalHead,
28 JournalPayload, RetryAdvice, RunId, TenantId, Timestamp,
29};
30
31const INTENT_DIGEST_DOMAIN: &[u8] = b"stateknot-outbox-intent-v1\0";
32const DELIVERY_DIGEST_DOMAIN: &[u8] = b"stateknot-outbox-delivery-v1\0";
33const ATTEMPT_START_DIGEST_DOMAIN: &[u8] = b"stateknot-outbox-attempt-start-v1\0";
34const ATTEMPT_COMPLETION_DIGEST_DOMAIN: &[u8] = b"stateknot-outbox-attempt-completion-v1\0";
35
36pub const MAX_OUTBOX_ATTEMPTS: usize = 64;
38
39pub const MAX_OUTBOX_ATTEMPT_LEASE_MILLIS: i64 = 300_000;
45
46#[derive(Clone, Debug, Deserialize, Eq, Hash, JsonSchema, PartialEq, Serialize)]
53#[serde(deny_unknown_fields)]
54pub struct OutboxDestinationRef {
55 tenant_id: TenantId,
56 destination_id: DestinationId,
57 snapshot_digest: Digest,
58}
59
60impl OutboxDestinationRef {
61 #[must_use]
63 pub const fn new(
64 tenant_id: TenantId,
65 destination_id: DestinationId,
66 snapshot_digest: Digest,
67 ) -> Self {
68 Self {
69 tenant_id,
70 destination_id,
71 snapshot_digest,
72 }
73 }
74
75 #[must_use]
77 pub const fn tenant_id(&self) -> &TenantId {
78 &self.tenant_id
79 }
80
81 #[must_use]
83 pub const fn destination_id(&self) -> DestinationId {
84 self.destination_id
85 }
86
87 #[must_use]
89 pub const fn snapshot_digest(&self) -> Digest {
90 self.snapshot_digest
91 }
92}
93
94#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
100#[serde(deny_unknown_fields)]
101pub struct OutboxDeliveryIntent {
102 tenant_id: TenantId,
103 run_id: RunId,
104 delivery_id: DeliveryId,
105 origin_event_id: EventId,
106 destination: OutboxDestinationRef,
107 payload: JournalPayload,
108 expires_at: Timestamp,
109 intent_digest: Digest,
110}
111
112impl OutboxDeliveryIntent {
113 #[allow(clippy::too_many_arguments)]
123 pub fn new(
124 tenant_id: TenantId,
125 run_id: RunId,
126 delivery_id: DeliveryId,
127 origin_event_id: EventId,
128 destination: OutboxDestinationRef,
129 payload: JournalPayload,
130 expires_at: Timestamp,
131 ) -> Result<Self, OutboxDeliveryError> {
132 if destination.tenant_id() != &tenant_id {
133 return Err(OutboxDeliveryError::DestinationTenantMismatch);
134 }
135 let intent_digest = compute_intent_digest(&OutboxIntentDigestWire {
136 tenant_id: &tenant_id,
137 run_id,
138 delivery_id,
139 origin_event_id,
140 destination: &destination,
141 payload_digest: payload.digest(),
142 expires_at,
143 })?;
144 Ok(Self {
145 tenant_id,
146 run_id,
147 delivery_id,
148 origin_event_id,
149 destination,
150 payload,
151 expires_at,
152 intent_digest,
153 })
154 }
155
156 #[allow(clippy::too_many_arguments)]
162 pub fn restore(
163 tenant_id: TenantId,
164 run_id: RunId,
165 delivery_id: DeliveryId,
166 origin_event_id: EventId,
167 destination: OutboxDestinationRef,
168 payload: JournalPayload,
169 expires_at: Timestamp,
170 intent_digest: Digest,
171 ) -> Result<Self, OutboxDeliveryError> {
172 let restored = Self::new(
173 tenant_id,
174 run_id,
175 delivery_id,
176 origin_event_id,
177 destination,
178 payload,
179 expires_at,
180 )?;
181 if restored.intent_digest != intent_digest {
182 return Err(OutboxDeliveryError::IntentDigestMismatch);
183 }
184 Ok(restored)
185 }
186
187 #[must_use]
189 pub const fn tenant_id(&self) -> &TenantId {
190 &self.tenant_id
191 }
192
193 #[must_use]
195 pub const fn run_id(&self) -> RunId {
196 self.run_id
197 }
198
199 #[must_use]
201 pub const fn delivery_id(&self) -> DeliveryId {
202 self.delivery_id
203 }
204
205 #[must_use]
207 pub const fn origin_event_id(&self) -> EventId {
208 self.origin_event_id
209 }
210
211 #[must_use]
213 pub const fn destination(&self) -> &OutboxDestinationRef {
214 &self.destination
215 }
216
217 #[must_use]
219 pub const fn payload(&self) -> &JournalPayload {
220 &self.payload
221 }
222
223 #[must_use]
225 pub const fn expires_at(&self) -> Timestamp {
226 self.expires_at
227 }
228
229 #[must_use]
231 pub const fn intent_digest(&self) -> Digest {
232 self.intent_digest
233 }
234}
235
236impl fmt::Debug for OutboxDeliveryIntent {
237 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
238 formatter
239 .debug_struct("OutboxDeliveryIntent")
240 .field("tenant_id", &self.tenant_id)
241 .field("run_id", &self.run_id)
242 .field("delivery_id", &self.delivery_id)
243 .field("origin_event_id", &self.origin_event_id)
244 .field("destination", &self.destination)
245 .field("payload", &self.payload)
246 .field("expires_at", &self.expires_at)
247 .field("intent_digest", &self.intent_digest)
248 .finish_non_exhaustive()
249 }
250}
251
252impl<'de> Deserialize<'de> for OutboxDeliveryIntent {
253 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
254 where
255 D: Deserializer<'de>,
256 {
257 #[derive(Deserialize)]
258 #[serde(deny_unknown_fields)]
259 struct Wire {
260 tenant_id: TenantId,
261 run_id: RunId,
262 delivery_id: DeliveryId,
263 origin_event_id: EventId,
264 destination: OutboxDestinationRef,
265 payload: JournalPayload,
266 expires_at: Timestamp,
267 intent_digest: Digest,
268 }
269
270 let wire = Wire::deserialize(deserializer)?;
271 Self::restore(
272 wire.tenant_id,
273 wire.run_id,
274 wire.delivery_id,
275 wire.origin_event_id,
276 wire.destination,
277 wire.payload,
278 wire.expires_at,
279 wire.intent_digest,
280 )
281 .map_err(de::Error::custom)
282 }
283}
284
285#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
287#[serde(deny_unknown_fields)]
288pub struct OutboxDelivery {
289 intent: OutboxDeliveryIntent,
290 origin: JournalHead,
291 digest: Digest,
292}
293
294impl OutboxDelivery {
295 pub fn commit(
302 intent: OutboxDeliveryIntent,
303 origin: JournalHead,
304 ) -> Result<Self, OutboxDeliveryError> {
305 validate_delivery_shape(&intent, &origin)?;
306 let digest = compute_delivery_digest(&OutboxDeliveryDigestWire {
307 tenant_id: &intent.tenant_id,
308 run_id: intent.run_id,
309 delivery_id: intent.delivery_id,
310 intent_digest: intent.intent_digest,
311 origin: &origin,
312 expires_at: intent.expires_at,
313 })?;
314 Ok(Self {
315 intent,
316 origin,
317 digest,
318 })
319 }
320
321 pub fn restore(
327 intent: OutboxDeliveryIntent,
328 origin: JournalHead,
329 digest: Digest,
330 ) -> Result<Self, OutboxDeliveryError> {
331 let restored = Self::commit(intent, origin)?;
332 if restored.digest != digest {
333 return Err(OutboxDeliveryError::DeliveryDigestMismatch);
334 }
335 Ok(restored)
336 }
337
338 #[must_use]
340 pub const fn intent(&self) -> &OutboxDeliveryIntent {
341 &self.intent
342 }
343
344 #[must_use]
346 pub const fn origin(&self) -> &JournalHead {
347 &self.origin
348 }
349
350 #[must_use]
352 pub const fn digest(&self) -> Digest {
353 self.digest
354 }
355
356 #[must_use]
358 pub fn head(&self) -> OutboxDeliveryHead {
359 OutboxDeliveryHead {
360 tenant_id: self.intent.tenant_id.clone(),
361 run_id: self.intent.run_id,
362 delivery_id: self.intent.delivery_id,
363 origin: self.origin.clone(),
364 intent_digest: self.intent.intent_digest,
365 expires_at: self.intent.expires_at,
366 digest: self.digest,
367 }
368 }
369}
370
371impl fmt::Debug for OutboxDelivery {
372 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
373 formatter
374 .debug_struct("OutboxDelivery")
375 .field("intent", &self.intent)
376 .field("origin", &self.origin)
377 .field("digest", &self.digest)
378 .finish_non_exhaustive()
379 }
380}
381
382impl<'de> Deserialize<'de> for OutboxDelivery {
383 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
384 where
385 D: Deserializer<'de>,
386 {
387 #[derive(Deserialize)]
388 #[serde(deny_unknown_fields)]
389 struct Wire {
390 intent: OutboxDeliveryIntent,
391 origin: JournalHead,
392 digest: Digest,
393 }
394
395 let wire = Wire::deserialize(deserializer)?;
396 Self::restore(wire.intent, wire.origin, wire.digest).map_err(de::Error::custom)
397 }
398}
399
400#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
402#[serde(deny_unknown_fields)]
403pub struct OutboxDeliveryHead {
404 tenant_id: TenantId,
405 run_id: RunId,
406 delivery_id: DeliveryId,
407 origin: JournalHead,
408 intent_digest: Digest,
409 expires_at: Timestamp,
410 digest: Digest,
411}
412
413impl OutboxDeliveryHead {
414 #[allow(clippy::too_many_arguments)]
421 pub fn restore(
422 tenant_id: TenantId,
423 run_id: RunId,
424 delivery_id: DeliveryId,
425 origin: JournalHead,
426 intent_digest: Digest,
427 expires_at: Timestamp,
428 digest: Digest,
429 ) -> Result<Self, OutboxDeliveryError> {
430 validate_delivery_head_scope(&tenant_id, run_id, &origin, expires_at)?;
431 let expected = compute_delivery_digest(&OutboxDeliveryDigestWire {
432 tenant_id: &tenant_id,
433 run_id,
434 delivery_id,
435 intent_digest,
436 origin: &origin,
437 expires_at,
438 })?;
439 if expected != digest {
440 return Err(OutboxDeliveryError::DeliveryDigestMismatch);
441 }
442 Ok(Self {
443 tenant_id,
444 run_id,
445 delivery_id,
446 origin,
447 intent_digest,
448 expires_at,
449 digest,
450 })
451 }
452
453 #[must_use]
455 pub const fn tenant_id(&self) -> &TenantId {
456 &self.tenant_id
457 }
458
459 #[must_use]
461 pub const fn run_id(&self) -> RunId {
462 self.run_id
463 }
464
465 #[must_use]
467 pub const fn delivery_id(&self) -> DeliveryId {
468 self.delivery_id
469 }
470
471 #[must_use]
473 pub const fn origin(&self) -> &JournalHead {
474 &self.origin
475 }
476
477 #[must_use]
479 pub const fn intent_digest(&self) -> Digest {
480 self.intent_digest
481 }
482
483 #[must_use]
485 pub const fn expires_at(&self) -> Timestamp {
486 self.expires_at
487 }
488
489 #[must_use]
491 pub const fn digest(&self) -> Digest {
492 self.digest
493 }
494}
495
496impl<'de> Deserialize<'de> for OutboxDeliveryHead {
497 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
498 where
499 D: Deserializer<'de>,
500 {
501 #[derive(Deserialize)]
502 #[serde(deny_unknown_fields)]
503 struct Wire {
504 tenant_id: TenantId,
505 run_id: RunId,
506 delivery_id: DeliveryId,
507 origin: JournalHead,
508 intent_digest: Digest,
509 expires_at: Timestamp,
510 digest: Digest,
511 }
512
513 let wire = Wire::deserialize(deserializer)?;
514 Self::restore(
515 wire.tenant_id,
516 wire.run_id,
517 wire.delivery_id,
518 wire.origin,
519 wire.intent_digest,
520 wire.expires_at,
521 wire.digest,
522 )
523 .map_err(de::Error::custom)
524 }
525}
526
527#[derive(Clone, Debug, Deserialize, Eq, Hash, JsonSchema, PartialEq, Serialize)]
533#[serde(deny_unknown_fields)]
534pub struct DeliveryFence {
535 tenant_id: TenantId,
536 run_id: RunId,
537 delivery_id: DeliveryId,
538 attempt_id: AttemptId,
539 epoch: FencingEpoch,
540}
541
542impl DeliveryFence {
543 #[must_use]
545 pub const fn new(
546 tenant_id: TenantId,
547 run_id: RunId,
548 delivery_id: DeliveryId,
549 attempt_id: AttemptId,
550 epoch: FencingEpoch,
551 ) -> Self {
552 Self {
553 tenant_id,
554 run_id,
555 delivery_id,
556 attempt_id,
557 epoch,
558 }
559 }
560
561 #[must_use]
563 pub const fn tenant_id(&self) -> &TenantId {
564 &self.tenant_id
565 }
566
567 #[must_use]
569 pub const fn run_id(&self) -> RunId {
570 self.run_id
571 }
572
573 #[must_use]
575 pub const fn delivery_id(&self) -> DeliveryId {
576 self.delivery_id
577 }
578
579 #[must_use]
581 pub const fn attempt_id(&self) -> AttemptId {
582 self.attempt_id
583 }
584
585 #[must_use]
587 pub const fn epoch(&self) -> FencingEpoch {
588 self.epoch
589 }
590}
591
592#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, PartialEq, Serialize)]
594#[serde(rename_all = "snake_case")]
595#[non_exhaustive]
596pub enum OutboxAttemptStatus {
597 Delivering,
599 Acknowledged,
601 Failed,
603}
604
605#[allow(clippy::large_enum_variant)]
607#[derive(Clone, JsonSchema, Serialize)]
608#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
609#[non_exhaustive]
610pub enum OutboxAttemptOutcome {
611 Acknowledged {
613 #[serde(skip_serializing_if = "Option::is_none")]
615 evidence_digest: Option<Digest>,
616 },
617 Failed {
619 failure: Failure,
621 },
622}
623
624impl OutboxAttemptOutcome {
625 #[must_use]
627 pub const fn status(&self) -> OutboxAttemptStatus {
628 match self {
629 Self::Acknowledged { .. } => OutboxAttemptStatus::Acknowledged,
630 Self::Failed { .. } => OutboxAttemptStatus::Failed,
631 }
632 }
633
634 #[must_use]
636 pub const fn evidence_digest(&self) -> Option<Digest> {
637 match self {
638 Self::Acknowledged { evidence_digest } => *evidence_digest,
639 Self::Failed { .. } => None,
640 }
641 }
642
643 #[must_use]
645 pub const fn failure(&self) -> Option<&Failure> {
646 match self {
647 Self::Acknowledged { .. } => None,
648 Self::Failed { failure } => Some(failure),
649 }
650 }
651}
652
653impl fmt::Debug for OutboxAttemptOutcome {
654 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
655 match self {
656 Self::Acknowledged { evidence_digest } => formatter
657 .debug_struct("Acknowledged")
658 .field("evidence_digest", evidence_digest)
659 .finish(),
660 Self::Failed { failure } => formatter
661 .debug_struct("Failed")
662 .field("failure_id", &failure.id())
663 .field("category", &failure.category())
664 .field("code", failure.code())
665 .field("origin", failure.origin())
666 .field("retry_advice", &failure.retry_advice())
667 .finish_non_exhaustive(),
668 }
669 }
670}
671
672impl<'de> Deserialize<'de> for OutboxAttemptOutcome {
673 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
674 where
675 D: Deserializer<'de>,
676 {
677 #[allow(clippy::large_enum_variant)]
678 #[derive(Deserialize)]
679 #[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
680 enum Wire {
681 Acknowledged {
682 #[serde(default)]
683 evidence_digest: Option<Digest>,
684 },
685 Failed {
686 failure: Failure,
687 },
688 }
689
690 Ok(match Wire::deserialize(deserializer)? {
691 Wire::Acknowledged { evidence_digest } => Self::Acknowledged { evidence_digest },
692 Wire::Failed { failure } => Self::Failed { failure },
693 })
694 }
695}
696
697#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
699#[serde(deny_unknown_fields)]
700pub struct OutboxAttemptStart {
701 delivery: OutboxDeliveryHead,
702 fence: DeliveryFence,
703 started_at: Timestamp,
704 expires_at: Timestamp,
705 digest: Digest,
706}
707
708impl OutboxAttemptStart {
709 pub fn new(
716 delivery: &OutboxDelivery,
717 fence: DeliveryFence,
718 started_at: Timestamp,
719 expires_at: Timestamp,
720 ) -> Result<Self, OutboxAttemptError> {
721 Self::materialize(delivery.head(), fence, started_at, expires_at)
722 }
723
724 pub fn restore(
730 delivery: OutboxDeliveryHead,
731 fence: DeliveryFence,
732 started_at: Timestamp,
733 expires_at: Timestamp,
734 digest: Digest,
735 ) -> Result<Self, OutboxAttemptError> {
736 let restored = Self::materialize(delivery, fence, started_at, expires_at)?;
737 if restored.digest != digest {
738 return Err(OutboxAttemptError::StartDigestMismatch);
739 }
740 Ok(restored)
741 }
742
743 fn materialize(
744 delivery: OutboxDeliveryHead,
745 fence: DeliveryFence,
746 started_at: Timestamp,
747 expires_at: Timestamp,
748 ) -> Result<Self, OutboxAttemptError> {
749 validate_attempt_start(&delivery, &fence, started_at, expires_at)?;
750 let digest = compute_attempt_start_digest(&OutboxAttemptStartDigestWire {
751 delivery: &delivery,
752 fence: &fence,
753 started_at,
754 expires_at,
755 })?;
756 Ok(Self {
757 delivery,
758 fence,
759 started_at,
760 expires_at,
761 digest,
762 })
763 }
764
765 #[must_use]
767 pub const fn delivery(&self) -> &OutboxDeliveryHead {
768 &self.delivery
769 }
770
771 #[must_use]
773 pub const fn fence(&self) -> &DeliveryFence {
774 &self.fence
775 }
776
777 #[must_use]
779 pub const fn started_at(&self) -> Timestamp {
780 self.started_at
781 }
782
783 #[must_use]
785 pub const fn expires_at(&self) -> Timestamp {
786 self.expires_at
787 }
788
789 #[must_use]
791 pub const fn digest(&self) -> Digest {
792 self.digest
793 }
794
795 #[must_use]
797 pub fn head(&self) -> OutboxAttemptStartHead {
798 OutboxAttemptStartHead {
799 delivery: self.delivery.clone(),
800 fence: self.fence.clone(),
801 started_at: self.started_at,
802 expires_at: self.expires_at,
803 digest: self.digest,
804 }
805 }
806}
807
808impl fmt::Debug for OutboxAttemptStart {
809 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
810 formatter
811 .debug_struct("OutboxAttemptStart")
812 .field("delivery", &self.delivery)
813 .field("fence", &self.fence)
814 .field("started_at", &self.started_at)
815 .field("expires_at", &self.expires_at)
816 .field("digest", &self.digest)
817 .finish_non_exhaustive()
818 }
819}
820
821impl<'de> Deserialize<'de> for OutboxAttemptStart {
822 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
823 where
824 D: Deserializer<'de>,
825 {
826 #[derive(Deserialize)]
827 #[serde(deny_unknown_fields)]
828 struct Wire {
829 delivery: OutboxDeliveryHead,
830 fence: DeliveryFence,
831 started_at: Timestamp,
832 expires_at: Timestamp,
833 digest: Digest,
834 }
835
836 let wire = Wire::deserialize(deserializer)?;
837 Self::restore(
838 wire.delivery,
839 wire.fence,
840 wire.started_at,
841 wire.expires_at,
842 wire.digest,
843 )
844 .map_err(de::Error::custom)
845 }
846}
847
848#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
850#[serde(deny_unknown_fields)]
851pub struct OutboxAttemptStartHead {
852 delivery: OutboxDeliveryHead,
853 fence: DeliveryFence,
854 started_at: Timestamp,
855 expires_at: Timestamp,
856 digest: Digest,
857}
858
859impl OutboxAttemptStartHead {
860 pub fn restore(
866 delivery: OutboxDeliveryHead,
867 fence: DeliveryFence,
868 started_at: Timestamp,
869 expires_at: Timestamp,
870 digest: Digest,
871 ) -> Result<Self, OutboxAttemptError> {
872 Ok(OutboxAttemptStart::restore(delivery, fence, started_at, expires_at, digest)?.head())
873 }
874
875 #[must_use]
877 pub const fn delivery(&self) -> &OutboxDeliveryHead {
878 &self.delivery
879 }
880
881 #[must_use]
883 pub const fn fence(&self) -> &DeliveryFence {
884 &self.fence
885 }
886
887 #[must_use]
889 pub const fn started_at(&self) -> Timestamp {
890 self.started_at
891 }
892
893 #[must_use]
895 pub const fn expires_at(&self) -> Timestamp {
896 self.expires_at
897 }
898
899 #[must_use]
901 pub const fn digest(&self) -> Digest {
902 self.digest
903 }
904}
905
906impl<'de> Deserialize<'de> for OutboxAttemptStartHead {
907 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
908 where
909 D: Deserializer<'de>,
910 {
911 #[derive(Deserialize)]
912 #[serde(deny_unknown_fields)]
913 struct Wire {
914 delivery: OutboxDeliveryHead,
915 fence: DeliveryFence,
916 started_at: Timestamp,
917 expires_at: Timestamp,
918 digest: Digest,
919 }
920
921 let wire = Wire::deserialize(deserializer)?;
922 OutboxAttemptStart::restore(
923 wire.delivery,
924 wire.fence,
925 wire.started_at,
926 wire.expires_at,
927 wire.digest,
928 )
929 .map(|start| start.head())
930 .map_err(de::Error::custom)
931 }
932}
933
934#[derive(Clone, JsonSchema, Serialize)]
936#[serde(deny_unknown_fields)]
937pub struct OutboxAttemptCompletion {
938 start: OutboxAttemptStartHead,
939 outcome: OutboxAttemptOutcome,
940 completed_at: Timestamp,
941 digest: Digest,
942}
943
944impl OutboxAttemptCompletion {
945 pub fn acknowledge(
951 start: &OutboxAttemptStart,
952 evidence_digest: Option<Digest>,
953 completed_at: Timestamp,
954 ) -> Result<Self, OutboxAttemptError> {
955 Self::materialize(
956 start.head(),
957 OutboxAttemptOutcome::Acknowledged { evidence_digest },
958 completed_at,
959 )
960 }
961
962 pub fn fail(
972 start: &OutboxAttemptStart,
973 failure: Failure,
974 completed_at: Timestamp,
975 ) -> Result<Self, OutboxAttemptError> {
976 Self::materialize(
977 start.head(),
978 OutboxAttemptOutcome::Failed { failure },
979 completed_at,
980 )
981 }
982
983 pub fn restore(
989 start: OutboxAttemptStartHead,
990 outcome: OutboxAttemptOutcome,
991 completed_at: Timestamp,
992 digest: Digest,
993 ) -> Result<Self, OutboxAttemptError> {
994 let restored = Self::materialize(start, outcome, completed_at)?;
995 if restored.digest != digest {
996 return Err(OutboxAttemptError::CompletionDigestMismatch);
997 }
998 Ok(restored)
999 }
1000
1001 fn materialize(
1002 start: OutboxAttemptStartHead,
1003 outcome: OutboxAttemptOutcome,
1004 completed_at: Timestamp,
1005 ) -> Result<Self, OutboxAttemptError> {
1006 validate_attempt_completion(&start, &outcome, completed_at)?;
1007 let digest = compute_attempt_completion_digest(&OutboxAttemptCompletionDigestWire {
1008 start: &start,
1009 outcome: &outcome,
1010 completed_at,
1011 })?;
1012 Ok(Self {
1013 start,
1014 outcome,
1015 completed_at,
1016 digest,
1017 })
1018 }
1019
1020 #[must_use]
1022 pub const fn start(&self) -> &OutboxAttemptStartHead {
1023 &self.start
1024 }
1025
1026 #[must_use]
1028 pub const fn outcome(&self) -> &OutboxAttemptOutcome {
1029 &self.outcome
1030 }
1031
1032 #[must_use]
1034 pub const fn status(&self) -> OutboxAttemptStatus {
1035 self.outcome.status()
1036 }
1037
1038 #[must_use]
1040 pub const fn completed_at(&self) -> Timestamp {
1041 self.completed_at
1042 }
1043
1044 #[must_use]
1046 pub const fn digest(&self) -> Digest {
1047 self.digest
1048 }
1049}
1050
1051impl fmt::Debug for OutboxAttemptCompletion {
1052 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1053 formatter
1054 .debug_struct("OutboxAttemptCompletion")
1055 .field("start", &self.start)
1056 .field("outcome", &self.outcome)
1057 .field("completed_at", &self.completed_at)
1058 .field("digest", &self.digest)
1059 .finish_non_exhaustive()
1060 }
1061}
1062
1063impl<'de> Deserialize<'de> for OutboxAttemptCompletion {
1064 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1065 where
1066 D: Deserializer<'de>,
1067 {
1068 #[derive(Deserialize)]
1069 #[serde(deny_unknown_fields)]
1070 struct Wire {
1071 start: OutboxAttemptStartHead,
1072 outcome: OutboxAttemptOutcome,
1073 completed_at: Timestamp,
1074 digest: Digest,
1075 }
1076
1077 let wire = Wire::deserialize(deserializer)?;
1078 Self::restore(wire.start, wire.outcome, wire.completed_at, wire.digest)
1079 .map_err(de::Error::custom)
1080 }
1081}
1082
1083#[derive(Clone, JsonSchema, Serialize)]
1085#[serde(deny_unknown_fields)]
1086pub struct OutboxAttempt {
1087 start: OutboxAttemptStart,
1088 #[serde(skip_serializing_if = "Option::is_none")]
1089 completion: Option<OutboxAttemptCompletion>,
1090}
1091
1092impl OutboxAttempt {
1093 #[must_use]
1095 pub const fn delivering(start: OutboxAttemptStart) -> Self {
1096 Self {
1097 start,
1098 completion: None,
1099 }
1100 }
1101
1102 pub fn restore(
1109 start: OutboxAttemptStart,
1110 completion: Option<OutboxAttemptCompletion>,
1111 ) -> Result<Self, OutboxAttemptError> {
1112 if completion
1113 .as_ref()
1114 .is_some_and(|completion| completion.start() != &start.head())
1115 {
1116 return Err(OutboxAttemptError::CompletionStartMismatch);
1117 }
1118 Ok(Self { start, completion })
1119 }
1120
1121 #[must_use]
1123 pub const fn start(&self) -> &OutboxAttemptStart {
1124 &self.start
1125 }
1126
1127 #[must_use]
1129 pub const fn completion(&self) -> Option<&OutboxAttemptCompletion> {
1130 self.completion.as_ref()
1131 }
1132
1133 #[must_use]
1135 pub const fn status(&self) -> OutboxAttemptStatus {
1136 match &self.completion {
1137 Some(completion) => completion.status(),
1138 None => OutboxAttemptStatus::Delivering,
1139 }
1140 }
1141}
1142
1143impl fmt::Debug for OutboxAttempt {
1144 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1145 formatter
1146 .debug_struct("OutboxAttempt")
1147 .field("start", &self.start)
1148 .field("completion", &self.completion)
1149 .finish_non_exhaustive()
1150 }
1151}
1152
1153impl<'de> Deserialize<'de> for OutboxAttempt {
1154 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1155 where
1156 D: Deserializer<'de>,
1157 {
1158 #[derive(Deserialize)]
1159 #[serde(deny_unknown_fields)]
1160 struct Wire {
1161 start: OutboxAttemptStart,
1162 #[serde(default)]
1163 completion: Option<OutboxAttemptCompletion>,
1164 }
1165
1166 let wire = Wire::deserialize(deserializer)?;
1167 Self::restore(wire.start, wire.completion).map_err(de::Error::custom)
1168 }
1169}
1170
1171#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, PartialEq, Serialize)]
1173#[serde(rename_all = "snake_case")]
1174#[non_exhaustive]
1175pub enum OutboxDeliveryStatus {
1176 Pending,
1178 Delivering,
1180 RetryScheduled,
1182 Acknowledged,
1184 DeadLetter,
1186 Expired,
1188}
1189
1190#[derive(Clone, Debug)]
1196pub struct OutboxAttemptHistoryVerifier {
1197 delivery: OutboxDeliveryHead,
1198 last: Option<OutboxAttempt>,
1199 attempt_ids: BTreeSet<AttemptId>,
1200 count: usize,
1201}
1202
1203impl OutboxAttemptHistoryVerifier {
1204 #[must_use]
1206 pub fn new(delivery: &OutboxDelivery) -> Self {
1207 Self {
1208 delivery: delivery.head(),
1209 last: None,
1210 attempt_ids: BTreeSet::new(),
1211 count: 0,
1212 }
1213 }
1214
1215 #[must_use]
1217 pub const fn delivery(&self) -> &OutboxDeliveryHead {
1218 &self.delivery
1219 }
1220
1221 #[must_use]
1223 pub const fn count(&self) -> usize {
1224 self.count
1225 }
1226
1227 #[must_use]
1229 pub const fn last(&self) -> Option<&OutboxAttempt> {
1230 self.last.as_ref()
1231 }
1232
1233 pub fn verify_next(
1240 &mut self,
1241 attempt: &OutboxAttempt,
1242 ) -> Result<(), OutboxAttemptHistoryError> {
1243 if self.count == MAX_OUTBOX_ATTEMPTS {
1244 return Err(OutboxAttemptHistoryError::AttemptLimitExceeded);
1245 }
1246 if attempt.start.delivery != self.delivery {
1247 return Err(OutboxAttemptHistoryError::DeliveryMismatch);
1248 }
1249 let attempt_id = attempt.start.fence.attempt_id;
1250 if self.attempt_ids.contains(&attempt_id) {
1251 return Err(OutboxAttemptHistoryError::AttemptIdReused { attempt_id });
1252 }
1253
1254 if let Some(previous) = self.last.as_ref() {
1255 validate_attempt_successor(previous, attempt)?;
1256 } else if attempt.start.fence.epoch != FencingEpoch::FIRST {
1257 return Err(OutboxAttemptHistoryError::FirstEpochInvalid {
1258 actual: attempt.start.fence.epoch,
1259 });
1260 }
1261
1262 self.attempt_ids.insert(attempt_id);
1263 self.last = Some(attempt.clone());
1264 self.count += 1;
1265 Ok(())
1266 }
1267
1268 pub fn status_at(
1275 &self,
1276 observed_at: Timestamp,
1277 ) -> Result<OutboxDeliveryStatus, OutboxAttemptHistoryError> {
1278 let latest_at = self.last.as_ref().map_or_else(
1279 || self.delivery.origin.recorded_at(),
1280 |attempt| {
1281 attempt.completion.as_ref().map_or_else(
1282 || attempt.start.started_at,
1283 |completion| completion.completed_at,
1284 )
1285 },
1286 );
1287 if observed_at < latest_at {
1288 return Err(OutboxAttemptHistoryError::ObservationClockRegression {
1289 latest_at,
1290 observed_at,
1291 });
1292 }
1293
1294 if let Some(completion) = self
1295 .last
1296 .as_ref()
1297 .and_then(|value| value.completion.as_ref())
1298 {
1299 match completion.outcome() {
1300 OutboxAttemptOutcome::Acknowledged { .. } => {
1301 return Ok(OutboxDeliveryStatus::Acknowledged);
1302 }
1303 OutboxAttemptOutcome::Failed { failure }
1304 if matches!(failure.retry_advice(), RetryAdvice::Never) =>
1305 {
1306 return Ok(OutboxDeliveryStatus::DeadLetter);
1307 }
1308 OutboxAttemptOutcome::Failed { .. } if self.count == MAX_OUTBOX_ATTEMPTS => {
1309 return Ok(OutboxDeliveryStatus::DeadLetter);
1310 }
1311 OutboxAttemptOutcome::Failed { .. } => {}
1312 }
1313 }
1314
1315 if let Some(last) = self.last.as_ref() {
1316 if last.completion.is_none()
1317 && self.count == MAX_OUTBOX_ATTEMPTS
1318 && observed_at >= last.start.expires_at
1319 {
1320 return Ok(if last.start.expires_at < self.delivery.expires_at {
1321 OutboxDeliveryStatus::DeadLetter
1322 } else {
1323 OutboxDeliveryStatus::Expired
1324 });
1325 }
1326 }
1327
1328 if observed_at >= self.delivery.expires_at {
1329 return Ok(OutboxDeliveryStatus::Expired);
1330 }
1331
1332 let Some(last) = self.last.as_ref() else {
1333 return Ok(OutboxDeliveryStatus::Pending);
1334 };
1335 let Some(completion) = last.completion.as_ref() else {
1336 if observed_at < last.start.expires_at {
1337 return Ok(OutboxDeliveryStatus::Delivering);
1338 }
1339 return Ok(OutboxDeliveryStatus::Pending);
1340 };
1341
1342 let OutboxAttemptOutcome::Failed { failure } = completion.outcome() else {
1343 return Ok(OutboxDeliveryStatus::Acknowledged);
1344 };
1345 let RetryAdvice::SafeAfter { delay } = failure.retry_advice() else {
1346 return Ok(OutboxDeliveryStatus::DeadLetter);
1347 };
1348 let eligible_at = retry_eligible_at(completion.completed_at, delay.as_i64())
1349 .map_err(|_| OutboxAttemptHistoryError::RetryDelayOutOfRange)?;
1350 Ok(if observed_at < eligible_at {
1351 OutboxDeliveryStatus::RetryScheduled
1352 } else {
1353 OutboxDeliveryStatus::Pending
1354 })
1355 }
1356}
1357
1358#[derive(Clone, Debug, Eq, Error, PartialEq)]
1360#[non_exhaustive]
1361pub enum OutboxDeliveryError {
1362 #[error("outbox destination crosses the delivery tenant boundary")]
1364 DestinationTenantMismatch,
1365 #[error("outbox origin crosses the delivery tenant boundary")]
1367 OriginTenantMismatch,
1368 #[error("outbox origin does not belong to the delivery run")]
1370 OriginRunMismatch,
1371 #[error("outbox origin event does not match the enqueue intent")]
1373 OriginEventMismatch,
1374 #[error("outbox delivery deadline must be after its origin")]
1376 DeadlineNotAfterOrigin,
1377 #[error("outbox intent digest does not match its fields")]
1379 IntentDigestMismatch,
1380 #[error("outbox delivery digest does not match its fields")]
1382 DeliveryDigestMismatch,
1383 #[error("outbox delivery integrity calculation failed: {source}")]
1385 Integrity {
1386 #[source]
1388 source: OutboxDeliveryIntegrityError,
1389 },
1390}
1391
1392impl From<OutboxDeliveryIntegrityError> for OutboxDeliveryError {
1393 fn from(source: OutboxDeliveryIntegrityError) -> Self {
1394 Self::Integrity { source }
1395 }
1396}
1397
1398#[derive(Clone, Debug, Eq, Error, PartialEq)]
1400#[non_exhaustive]
1401pub enum OutboxDeliveryIntegrityError {
1402 #[error("outbox delivery checksum preimage serialization failed")]
1404 CanonicalSerialization,
1405}
1406
1407#[derive(Clone, Debug, Eq, Error, PartialEq)]
1409#[non_exhaustive]
1410pub enum OutboxAttemptError {
1411 #[error("outbox attempt fence crosses the delivery tenant boundary")]
1413 FenceTenantMismatch,
1414 #[error("outbox attempt fence does not belong to the delivery run")]
1416 FenceRunMismatch,
1417 #[error("outbox attempt fence does not belong to the delivery")]
1419 FenceDeliveryMismatch,
1420 #[error("outbox attempt starts before its delivery origin")]
1422 StartBeforeOrigin,
1423 #[error("outbox attempt starts at or after the delivery deadline")]
1425 StartOutsideDeliveryWindow,
1426 #[error("outbox attempt expiry must be after its start")]
1428 ExpiryNotAfterStart,
1429 #[error("outbox attempt expiry exceeds the delivery deadline")]
1431 ExpiryAfterDeliveryDeadline,
1432 #[error("outbox attempt lease is {actual_millis}ms; maximum is {maximum_millis}ms")]
1434 LeaseTooLong {
1435 maximum_millis: i64,
1437 actual_millis: i64,
1439 },
1440 #[error("outbox attempt completion precedes its start")]
1442 CompletionBeforeStart,
1443 #[error("outbox attempt completion is outside its live fence")]
1445 CompletionOutsideFence,
1446 #[error("outbox failure cannot require external reconciliation")]
1448 ReconciliationUnsupported,
1449 #[error("outbox retry delay exceeds the supported timestamp range")]
1451 RetryDelayOutOfRange,
1452 #[error("outbox attempt completion does not belong to its start")]
1454 CompletionStartMismatch,
1455 #[error("outbox attempt start digest does not match its fields")]
1457 StartDigestMismatch,
1458 #[error("outbox attempt completion digest does not match its fields")]
1460 CompletionDigestMismatch,
1461 #[error("outbox attempt integrity calculation failed: {source}")]
1463 Integrity {
1464 #[source]
1466 source: OutboxAttemptIntegrityError,
1467 },
1468}
1469
1470impl From<OutboxAttemptIntegrityError> for OutboxAttemptError {
1471 fn from(source: OutboxAttemptIntegrityError) -> Self {
1472 Self::Integrity { source }
1473 }
1474}
1475
1476#[derive(Clone, Debug, Eq, Error, PartialEq)]
1478#[non_exhaustive]
1479pub enum OutboxAttemptIntegrityError {
1480 #[error("outbox attempt checksum preimage serialization failed")]
1482 CanonicalSerialization,
1483}
1484
1485#[derive(Clone, Debug, Eq, Error, PartialEq)]
1487#[non_exhaustive]
1488pub enum OutboxAttemptHistoryError {
1489 #[error("outbox delivery exceeded its physical attempt limit")]
1491 AttemptLimitExceeded,
1492 #[error("outbox attempt history changed its logical delivery")]
1494 DeliveryMismatch,
1495 #[error("outbox attempt history reused physical attempt {attempt_id}")]
1497 AttemptIdReused {
1498 attempt_id: AttemptId,
1500 },
1501 #[error("first outbox attempt used epoch {actual}; expected one")]
1503 FirstEpochInvalid {
1504 actual: FencingEpoch,
1506 },
1507 #[error("outbox attempt fencing epoch is not the exact successor")]
1509 EpochNotSuccessor,
1510 #[error("outbox attempt history durable clock regressed")]
1512 ClockRegression,
1513 #[error("unfinished outbox attempt cannot be replaced before lease expiry")]
1515 LiveAttemptSuperseded,
1516 #[error("acknowledged outbox delivery cannot start another attempt")]
1518 PreviousAttemptAcknowledged,
1519 #[error("outbox failure recovery advice does not authorize automatic retry")]
1521 RetryNotAuthorized,
1522 #[error("outbox retry started before its explicit safe-after delay elapsed")]
1524 RetryDelayNotElapsed {
1525 eligible_at: Timestamp,
1527 started_at: Timestamp,
1529 },
1530 #[error("outbox retry delay exceeds the supported timestamp range")]
1532 RetryDelayOutOfRange,
1533 #[error("outbox status observation clock regressed")]
1535 ObservationClockRegression {
1536 latest_at: Timestamp,
1538 observed_at: Timestamp,
1540 },
1541}
1542
1543#[derive(Serialize)]
1544struct OutboxIntentDigestWire<'a> {
1545 tenant_id: &'a TenantId,
1546 run_id: RunId,
1547 delivery_id: DeliveryId,
1548 origin_event_id: EventId,
1549 destination: &'a OutboxDestinationRef,
1550 payload_digest: Digest,
1551 expires_at: Timestamp,
1552}
1553
1554#[derive(Serialize)]
1555struct OutboxDeliveryDigestWire<'a> {
1556 tenant_id: &'a TenantId,
1557 run_id: RunId,
1558 delivery_id: DeliveryId,
1559 intent_digest: Digest,
1560 origin: &'a JournalHead,
1561 expires_at: Timestamp,
1562}
1563
1564#[derive(Serialize)]
1565struct OutboxAttemptStartDigestWire<'a> {
1566 delivery: &'a OutboxDeliveryHead,
1567 fence: &'a DeliveryFence,
1568 started_at: Timestamp,
1569 expires_at: Timestamp,
1570}
1571
1572#[derive(Serialize)]
1573struct OutboxAttemptCompletionDigestWire<'a> {
1574 start: &'a OutboxAttemptStartHead,
1575 outcome: &'a OutboxAttemptOutcome,
1576 completed_at: Timestamp,
1577}
1578
1579fn compute_intent_digest(
1580 value: &OutboxIntentDigestWire<'_>,
1581) -> Result<Digest, OutboxDeliveryIntegrityError> {
1582 delivery_digest(INTENT_DIGEST_DOMAIN, value)
1583}
1584
1585fn compute_delivery_digest(
1586 value: &OutboxDeliveryDigestWire<'_>,
1587) -> Result<Digest, OutboxDeliveryIntegrityError> {
1588 delivery_digest(DELIVERY_DIGEST_DOMAIN, value)
1589}
1590
1591fn delivery_digest<T: Serialize>(
1592 domain: &[u8],
1593 value: &T,
1594) -> Result<Digest, OutboxDeliveryIntegrityError> {
1595 let canonical = serde_json_canonicalizer::to_vec(value)
1596 .map_err(|_| OutboxDeliveryIntegrityError::CanonicalSerialization)?;
1597 let mut preimage = Vec::with_capacity(domain.len() + canonical.len());
1598 preimage.extend_from_slice(domain);
1599 preimage.extend_from_slice(&canonical);
1600 Ok(Digest::sha256(preimage))
1601}
1602
1603fn compute_attempt_start_digest(
1604 value: &OutboxAttemptStartDigestWire<'_>,
1605) -> Result<Digest, OutboxAttemptIntegrityError> {
1606 attempt_digest(ATTEMPT_START_DIGEST_DOMAIN, value)
1607}
1608
1609fn compute_attempt_completion_digest(
1610 value: &OutboxAttemptCompletionDigestWire<'_>,
1611) -> Result<Digest, OutboxAttemptIntegrityError> {
1612 attempt_digest(ATTEMPT_COMPLETION_DIGEST_DOMAIN, value)
1613}
1614
1615fn attempt_digest<T: Serialize>(
1616 domain: &[u8],
1617 value: &T,
1618) -> Result<Digest, OutboxAttemptIntegrityError> {
1619 let canonical = serde_json_canonicalizer::to_vec(value)
1620 .map_err(|_| OutboxAttemptIntegrityError::CanonicalSerialization)?;
1621 let mut preimage = Vec::with_capacity(domain.len() + canonical.len());
1622 preimage.extend_from_slice(domain);
1623 preimage.extend_from_slice(&canonical);
1624 Ok(Digest::sha256(preimage))
1625}
1626
1627fn validate_delivery_shape(
1628 intent: &OutboxDeliveryIntent,
1629 origin: &JournalHead,
1630) -> Result<(), OutboxDeliveryError> {
1631 validate_delivery_head_scope(&intent.tenant_id, intent.run_id, origin, intent.expires_at)?;
1632 if origin.event_id() != intent.origin_event_id {
1633 return Err(OutboxDeliveryError::OriginEventMismatch);
1634 }
1635 Ok(())
1636}
1637
1638fn validate_delivery_head_scope(
1639 tenant_id: &TenantId,
1640 run_id: RunId,
1641 origin: &JournalHead,
1642 expires_at: Timestamp,
1643) -> Result<(), OutboxDeliveryError> {
1644 if origin.tenant_id() != tenant_id {
1645 return Err(OutboxDeliveryError::OriginTenantMismatch);
1646 }
1647 if origin.run_id() != run_id {
1648 return Err(OutboxDeliveryError::OriginRunMismatch);
1649 }
1650 if expires_at <= origin.recorded_at() {
1651 return Err(OutboxDeliveryError::DeadlineNotAfterOrigin);
1652 }
1653 Ok(())
1654}
1655
1656fn validate_attempt_start(
1657 delivery: &OutboxDeliveryHead,
1658 fence: &DeliveryFence,
1659 started_at: Timestamp,
1660 expires_at: Timestamp,
1661) -> Result<(), OutboxAttemptError> {
1662 if fence.tenant_id != delivery.tenant_id {
1663 return Err(OutboxAttemptError::FenceTenantMismatch);
1664 }
1665 if fence.run_id != delivery.run_id {
1666 return Err(OutboxAttemptError::FenceRunMismatch);
1667 }
1668 if fence.delivery_id != delivery.delivery_id {
1669 return Err(OutboxAttemptError::FenceDeliveryMismatch);
1670 }
1671 if started_at < delivery.origin.recorded_at() {
1672 return Err(OutboxAttemptError::StartBeforeOrigin);
1673 }
1674 if started_at >= delivery.expires_at {
1675 return Err(OutboxAttemptError::StartOutsideDeliveryWindow);
1676 }
1677 if expires_at <= started_at {
1678 return Err(OutboxAttemptError::ExpiryNotAfterStart);
1679 }
1680 if expires_at > delivery.expires_at {
1681 return Err(OutboxAttemptError::ExpiryAfterDeliveryDeadline);
1682 }
1683 let duration_micros =
1684 i128::from(expires_at.unix_micros()) - i128::from(started_at.unix_micros());
1685 let maximum_micros = i128::from(MAX_OUTBOX_ATTEMPT_LEASE_MILLIS) * 1_000;
1686 if duration_micros > maximum_micros {
1687 let actual_millis = i64::try_from((duration_micros + 999) / 1_000).unwrap_or(i64::MAX);
1688 return Err(OutboxAttemptError::LeaseTooLong {
1689 maximum_millis: MAX_OUTBOX_ATTEMPT_LEASE_MILLIS,
1690 actual_millis,
1691 });
1692 }
1693 Ok(())
1694}
1695
1696fn validate_attempt_completion(
1697 start: &OutboxAttemptStartHead,
1698 outcome: &OutboxAttemptOutcome,
1699 completed_at: Timestamp,
1700) -> Result<(), OutboxAttemptError> {
1701 if completed_at < start.started_at {
1702 return Err(OutboxAttemptError::CompletionBeforeStart);
1703 }
1704 if completed_at >= start.expires_at {
1705 return Err(OutboxAttemptError::CompletionOutsideFence);
1706 }
1707 if let OutboxAttemptOutcome::Failed { failure } = outcome {
1708 match failure.retry_advice() {
1709 RetryAdvice::ReconcileFirst => {
1710 return Err(OutboxAttemptError::ReconciliationUnsupported);
1711 }
1712 RetryAdvice::SafeAfter { delay } => {
1713 retry_eligible_at(completed_at, delay.as_i64())?;
1714 }
1715 RetryAdvice::Never => {}
1716 }
1717 }
1718 Ok(())
1719}
1720
1721fn validate_attempt_successor(
1722 previous: &OutboxAttempt,
1723 next: &OutboxAttempt,
1724) -> Result<(), OutboxAttemptHistoryError> {
1725 if next.start.fence.epoch
1726 != previous
1727 .start
1728 .fence
1729 .epoch
1730 .checked_next()
1731 .ok_or(OutboxAttemptHistoryError::AttemptLimitExceeded)?
1732 {
1733 return Err(OutboxAttemptHistoryError::EpochNotSuccessor);
1734 }
1735
1736 let anchor = previous
1737 .completion
1738 .as_ref()
1739 .map_or(previous.start.expires_at, |completion| {
1740 completion.completed_at
1741 });
1742 if next.start.started_at < anchor {
1743 return Err(if previous.completion.is_none() {
1744 OutboxAttemptHistoryError::LiveAttemptSuperseded
1745 } else {
1746 OutboxAttemptHistoryError::ClockRegression
1747 });
1748 }
1749
1750 let Some(completion) = previous.completion.as_ref() else {
1751 return Ok(());
1752 };
1753 match completion.outcome() {
1754 OutboxAttemptOutcome::Acknowledged { .. } => {
1755 Err(OutboxAttemptHistoryError::PreviousAttemptAcknowledged)
1756 }
1757 OutboxAttemptOutcome::Failed { failure } => match failure.retry_advice() {
1758 RetryAdvice::SafeAfter { delay } => {
1759 let eligible_at = retry_eligible_at(completion.completed_at, delay.as_i64())
1760 .map_err(|_| OutboxAttemptHistoryError::RetryDelayOutOfRange)?;
1761 if next.start.started_at < eligible_at {
1762 Err(OutboxAttemptHistoryError::RetryDelayNotElapsed {
1763 eligible_at,
1764 started_at: next.start.started_at,
1765 })
1766 } else {
1767 Ok(())
1768 }
1769 }
1770 RetryAdvice::Never | RetryAdvice::ReconcileFirst => {
1771 Err(OutboxAttemptHistoryError::RetryNotAuthorized)
1772 }
1773 },
1774 }
1775}
1776
1777fn retry_eligible_at(
1778 completed_at: Timestamp,
1779 delay_millis: i64,
1780) -> Result<Timestamp, OutboxAttemptError> {
1781 let eligible_micros = i128::from(completed_at.unix_micros()) + i128::from(delay_millis) * 1_000;
1782 if eligible_micros > i128::from(Timestamp::MAX.unix_micros()) {
1783 return Err(OutboxAttemptError::RetryDelayOutOfRange);
1784 }
1785 Timestamp::from_unix_micros(
1786 i64::try_from(eligible_micros).map_err(|_| OutboxAttemptError::RetryDelayOutOfRange)?,
1787 )
1788 .map_err(|_| OutboxAttemptError::RetryDelayOutOfRange)
1789}
1790
1791#[cfg(test)]
1792mod tests {
1793 use super::*;
1794 use crate::{
1795 BoundedJson, DurationMillis, FailureCategory, FailureCode, FailureId, FailureMessage,
1796 FailureOrigin, JournalEventKind, JournalSequence, SchemaId, SchemaReference, Version,
1797 };
1798 use proptest::prelude::*;
1799 use serde_json::{Value, from_value, json, to_value};
1800
1801 const BASE_MICROS: i64 = 1_893_456_000_000_000;
1802
1803 fn id<T: std::str::FromStr>(suffix: u8) -> T
1804 where
1805 T::Err: fmt::Debug,
1806 {
1807 format!("01912345-6789-7abc-8def-0123456789{suffix:02x}")
1808 .parse()
1809 .unwrap()
1810 }
1811
1812 fn timestamp(offset_micros: i64) -> Timestamp {
1813 Timestamp::from_unix_micros(BASE_MICROS + offset_micros).unwrap()
1814 }
1815
1816 fn payload() -> JournalPayload {
1817 JournalPayload::new(
1818 SchemaReference::new(
1819 "https://stateknot.github.io/schema/outbox-test/1.0.0"
1820 .parse::<SchemaId>()
1821 .unwrap(),
1822 Version::new(1, 0, 0),
1823 Digest::sha256(b"outbox-test-schema"),
1824 ),
1825 JournalEventKind::new("a2a-task-update").unwrap(),
1826 BoundedJson::try_from_value(json!({
1827 "task_id": "task-42",
1828 "state": "completed"
1829 }))
1830 .unwrap(),
1831 )
1832 .unwrap()
1833 }
1834
1835 fn delivery_with_deadline(deadline_offset_micros: i64) -> OutboxDelivery {
1836 let tenant_id = TenantId::new("tenant-a").unwrap();
1837 let run_id = id::<RunId>(0x10);
1838 let origin_event_id = id::<EventId>(0x11);
1839 let destination = OutboxDestinationRef::new(
1840 tenant_id.clone(),
1841 id::<DestinationId>(0x12),
1842 Digest::sha256(b"destination-snapshot"),
1843 );
1844 let intent = OutboxDeliveryIntent::new(
1845 tenant_id.clone(),
1846 run_id,
1847 id::<DeliveryId>(0x13),
1848 origin_event_id,
1849 destination,
1850 payload(),
1851 timestamp(deadline_offset_micros),
1852 )
1853 .unwrap();
1854 let origin = JournalHead::new(
1855 tenant_id,
1856 run_id,
1857 JournalSequence::FIRST,
1858 origin_event_id,
1859 timestamp(0),
1860 Digest::sha256(b"origin-event"),
1861 );
1862 OutboxDelivery::commit(intent, origin).unwrap()
1863 }
1864
1865 fn delivery() -> OutboxDelivery {
1866 delivery_with_deadline(86_400_000_000)
1867 }
1868
1869 fn start(
1870 delivery: &OutboxDelivery,
1871 suffix: u8,
1872 epoch: u64,
1873 started_offset_micros: i64,
1874 lease_micros: i64,
1875 ) -> OutboxAttemptStart {
1876 OutboxAttemptStart::new(
1877 delivery,
1878 DeliveryFence::new(
1879 delivery.intent().tenant_id().clone(),
1880 delivery.intent().run_id(),
1881 delivery.intent().delivery_id(),
1882 id::<AttemptId>(suffix),
1883 FencingEpoch::new(epoch).unwrap(),
1884 ),
1885 timestamp(started_offset_micros),
1886 timestamp(started_offset_micros + lease_micros),
1887 )
1888 .unwrap()
1889 }
1890
1891 fn failure(suffix: u8, retry_advice: RetryAdvice) -> Failure {
1892 let category = if matches!(retry_advice, RetryAdvice::ReconcileFirst) {
1893 FailureCategory::AmbiguousExternalOutcome
1894 } else {
1895 FailureCategory::Internal
1896 };
1897 Failure::new(
1898 id::<FailureId>(suffix),
1899 category,
1900 FailureCode::new("outbox.delivery_failed").unwrap(),
1901 FailureOrigin::new("stateknot.outbox.test").unwrap(),
1902 FailureMessage::new("Delivery failed safely").unwrap(),
1903 retry_advice,
1904 )
1905 .unwrap()
1906 }
1907
1908 #[test]
1909 fn delivery_binds_origin_destination_payload_deadline_and_every_digest() {
1910 let delivery = delivery();
1911 let encoded = to_value(&delivery).unwrap();
1912 assert_eq!(
1913 from_value::<OutboxDelivery>(encoded.clone()).unwrap(),
1914 delivery
1915 );
1916 assert_eq!(
1917 from_value::<OutboxDeliveryHead>(to_value(delivery.head()).unwrap()).unwrap(),
1918 delivery.head()
1919 );
1920
1921 for path in ["delivery_id", "expires_at"] {
1922 let mut changed = to_value(delivery.head()).unwrap();
1923 changed[path] = if path == "delivery_id" {
1924 json!(id::<DeliveryId>(0x14))
1925 } else {
1926 json!(timestamp(86_399_000_000))
1927 };
1928 assert!(from_value::<OutboxDeliveryHead>(changed).is_err());
1929 }
1930
1931 let mut changed_payload = encoded;
1932 changed_payload["intent"]["payload"]["data"]["state"] = json!("failed");
1933 assert!(from_value::<OutboxDelivery>(changed_payload).is_err());
1934 }
1935
1936 #[test]
1937 fn delivery_rejects_crossed_scope_substituted_origin_and_closed_deadline() {
1938 let delivery = delivery();
1939 let intent = delivery.intent().clone();
1940 let origin = delivery.origin().clone();
1941
1942 let crossed = JournalHead::new(
1943 TenantId::new("tenant-b").unwrap(),
1944 origin.run_id(),
1945 origin.sequence(),
1946 origin.event_id(),
1947 origin.recorded_at(),
1948 origin.digest(),
1949 );
1950 assert_eq!(
1951 OutboxDelivery::commit(intent.clone(), crossed),
1952 Err(OutboxDeliveryError::OriginTenantMismatch)
1953 );
1954
1955 let substituted = JournalHead::new(
1956 origin.tenant_id().clone(),
1957 origin.run_id(),
1958 origin.sequence(),
1959 id::<EventId>(0x15),
1960 origin.recorded_at(),
1961 origin.digest(),
1962 );
1963 assert_eq!(
1964 OutboxDelivery::commit(intent, substituted),
1965 Err(OutboxDeliveryError::OriginEventMismatch)
1966 );
1967
1968 let deadline = delivery_with_deadline(1);
1969 let mut changed = to_value(deadline).unwrap();
1970 changed["intent"]["expires_at"] = json!(timestamp(0));
1971 assert!(from_value::<OutboxDelivery>(changed).is_err());
1972 }
1973
1974 #[test]
1975 fn attempt_lease_and_completion_enforce_exclusive_time_boundaries() {
1976 let delivery = delivery_with_deadline(600_000_000);
1977 let live = start(&delivery, 0x20, 1, 1_000_000, 10_000_000);
1978 assert!(
1979 OutboxAttemptCompletion::acknowledge(
1980 &live,
1981 Some(Digest::sha256(b"ack")),
1982 timestamp(10_999_999),
1983 )
1984 .is_ok()
1985 );
1986 assert!(matches!(
1987 OutboxAttemptCompletion::acknowledge(&live, None, timestamp(11_000_000)),
1988 Err(OutboxAttemptError::CompletionOutsideFence)
1989 ));
1990
1991 let too_long = OutboxAttemptStart::new(
1992 &delivery,
1993 DeliveryFence::new(
1994 delivery.intent().tenant_id().clone(),
1995 delivery.intent().run_id(),
1996 delivery.intent().delivery_id(),
1997 id::<AttemptId>(0x21),
1998 FencingEpoch::new(2).unwrap(),
1999 ),
2000 timestamp(1_000_000),
2001 timestamp(1_000_000 + (MAX_OUTBOX_ATTEMPT_LEASE_MILLIS + 1) * 1_000),
2002 );
2003 assert!(matches!(
2004 too_long,
2005 Err(OutboxAttemptError::LeaseTooLong { .. })
2006 ));
2007 }
2008
2009 #[test]
2010 fn outbox_rejects_reconcile_first_because_duplicates_are_the_contract() {
2011 let delivery = delivery();
2012 let start = start(&delivery, 0x22, 1, 1_000_000, 10_000_000);
2013 assert!(matches!(
2014 OutboxAttemptCompletion::fail(
2015 &start,
2016 failure(0x23, RetryAdvice::ReconcileFirst),
2017 timestamp(2_000_000),
2018 ),
2019 Err(OutboxAttemptError::ReconciliationUnsupported)
2020 ));
2021 }
2022
2023 #[test]
2024 fn lost_ack_recovery_waits_for_fixed_expiry_and_advances_exact_epoch() {
2025 let delivery = delivery();
2026 let first = OutboxAttempt::delivering(start(&delivery, 0x30, 1, 1_000_000, 5_000_000));
2027 let early = OutboxAttempt::delivering(start(&delivery, 0x31, 2, 5_999_999, 5_000_000));
2028 let recovered = OutboxAttempt::delivering(start(&delivery, 0x31, 2, 6_000_000, 5_000_000));
2029
2030 let mut verifier = OutboxAttemptHistoryVerifier::new(&delivery);
2031 verifier.verify_next(&first).unwrap();
2032 assert_eq!(
2033 verifier.verify_next(&early),
2034 Err(OutboxAttemptHistoryError::LiveAttemptSuperseded)
2035 );
2036 assert_eq!(verifier.count(), 1);
2037 verifier.verify_next(&recovered).unwrap();
2038 assert_eq!(verifier.count(), 2);
2039 }
2040
2041 #[test]
2042 fn safe_after_retry_and_status_projection_use_durable_database_time() {
2043 let delivery = delivery();
2044 let first_start = start(&delivery, 0x40, 1, 1_000_000, 10_000_000);
2045 let completion = OutboxAttemptCompletion::fail(
2046 &first_start,
2047 failure(
2048 0x41,
2049 RetryAdvice::SafeAfter {
2050 delay: DurationMillis::new(2_500).unwrap(),
2051 },
2052 ),
2053 timestamp(2_000_000),
2054 )
2055 .unwrap();
2056 let first = OutboxAttempt::restore(first_start, Some(completion)).unwrap();
2057
2058 let mut verifier = OutboxAttemptHistoryVerifier::new(&delivery);
2059 verifier.verify_next(&first).unwrap();
2060 assert_eq!(
2061 verifier.status_at(timestamp(4_499_999)).unwrap(),
2062 OutboxDeliveryStatus::RetryScheduled
2063 );
2064 assert_eq!(
2065 verifier.status_at(timestamp(4_500_000)).unwrap(),
2066 OutboxDeliveryStatus::Pending
2067 );
2068
2069 let early = OutboxAttempt::delivering(start(&delivery, 0x42, 2, 4_499_999, 1_000_000));
2070 assert!(matches!(
2071 verifier.verify_next(&early),
2072 Err(OutboxAttemptHistoryError::RetryDelayNotElapsed { .. })
2073 ));
2074 let retry = OutboxAttempt::delivering(start(&delivery, 0x42, 2, 4_500_000, 1_000_000));
2075 verifier.verify_next(&retry).unwrap();
2076 }
2077
2078 #[test]
2079 fn acknowledgement_and_never_failures_are_absorbing_terminal_states() {
2080 let delivery = delivery();
2081 let acknowledged_start = start(&delivery, 0x50, 1, 1_000_000, 10_000_000);
2082 let acknowledged = OutboxAttempt::restore(
2083 acknowledged_start.clone(),
2084 Some(
2085 OutboxAttemptCompletion::acknowledge(
2086 &acknowledged_start,
2087 None,
2088 timestamp(2_000_000),
2089 )
2090 .unwrap(),
2091 ),
2092 )
2093 .unwrap();
2094 let successor = OutboxAttempt::delivering(start(&delivery, 0x51, 2, 3_000_000, 1_000_000));
2095 let mut verifier = OutboxAttemptHistoryVerifier::new(&delivery);
2096 verifier.verify_next(&acknowledged).unwrap();
2097 assert_eq!(
2098 verifier.status_at(timestamp(3_000_000)).unwrap(),
2099 OutboxDeliveryStatus::Acknowledged
2100 );
2101 assert_eq!(
2102 verifier.verify_next(&successor),
2103 Err(OutboxAttemptHistoryError::PreviousAttemptAcknowledged)
2104 );
2105
2106 let failed_start = start(&delivery, 0x52, 1, 1_000_000, 10_000_000);
2107 let failed = OutboxAttempt::restore(
2108 failed_start.clone(),
2109 Some(
2110 OutboxAttemptCompletion::fail(
2111 &failed_start,
2112 failure(0x53, RetryAdvice::Never),
2113 timestamp(2_000_000),
2114 )
2115 .unwrap(),
2116 ),
2117 )
2118 .unwrap();
2119 let mut verifier = OutboxAttemptHistoryVerifier::new(&delivery);
2120 verifier.verify_next(&failed).unwrap();
2121 assert_eq!(
2122 verifier.status_at(timestamp(3_000_000)).unwrap(),
2123 OutboxDeliveryStatus::DeadLetter
2124 );
2125 assert_eq!(
2126 verifier.verify_next(&successor),
2127 Err(OutboxAttemptHistoryError::RetryNotAuthorized)
2128 );
2129 }
2130
2131 #[test]
2132 fn attempt_history_is_hard_bounded_and_rejections_do_not_advance_state() {
2133 let delivery = delivery();
2134 let mut verifier = OutboxAttemptHistoryVerifier::new(&delivery);
2135 for index in 0..MAX_OUTBOX_ATTEMPTS {
2136 let started_offset = 1_000_000 + i64::try_from(index).unwrap() * 2_000;
2137 let attempt_start = start(
2138 &delivery,
2139 u8::try_from(0x80 + index).unwrap(),
2140 u64::try_from(index + 1).unwrap(),
2141 started_offset,
2142 1_000,
2143 );
2144 let completion = OutboxAttemptCompletion::fail(
2145 &attempt_start,
2146 failure(
2147 u8::try_from(0x40 + index).unwrap(),
2148 RetryAdvice::SafeAfter {
2149 delay: DurationMillis::ZERO,
2150 },
2151 ),
2152 timestamp(started_offset + 500),
2153 )
2154 .unwrap();
2155 verifier
2156 .verify_next(&OutboxAttempt::restore(attempt_start, Some(completion)).unwrap())
2157 .unwrap();
2158 }
2159 assert_eq!(verifier.count(), MAX_OUTBOX_ATTEMPTS);
2160 assert_eq!(
2161 verifier.status_at(timestamp(2_000_000)).unwrap(),
2162 OutboxDeliveryStatus::DeadLetter
2163 );
2164 assert_eq!(
2165 verifier.status_at(timestamp(90_000_000_000)).unwrap(),
2166 OutboxDeliveryStatus::DeadLetter,
2167 "attempt exhaustion is an absorbing terminal state"
2168 );
2169 let extra = OutboxAttempt::delivering(start(
2170 &delivery,
2171 0x7f,
2172 u64::try_from(MAX_OUTBOX_ATTEMPTS + 1).unwrap(),
2173 2_000_000,
2174 1_000,
2175 ));
2176 assert_eq!(
2177 verifier.verify_next(&extra),
2178 Err(OutboxAttemptHistoryError::AttemptLimitExceeded)
2179 );
2180 assert_eq!(verifier.count(), MAX_OUTBOX_ATTEMPTS);
2181 }
2182
2183 #[test]
2184 fn all_integrity_bearing_wires_are_closed_and_revalidated() {
2185 let delivery = delivery();
2186 let start = start(&delivery, 0x60, 1, 1_000_000, 10_000_000);
2187 let completion = OutboxAttemptCompletion::acknowledge(
2188 &start,
2189 Some(Digest::sha256(b"ack")),
2190 timestamp(2_000_000),
2191 )
2192 .unwrap();
2193 let attempt = OutboxAttempt::restore(start.clone(), Some(completion.clone())).unwrap();
2194
2195 macro_rules! rejects_extra {
2196 ($value:expr, $type:ty) => {{
2197 let mut extra = to_value($value).unwrap();
2198 extra["unsafe_extension"] = Value::Bool(true);
2199 assert!(from_value::<$type>(extra).is_err());
2200 }};
2201 }
2202 rejects_extra!(delivery.intent(), OutboxDeliveryIntent);
2203 rejects_extra!(&delivery, OutboxDelivery);
2204 rejects_extra!(delivery.head(), OutboxDeliveryHead);
2205 rejects_extra!(&start, OutboxAttemptStart);
2206 rejects_extra!(start.head(), OutboxAttemptStartHead);
2207 rejects_extra!(&completion, OutboxAttemptCompletion);
2208 rejects_extra!(&attempt, OutboxAttempt);
2209
2210 let mut changed = to_value(completion).unwrap();
2211 changed["outcome"]["evidence_digest"] = json!(Digest::sha256(b"changed"));
2212 assert!(from_value::<OutboxAttemptCompletion>(changed).is_err());
2213 }
2214
2215 proptest! {
2216 #[test]
2217 fn safe_after_projection_changes_only_at_the_exact_boundary(
2218 delay_millis in 1_i64..=86_000_000_i64,
2219 ) {
2220 let delivery = delivery_with_deadline(86_400_000_000);
2221 let attempt_start = start(&delivery, 0x70, 1, 1_000_000, 10_000_000);
2222 let completed_at = timestamp(2_000_000);
2223 let completion = OutboxAttemptCompletion::fail(
2224 &attempt_start,
2225 failure(
2226 0x71,
2227 RetryAdvice::SafeAfter {
2228 delay: DurationMillis::new(delay_millis).unwrap(),
2229 },
2230 ),
2231 completed_at,
2232 )
2233 .unwrap();
2234 let mut verifier = OutboxAttemptHistoryVerifier::new(&delivery);
2235 verifier
2236 .verify_next(&OutboxAttempt::restore(attempt_start, Some(completion)).unwrap())
2237 .unwrap();
2238 let eligible_at = timestamp(2_000_000 + delay_millis * 1_000);
2239 let before = Timestamp::from_unix_micros(eligible_at.unix_micros() - 1).unwrap();
2240
2241 prop_assert_eq!(
2242 verifier.status_at(before).unwrap(),
2243 OutboxDeliveryStatus::RetryScheduled
2244 );
2245 prop_assert_eq!(
2246 verifier.status_at(eligible_at).unwrap(),
2247 OutboxDeliveryStatus::Pending
2248 );
2249 }
2250
2251 #[test]
2252 fn fixed_attempt_lease_acceptance_matches_the_published_bound(
2253 lease_millis in 1_i64..=MAX_OUTBOX_ATTEMPT_LEASE_MILLIS + 1,
2254 ) {
2255 let delivery = delivery_with_deadline(600_000_000);
2256 let result = OutboxAttemptStart::new(
2257 &delivery,
2258 DeliveryFence::new(
2259 delivery.intent().tenant_id().clone(),
2260 delivery.intent().run_id(),
2261 delivery.intent().delivery_id(),
2262 id::<AttemptId>(0x72),
2263 FencingEpoch::FIRST,
2264 ),
2265 timestamp(1_000_000),
2266 timestamp(1_000_000 + lease_millis * 1_000),
2267 );
2268 prop_assert_eq!(result.is_ok(), lease_millis <= MAX_OUTBOX_ATTEMPT_LEASE_MILLIS);
2269 }
2270 }
2271}