foxtive_worker/
lib.rs

1//! # Foxtive Worker
2//!
3//! A background worker framework for message processing, event-driven architectures,
4//! and long-running background tasks.
5//!
6//! ## Overview
7//!
8//! Foxtive Worker provides a robust foundation for building message-processing workers
9//! with features like:
10//! - Manual message acknowledgment (ack/nack)
11//! - Multiple backend support (RabbitMQ, Redis Streams, in-memory)
12//! - Worker pools with load balancing
13//! - Composable middleware pipeline
14//! - Comprehensive observability and metrics
15//! - HTTP health endpoints for Kubernetes integration
16//!
17//! ## Quick Start
18//!
19//! ```rust,no_run
20//! use foxtive_worker::{Worker, ReceivedMessage};
21//! use foxtive_worker::error::WorkerResult;
22//! use async_trait::async_trait;
23//!
24//! struct MyWorker;
25//!
26//! #[async_trait]
27//! impl Worker for MyWorker {
28//!     fn id(&self) -> &str { "my-worker" }
29//!     
30//!     async fn process(&self, message: ReceivedMessage<serde_json::Value>) -> WorkerResult<()> {
31//!         println!("Processing: {}", message.message.id);
32//!         // Your processing logic here
33//!         message.ack().await?;
34//!         Ok(())
35//!     }
36//! }
37//! ```
38//!
39//! ## Core Concepts
40//!
41//! ### Message Abstraction
42//!
43//! Messages are separated into pure data (`Message<T>`) and acknowledgment capability
44//! (`AckHandle`), combined in `ReceivedMessage<T>` for safe concurrent processing.
45//!
46//! ### Two-Level Backoff System
47//!
48//! - **Worker Restart Backoff**: Controls worker restart after crashes (via `Worker::restart_backoff_strategy()`)
49//! - **Message Retry Backoff**: Controls retry delays for failed messages (via RetryHandler middleware)
50//!
51//! These are independent strategies serving different purposes.
52
53pub mod backends;
54pub mod batch;
55pub mod batch_processor;
56pub mod builder;
57pub mod dlq;
58pub mod error;
59pub mod health;
60pub mod http;
61pub mod message;
62mod message_properties;
63pub mod metrics;
64pub mod middleware;
65pub mod pool;
66pub mod strategies;
67pub mod stress;
68pub mod worker;
69
70// Re-exports for convenience
71pub use crate::backends::{MemoryBackend, MessageBackend};
72pub use crate::builder::WorkerPoolBuilder;
73pub use crate::error::{WorkerError, WorkerResult};
74pub use crate::message::{AckHandle, Message, MessageMetadata, ReceivedMessage};
75pub use crate::message_properties::MessageProperties;
76pub use crate::pool::WorkerPool;
77pub use crate::strategies::LoadBalancingStrategy;
78pub use crate::worker::{BackoffStrategy, Worker};
79
80// Re-export resilient backend for all configurations
81pub use crate::backends::{ReconnectStrategy, ResilientBackend, ResilientBackendBuilder};
82
83#[cfg(feature = "rabbitmq")]
84pub use crate::backends::{RabbitMqBackend, RabbitMqConsumerConfig};
85
86#[cfg(feature = "redis-stream")]
87pub use crate::backends::{RedisStreamBackend, RedisStreamConsumerConfig};
88
89pub use crate::middleware::{
90    MessageHandler, Middleware, MiddlewareChain, MiddlewareResult, ack_nack::AckNackMiddleware,
91    batch::BatchMiddleware, circuit_breaker::CircuitBreakerMiddleware,
92    processing_timeout::ProcessingTimeoutMiddleware, retry_handler::RetryHandler,
93    tracing::TracingMiddleware,
94};
95
96#[cfg(feature = "rate-limit")]
97pub use crate::middleware::rate_limit::RateLimitMiddleware;
98
99#[cfg(feature = "metrics")]
100pub use crate::metrics::MetricsCollector;
101#[cfg(not(feature = "metrics"))]
102pub use crate::metrics::NoOpMetrics as MetricsCollector;
103
104pub use crate::batch::{
105    BatchConfig, BatchHandler, BatchMetadata, BatchStatus, MessageBatch, ReceivedBatchMessage,
106};
107pub use crate::batch_processor::BatchProcessor;
108pub use crate::dlq::{DeadLetterMessage, PoisonPillConfig, PoisonPillTracker};
109pub use crate::health::{HealthCheck, HealthStatus, WorkerHealth, WorkerPoolHealth};
110
111/// Common types and traits used throughout the crate.
112pub mod prelude {
113    pub use crate::backends::ReceiveResult;
114    pub use crate::backends::{MemoryBackend, MessageBackend};
115    pub use crate::backends::{ReconnectStrategy, ResilientBackend, ResilientBackendBuilder};
116    pub use crate::builder::WorkerPoolBuilder;
117    pub use crate::error::{WorkerError, WorkerResult};
118    pub use crate::message::{
119        AckHandle, Message, MessageMetadata, ReceivedJsonMessage, ReceivedMessage,
120    };
121    pub use crate::message_properties::MessageProperties;
122    pub use crate::pool::WorkerPool;
123    pub use crate::strategies::LoadBalancingStrategy;
124    pub use crate::worker::{BackoffStrategy, Worker};
125
126    #[cfg(feature = "rabbitmq")]
127    pub use crate::backends::{RabbitMqBackend, RabbitMqConsumerConfig};
128
129    #[cfg(feature = "redis-stream")]
130    pub use crate::backends::{RedisStreamBackend, RedisStreamConsumerConfig};
131
132    pub use crate::middleware::ack_nack::AckNackMiddleware;
133    pub use crate::middleware::circuit_breaker::CircuitBreakerMiddleware;
134    pub use crate::middleware::processing_timeout::ProcessingTimeoutMiddleware;
135    #[cfg(feature = "rate-limit")]
136    pub use crate::middleware::rate_limit::RateLimitMiddleware;
137    pub use crate::middleware::retry_handler::RetryHandler;
138    pub use crate::middleware::tracing::TracingMiddleware;
139    pub use crate::middleware::{MessageHandler, Middleware, MiddlewareChain, MiddlewareResult};
140
141    #[cfg(feature = "metrics")]
142    pub use crate::metrics::MetricsCollector;
143    #[cfg(not(feature = "metrics"))]
144    pub use crate::metrics::NoOpMetrics as MetricsCollector;
145    pub use crate::metrics::WorkerMetrics;
146
147    pub use crate::health::{HealthCheck, HealthStatus, WorkerHealth, WorkerPoolHealth};
148}
foxtive_worker/lib.rs

foxtive_worker/
lib.rs
