Skip to main content

nidus_sqs/
lib.rs

1#![forbid(unsafe_code)]
2#![deny(missing_docs)]
3
4//! First-party AWS SQS integration for Nidus.
5//!
6//! The adapter exposes the official AWS SDK client and preserves SQS standard,
7//! FIFO, visibility timeout, long polling, message attributes, and DLQ APIs.
8//! Standard queues are at-least-once; handlers must be idempotent and delete a
9//! receipt only after successful processing.
10
11use std::{
12    fmt,
13    sync::{
14        Arc,
15        atomic::{AtomicBool, Ordering},
16    },
17    time::{Duration, Instant},
18};
19
20use async_trait::async_trait;
21use aws_sdk_sqs::types::Message;
22#[cfg(feature = "health")]
23use aws_sdk_sqs::types::QueueAttributeName;
24use nidus_core::{Container, LifecycleHook, NidusError};
25use nidus_integrations::{
26    IntegrationEvent, IntegrationStatus, IntegrationTelemetry, MessageEnvelope,
27};
28use serde::Serialize;
29use thiserror::Error;
30use tokio::sync::{Semaphore, SemaphorePermit};
31
32const MAX_MESSAGE_BYTES: usize = 1024 * 1024;
33const MAX_IN_FLIGHT: usize = 65_536;
34
35/// Result type for SQS adapter operations.
36pub type Result<T> = std::result::Result<T, SqsError>;
37
38/// SQS adapter error preserving the official SDK source error.
39#[derive(Debug, Error)]
40pub enum SqsError {
41    /// The AWS SDK returned an SQS error.
42    #[error("AWS SQS operation failed: {source}")]
43    Sdk {
44        /// Top-level AWS SQS source error.
45        #[source]
46        source: Box<aws_sdk_sqs::Error>,
47    },
48    /// Shared envelope serialization failed.
49    #[error(transparent)]
50    Integration(#[from] nidus_integrations::IntegrationError),
51    /// Nidus provider registration failed.
52    #[error(transparent)]
53    Nidus(#[from] NidusError),
54    /// Adapter configuration was unsafe or incomplete.
55    #[error("invalid SQS configuration: {message}")]
56    Configuration {
57        /// Redaction-safe validation message.
58        message: &'static str,
59    },
60    /// The message exceeded the SQS one-mebibyte limit.
61    #[error("SQS message is {actual} bytes, exceeding the {maximum}-byte limit")]
62    MessageTooLarge {
63        /// Actual encoded size.
64        actual: usize,
65        /// SQS maximum size.
66        maximum: usize,
67    },
68    /// An envelope was not valid UTF-8 JSON.
69    #[error("SQS envelope encoding was not UTF-8")]
70    InvalidUtf8,
71    /// The bounded provider was closed during an operation.
72    #[error("SQS provider is shutting down")]
73    ShuttingDown,
74    /// Admitted AWS requests did not drain before the shutdown deadline.
75    #[error("SQS shutdown exceeded its configured timeout")]
76    ShutdownTimeout,
77}
78
79/// Typed SQS long-polling, visibility, and concurrency configuration.
80#[derive(Clone, Eq, PartialEq)]
81pub struct SqsConfig {
82    queue_url: String,
83    wait_time_seconds: i32,
84    visibility_timeout_seconds: i32,
85    max_messages: i32,
86    max_in_flight: usize,
87    shutdown_timeout: Duration,
88    allow_http_local: bool,
89}
90
91impl SqsConfig {
92    /// Creates secure long-polling SQS configuration.
93    pub fn new(queue_url: impl Into<String>) -> Self {
94        Self {
95            queue_url: queue_url.into(),
96            wait_time_seconds: 20,
97            visibility_timeout_seconds: 60,
98            max_messages: 10,
99            max_in_flight: 64,
100            shutdown_timeout: Duration::from_secs(30),
101            allow_http_local: false,
102        }
103    }
104
105    /// Sets the long-poll wait time in the SQS range `0..=20` seconds.
106    pub fn with_wait_time_seconds(mut self, value: i32) -> Self {
107        self.wait_time_seconds = value;
108        self
109    }
110
111    /// Sets the per-receive visibility timeout in `0..=43200` seconds.
112    pub fn with_visibility_timeout_seconds(mut self, value: i32) -> Self {
113        self.visibility_timeout_seconds = value;
114        self
115    }
116
117    /// Sets the receive batch size in the SQS range `1..=10`.
118    pub fn with_max_messages(mut self, value: i32) -> Self {
119        self.max_messages = value;
120        self
121    }
122
123    /// Sets the maximum concurrent provider-owned AWS requests.
124    pub fn with_max_in_flight(mut self, value: usize) -> Self {
125        self.max_in_flight = value;
126        self
127    }
128
129    /// Sets how long graceful shutdown waits for admitted AWS requests.
130    pub fn with_shutdown_timeout(mut self, value: Duration) -> Self {
131        self.shutdown_timeout = value;
132        self
133    }
134
135    /// Explicitly permits an HTTP queue endpoint for LocalStack-style tests.
136    pub fn allow_http_for_local_development(mut self) -> Self {
137        self.allow_http_local = true;
138        self
139    }
140
141    /// Returns the configured queue URL.
142    pub fn queue_url(&self) -> &str {
143        &self.queue_url
144    }
145
146    /// Validates SQS service limits and TLS before client creation.
147    pub fn validate(&self) -> Result<()> {
148        if self.queue_url.trim().is_empty() {
149            return Err(SqsError::Configuration {
150                message: "SQS queue_url cannot be empty",
151            });
152        }
153        if !(0..=20).contains(&self.wait_time_seconds)
154            || !(0..=43_200).contains(&self.visibility_timeout_seconds)
155            || !(1..=10).contains(&self.max_messages)
156            || self.max_in_flight == 0
157            || self.max_in_flight > MAX_IN_FLIGHT
158            || self.shutdown_timeout.is_zero()
159        {
160            return Err(SqsError::Configuration {
161                message: "SQS polling, visibility, batch, or concurrency bounds are invalid",
162            });
163        }
164        if self.queue_url.starts_with("http://") && !self.allow_http_local {
165            return Err(SqsError::Configuration {
166                message: "HTTP SQS endpoints require an explicit local-development opt-in",
167            });
168        }
169        if self.queue_url.starts_with("http://") && !sqs_url_is_loopback(&self.queue_url) {
170            return Err(SqsError::Configuration {
171                message: "HTTP SQS endpoints are restricted to loopback",
172            });
173        }
174        if !self.queue_url.starts_with("https://") && !self.queue_url.starts_with("http://") {
175            return Err(SqsError::Configuration {
176                message: "SQS queue URLs must use HTTPS or explicit loopback HTTP",
177            });
178        }
179        Ok(())
180    }
181}
182
183fn sqs_url_is_loopback(url: &str) -> bool {
184    url::Url::parse(url).ok().is_some_and(|url| {
185        url.scheme() == "http"
186            && match url.host() {
187                Some(url::Host::Domain(host)) => host.eq_ignore_ascii_case("localhost"),
188                Some(url::Host::Ipv4(host)) => host.is_loopback(),
189                Some(url::Host::Ipv6(host)) => host.is_loopback(),
190                None => false,
191            }
192    })
193}
194
195impl fmt::Debug for SqsConfig {
196    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
197        formatter
198            .debug_struct("SqsConfig")
199            .field("queue_url", &"<redacted>")
200            .field("wait_time_seconds", &self.wait_time_seconds)
201            .field(
202                "visibility_timeout_seconds",
203                &self.visibility_timeout_seconds,
204            )
205            .field("max_messages", &self.max_messages)
206            .field("max_in_flight", &self.max_in_flight)
207            .field("shutdown_timeout", &self.shutdown_timeout)
208            .field("allow_http_local", &self.allow_http_local)
209            .finish()
210    }
211}
212
213/// Successful SQS send identifiers.
214#[derive(Clone, Debug, Eq, PartialEq)]
215pub struct SqsSendReceipt {
216    message_id: Option<String>,
217    sequence_number: Option<String>,
218}
219
220impl SqsSendReceipt {
221    /// Returns the AWS-assigned message id, when provided.
222    pub fn message_id(&self) -> Option<&str> {
223        self.message_id.as_deref()
224    }
225
226    /// Returns the FIFO sequence number, when provided.
227    pub fn sequence_number(&self) -> Option<&str> {
228        self.sequence_number.as_deref()
229    }
230}
231
232/// Builder for an SQS provider using either an injected or environment client.
233#[derive(Clone)]
234pub struct SqsProviderBuilder {
235    config: SqsConfig,
236    client: Option<aws_sdk_sqs::Client>,
237    telemetry: IntegrationTelemetry,
238}
239
240impl SqsProviderBuilder {
241    /// Creates a builder using the standard AWS credential and region chain.
242    pub fn new(config: SqsConfig) -> Self {
243        Self {
244            config,
245            client: None,
246            telemetry: IntegrationTelemetry::new(),
247        }
248    }
249
250    /// Creates a builder with an existing official AWS SDK client.
251    pub fn from_client(config: SqsConfig, client: aws_sdk_sqs::Client) -> Self {
252        Self {
253            config,
254            client: Some(client),
255            telemetry: IntegrationTelemetry::new(),
256        }
257    }
258
259    /// Adds shared tracing, metrics, dashboard, or custom telemetry.
260    pub fn telemetry(mut self, telemetry: IntegrationTelemetry) -> Self {
261        self.telemetry = telemetry;
262        self
263    }
264
265    /// Loads AWS configuration when needed and creates the provider.
266    pub async fn connect(self) -> Result<SqsProvider> {
267        self.config.validate()?;
268        let client = match self.client {
269            Some(client) => client,
270            None => {
271                let sdk_config =
272                    aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
273                aws_sdk_sqs::Client::new(&sdk_config)
274            }
275        };
276        Ok(SqsProvider {
277            in_flight: Arc::new(Semaphore::new(self.config.max_in_flight)),
278            max_in_flight: self.config.max_in_flight as u32,
279            shutting_down: Arc::new(AtomicBool::new(false)),
280            shutdown_complete: Arc::new(AtomicBool::new(false)),
281            config: self.config,
282            client,
283            telemetry: self.telemetry,
284        })
285    }
286
287    /// Creates and registers the provider as a Nidus singleton.
288    pub async fn register(self, container: &mut Container) -> Result<()> {
289        container.register_singleton(self.connect().await?)?;
290        Ok(())
291    }
292}
293
294impl fmt::Debug for SqsProviderBuilder {
295    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
296        formatter
297            .debug_struct("SqsProviderBuilder")
298            .field("config", &self.config)
299            .field("client", &self.client.as_ref().map(|_| "injected"))
300            .field("telemetry", &self.telemetry)
301            .finish()
302    }
303}
304
305/// Nidus provider exposing the official AWS SQS SDK client.
306#[derive(Clone)]
307pub struct SqsProvider {
308    config: SqsConfig,
309    client: aws_sdk_sqs::Client,
310    in_flight: Arc<Semaphore>,
311    max_in_flight: u32,
312    shutting_down: Arc<AtomicBool>,
313    shutdown_complete: Arc<AtomicBool>,
314    telemetry: IntegrationTelemetry,
315}
316
317impl SqsProvider {
318    /// Creates an SQS provider builder using the AWS environment chain.
319    pub fn builder(config: SqsConfig) -> SqsProviderBuilder {
320        SqsProviderBuilder::new(config)
321    }
322
323    /// Creates an SQS provider builder with an existing native client.
324    pub fn builder_with_client(
325        config: SqsConfig,
326        client: aws_sdk_sqs::Client,
327    ) -> SqsProviderBuilder {
328        SqsProviderBuilder::from_client(config, client)
329    }
330
331    /// Returns the native official AWS SQS client.
332    pub fn client(&self) -> &aws_sdk_sqs::Client {
333        &self.client
334    }
335
336    /// Sends a standard-queue UTF-8 message.
337    pub async fn send(&self, body: impl Into<String>) -> Result<SqsSendReceipt> {
338        self.send_inner(body.into(), None, None).await
339    }
340
341    /// Sends a FIFO message with explicit group and deduplication ids.
342    pub async fn send_fifo(
343        &self,
344        body: impl Into<String>,
345        message_group_id: impl Into<String>,
346        deduplication_id: impl Into<String>,
347    ) -> Result<SqsSendReceipt> {
348        self.send_inner(
349            body.into(),
350            Some(message_group_id.into()),
351            Some(deduplication_id.into()),
352        )
353        .await
354    }
355
356    /// Sends a bounded shared envelope to a standard queue.
357    pub async fn send_envelope<T>(&self, envelope: &MessageEnvelope<T>) -> Result<SqsSendReceipt>
358    where
359        T: Serialize,
360    {
361        let body = String::from_utf8(envelope.to_json()?).map_err(|_| SqsError::InvalidUtf8)?;
362        self.send(body).await
363    }
364
365    /// Long-polls and returns native AWS SDK message values.
366    ///
367    /// Messages remain in flight until [`Self::delete`] succeeds or their
368    /// visibility timeout expires. Duplicate delivery remains possible.
369    pub async fn receive(&self) -> Result<Vec<Message>> {
370        let _permit = self.acquire_permit().await?;
371        let started_at = Instant::now();
372        let output = self
373            .client
374            .receive_message()
375            .queue_url(&self.config.queue_url)
376            .wait_time_seconds(self.config.wait_time_seconds)
377            .visibility_timeout(self.config.visibility_timeout_seconds)
378            .max_number_of_messages(self.config.max_messages)
379            .send()
380            .await
381            .map_err(sdk_error);
382        self.record("receive", output.is_ok(), started_at).await;
383        Ok(output?.messages().to_vec())
384    }
385
386    /// Deletes a successfully processed message by receipt handle.
387    pub async fn delete(&self, receipt_handle: &str) -> Result<()> {
388        if receipt_handle.is_empty() {
389            return Err(SqsError::Configuration {
390                message: "SQS receipt_handle cannot be empty",
391            });
392        }
393        let _permit = self.acquire_permit().await?;
394        let started_at = Instant::now();
395        let result = self
396            .client
397            .delete_message()
398            .queue_url(&self.config.queue_url)
399            .receipt_handle(receipt_handle)
400            .send()
401            .await
402            .map_err(sdk_error);
403        self.record("delete", result.is_ok(), started_at).await;
404        result?;
405        Ok(())
406    }
407
408    /// Extends or terminates a message visibility lease.
409    pub async fn change_visibility(
410        &self,
411        receipt_handle: &str,
412        visibility_timeout_seconds: i32,
413    ) -> Result<()> {
414        if receipt_handle.is_empty() || !(0..=43_200).contains(&visibility_timeout_seconds) {
415            return Err(SqsError::Configuration {
416                message: "SQS receipt handle or visibility timeout is invalid",
417            });
418        }
419        let _permit = self.acquire_permit().await?;
420        let started_at = Instant::now();
421        let result = self
422            .client
423            .change_message_visibility()
424            .queue_url(&self.config.queue_url)
425            .receipt_handle(receipt_handle)
426            .visibility_timeout(visibility_timeout_seconds)
427            .send()
428            .await
429            .map_err(sdk_error);
430        self.record("change_visibility", result.is_ok(), started_at)
431            .await;
432        result?;
433        Ok(())
434    }
435
436    /// Checks queue access with `GetQueueAttributes`.
437    #[cfg(feature = "health")]
438    pub async fn health_status(&self) -> nidus_http::health::HealthStatus {
439        let Ok(_permit) = self.acquire_permit().await else {
440            return nidus_http::health::HealthStatus::down("sqs provider is shutting down");
441        };
442        let started_at = Instant::now();
443        let result = self
444            .client
445            .get_queue_attributes()
446            .queue_url(&self.config.queue_url)
447            .attribute_names(QueueAttributeName::QueueArn)
448            .send()
449            .await;
450        self.record("health", result.is_ok(), started_at).await;
451        if result.is_ok() {
452            nidus_http::health::HealthStatus::up()
453        } else {
454            nidus_http::health::HealthStatus::down("sqs queue check failed")
455        }
456    }
457
458    /// Adds this provider as a readiness check on a health registry.
459    #[cfg(feature = "health")]
460    pub fn register_ready_check(
461        self: Arc<Self>,
462        registry: nidus_http::health::HealthRegistry,
463        name: impl Into<String>,
464    ) -> nidus_http::health::HealthRegistry {
465        registry.ready_check(name, move || {
466            let provider = Arc::clone(&self);
467            async move { provider.health_status().await }
468        })
469    }
470
471    /// Stops new adapter-owned work and waits for admitted AWS requests.
472    ///
473    /// The official SDK client has no transport close handshake; injected
474    /// native client clones remain under application ownership.
475    pub async fn shutdown(&self) -> Result<()> {
476        if self.shutdown_complete.load(Ordering::Acquire) {
477            return Ok(());
478        }
479        self.shutting_down.store(true, Ordering::Release);
480        let started_at = Instant::now();
481        let result = match tokio::time::timeout(
482            self.config.shutdown_timeout,
483            self.in_flight.acquire_many(self.max_in_flight),
484        )
485        .await
486        {
487            Ok(Ok(drained)) => {
488                self.shutdown_complete.store(true, Ordering::Release);
489                self.in_flight.close();
490                drop(drained);
491                Ok(())
492            }
493            Ok(Err(_)) => Err(SqsError::ShuttingDown),
494            Err(_) => Err(SqsError::ShutdownTimeout),
495        };
496        self.record("shutdown", result.is_ok(), started_at).await;
497        result
498    }
499
500    async fn send_inner(
501        &self,
502        body: String,
503        message_group_id: Option<String>,
504        deduplication_id: Option<String>,
505    ) -> Result<SqsSendReceipt> {
506        if body.len() > MAX_MESSAGE_BYTES {
507            return Err(SqsError::MessageTooLarge {
508                actual: body.len(),
509                maximum: MAX_MESSAGE_BYTES,
510            });
511        }
512        let _permit = self.acquire_permit().await?;
513        let started_at = Instant::now();
514        let output = self
515            .client
516            .send_message()
517            .queue_url(&self.config.queue_url)
518            .message_body(body)
519            .set_message_group_id(message_group_id)
520            .set_message_deduplication_id(deduplication_id)
521            .send()
522            .await
523            .map_err(sdk_error);
524        self.record("send", output.is_ok(), started_at).await;
525        let output = output?;
526        Ok(SqsSendReceipt {
527            message_id: output.message_id().map(str::to_owned),
528            sequence_number: output.sequence_number().map(str::to_owned),
529        })
530    }
531
532    async fn record(&self, operation: &'static str, success: bool, started_at: Instant) {
533        self.telemetry
534            .record(&IntegrationEvent::new(
535                "nidus-sqs",
536                operation,
537                if success {
538                    IntegrationStatus::Success
539                } else {
540                    IntegrationStatus::Failure
541                },
542                started_at.elapsed(),
543            ))
544            .await;
545    }
546
547    async fn acquire_permit(&self) -> Result<SemaphorePermit<'_>> {
548        if self.shutting_down.load(Ordering::Acquire) {
549            return Err(SqsError::ShuttingDown);
550        }
551        let permit = self
552            .in_flight
553            .acquire()
554            .await
555            .map_err(|_| SqsError::ShuttingDown)?;
556        if self.shutting_down.load(Ordering::Acquire) {
557            return Err(SqsError::ShuttingDown);
558        }
559        Ok(permit)
560    }
561}
562
563impl fmt::Debug for SqsProvider {
564    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
565        formatter
566            .debug_struct("SqsProvider")
567            .field("config", &self.config)
568            .field("client", &"aws_sdk_sqs::Client")
569            .field("shutting_down", &self.shutting_down.load(Ordering::Acquire))
570            .field("available_permits", &self.in_flight.available_permits())
571            .field("telemetry", &self.telemetry)
572            .finish()
573    }
574}
575
576#[async_trait]
577impl LifecycleHook for SqsProvider {
578    async fn on_shutdown(&self) -> nidus_core::Result<()> {
579        self.shutdown()
580            .await
581            .map_err(|_| NidusError::ApplicationBuild {
582                message: "SQS requests failed to drain during shutdown".to_owned(),
583            })
584    }
585}
586
587fn sdk_error(error: impl Into<aws_sdk_sqs::Error>) -> SqsError {
588    SqsError::Sdk {
589        source: Box::new(error.into()),
590    }
591}