1#![forbid(unsafe_code)]
2#![deny(missing_docs)]
3
4use 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
35pub type Result<T> = std::result::Result<T, SqsError>;
37
38#[derive(Debug, Error)]
40pub enum SqsError {
41 #[error("AWS SQS operation failed: {source}")]
43 Sdk {
44 #[source]
46 source: Box<aws_sdk_sqs::Error>,
47 },
48 #[error(transparent)]
50 Integration(#[from] nidus_integrations::IntegrationError),
51 #[error(transparent)]
53 Nidus(#[from] NidusError),
54 #[error("invalid SQS configuration: {message}")]
56 Configuration {
57 message: &'static str,
59 },
60 #[error("SQS message is {actual} bytes, exceeding the {maximum}-byte limit")]
62 MessageTooLarge {
63 actual: usize,
65 maximum: usize,
67 },
68 #[error("SQS envelope encoding was not UTF-8")]
70 InvalidUtf8,
71 #[error("SQS provider is shutting down")]
73 ShuttingDown,
74 #[error("SQS shutdown exceeded its configured timeout")]
76 ShutdownTimeout,
77}
78
79#[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 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 pub fn with_wait_time_seconds(mut self, value: i32) -> Self {
107 self.wait_time_seconds = value;
108 self
109 }
110
111 pub fn with_visibility_timeout_seconds(mut self, value: i32) -> Self {
113 self.visibility_timeout_seconds = value;
114 self
115 }
116
117 pub fn with_max_messages(mut self, value: i32) -> Self {
119 self.max_messages = value;
120 self
121 }
122
123 pub fn with_max_in_flight(mut self, value: usize) -> Self {
125 self.max_in_flight = value;
126 self
127 }
128
129 pub fn with_shutdown_timeout(mut self, value: Duration) -> Self {
131 self.shutdown_timeout = value;
132 self
133 }
134
135 pub fn allow_http_for_local_development(mut self) -> Self {
137 self.allow_http_local = true;
138 self
139 }
140
141 pub fn queue_url(&self) -> &str {
143 &self.queue_url
144 }
145
146 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#[derive(Clone, Debug, Eq, PartialEq)]
215pub struct SqsSendReceipt {
216 message_id: Option<String>,
217 sequence_number: Option<String>,
218}
219
220impl SqsSendReceipt {
221 pub fn message_id(&self) -> Option<&str> {
223 self.message_id.as_deref()
224 }
225
226 pub fn sequence_number(&self) -> Option<&str> {
228 self.sequence_number.as_deref()
229 }
230}
231
232#[derive(Clone)]
234pub struct SqsProviderBuilder {
235 config: SqsConfig,
236 client: Option<aws_sdk_sqs::Client>,
237 telemetry: IntegrationTelemetry,
238}
239
240impl SqsProviderBuilder {
241 pub fn new(config: SqsConfig) -> Self {
243 Self {
244 config,
245 client: None,
246 telemetry: IntegrationTelemetry::new(),
247 }
248 }
249
250 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 pub fn telemetry(mut self, telemetry: IntegrationTelemetry) -> Self {
261 self.telemetry = telemetry;
262 self
263 }
264
265 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 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#[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 pub fn builder(config: SqsConfig) -> SqsProviderBuilder {
320 SqsProviderBuilder::new(config)
321 }
322
323 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 pub fn client(&self) -> &aws_sdk_sqs::Client {
333 &self.client
334 }
335
336 pub async fn send(&self, body: impl Into<String>) -> Result<SqsSendReceipt> {
338 self.send_inner(body.into(), None, None).await
339 }
340
341 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 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 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 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 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 #[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 #[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 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}