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 alerting;
112pub mod broker;
113pub mod caching_backend;
114pub mod circuit_breaker_registry;
115pub mod config;
116pub mod control;
117pub mod dag;
118pub mod error;
119pub mod event;
120pub mod event_filter;
121pub mod event_persistence;
122pub mod exception;
123pub mod executor;
124pub mod in_memory_broker;
125pub mod lock;
126pub mod pii;
127pub mod rate_limit;
128pub mod rate_limit_distributed;
129pub mod result;
130pub mod result_groups;
131pub mod result_tombstone;
132pub mod result_ttl;
133pub mod retry;
134pub mod revocation;
135pub mod router;
136pub mod sanitize;
137pub mod state;
138pub mod task;
139pub mod task_signature;
140pub mod tenant_rate_limit;
141pub mod time_limit;
142
143pub use alerting::{
144    AlertEvaluator, AlertRule, AlertRuleKind, AlertStatus, EventSnapshot, EventSnapshotBuilder,
145    RuleAlert,
146};
147pub use broker::{Broker, BrokerMessage};
148pub use caching_backend::CachingResultBackend;
149pub use circuit_breaker_registry::{
150    CircuitBreaker, CircuitBreakerConfig, CircuitBreakerError, CircuitSnapshot, CircuitState,
151    TaskTypeCircuitBreakers,
152};
153pub use config::{
154    BackendTransport, BeatSchedule, BrokerTransport, CeleryConfig, ConfigError, ConfigValidation,
155    ConfigWarning, ScheduleDefinition, TaskConfig, TaskRoute,
156};
157pub use control::{
158    ActiveTaskInfo, BrokerStats, ControlCommand, ControlResponse, DeliveryInfo, InspectCommand,
159    InspectResponse, PoolStats, QueueCommand, QueueResponse, QueueStats, RequestInfo,
160    ReservedTaskInfo, ScheduledTaskInfo, WorkerConf, WorkerReport, WorkerStats,
161};
162pub use dag::{DagNode, TaskDag};
163pub use error::{CelersError, Result};
164pub use event::{
165    Alert, AlertCondition, AlertContext, AlertHandler, AlertManager, AlertSeverity,
166    CompositeEventEmitter, Event, EventDispatcher, EventEmitter, EventFilter, EventMonitor,
167    EventReceiver, EventStats, EventStorage, EventStream, FileEventStorage, InMemoryEventEmitter,
168    InMemoryEventStorage, LogLevel, LoggingAlertHandler, LoggingEventEmitter, NoOpEventEmitter,
169    TaskEvent, TaskEventBuilder, WorkerEvent, WorkerEventBuilder,
170};
171pub use event_filter::{
172    CollectingEventHandler, CompositeEventFilter, EventFilterTrait, EventHandlerTrait, EventRouter,
173    ExactEventFilter, FilterMode, GlobEventFilter, LoggingEventHandler, PrefixEventFilter,
174};
175pub use event_persistence::{
176    EventPersister, FileEventPersister, FileEventPersisterConfig, RotationPolicy,
177};
178pub use exception::{
179    ExceptionAction, ExceptionCategory, ExceptionHandler, ExceptionHandlerChain, ExceptionPolicy,
180    LoggingExceptionHandler, PolicyExceptionHandler, TaskException, TracebackFrame,
181};
182pub use executor::TaskRegistry;
183pub use in_memory_broker::{InMemoryBroker, InMemoryResultBackend};
184pub use lock::DistributedLockBackend;
185pub use pii::{PiiConfig, PiiDetector, PiiKind, PiiMatch, PiiReport};
186pub use rate_limit::{
187    create_rate_limiter, DistributedRateLimiter, DistributedRateLimiterCoordinator,
188    DistributedRateLimiterState, DistributedSlidingWindowSpec, DistributedTokenBucketSpec,
189    RateLimitConfig, RateLimiter, SlidingWindow, TaskRateLimiter, TokenBucket, WorkerRateLimiter,
190};
191// Note: `rate_limit_distributed::DistributedRateLimiter` is intentionally NOT
192// re-exported at the crate root to avoid clashing with the existing
193// `rate_limit::DistributedRateLimiter` trait above. Access the cluster-wide
194// limiter struct via `celers_core::rate_limit_distributed::DistributedRateLimiter`.
195pub use rate_limit_distributed::{
196    AcquireOutcome, DistributedAlgorithm, DistributedRateLimitBackend, InMemoryDistributedBackend,
197    RateLimitParams,
198};
199pub use result::{
200    AsyncResult, ExtendedResultStore, ResultChunk, ResultChunker, ResultCompressor, ResultMetadata,
201    ResultStore, ResultTombstone, TaskResultValue,
202};
203pub use result_groups::{GroupChild, GroupStatus, ResultGroup};
204pub use result_tombstone::{ResultExistence, TombstoneExt, TombstoneRegistry};
205pub use result_ttl::{ResolvedResultTtl, ResultTtlConfig};
206pub use retry::{RetryPolicy, RetryStrategy};
207pub use revocation::{
208    PatternRevocation, RevocationManager, RevocationMode, RevocationRequest, RevocationResult,
209    RevocationState, WorkerRevocationManager,
210};
211pub use router::{
212    ArgumentCondition, GlobPattern, PatternMatcher, RegexPattern, RouteResult, RouteRule, Router,
213    RouterBuilder, RoutingConfig,
214};
215pub use sanitize::{
216    OversizeAction, SanitizeError, SanitizeReport, Sanitizer, SanitizerConfig, TaskValue, ValueKind,
217};
218pub use state::{StateHistory, StateTransition, TaskState};
219pub use task::{SerializedTask, Task, TaskId, TaskMetadata};
220pub use task_signature::{
221    HmacSha256, Sha256, SignatureAlgorithm, SignatureError, SignedFields, TaskSignature, TaskSigner,
222};
223pub use tenant_rate_limit::{TenantRateLimit, TenantRateLimiter, TenantUsage};
224pub use time_limit::{
225    TaskTimeLimits, TimeLimit, TimeLimitConfig, TimeLimitExceeded, TimeLimitSettings,
226    TimeLimitStatus, WorkerTimeLimits,
227};
celers_core/lib.rs

celers_core/
lib.rs
