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 exception;
118pub mod executor;
119pub mod rate_limit;
120pub mod result;
121pub mod retry;
122pub mod revocation;
123pub mod router;
124pub mod state;
125pub mod task;
126pub mod time_limit;
127
128pub use broker::{Broker, BrokerMessage};
129pub use config::{
130    BackendTransport, BeatSchedule, BrokerTransport, CeleryConfig, ScheduleDefinition, TaskConfig,
131    TaskRoute,
132};
133pub use control::{
134    ActiveTaskInfo, BrokerStats, ControlCommand, ControlResponse, DeliveryInfo, InspectCommand,
135    InspectResponse, PoolStats, QueueCommand, QueueResponse, QueueStats, RequestInfo,
136    ReservedTaskInfo, ScheduledTaskInfo, WorkerConf, WorkerReport, WorkerStats,
137};
138pub use dag::{DagNode, TaskDag};
139pub use error::{CelersError, Result};
140pub use event::{
141    Alert, AlertCondition, AlertContext, AlertHandler, AlertManager, AlertSeverity,
142    CompositeEventEmitter, Event, EventDispatcher, EventEmitter, EventFilter, EventMonitor,
143    EventReceiver, EventStats, EventStorage, EventStream, FileEventStorage, InMemoryEventEmitter,
144    InMemoryEventStorage, LogLevel, LoggingAlertHandler, LoggingEventEmitter, NoOpEventEmitter,
145    TaskEvent, TaskEventBuilder, WorkerEvent, WorkerEventBuilder,
146};
147pub use exception::{
148    ExceptionAction, ExceptionCategory, ExceptionHandler, ExceptionHandlerChain, ExceptionPolicy,
149    LoggingExceptionHandler, PolicyExceptionHandler, TaskException, TracebackFrame,
150};
151pub use executor::TaskRegistry;
152pub use rate_limit::{
153    create_rate_limiter, DistributedRateLimiter, DistributedRateLimiterCoordinator,
154    DistributedRateLimiterState, DistributedSlidingWindowSpec, DistributedTokenBucketSpec,
155    RateLimitConfig, RateLimiter, SlidingWindow, TaskRateLimiter, TokenBucket, WorkerRateLimiter,
156};
157pub use result::{
158    AsyncResult, ExtendedResultStore, ResultChunk, ResultChunker, ResultCompressor, ResultMetadata,
159    ResultStore, ResultTombstone, TaskResultValue,
160};
161pub use retry::{RetryPolicy, RetryStrategy};
162pub use revocation::{
163    PatternRevocation, RevocationManager, RevocationMode, RevocationRequest, RevocationResult,
164    RevocationState, WorkerRevocationManager,
165};
166pub use router::{
167    ArgumentCondition, GlobPattern, PatternMatcher, RegexPattern, RouteResult, RouteRule, Router,
168    RouterBuilder, RoutingConfig,
169};
170pub use state::{StateHistory, StateTransition, TaskState};
171pub use task::{SerializedTask, Task, TaskId, TaskMetadata};
172pub use time_limit::{
173    TaskTimeLimits, TimeLimit, TimeLimitConfig, TimeLimitExceeded, TimeLimitSettings,
174    TimeLimitStatus, WorkerTimeLimits,
175};
celers_core/lib.rs

celers_core/
lib.rs
