1use crate::TraceContext;
2use crate::error::{ForgeError, Result};
3use async_trait::async_trait;
4use bytes::Bytes;
5use serde::de::DeserializeOwned;
6use std::fmt;
7use std::sync::{
8 Arc,
9 atomic::{AtomicBool, Ordering},
10};
11use std::time::{Duration, SystemTime};
12use tokio::sync::Notify;
13use uuid::Uuid;
14
15pub const MAX_PAYLOAD_BYTES: usize = 256 * 1024;
18
19pub const MAX_WAIT: Duration = Duration::from_secs(20);
21
22pub const MAX_VISIBILITY_TIMEOUT: Duration = Duration::from_secs(12 * 60 * 60);
24
25pub const MAX_OPERATOR_BATCH: u32 = 100;
27pub const MAX_ENQUEUE_BATCH: usize = 100;
29pub const MAX_DEQUEUE_BATCH: usize = 10;
31
32pub const MAX_FAILURE_SUMMARY_BYTES: usize = 512;
35
36pub const MAX_CONCURRENCY_KEY_BYTES: usize = 256;
38pub const MAX_CORRELATION_ID_BYTES: usize = 256;
40pub const MAX_SCHEMA_BYTES: usize = 256;
42pub const MAX_CONTENT_TYPE_BYTES: usize = 128;
44pub const MAX_ARTIFACT_REFS: usize = 32;
46
47#[derive(Debug, Clone, Copy)]
48pub(crate) struct TerminalRetention {
49 pub succeeded: Duration,
50 pub dead: Duration,
51 pub cancelled: Duration,
52}
53
54#[derive(
59 Debug,
60 Clone,
61 Copy,
62 Default,
63 PartialEq,
64 Eq,
65 PartialOrd,
66 Ord,
67 serde::Serialize,
68 serde::Deserialize,
69)]
70#[serde(rename_all = "snake_case")]
71pub enum Priority {
72 Low,
73 #[default]
74 Normal,
75 High,
76}
77
78impl Priority {
79 pub(crate) const fn rank(self) -> i16 {
80 match self {
81 Self::Low => 0,
82 Self::Normal => 1,
83 Self::High => 2,
84 }
85 }
86
87 pub(crate) const fn from_rank(value: i16) -> Self {
88 match value {
89 0 => Self::Low,
90 2 => Self::High,
91 _ => Self::Normal,
92 }
93 }
94}
95
96#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
99#[serde(rename_all = "snake_case")]
100pub enum JobState {
101 Queued,
102 Delayed,
103 Leased,
104 Retrying,
105 Succeeded,
106 Dead,
107 CancelRequested,
108 Cancelled,
109}
110
111impl JobState {
112 pub const fn is_terminal(self) -> bool {
113 matches!(self, Self::Succeeded | Self::Dead | Self::Cancelled)
114 }
115}
116
117#[derive(Debug, Clone, PartialEq, Eq)]
119pub struct JobStatus {
120 pub id: JobId,
121 pub queue: String,
122 pub state: JobState,
123 pub attempt_count: u32,
124 pub max_attempts: u32,
125 pub priority: Priority,
126 pub concurrency_key: Option<String>,
127 pub enqueued_at: SystemTime,
128 pub available_at: SystemTime,
129 pub completed_at: Option<SystemTime>,
130}
131
132#[derive(Debug, Clone)]
134pub struct JobStatusFilter {
135 pub queue: Option<String>,
136 pub states: Vec<JobState>,
137 pub cursor: Option<crate::Cursor>,
138 pub limit: u32,
139}
140
141impl Default for JobStatusFilter {
142 fn default() -> Self {
143 Self {
144 queue: None,
145 states: Vec::new(),
146 cursor: None,
147 limit: 50,
148 }
149 }
150}
151
152#[derive(Debug, Clone, PartialEq, Eq)]
154pub struct JobStatusPage {
155 pub items: Vec<JobStatus>,
156 pub next_cursor: Option<crate::Cursor>,
157}
158
159#[derive(Clone, Default)]
162pub struct JobCancellation {
163 cancelled: Arc<AtomicBool>,
164 notify: Arc<Notify>,
165}
166
167impl fmt::Debug for JobCancellation {
168 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
169 f.debug_struct("JobCancellation")
170 .field("cancelled", &self.is_cancelled())
171 .finish()
172 }
173}
174
175impl JobCancellation {
176 pub fn is_cancelled(&self) -> bool {
177 self.cancelled.load(Ordering::Acquire)
178 }
179
180 pub async fn cancelled(&self) {
181 if self.is_cancelled() {
182 return;
183 }
184 let notified = self.notify.notified();
185 if self.is_cancelled() {
186 return;
187 }
188 notified.await;
189 }
190
191 pub(crate) fn signal(&self) {
192 if !self.cancelled.swap(true, Ordering::AcqRel) {
193 self.notify.notify_waiters();
194 }
195 }
196}
197
198#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
200pub struct ArtifactRef {
201 pub uri: String,
202 #[serde(skip_serializing_if = "Option::is_none")]
203 pub content_type: Option<String>,
204 #[serde(skip_serializing_if = "Option::is_none")]
205 pub version: Option<String>,
206}
207
208#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
211pub struct QueueEnvelope {
212 pub version: u16,
213 pub schema: String,
214 pub content_type: String,
215 #[serde(skip_serializing_if = "Option::is_none")]
216 pub correlation_id: Option<String>,
217 #[serde(skip_serializing_if = "Option::is_none")]
218 pub trace_context: Option<TraceContext>,
219 #[serde(default, skip_serializing_if = "Vec::is_empty")]
220 pub artifacts: Vec<ArtifactRef>,
221 pub body: Vec<u8>,
222}
223
224impl QueueEnvelope {
225 pub const VERSION: u16 = 1;
226
227 pub fn new(
228 schema: impl Into<String>,
229 content_type: impl Into<String>,
230 body: impl Into<Vec<u8>>,
231 ) -> Self {
232 Self {
233 version: Self::VERSION,
234 schema: schema.into(),
235 content_type: content_type.into(),
236 correlation_id: None,
237 trace_context: None,
238 artifacts: Vec::new(),
239 body: body.into(),
240 }
241 }
242
243 pub fn encode(&self) -> Result<Bytes> {
245 self.validate()?;
246 let bytes = serde_json::to_vec(self)
247 .map_err(|e| ForgeError::invalid(format!("could not encode queue envelope: {e}")))?;
248 if bytes.len() > MAX_PAYLOAD_BYTES {
249 return Err(ForgeError::limit(format!(
250 "encoded envelope is {} bytes; max is {MAX_PAYLOAD_BYTES}; store large bodies in blob storage and reference them",
251 bytes.len()
252 )));
253 }
254 Ok(Bytes::from(bytes))
255 }
256
257 pub fn decode(bytes: &[u8]) -> Result<Self> {
258 let value: Self = serde_json::from_slice(bytes)
259 .map_err(|e| ForgeError::invalid(format!("could not decode queue envelope: {e}")))?;
260 value.validate()?;
261 if bytes.len() > MAX_PAYLOAD_BYTES {
262 return Err(ForgeError::limit(
263 "encoded envelope exceeds the queue payload limit",
264 ));
265 }
266 Ok(value)
267 }
268
269 pub fn validate(&self) -> Result<()> {
270 if self.version != Self::VERSION {
271 return Err(ForgeError::invalid(format!(
272 "unsupported queue envelope version {}",
273 self.version
274 )));
275 }
276 check_metadata("schema", &self.schema, MAX_SCHEMA_BYTES)?;
277 check_metadata("content_type", &self.content_type, MAX_CONTENT_TYPE_BYTES)?;
278 if let Some(value) = &self.correlation_id {
279 check_metadata("correlation_id", value, MAX_CORRELATION_ID_BYTES)?;
280 }
281 if let Some(value) = &self.trace_context {
282 value.validate()?;
283 }
284 if self.artifacts.len() > MAX_ARTIFACT_REFS {
285 return Err(ForgeError::limit(format!(
286 "envelope has {} artifact references; max is {MAX_ARTIFACT_REFS}",
287 self.artifacts.len()
288 )));
289 }
290 for artifact in &self.artifacts {
291 check_metadata("artifact uri", &artifact.uri, 2048)?;
292 if let Some(value) = &artifact.content_type {
293 check_metadata("artifact content_type", value, MAX_CONTENT_TYPE_BYTES)?;
294 }
295 if let Some(value) = &artifact.version {
296 check_metadata("artifact version", value, 256)?;
297 }
298 }
299 Ok(())
300 }
301}
302
303fn check_metadata(name: &str, value: &str, max: usize) -> Result<()> {
304 if value.is_empty() {
305 return Err(ForgeError::invalid(format!("{name} must not be empty")));
306 }
307 if value.len() > max {
308 return Err(ForgeError::limit(format!(
309 "{name} is {} bytes; max is {max}",
310 value.len()
311 )));
312 }
313 Ok(())
314}
315
316#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
318pub struct JobId(pub Uuid);
319
320impl JobId {
321 pub fn new() -> Self {
322 Self(Uuid::new_v4())
323 }
324
325 pub fn parse(value: &str) -> Result<Self> {
326 Uuid::parse_str(value)
327 .map(Self)
328 .map_err(|_| ForgeError::invalid("job id must be a UUID"))
329 }
330}
331
332impl Default for JobId {
333 fn default() -> Self {
334 Self::new()
335 }
336}
337
338impl fmt::Display for JobId {
339 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
340 self.0.fmt(f)
341 }
342}
343
344#[non_exhaustive]
346#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
347pub enum Backoff {
348 Exponential { base: Duration, cap: Duration },
350}
351
352impl Default for Backoff {
353 fn default() -> Self {
354 Self::Exponential {
355 base: Duration::from_secs(1),
356 cap: Duration::from_secs(300),
357 }
358 }
359}
360
361impl Backoff {
362 pub fn delay_for_attempt(&self, attempt: u32, seed: u64) -> Duration {
367 let n = attempt.max(1);
368 let Backoff::Exponential { base, cap } = self;
369 let factor = 1u64.checked_shl(n - 1).unwrap_or(u64::MAX);
371 let base_ms = duration_ms(*base)
372 .saturating_mul(factor)
373 .min(duration_ms(*cap));
374 let base_ms = base_ms.min(duration_ms(MAX_BACKOFF));
377 Duration::from_millis(jitter_ms(base_ms, seed))
378 }
379}
380
381const MAX_BACKOFF: Duration = Duration::from_secs(12 * 60 * 60);
384
385fn duration_ms(d: Duration) -> u64 {
386 u64::try_from(d.as_millis()).unwrap_or(u64::MAX)
387}
388
389fn jitter_ms(base_ms: u64, seed: u64) -> u64 {
392 if base_ms == 0 {
393 return 0;
394 }
395 let r = seed
396 .wrapping_mul(6_364_136_223_846_793_005)
397 .wrapping_add(1_442_695_040_888_963_407);
398 let frac = (r >> 11) as f64 / (1u64 << 53) as f64;
399 let factor = 0.75 + 0.5 * frac; (base_ms as f64 * factor) as u64
401}
402
403#[non_exhaustive]
405#[derive(Debug, Clone)]
406pub struct EnqueueOpts {
407 pub delay: Duration,
409 pub max_attempts: u32,
411 pub dedup_id: Option<String>,
414 pub job_id: Option<JobId>,
419 pub trace_context: Option<TraceContext>,
422 pub priority: Priority,
424 pub concurrency_key: Option<String>,
426}
427
428impl Default for EnqueueOpts {
429 fn default() -> Self {
430 Self {
431 delay: Duration::ZERO,
432 max_attempts: 5,
433 dedup_id: None,
434 job_id: None,
435 trace_context: None,
436 priority: Priority::Normal,
437 concurrency_key: None,
438 }
439 }
440}
441
442impl EnqueueOpts {
443 pub fn new() -> Self {
444 Self::default()
445 }
446 pub fn with_delay(mut self, delay: Duration) -> Self {
448 self.delay = delay;
449 self
450 }
451 pub fn with_max_attempts(mut self, max_attempts: u32) -> Self {
453 self.max_attempts = max_attempts;
454 self
455 }
456 pub fn with_dedup_id(mut self, dedup_id: impl Into<String>) -> Self {
458 self.dedup_id = Some(dedup_id.into());
459 self
460 }
461 pub fn with_job_id(mut self, job_id: JobId) -> Self {
464 self.job_id = Some(job_id);
465 self
466 }
467
468 pub fn with_trace_context(mut self, trace_context: TraceContext) -> Self {
469 self.trace_context = Some(trace_context);
470 self
471 }
472
473 pub fn with_priority(mut self, priority: Priority) -> Self {
474 self.priority = priority;
475 self
476 }
477
478 pub fn with_concurrency_key(mut self, key: impl Into<String>) -> Self {
479 self.concurrency_key = Some(key.into());
480 self
481 }
482}
483
484#[derive(Debug, Clone)]
486pub struct BatchEnqueueItem {
487 pub payload: Bytes,
488 pub opts: EnqueueOpts,
489}
490
491impl BatchEnqueueItem {
492 pub fn new(payload: impl Into<Bytes>, opts: EnqueueOpts) -> Self {
493 Self {
494 payload: payload.into(),
495 opts,
496 }
497 }
498}
499
500#[derive(Debug)]
502pub struct BatchEnqueueResult {
503 pub job_id: Option<JobId>,
504 pub error: Option<ForgeError>,
505}
506
507impl BatchEnqueueResult {
508 fn from_result(result: Result<JobId>) -> Self {
509 match result {
510 Ok(job_id) => Self {
511 job_id: Some(job_id),
512 error: None,
513 },
514 Err(error) => Self {
515 job_id: None,
516 error: Some(error),
517 },
518 }
519 }
520}
521
522#[non_exhaustive]
524#[derive(Debug, Clone)]
525pub struct DequeueOpts {
526 pub wait: Duration,
528 pub visibility_timeout: Duration,
530 pub concurrency_limit_per_key: Option<u32>,
533}
534
535impl Default for DequeueOpts {
536 fn default() -> Self {
537 Self {
538 wait: Duration::from_secs(20),
539 visibility_timeout: Duration::from_secs(30),
540 concurrency_limit_per_key: None,
541 }
542 }
543}
544
545impl DequeueOpts {
546 pub fn new() -> Self {
547 Self::default()
548 }
549 pub fn with_wait(mut self, wait: Duration) -> Self {
551 self.wait = wait;
552 self
553 }
554 pub fn with_visibility_timeout(mut self, vt: Duration) -> Self {
556 self.visibility_timeout = vt;
557 self
558 }
559
560 pub fn with_concurrency_limit_per_key(mut self, limit: u32) -> Self {
561 self.concurrency_limit_per_key = Some(limit);
562 self
563 }
564}
565
566#[non_exhaustive]
568#[derive(Debug, Clone, Default)]
569pub struct NackOpts {
570 pub retry_in: Option<Duration>,
573 pub failure_summary: Option<String>,
576}
577
578impl NackOpts {
579 pub fn retry_in(delay: Duration) -> Self {
581 Self {
582 retry_in: Some(delay),
583 failure_summary: None,
584 }
585 }
586
587 pub fn with_failure_summary(mut self, summary: impl Into<String>) -> Self {
589 self.failure_summary = Some(safe_failure_summary(summary.into()));
590 self
591 }
592}
593
594#[derive(Debug, Clone, Copy, PartialEq, Eq)]
596pub enum RedriveDedupPolicy {
597 Clear,
599 Preserve,
601}
602
603#[derive(Debug, Clone, PartialEq, Eq)]
605pub struct RedriveOpts {
606 pub destination: String,
607 pub dedup_policy: RedriveDedupPolicy,
608}
609
610impl RedriveOpts {
611 pub fn new(destination: impl Into<String>, dedup_policy: RedriveDedupPolicy) -> Self {
612 Self {
613 destination: destination.into(),
614 dedup_policy,
615 }
616 }
617}
618
619#[derive(Debug, Clone, PartialEq, Eq)]
621pub struct DeadLetterInfo {
622 pub job_id: JobId,
623 pub queue: String,
624 pub attempt_count: u32,
625 pub enqueued_at: SystemTime,
626 pub dead_lettered_at: SystemTime,
627 pub failure_summary: Option<String>,
628}
629
630#[derive(Debug, Clone, PartialEq, Eq)]
633pub struct DeadLetterPage {
634 pub items: Vec<DeadLetterInfo>,
635 pub next_cursor: Option<crate::Cursor>,
636}
637
638#[derive(Debug, Clone, PartialEq, Eq)]
640pub struct RedriveBatchResult {
641 pub redriven: u32,
642 pub next_cursor: Option<crate::Cursor>,
643}
644
645pub(crate) fn safe_failure_summary(mut value: String) -> String {
646 if value.len() <= MAX_FAILURE_SUMMARY_BYTES {
647 return value;
648 }
649 let mut end = MAX_FAILURE_SUMMARY_BYTES;
650 while !value.is_char_boundary(end) {
651 end -= 1;
652 }
653 value.truncate(end);
654 value
655}
656
657#[non_exhaustive]
661#[derive(Debug, Clone, Copy, Default)]
662pub struct QueueDepth {
663 pub visible: u64,
667 pub in_flight: u64,
669 pub delayed: u64,
671 pub oldest_visible_age_ms: Option<u64>,
674}
675
676impl PartialEq for QueueDepth {
680 fn eq(&self, other: &Self) -> bool {
681 self.visible == other.visible
682 && self.in_flight == other.in_flight
683 && self.delayed == other.delayed
684 }
685}
686
687impl Eq for QueueDepth {}
688
689impl QueueDepth {
690 pub fn new(visible: u64, in_flight: u64, delayed: u64) -> Self {
693 Self {
694 visible,
695 in_flight,
696 delayed,
697 oldest_visible_age_ms: None,
698 }
699 }
700
701 pub fn with_oldest_visible_age_ms(mut self, age: Option<u64>) -> Self {
702 self.oldest_visible_age_ms = age;
703 self
704 }
705
706 pub fn total(&self) -> u64 {
708 self.visible
709 .saturating_add(self.in_flight)
710 .saturating_add(self.delayed)
711 }
712}
713
714#[derive(Debug, Clone, Copy, Default, PartialEq)]
717pub struct QueueStats {
718 pub enqueued_total: u64,
719 pub settled_total: u64,
720 pub dead_total: u64,
721 pub cancelled_total: u64,
722 pub enqueue_rate_per_minute: f64,
723 pub settle_rate_per_minute: f64,
724 pub oldest_visible_age_ms: Option<u64>,
725 pub paused: bool,
726}
727
728#[non_exhaustive]
730#[derive(Debug, Clone)]
731pub struct Job {
732 pub id: JobId,
734 pub queue: String,
736 pub payload: Bytes,
738 pub attempt: u32,
740 pub max_attempts: u32,
742 pub leased_until: SystemTime,
744 pub(crate) lease_token: Uuid,
748 pub trace_context: Option<TraceContext>,
750 pub cancellation: JobCancellation,
752 pub priority: Priority,
753 pub concurrency_key: Option<String>,
754}
755
756impl Job {
757 #[allow(clippy::too_many_arguments)]
762 pub fn new(
763 id: JobId,
764 queue: String,
765 payload: Bytes,
766 attempt: u32,
767 max_attempts: u32,
768 leased_until: SystemTime,
769 lease_token: Uuid,
770 ) -> Self {
771 Self {
772 id,
773 queue,
774 payload,
775 attempt,
776 max_attempts,
777 leased_until,
778 lease_token,
779 trace_context: None,
780 cancellation: JobCancellation::default(),
781 priority: Priority::Normal,
782 concurrency_key: None,
783 }
784 }
785
786 pub fn with_trace_context(mut self, trace_context: Option<TraceContext>) -> Self {
788 self.trace_context = trace_context;
789 self
790 }
791
792 pub fn with_scheduling(mut self, priority: Priority, concurrency_key: Option<String>) -> Self {
793 self.priority = priority;
794 self.concurrency_key = concurrency_key;
795 self
796 }
797
798 pub fn lease_token(&self) -> Uuid {
802 self.lease_token
803 }
804
805 pub fn payload_json<T: DeserializeOwned>(&self) -> Result<T> {
808 serde_json::from_slice(&self.payload)
809 .map_err(|e| ForgeError::invalid(format!("could not deserialize payload: {e}")))
810 }
811}
812
813#[async_trait]
819pub trait Queue: Send + Sync {
820 async fn enqueue(&self, queue: &str, payload: Bytes, opts: EnqueueOpts) -> Result<JobId>;
823
824 async fn enqueue_batch(
827 &self,
828 queue: &str,
829 items: Vec<BatchEnqueueItem>,
830 ) -> Result<Vec<BatchEnqueueResult>> {
831 if items.is_empty() || items.len() > MAX_ENQUEUE_BATCH {
832 return Err(ForgeError::limit(format!(
833 "batch enqueue size must be in 1..={MAX_ENQUEUE_BATCH}"
834 )));
835 }
836 let mut results = Vec::with_capacity(items.len());
837 for item in items {
838 results.push(BatchEnqueueResult::from_result(
839 self.enqueue(queue, item.payload, item.opts).await,
840 ));
841 }
842 Ok(results)
843 }
844
845 async fn dequeue(&self, queue: &str, opts: DequeueOpts) -> Result<Option<Job>>;
849
850 async fn dequeue_batch(
853 &self,
854 queue: &str,
855 max_items: usize,
856 opts: DequeueOpts,
857 ) -> Result<Vec<Job>> {
858 if max_items == 0 || max_items > MAX_DEQUEUE_BATCH {
859 return Err(ForgeError::limit(format!(
860 "batch dequeue size must be in 1..={MAX_DEQUEUE_BATCH}"
861 )));
862 }
863 let mut jobs = Vec::with_capacity(max_items);
864 let mut next = opts;
865 for _ in 0..max_items {
866 let Some(job) = self.dequeue(queue, next.clone()).await? else {
867 break;
868 };
869 jobs.push(job);
870 next.wait = Duration::ZERO;
871 }
872 Ok(jobs)
873 }
874
875 async fn ack(&self, job: &Job) -> Result<()>;
878
879 async fn nack(&self, job: &Job, opts: NackOpts) -> Result<()>;
883
884 async fn heartbeat(&self, job: &Job) -> Result<()>;
887
888 async fn cancellation_requested(&self, job: &Job) -> Result<bool> {
891 let _ = job;
892 Ok(false)
893 }
894
895 async fn cancel(&self, id: JobId) -> Result<Option<JobStatus>> {
898 let _ = id;
899 Err(ForgeError::not_configured(
900 "queue backend does not implement cancellation",
901 ))
902 }
903
904 async fn finish_cancellation(&self, job: &Job) -> Result<()> {
906 let _ = job;
907 Err(ForgeError::not_configured(
908 "queue backend does not implement cancellation",
909 ))
910 }
911
912 async fn status(&self, id: JobId) -> Result<Option<JobStatus>> {
913 let _ = id;
914 Err(ForgeError::not_configured(
915 "queue backend does not implement status lookup",
916 ))
917 }
918
919 async fn list_status(&self, filter: JobStatusFilter) -> Result<JobStatusPage> {
920 let _ = filter;
921 Err(ForgeError::not_configured(
922 "queue backend does not implement status listing",
923 ))
924 }
925
926 async fn depth(&self, queue: &str) -> Result<QueueDepth>;
930
931 async fn pause(&self, queue: &str) -> Result<()> {
933 let _ = queue;
934 Err(ForgeError::not_configured(
935 "queue backend does not implement pause",
936 ))
937 }
938
939 async fn resume(&self, queue: &str) -> Result<()> {
941 let _ = queue;
942 Err(ForgeError::not_configured(
943 "queue backend does not implement resume",
944 ))
945 }
946
947 async fn is_paused(&self, queue: &str) -> Result<bool> {
948 let _ = queue;
949 Err(ForgeError::not_configured(
950 "queue backend does not implement pause inspection",
951 ))
952 }
953
954 async fn stats(&self, queue: &str) -> Result<QueueStats> {
956 let _ = queue;
957 Err(ForgeError::not_configured(
958 "queue backend does not implement activity stats",
959 ))
960 }
961
962 async fn dead_letters(
965 &self,
966 queue: &str,
967 cursor: Option<crate::Cursor>,
968 limit: u32,
969 ) -> Result<DeadLetterPage> {
970 let _ = (queue, cursor, limit);
971 Err(ForgeError::not_configured(
972 "queue backend does not implement dead-letter inspection",
973 ))
974 }
975
976 async fn redrive(&self, job_id: JobId, opts: RedriveOpts) -> Result<bool> {
979 let _ = (job_id, opts);
980 Err(ForgeError::not_configured(
981 "queue backend does not implement dead-letter redrive",
982 ))
983 }
984
985 async fn redrive_batch(
987 &self,
988 queue: &str,
989 cursor: Option<crate::Cursor>,
990 limit: u32,
991 opts: RedriveOpts,
992 ) -> Result<RedriveBatchResult> {
993 let _ = (queue, cursor, limit, opts);
994 Err(ForgeError::not_configured(
995 "queue backend does not implement batch redrive",
996 ))
997 }
998
999 async fn purge_dead_letters_dry_run(&self, queue: &str) -> Result<u64> {
1001 let _ = queue;
1002 Err(ForgeError::not_configured(
1003 "queue backend does not implement dead-letter purge",
1004 ))
1005 }
1006
1007 async fn purge_dead_letters(&self, queue: &str, confirmation: &str) -> Result<u64> {
1009 let _ = (queue, confirmation);
1010 Err(ForgeError::not_configured(
1011 "queue backend does not implement dead-letter purge",
1012 ))
1013 }
1014}
1015
1016#[cfg(test)]
1017#[allow(clippy::unwrap_used, clippy::indexing_slicing, clippy::panic)]
1018mod tests {
1019 use super::*;
1020
1021 #[test]
1022 fn exponential_backoff_grows_and_caps() {
1023 let b = Backoff::Exponential {
1024 base: Duration::from_secs(1),
1025 cap: Duration::from_secs(300),
1026 };
1027 let d1 = b.delay_for_attempt(1, 7).as_millis();
1029 let d2 = b.delay_for_attempt(2, 7).as_millis();
1030 let d3 = b.delay_for_attempt(3, 7).as_millis();
1031 assert!((750..=1250).contains(&d1), "attempt1 ~1s, got {d1}ms");
1032 assert!((1500..=2500).contains(&d2), "attempt2 ~2s, got {d2}ms");
1033 assert!((3000..=5000).contains(&d3), "attempt3 ~4s, got {d3}ms");
1034 let far = b.delay_for_attempt(40, 7).as_millis();
1035 assert!(far <= 375_000, "capped at 300s + jitter, got {far}ms");
1036 assert!(far >= 225_000, "capped near 300s, got {far}ms");
1037 }
1038
1039 #[test]
1040 fn backoff_respects_the_global_ceiling() {
1041 let b = Backoff::Exponential {
1043 base: Duration::from_secs(3600),
1044 cap: Duration::from_secs(1000 * 3600),
1045 };
1046 let d = b.delay_for_attempt(999, 7).as_millis();
1047 let ceiling_ms = (MAX_BACKOFF.as_millis() as f64 * 1.25) as u128;
1048 assert!(d <= ceiling_ms, "capped at 12h + jitter, got {d}ms");
1049 }
1050
1051 #[test]
1052 fn high_attempt_does_not_panic_or_overflow() {
1053 let b = Backoff::Exponential {
1054 base: Duration::from_secs(1),
1055 cap: Duration::from_secs(300),
1056 };
1057 let _ = b.delay_for_attempt(u32::MAX, 1);
1059 }
1060
1061 #[test]
1062 fn jitter_varies_with_seed_but_is_deterministic() {
1063 let b = Backoff::Exponential {
1064 base: Duration::from_secs(10),
1065 cap: Duration::from_secs(300),
1066 };
1067 let a = b.delay_for_attempt(1, 1);
1068 let a_again = b.delay_for_attempt(1, 1);
1069 let other = b.delay_for_attempt(1, 999);
1070 assert_eq!(a, a_again, "same seed => same delay");
1071 assert_ne!(a, other, "different seed => (very likely) different delay");
1072 }
1073
1074 #[test]
1075 fn zero_base_stays_zero() {
1076 let b = Backoff::Exponential {
1077 base: Duration::ZERO,
1078 cap: Duration::from_secs(300),
1079 };
1080 assert_eq!(b.delay_for_attempt(3, 42), Duration::ZERO);
1081 }
1082}
1083
1084pub mod worker;
1085
1086mod memory;
1087mod postgres;
1088pub(crate) use memory::MemQueue;
1089pub(crate) use postgres::PgQueue;