Skip to main content

forgelib/queue/
mod.rs

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
15/// Largest allowed payload (256 KiB, the SQS `SendMessage` ceiling, enforced
16/// so a future SQS backend stays honest). Over => [`crate::error::ForgeError::Limit`].
17pub const MAX_PAYLOAD_BYTES: usize = 256 * 1024;
18
19/// Longest a `dequeue` long-poll may wait (SQS max). Larger is clamped, not rejected.
20pub const MAX_WAIT: Duration = Duration::from_secs(20);
21
22/// Largest visibility timeout / lease (SQS max). Out of range => `Invalid`.
23pub const MAX_VISIBILITY_TIMEOUT: Duration = Duration::from_secs(12 * 60 * 60);
24
25/// Maximum number of dead letters returned or redriven by one operator call.
26pub const MAX_OPERATOR_BATCH: u32 = 100;
27/// Maximum jobs accepted by one batch enqueue call.
28pub const MAX_ENQUEUE_BATCH: usize = 100;
29/// Maximum leases returned by one batch dequeue call.
30pub const MAX_DEQUEUE_BATCH: usize = 10;
31
32/// Maximum retained operator-safe failure summary. Worker implementations use a
33/// constant classification by default; applications may supply a redacted summary.
34pub const MAX_FAILURE_SUMMARY_BYTES: usize = 512;
35
36/// Largest concurrency key stored with a job.
37pub const MAX_CONCURRENCY_KEY_BYTES: usize = 256;
38/// Largest correlation id stored in a versioned envelope.
39pub const MAX_CORRELATION_ID_BYTES: usize = 256;
40/// Largest schema id stored in a versioned envelope.
41pub const MAX_SCHEMA_BYTES: usize = 256;
42/// Largest content type stored in a versioned envelope.
43pub const MAX_CONTENT_TYPE_BYTES: usize = 128;
44/// Maximum artifact references in one envelope.
45pub 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/// Deliberately small queue priority set. PostgreSQL and memory dequeue higher
55/// priorities first and preserve enqueue order within one priority. Continuous
56/// higher-priority traffic can starve lower priorities; callers that require a
57/// stronger fairness guarantee should use separate queues and worker allocations.
58#[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/// Public lifecycle state. `queued`, `delayed`, and `retrying` are views over the
97/// backend's available state; the distinction is based on due time and attempts.
98#[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/// Payload-free job status for application and operator views.
118#[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/// Bounded operator query. The cursor is opaque and scoped to the same queue/filter.
133#[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/// One bounded status page.
153#[derive(Debug, Clone, PartialEq, Eq)]
154pub struct JobStatusPage {
155    pub items: Vec<JobStatus>,
156    pub next_cursor: Option<crate::Cursor>,
157}
158
159/// Cooperative cancellation token carried by every leased job. Forge signals it,
160/// but cannot terminate application code; handlers must observe it and return.
161#[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/// A blob or external artifact referenced by a queue envelope.
199#[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/// Portable, versioned metadata envelope. Raw queue bytes remain fully supported;
209/// this helper is opt-in and is not the backend storage format.
210#[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    /// Validate metadata and the final encoded size together, then return enqueue-ready bytes.
244    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/// Opaque job identifier (a UUID under the hood).
317#[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/// Retry backoff strategy: exponential with jitter, capped.
345#[non_exhaustive]
346#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
347pub enum Backoff {
348    /// `base * 2^(attempt-1)`, capped at `cap`.
349    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    /// Delay before the `attempt`-th retry (1-based), with ±25% jitter at
363    /// millisecond precision. `seed` decorrelates a fleet retrying after a
364    /// shared outage; pass something per-job (e.g. id bytes) for that effect.
365    /// Saturating throughout: no panic at high attempt counts.
366    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        // 2^(n-1), saturating past 63 shifts.
370        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        // Respect a global ceiling so a huge `cap` can't park a job for years
375        // (the contract's "same cap rule").
376        let base_ms = base_ms.min(duration_ms(MAX_BACKOFF));
377        Duration::from_millis(jitter_ms(base_ms, seed))
378    }
379}
380
381/// Global ceiling on any computed backoff delay (before jitter), matching the
382/// queue's 12h visibility ceiling.
383const 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
389/// Apply ±25% jitter to `base_ms` via a deterministic LCG seeded by `seed`. No
390/// `rand` dependency; same seed yields same factor, keeping tests deterministic.
391fn 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; // [0.75, 1.25)
400    (base_ms as f64 * factor) as u64
401}
402
403/// Options for [`Queue::enqueue`].
404#[non_exhaustive]
405#[derive(Debug, Clone)]
406pub struct EnqueueOpts {
407    /// SQS `DelaySeconds`: the job is invisible until `now + delay`.
408    pub delay: Duration,
409    /// SQS redrive `maxReceiveCount`: deliveries before dead-lettering.
410    pub max_attempts: u32,
411    /// SQS `MessageDeduplicationId`: dedups enqueues per `(queue, dedup_id)`
412    /// within the dedup window. `None` disables dedup.
413    pub dedup_id: Option<String>,
414    /// Caller-selected id for systems layered on top of queue, such as `schedule`.
415    /// Normal app enqueues leave this unset and let the backend mint an id. Backends
416    /// must treat a repeated same-queue id as idempotent success, including when a
417    /// fresh `dedup_id` is also supplied.
418    pub job_id: Option<JobId>,
419    /// Reserved W3C propagation metadata. It is stored separately from the payload
420    /// and baggage has already passed an explicit allow-list.
421    pub trace_context: Option<TraceContext>,
422    /// Bounded priority. Strict priority is used; sustained higher priority can starve lower.
423    pub priority: Priority,
424    /// Optional application key used with `DequeueOpts::concurrency_limit_per_key`.
425    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    /// Set the initial visibility delay.
447    pub fn with_delay(mut self, delay: Duration) -> Self {
448        self.delay = delay;
449        self
450    }
451    /// Set the maximum delivery attempts before dead-lettering.
452    pub fn with_max_attempts(mut self, max_attempts: u32) -> Self {
453        self.max_attempts = max_attempts;
454        self
455    }
456    /// Set a deduplication id.
457    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    /// Set the job id the backend should assign. Intended for Forge primitives that
462    /// need stable correlation across retries; callers usually let queue mint ids.
463    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/// One independent item in a bounded batch enqueue.
485#[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/// Per-item batch result. A failed item does not roll back successful siblings.
501#[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/// Options for [`Queue::dequeue`].
523#[non_exhaustive]
524#[derive(Debug, Clone)]
525pub struct DequeueOpts {
526    /// SQS long-poll `WaitTimeSeconds`, clamped to [`MAX_WAIT`].
527    pub wait: Duration,
528    /// SQS `VisibilityTimeout`: the lease duration. `0 < t <=` [`MAX_VISIBILITY_TIMEOUT`].
529    pub visibility_timeout: Duration,
530    /// Maximum simultaneously leased jobs with the same non-empty concurrency key.
531    /// `None` disables key fairness. A job without a key is never constrained.
532    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    /// Set the long-poll wait.
550    pub fn with_wait(mut self, wait: Duration) -> Self {
551        self.wait = wait;
552        self
553    }
554    /// Set the lease/visibility timeout.
555    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/// Options for [`Queue::nack`].
567#[non_exhaustive]
568#[derive(Debug, Clone, Default)]
569pub struct NackOpts {
570    /// `None` retries immediately; `Some(d)` makes the job available no earlier
571    /// than `now + d`.
572    pub retry_in: Option<Duration>,
573    /// Redacted terminal diagnostic. It is truncated to 512 UTF-8 bytes before
574    /// persistence and must never contain payloads, credentials, or raw backend errors.
575    pub failure_summary: Option<String>,
576}
577
578impl NackOpts {
579    /// Retry no earlier than `now + delay`.
580    pub fn retry_in(delay: Duration) -> Self {
581        Self {
582            retry_in: Some(delay),
583            failure_summary: None,
584        }
585    }
586
587    /// Attach a bounded, caller-redacted diagnostic for eventual DLQ inspection.
588    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/// How a redrive treats a prior deduplication reservation.
595#[derive(Debug, Clone, Copy, PartialEq, Eq)]
596pub enum RedriveDedupPolicy {
597    /// Drop any reservation pointing at the job so the redrive is independent.
598    Clear,
599    /// Keep a live reservation pointing at the stable job id.
600    Preserve,
601}
602
603/// Required redrive choices. A destination is never inferred from the DLQ name.
604#[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/// One payload-free dead-letter record for operator tooling.
620#[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/// Bounded page of dead letters. `next_cursor` is opaque and valid only for the
631/// same logical queue and namespace.
632#[derive(Debug, Clone, PartialEq, Eq)]
633pub struct DeadLetterPage {
634    pub items: Vec<DeadLetterInfo>,
635    pub next_cursor: Option<crate::Cursor>,
636}
637
638/// Result of a bounded batch redrive.
639#[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/// Approximate message counts for a queue, mirroring the SQS CloudWatch
658/// `ApproximateNumberOfMessages*` metrics. All three are point-in-time estimates
659/// taken without locking, so a concurrent enqueue/lease may not be reflected yet.
660#[non_exhaustive]
661#[derive(Debug, Clone, Copy, Default)]
662pub struct QueueDepth {
663    /// Available for immediate delivery (SQS `ApproximateNumberOfMessagesVisible`).
664    /// Counts jobs whose lease has lapsed but not yet been reclaimed, since the next
665    /// `dequeue` will hand them out.
666    pub visible: u64,
667    /// Leased and not past the visibility deadline (SQS `…MessagesNotVisible`).
668    pub in_flight: u64,
669    /// Enqueued with a delay and not yet due (SQS `…MessagesDelayed`).
670    pub delayed: u64,
671    /// Milliseconds since the oldest immediately visible job was enqueued.
672    /// `None` when the queue has no visible jobs.
673    pub oldest_visible_age_ms: Option<u64>,
674}
675
676// Depth equality intentionally compares counts only. The age is sampled from a
677// moving clock and is diagnostic metadata, so including it would make two otherwise
678// identical point-in-time queue states compare unequal a millisecond apart.
679impl 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    /// Construct a depth snapshot. For backend implementors; app code receives this
691    /// from [`Queue::depth`].
692    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    /// Total non-terminal messages: `visible + in_flight + delayed` (saturating).
707    pub fn total(&self) -> u64 {
708        self.visible
709            .saturating_add(self.in_flight)
710            .saturating_add(self.delayed)
711    }
712}
713
714/// Read-only queue activity estimates. Monotonic counters and lifetime-average
715/// rates avoid scanning retained job rows.
716#[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/// A leased unit of work returned by [`Queue::dequeue`].
729#[non_exhaustive]
730#[derive(Debug, Clone)]
731pub struct Job {
732    /// Stable id (also the natural idempotency key for consumers).
733    pub id: JobId,
734    /// Source queue.
735    pub queue: String,
736    /// Opaque payload.
737    pub payload: Bytes,
738    /// 1 on first delivery, N on the Nth.
739    pub attempt: u32,
740    /// Deliveries before dead-lettering.
741    pub max_attempts: u32,
742    /// Lease deadline; refresh with [`Queue::heartbeat`] before it passes.
743    pub leased_until: SystemTime,
744    /// Per-lease fence token. `ack`/`nack`/`heartbeat` only affect the row while
745    /// it still carries this token; a redelivery mints a new one, so a stale
746    /// worker's calls become no-ops / `Precondition`.
747    pub(crate) lease_token: Uuid,
748    /// Reserved cross-process W3C propagation metadata, never mixed into payload bytes.
749    pub trace_context: Option<TraceContext>,
750    /// Cooperative application-cancellation signal.
751    pub cancellation: JobCancellation,
752    pub priority: Priority,
753    pub concurrency_key: Option<String>,
754}
755
756impl Job {
757    /// Construct a leased job. For backend implementors: a backend mints this from a
758    /// claimed row, supplying the per-lease fence `lease_token` that `ack`/`nack`/
759    /// `heartbeat` later check via [`Job::lease_token`]. App code never calls this; it
760    /// receives `Job`s from [`Queue::dequeue`].
761    #[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    /// Attach stored propagation metadata when a backend materializes the lease.
787    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    /// The per-lease fence token. For backend implementors: `ack`/`nack`/`heartbeat`
799    /// must only mutate the row while it still carries this token, so a stale worker's
800    /// calls become no-ops / `Precondition`.
801    pub fn lease_token(&self) -> Uuid {
802        self.lease_token
803    }
804
805    /// Deserialize the payload from JSON. A decode failure is
806    /// [`ForgeError::Invalid`]; the payload is caller data, not a backend error.
807    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/// A background job queue: at-least-once delivery, visibility-timeout leasing,
814/// `maxReceiveCount`-to-DLQ redrive. Mirrors AWS SQS.
815///
816/// Object-safe; the facade hands out `Arc<dyn Queue>`. Exact semantics live in
817/// <https://tryforge.dev/primitives/#queue>.
818#[async_trait]
819pub trait Queue: Send + Sync {
820    /// SQS `SendMessage`. Returns the assigned [`JobId`]. With `opts.dedup_id`,
821    /// a hit within the window returns the existing id (success, not an error).
822    async fn enqueue(&self, queue: &str, payload: Bytes, opts: EnqueueOpts) -> Result<JobId>;
823
824    /// Enqueue at most 100 independent items. Results preserve input order and
825    /// deterministic IDs; one invalid item does not roll back its siblings.
826    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    /// SQS `ReceiveMessage` (long-poll). Leases at most one due job for
846    /// `opts.visibility_timeout`; `Ok(None)` if none arrived within `opts.wait`.
847    /// Claiming does not increment attempts.
848    async fn dequeue(&self, queue: &str, opts: DequeueOpts) -> Result<Option<Job>>;
849
850    /// Lease up to 10 jobs. Only the first receive may long-poll; remaining claims
851    /// are immediate, so shutdown and lease settlement stay identical to single dequeue.
852    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    /// SQS `DeleteMessage` (`leased -> done`). Idempotent: acking a job whose
876    /// lease already expired and was reclaimed is `Ok(())`, not an error.
877    async fn ack(&self, job: &Job) -> Result<()>;
878
879    /// Mark the current delivery failed (`leased -> available`, or to the DLQ if
880    /// the incremented attempt count reaches `max_attempts`). The redelivery
881    /// increments attempts.
882    async fn nack(&self, job: &Job, opts: NackOpts) -> Result<()>;
883
884    /// Extend the lease (beanstalkd `touch`). [`crate::error::ForgeError::Precondition`]
885    /// if the lease was already lost to another worker; stop work on this job.
886    async fn heartbeat(&self, job: &Job) -> Result<()>;
887
888    /// Low-cost cancellation poll used by managed workers. A true result also signals
889    /// `job.cancellation`. It does not terminate the handler.
890    async fn cancellation_requested(&self, job: &Job) -> Result<bool> {
891        let _ = job;
892        Ok(false)
893    }
894
895    /// Request cancellation. Queued/delayed/retrying jobs become cancelled atomically;
896    /// leased jobs become cancel-requested until their handler cooperates or lease expires.
897    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    /// Finish a cooperative cancellation while the caller still owns the lease fence.
905    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    /// SQS `GetQueueAttributes`: approximate visible / in-flight / delayed counts
927    /// for `queue` ([`QueueDepth`]). Non-locking and point-in-time. Pass a
928    /// `"<queue>.dlq"` name to gauge a dead-letter backlog without leasing its jobs.
929    async fn depth(&self, queue: &str) -> Result<QueueDepth>;
930
931    /// Stop new leases from a queue. Existing leases continue and queued work is retained.
932    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    /// Resume leasing from a paused queue. Idempotent.
940    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    /// Indexed age plus counter-based throughput estimates; never scans payload rows.
955    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    /// Inspect payload-free dead-letter metadata for `queue` (the source queue,
963    /// without the reserved `.dlq` suffix).
964    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    /// Move one dead letter to an explicit destination. Returns false when the id
977    /// is absent or no longer in a dead-letter state.
978    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    /// Redrive at most 100 items from one source queue.
986    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    /// Count rows an exact-queue purge would remove. This has no side effects.
1000    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    /// Remove dead letters only when `confirmation` exactly equals `queue`.
1008    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        // Fixed seed so the ±25% jitter is deterministic.
1028        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        // A huge cap at a high attempt would be ~1000h without the global ceiling.
1042        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        // u32::MAX once drove a shift overflow in naive impls.
1058        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;