Skip to main content

yaiko_core/
queue.rs

1//! Bounded queue primitives with retry and dead-letter states.
2use std::collections::BTreeMap;
3#[derive(Debug, Clone, Copy, PartialEq, Eq)]
4pub enum QueueState {
5    Queued,
6    Claimed,
7    Acknowledged,
8    DeadLetter,
9}
10#[derive(Debug, Clone, PartialEq, Eq)]
11pub enum QueueError {
12    Capacity,
13    NotFound,
14    InvalidState,
15    InvalidRetries,
16}
17#[derive(Debug, Clone, PartialEq, Eq)]
18pub struct QueueItem {
19    pub id: String,
20    pub payload: Vec<u8>,
21    pub attempts: u32,
22    pub max_retries: u32,
23    pub state: QueueState,
24}
25#[derive(Debug, Clone)]
26pub struct Queue {
27    items: BTreeMap<String, QueueItem>,
28    capacity: usize,
29    next_id: u64,
30}
31impl Queue {
32    pub fn new(capacity: usize) -> Self {
33        Self {
34            items: BTreeMap::new(),
35            capacity,
36            next_id: 0,
37        }
38    }
39    pub fn enqueue(
40        &mut self,
41        payload: impl Into<Vec<u8>>,
42        max_retries: u32,
43    ) -> Result<QueueItem, QueueError> {
44        if self.items.len() >= self.capacity {
45            return Err(QueueError::Capacity);
46        }
47        if max_retries > 32 {
48            return Err(QueueError::InvalidRetries);
49        }
50        self.next_id += 1;
51        let item = QueueItem {
52            id: format!("queue-{}", self.next_id),
53            payload: payload.into(),
54            attempts: 0,
55            max_retries,
56            state: QueueState::Queued,
57        };
58        self.items.insert(item.id.clone(), item.clone());
59        Ok(item)
60    }
61    pub fn claim(&mut self) -> Option<QueueItem> {
62        let id = self
63            .items
64            .values()
65            .find(|x| x.state == QueueState::Queued)
66            .map(|x| x.id.clone())?;
67        let item = self.items.get_mut(&id).unwrap();
68        item.state = QueueState::Claimed;
69        Some(item.clone())
70    }
71    pub fn retry(&mut self, id: &str) -> Result<QueueItem, QueueError> {
72        let item = self.items.get_mut(id).ok_or(QueueError::NotFound)?;
73        if item.state != QueueState::Claimed {
74            return Err(QueueError::InvalidState);
75        }
76        item.attempts += 1;
77        if item.attempts > item.max_retries {
78            item.state = QueueState::DeadLetter
79        } else {
80            item.state = QueueState::Queued
81        }
82        Ok(item.clone())
83    }
84    pub fn acknowledge(&mut self, id: &str) -> Result<QueueItem, QueueError> {
85        let item = self.items.get_mut(id).ok_or(QueueError::NotFound)?;
86        if item.state != QueueState::Claimed {
87            return Err(QueueError::InvalidState);
88        }
89        item.state = QueueState::Acknowledged;
90        Ok(item.clone())
91    }
92    pub fn snapshot(&self) -> Vec<QueueItem> {
93        self.items.values().cloned().collect()
94    }
95}
96impl Default for Queue {
97    fn default() -> Self {
98        Self::new(1024)
99    }
100}
101#[cfg(test)]
102mod tests {
103    use super::*;
104    #[test]
105    fn claims_retries_and_acknowledges() {
106        let mut q = Queue::new(2);
107        let i = q.enqueue(b"render".to_vec(), 1).unwrap();
108        assert_eq!(q.claim().unwrap().id, i.id);
109        assert_eq!(q.retry(&i.id).unwrap().state, QueueState::Queued);
110        q.claim();
111        assert_eq!(
112            q.acknowledge(&i.id).unwrap().state,
113            QueueState::Acknowledged
114        )
115    }
116    #[test]
117    fn dead_letters_and_enforces_bounds() {
118        let mut q = Queue::new(1);
119        let i = q.enqueue(Vec::new(), 0).unwrap();
120        q.claim();
121        assert_eq!(q.retry(&i.id).unwrap().state, QueueState::DeadLetter);
122        assert!(q.enqueue(Vec::new(), 0).is_err());
123        assert!(q.enqueue(Vec::new(), 33).is_err())
124    }
125}