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

foxtive_worker/
lib.rs
