celers_core/lib.rs
1//! `CeleRS` Core - Type-safe distributed task queue library
2//!
3//! This crate provides the core abstractions and types for building
4//! distributed task processing systems in Rust.
5//!
6//! # Quick Start
7//!
8//! ## Basic Task Creation
9//!
10//! ```rust
11//! use celers_core::{SerializedTask, TaskMetadata, TaskState};
12//!
13//! // Create a simple task
14//! let task = SerializedTask::new("process_data".to_string(), vec![1, 2, 3, 4, 5])
15//! .with_priority(5)
16//! .with_max_retries(3)
17//! .with_timeout(60);
18//!
19//! assert_eq!(task.metadata.state, TaskState::Pending);
20//! assert!(task.has_priority());
21//! ```
22//!
23//! ## Task Dependencies and Workflows
24//!
25//! ```rust
26//! use celers_core::{TaskDag, TaskId, SerializedTask};
27//! use uuid::Uuid;
28//!
29//! // Create a DAG for task dependencies
30//! let mut dag = TaskDag::new();
31//!
32//! let load_task = Uuid::new_v4();
33//! let transform_task = Uuid::new_v4();
34//! let save_task = Uuid::new_v4();
35//!
36//! dag.add_node(load_task, "load_data");
37//! dag.add_node(transform_task, "transform_data");
38//! dag.add_node(save_task, "save_results");
39//!
40//! // Define dependencies: transform depends on load, save depends on transform
41//! dag.add_dependency(transform_task, load_task).unwrap();
42//! dag.add_dependency(save_task, transform_task).unwrap();
43//!
44//! // Validate DAG (no cycles)
45//! assert!(dag.validate().is_ok());
46//!
47//! // Get execution order
48//! let order = dag.topological_sort().unwrap();
49//! assert_eq!(order, vec![load_task, transform_task, save_task]);
50//! ```
51//!
52//! ## Retry Strategies
53//!
54//! ```rust
55//! use celers_core::RetryStrategy;
56//!
57//! // Exponential backoff
58//! let strategy = RetryStrategy::exponential(1000, 2.0); // 1s initial, 2x multiplier
59//!
60//! assert_eq!(strategy.calculate_delay(0, None), 1000); // 1s
61//! assert_eq!(strategy.calculate_delay(1, Some(1000)), 2000); // 2s
62//! assert_eq!(strategy.calculate_delay(2, Some(2000)), 4000); // 4s
63//!
64//! // Fixed delay retry strategy
65//! let fixed = RetryStrategy::fixed(5000); // 5 seconds
66//! assert_eq!(fixed.calculate_delay(0, None), 5000);
67//! assert_eq!(fixed.calculate_delay(10, Some(5000)), 5000);
68//! ```
69//!
70//! ## State Tracking
71//!
72//! ```rust
73//! use celers_core::{StateHistory, TaskState};
74//!
75//! let mut history = StateHistory::with_initial(TaskState::Pending);
76//!
77//! // Track state transitions
78//! history.transition(TaskState::Running);
79//! history.transition(TaskState::Succeeded(vec![1, 2, 3]));
80//!
81//! assert_eq!(history.transition_count(), 2);
82//! assert!(history.current_state().unwrap().is_terminal());
83//! ```
84//!
85//! ## Exception Handling
86//!
87//! ```rust
88//! use celers_core::{TaskException, ExceptionCategory, ExceptionPolicy};
89//!
90//! // Create an exception policy
91//! let policy = ExceptionPolicy::new()
92//! .retry_on(&["Temporary*", "Network*"])
93//! .fail_on(&["Fatal*", "Critical*"])
94//! .ignore_on(&["Ignorable*"]);
95//!
96//! // Build an exception
97//! let exception = TaskException::new("TemporaryError", "Connection timeout")
98//! .with_category(ExceptionCategory::Retryable);
99//! ```
100//!
101//! # Core Concepts
102//!
103//! - **Tasks**: Units of work that can be executed asynchronously
104//! - **Brokers**: Message queue backends for task distribution
105//! - **States**: Task lifecycle state machine (Pending → Running → Success/Failure)
106//! - **Dependencies**: DAG-based task dependency management
107//! - **Retries**: Flexible retry strategies with backoff
108//! - **Routing**: Pattern-based task routing to queues
109//! - **Rate Limiting**: Token bucket and sliding window algorithms
110
111pub mod broker;
112pub mod config;
113pub mod control;
114pub mod dag;
115pub mod error;
116pub mod event;
117pub mod event_filter;
118pub mod event_persistence;
119pub mod exception;
120pub mod executor;
121pub mod lock;
122pub mod rate_limit;
123pub mod result;
124pub mod retry;
125pub mod revocation;
126pub mod router;
127pub mod state;
128pub mod task;
129pub mod time_limit;
130
131pub use broker::{Broker, BrokerMessage};
132pub use config::{
133 BackendTransport, BeatSchedule, BrokerTransport, CeleryConfig, ConfigError, ConfigValidation,
134 ConfigWarning, ScheduleDefinition, TaskConfig, TaskRoute,
135};
136pub use control::{
137 ActiveTaskInfo, BrokerStats, ControlCommand, ControlResponse, DeliveryInfo, InspectCommand,
138 InspectResponse, PoolStats, QueueCommand, QueueResponse, QueueStats, RequestInfo,
139 ReservedTaskInfo, ScheduledTaskInfo, WorkerConf, WorkerReport, WorkerStats,
140};
141pub use dag::{DagNode, TaskDag};
142pub use error::{CelersError, Result};
143pub use event::{
144 Alert, AlertCondition, AlertContext, AlertHandler, AlertManager, AlertSeverity,
145 CompositeEventEmitter, Event, EventDispatcher, EventEmitter, EventFilter, EventMonitor,
146 EventReceiver, EventStats, EventStorage, EventStream, FileEventStorage, InMemoryEventEmitter,
147 InMemoryEventStorage, LogLevel, LoggingAlertHandler, LoggingEventEmitter, NoOpEventEmitter,
148 TaskEvent, TaskEventBuilder, WorkerEvent, WorkerEventBuilder,
149};
150pub use event_filter::{
151 CollectingEventHandler, CompositeEventFilter, EventFilterTrait, EventHandlerTrait, EventRouter,
152 ExactEventFilter, FilterMode, GlobEventFilter, LoggingEventHandler, PrefixEventFilter,
153};
154pub use event_persistence::{
155 EventPersister, FileEventPersister, FileEventPersisterConfig, RotationPolicy,
156};
157pub use exception::{
158 ExceptionAction, ExceptionCategory, ExceptionHandler, ExceptionHandlerChain, ExceptionPolicy,
159 LoggingExceptionHandler, PolicyExceptionHandler, TaskException, TracebackFrame,
160};
161pub use executor::TaskRegistry;
162pub use lock::DistributedLockBackend;
163pub use rate_limit::{
164 create_rate_limiter, DistributedRateLimiter, DistributedRateLimiterCoordinator,
165 DistributedRateLimiterState, DistributedSlidingWindowSpec, DistributedTokenBucketSpec,
166 RateLimitConfig, RateLimiter, SlidingWindow, TaskRateLimiter, TokenBucket, WorkerRateLimiter,
167};
168pub use result::{
169 AsyncResult, ExtendedResultStore, ResultChunk, ResultChunker, ResultCompressor, ResultMetadata,
170 ResultStore, ResultTombstone, TaskResultValue,
171};
172pub use retry::{RetryPolicy, RetryStrategy};
173pub use revocation::{
174 PatternRevocation, RevocationManager, RevocationMode, RevocationRequest, RevocationResult,
175 RevocationState, WorkerRevocationManager,
176};
177pub use router::{
178 ArgumentCondition, GlobPattern, PatternMatcher, RegexPattern, RouteResult, RouteRule, Router,
179 RouterBuilder, RoutingConfig,
180};
181pub use state::{StateHistory, StateTransition, TaskState};
182pub use task::{SerializedTask, Task, TaskId, TaskMetadata};
183pub use time_limit::{
184 TaskTimeLimits, TimeLimit, TimeLimitConfig, TimeLimitExceeded, TimeLimitSettings,
185 TimeLimitStatus, WorkerTimeLimits,
186};