Skip to main content

alien_core/resources/
queue.rs

1use crate::error::{ErrorData, Result};
2use crate::resource::{ResourceDefinition, ResourceOutputsDefinition, ResourceRef};
3use crate::ResourceType;
4use alien_error::AlienError;
5use bon::Builder;
6use serde::{Deserialize, Serialize};
7use std::any::Any;
8
9/// Represents a message queue resource with minimal, portable semantics.
10/// Queue integrates with platform-native services (AWS SQS, GCP Pub/Sub, Azure Service Bus).
11#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Builder)]
12#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
13#[serde(rename_all = "camelCase", deny_unknown_fields)]
14#[builder(start_fn = new)]
15pub struct Queue {
16    /// Identifier for the queue. Must contain only alphanumeric characters, hyphens, and underscores ([A-Za-z0-9-_]).
17    /// Maximum 64 characters.
18    #[builder(start_fn)]
19    pub id: String,
20
21    /// Move a message to another Queue in the stack after it failed to be processed
22    /// `max_attempts` times. Omitted when absent so existing serialized configurations and
23    /// setup digests do not change.
24    #[serde(default, skip_serializing_if = "Option::is_none")]
25    pub dead_letter: Option<QueueDeadLetter>,
26}
27
28/// Default number of delivery attempts before a message moves to the dead-letter queue.
29pub const DEFAULT_DEAD_LETTER_MAX_ATTEMPTS: u32 = 5;
30/// Fewest delivery attempts a dead-letter setting accepts (the Pub/Sub range).
31pub const MIN_DEAD_LETTER_MAX_ATTEMPTS: u32 = 5;
32/// Most delivery attempts a dead-letter setting accepts (the Pub/Sub range).
33pub const MAX_DEAD_LETTER_MAX_ATTEMPTS: u32 = 100;
34
35fn default_dead_letter_max_attempts() -> u32 {
36    DEFAULT_DEAD_LETTER_MAX_ATTEMPTS
37}
38
39/// Where a Queue moves messages that keep failing.
40///
41/// The target is a normal Queue in the same stack with the same lifecycle. The attempt count is
42/// approximate: it is the cloud's own delivery count (SQS counts every receive, Pub/Sub is
43/// best-effort). The payload is preserved; there is no portable failure reason.
44#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Builder)]
45#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
46#[serde(rename_all = "camelCase", deny_unknown_fields)]
47pub struct QueueDeadLetter {
48    /// The Queue that receives the messages. Must be a Queue in the stack with the same
49    /// lifecycle, must not be this Queue and must not have a dead-letter setting itself.
50    pub queue: ResourceRef,
51
52    /// Deliveries after which the message moves (5 to 100, default 5).
53    #[serde(default = "default_dead_letter_max_attempts")]
54    #[builder(default = default_dead_letter_max_attempts())]
55    #[cfg_attr(feature = "openapi", schema(minimum = 5, maximum = 100, default = 5))]
56    pub max_attempts: u32,
57}
58
59impl Queue {
60    /// The resource type identifier for Queue
61    pub const RESOURCE_TYPE: ResourceType = ResourceType::from_static("queue");
62
63    /// Returns the queue's unique identifier.
64    pub fn id(&self) -> &str {
65        &self.id
66    }
67}
68
69/// SQS keeps messages for 4 days by default. A dead-lettered message keeps its original send
70/// time, so a queue that receives them keeps messages for the SQS maximum of 14 days.
71pub const AWS_DEFAULT_RETENTION_SECONDS: u32 = 4 * 24 * 60 * 60;
72/// Retention for an SQS queue that is a dead-letter target.
73pub const AWS_DEAD_LETTER_TARGET_RETENTION_SECONDS: u32 = 14 * 24 * 60 * 60;
74
75/// Ids of the Queues in `stack` that dead-letter into `queue_id`, sorted.
76pub fn queues_dead_lettering_to(stack: &crate::Stack, queue_id: &str) -> Vec<String> {
77    let mut sources: Vec<String> = stack
78        .resources
79        .iter()
80        .filter(|(_, entry)| {
81            entry
82                .config
83                .downcast_ref::<Queue>()
84                .and_then(|queue| queue.dead_letter.as_ref())
85                .is_some_and(|dead_letter| dead_letter.queue.id == queue_id)
86        })
87        .map(|(id, _)| id.clone())
88        .collect();
89    sources.sort();
90    sources
91}
92
93/// Whether the Queue `queue_id` of `stack` has a dead-letter setting.
94pub fn queue_has_dead_letter(stack: &crate::Stack, queue_id: &str) -> bool {
95    stack
96        .resources
97        .get(queue_id)
98        .and_then(|entry| entry.config.downcast_ref::<Queue>())
99        .is_some_and(|queue| queue.dead_letter.is_some())
100}
101
102/// Whether a Live Worker of `stack` is triggered by the Queue `queue_id`. (A setup-owned Worker's
103/// subscription is written by setup, which also grants on it directly.)
104pub fn queue_has_worker_trigger(stack: &crate::Stack, queue_id: &str) -> bool {
105    stack.resources.values().any(|entry| {
106        entry.lifecycle == crate::ResourceLifecycle::Live
107            && entry
108            .config
109            .downcast_ref::<crate::Worker>()
110            .is_some_and(|worker| {
111                worker.triggers.iter().any(|trigger| {
112                    matches!(trigger, crate::WorkerTrigger::Queue { queue, .. } if queue.id == queue_id)
113                })
114            })
115    })
116}
117
118/// Whether the Queue `queue_id` is setup-owned (Frozen), has a dead-letter setting and is the
119/// trigger of a Worker. A Worker's push subscription on such a queue is not written by anything
120/// that holds IAM write access at runtime, so setup grants the Pub/Sub service agent
121/// `roles/pubsub.subscriber` for the project once (Google's documented grant for dead-letter
122/// subscriptions) instead. See `queues_needing_project_push_subscriber`.
123pub fn queue_needs_project_push_subscriber(stack: &crate::Stack, queue_id: &str) -> bool {
124    stack.resources.get(queue_id).is_some_and(|entry| {
125        entry.lifecycle == crate::ResourceLifecycle::Frozen
126            && entry
127                .config
128                .downcast_ref::<Queue>()
129                .is_some_and(|queue| queue.dead_letter.is_some())
130    }) && queue_has_worker_trigger(stack, queue_id)
131}
132
133/// The Queues of `stack` that need the project-level subscriber grant of the Pub/Sub service
134/// agent, sorted. One grant serves all of them, so it stays while any of them remains.
135pub fn queues_needing_project_push_subscriber(stack: &crate::Stack) -> Vec<String> {
136    let mut ids: Vec<String> = stack
137        .resources
138        .keys()
139        .filter(|id| queue_needs_project_push_subscriber(stack, id))
140        .cloned()
141        .collect();
142    ids.sort();
143    ids
144}
145
146/// Outputs generated by a successfully provisioned Queue.
147#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
148#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
149#[serde(rename_all = "camelCase")]
150pub struct QueueOutputs {
151    /// The name of the queue (platform-specific physical name).
152    pub queue_name: String,
153    /// Platform-specific identifier or URL (e.g., SQS URL, Pub/Sub topic/subscription).
154    #[serde(skip_serializing_if = "Option::is_none")]
155    pub identifier: Option<String>,
156}
157
158impl ResourceOutputsDefinition for QueueOutputs {
159    fn get_resource_type(&self) -> ResourceType {
160        Queue::RESOURCE_TYPE.clone()
161    }
162
163    fn as_any(&self) -> &dyn Any {
164        self
165    }
166
167    fn box_clone(&self) -> Box<dyn ResourceOutputsDefinition> {
168        Box::new(self.clone())
169    }
170
171    fn outputs_eq(&self, other: &dyn ResourceOutputsDefinition) -> bool {
172        other.as_any().downcast_ref::<QueueOutputs>() == Some(self)
173    }
174
175    fn to_json_value(&self) -> serde_json::Result<serde_json::Value> {
176        serde_json::to_value(self)
177    }
178}
179
180// Implementation of ResourceDefinition trait for Queue
181impl ResourceDefinition for Queue {
182    fn get_resource_type(&self) -> ResourceType {
183        Self::RESOURCE_TYPE
184    }
185
186    fn id(&self) -> &str {
187        &self.id
188    }
189
190    fn replace_after_failed_create_is_safe(&self) -> bool {
191        // Deleting it destroys messages not yet consumed.
192        false
193    }
194
195    fn get_dependencies(&self) -> Vec<ResourceRef> {
196        self.dead_letter
197            .iter()
198            .map(|dead_letter| dead_letter.queue.clone())
199            .collect()
200    }
201
202    fn validate_update(&self, new_config: &dyn ResourceDefinition) -> Result<()> {
203        // Downcast to Queue type to use the existing validate_update method
204        let new_queue = new_config.as_any().downcast_ref::<Queue>().ok_or_else(|| {
205            AlienError::new(ErrorData::UnexpectedResourceType {
206                resource_id: self.id.clone(),
207                expected: Self::RESOURCE_TYPE,
208                actual: new_config.get_resource_type(),
209            })
210        })?;
211
212        if self.id != new_queue.id {
213            return Err(AlienError::new(ErrorData::InvalidResourceUpdate {
214                resource_id: self.id.clone(),
215                reason: "the 'id' field is immutable".to_string(),
216            }));
217        }
218        Ok(())
219    }
220
221    fn as_any(&self) -> &dyn Any {
222        self
223    }
224
225    fn as_any_mut(&mut self) -> &mut dyn Any {
226        self
227    }
228
229    fn box_clone(&self) -> Box<dyn ResourceDefinition> {
230        Box::new(self.clone())
231    }
232
233    fn resource_eq(&self, other: &dyn ResourceDefinition) -> bool {
234        other.as_any().downcast_ref::<Queue>() == Some(self)
235    }
236
237    fn to_json_value(&self) -> serde_json::Result<serde_json::Value> {
238        serde_json::to_value(self)
239    }
240}
241
242#[cfg(test)]
243mod tests {
244    use super::*;
245
246    #[test]
247    fn test_queue_builder() {
248        let q = Queue::new("my-queue".to_string()).build();
249        assert_eq!(q.id, "my-queue");
250    }
251
252    #[test]
253    fn test_queue_resource_type() {
254        assert_eq!(Queue::RESOURCE_TYPE.as_ref(), "queue");
255    }
256
257    #[test]
258    fn test_queue_resource_definition() {
259        let q = Queue::new("test-q".to_string()).build();
260        assert_eq!(q.get_resource_type(), Queue::RESOURCE_TYPE);
261        assert_eq!(q.id(), "test-q");
262        assert!(q.get_dependencies().is_empty());
263    }
264
265    #[test]
266    fn absent_dead_letter_serializes_exactly_as_before() {
267        let q = Queue::new("tasks".to_string()).build();
268        assert_eq!(serde_json::to_string(&q).unwrap(), r#"{"id":"tasks"}"#);
269        let parsed: Queue = serde_json::from_str(r#"{"id":"tasks"}"#).unwrap();
270        assert_eq!(parsed, q);
271    }
272
273    #[test]
274    fn dead_letter_round_trips_in_camel_case_and_is_a_dependency() {
275        let target = ResourceRef::new(Queue::RESOURCE_TYPE, "failed");
276        let q = Queue::new("tasks".to_string())
277            .dead_letter(
278                QueueDeadLetter::builder()
279                    .queue(target.clone())
280                    .max_attempts(7)
281                    .build(),
282            )
283            .build();
284        let json = serde_json::to_value(&q).unwrap();
285        assert_eq!(json["deadLetter"]["maxAttempts"], 7);
286        assert_eq!(json["deadLetter"]["queue"]["id"], "failed");
287        assert_eq!(serde_json::from_value::<Queue>(json).unwrap(), q);
288        assert_eq!(q.get_dependencies(), vec![target]);
289    }
290
291    #[test]
292    fn dead_letter_max_attempts_defaults_to_five_and_rejects_unknown_fields() {
293        let parsed: Queue = serde_json::from_value(serde_json::json!({
294            "id": "tasks",
295            "deadLetter": {"queue": {"type": "queue", "id": "failed"}}
296        }))
297        .unwrap();
298        assert_eq!(parsed.dead_letter.unwrap().max_attempts, 5);
299        assert!(serde_json::from_value::<Queue>(serde_json::json!({
300            "id": "tasks",
301            "deadLetter": {"queue": {"type": "queue", "id": "failed"}, "retries": 3}
302        }))
303        .is_err());
304    }
305
306    #[test]
307    fn dead_letter_can_be_added_changed_and_removed_by_update() {
308        let plain = Queue::new("tasks".to_string()).build();
309        let with = Queue::new("tasks".to_string())
310            .dead_letter(
311                QueueDeadLetter::builder()
312                    .queue(ResourceRef::new(Queue::RESOURCE_TYPE, "failed"))
313                    .build(),
314            )
315            .build();
316        assert!(plain.validate_update(&with).is_ok());
317        assert!(with.validate_update(&plain).is_ok());
318    }
319
320    #[test]
321    fn test_queue_validate_update() {
322        let original = Queue::new("test-q".to_string()).build();
323        let valid_update = Queue::new("test-q".to_string()).build();
324        let invalid_update = Queue::new("different-q".to_string()).build();
325
326        assert!(original.validate_update(&valid_update).is_ok());
327        assert!(original.validate_update(&invalid_update).is_err());
328    }
329}