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 error;
54pub mod message;
55pub mod worker;
56pub mod pool;
57pub mod strategies;
58pub mod builder;
59pub mod backends;
60pub mod middleware;
61pub mod metrics;
62pub mod health;
63pub mod dlq;
64pub mod batch;
65pub mod batch_processor;
66pub mod http;
67pub mod stress;
68
69// Re-exports for convenience
70pub use crate::error::{WorkerError, WorkerResult};
71pub use crate::message::{AckHandle, Message, MessageMetadata, ReceivedMessage};
72pub use crate::worker::{BackoffStrategy, Worker};
73pub use crate::pool::WorkerPool;
74pub use crate::strategies::LoadBalancingStrategy;
75pub use crate::builder::WorkerPoolBuilder;
76pub use crate::backends::{MessageBackend, MemoryBackend};
77
78// Re-export resilient backend for all configurations
79pub use crate::backends::{ResilientBackend, ResilientBackendBuilder, ReconnectStrategy};
80
81#[cfg(feature = "rabbitmq")]
82pub use crate::backends::{RabbitMqBackend, RabbitMqConsumerConfig};
83
84#[cfg(feature = "redis-stream")]
85pub use crate::backends::{RedisStreamBackend, RedisStreamConsumerConfig};
86
87pub use crate::middleware::{
88    Middleware, MessageHandler, MiddlewareChain,
89    ack_nack::AckNackMiddleware,
90    circuit_breaker::CircuitBreakerMiddleware,
91    tracing::TracingMiddleware,
92    retry_handler::RetryHandler,
93    batch::BatchMiddleware,
94    processing_timeout::ProcessingTimeoutMiddleware,
95};
96
97#[cfg(feature = "rate-limit")]
98pub use crate::middleware::rate_limit::RateLimitMiddleware;
99
100#[cfg(feature = "metrics")]
101pub use crate::metrics::MetricsCollector;
102#[cfg(not(feature = "metrics"))]
103pub use crate::metrics::NoOpMetrics as MetricsCollector;
104
105pub use crate::health::{HealthCheck, HealthStatus, WorkerPoolHealth, WorkerHealth};
106pub use crate::dlq::{DeadLetterMessage, PoisonPillConfig, PoisonPillTracker};
107pub use crate::batch::{BatchHandler, BatchConfig, MessageBatch, ReceivedBatchMessage, BatchMetadata, BatchStatus};
108pub use crate::batch_processor::BatchProcessor;
109
110/// Common types and traits used throughout the crate.
111pub mod prelude {
112    pub use crate::error::{WorkerError, WorkerResult};
113    pub use crate::message::{AckHandle, Message, MessageMetadata, ReceivedMessage, ReceivedJsonMessage};
114    pub use crate::worker::{BackoffStrategy, Worker};
115    pub use crate::pool::WorkerPool;
116    pub use crate::strategies::LoadBalancingStrategy;
117    pub use crate::builder::WorkerPoolBuilder;
118    pub use crate::backends::{MessageBackend, MemoryBackend};
119    pub use crate::backends::ReceiveResult;
120    pub use crate::backends::{ResilientBackend, ResilientBackendBuilder, ReconnectStrategy};
121    
122    #[cfg(feature = "rabbitmq")]
123    pub use crate::backends::{RabbitMqBackend, RabbitMqConsumerConfig};
124    
125    #[cfg(feature = "redis-stream")]
126    pub use crate::backends::{RedisStreamBackend, RedisStreamConsumerConfig};
127    
128    pub use crate::middleware::{Middleware, MessageHandler, MiddlewareChain};
129    pub use crate::middleware::ack_nack::AckNackMiddleware;
130    #[cfg(feature = "rate-limit")]
131    pub use crate::middleware::rate_limit::RateLimitMiddleware;
132    pub use crate::middleware::circuit_breaker::CircuitBreakerMiddleware;
133    pub use crate::middleware::tracing::TracingMiddleware;
134    pub use crate::middleware::retry_handler::RetryHandler;
135    pub use crate::middleware::processing_timeout::ProcessingTimeoutMiddleware;
136
137    pub use crate::metrics::WorkerMetrics;
138    #[cfg(feature = "metrics")]
139    pub use crate::metrics::MetricsCollector;
140    #[cfg(not(feature = "metrics"))]
141    pub use crate::metrics::NoOpMetrics as MetricsCollector;
142
143    pub use crate::health::{HealthCheck, HealthStatus, WorkerPoolHealth, WorkerHealth};
144}
foxtive_worker/lib.rs

foxtive_worker/
lib.rs
