|
1 | 1 | //! # A3S Lane |
2 | 2 | //! |
3 | | -//! A high-performance, priority-based command queue for async task scheduling with comprehensive |
4 | | -//! reliability, scalability, and observability features. |
| 3 | +//! A priority-based command queue for async task scheduling. |
5 | 4 | //! |
6 | | -//! ## Overview |
| 5 | +//! ## Core (always compiled) |
7 | 6 | //! |
8 | | -//! A3S Lane provides a lane-based priority command queue system designed for managing concurrent |
9 | | -//! async operations with different priority levels. Commands are organized into lanes, each with |
10 | | -//! configurable concurrency limits, timeouts, retry policies, and rate limiting. |
| 7 | +//! - Priority-based scheduling with per-lane concurrency control |
| 8 | +//! - Command timeout and retry policies (exponential backoff, fixed delay) |
| 9 | +//! - Dead letter queue for permanently failed commands |
| 10 | +//! - Persistent storage (pluggable `Storage` trait, `LocalStorage` included) |
| 11 | +//! - Event system for queue lifecycle notifications |
| 12 | +//! - Graceful shutdown with drain support |
11 | 13 | //! |
12 | | -//! ## Core Features |
| 14 | +//! ## Feature Flags |
13 | 15 | //! |
14 | | -//! ### Phase 1: Core Queue System |
15 | | -//! - **Priority-based scheduling**: Commands execute based on lane priority (lower = higher priority) |
16 | | -//! - **Concurrency control**: Per-lane min/max concurrency limits with semaphore-based coordination |
17 | | -//! - **Built-in lanes**: 6 predefined lanes (system, control, query, session, skill, prompt) |
18 | | -//! - **Event system**: Subscribe to queue events for real-time monitoring |
19 | | -//! - **Health monitoring**: Track queue depth and active command counts |
20 | | -//! - **Builder pattern**: Flexible, ergonomic queue configuration |
21 | | -//! |
22 | | -//! ### Phase 2: Reliability |
23 | | -//! - **Command timeout**: Configurable timeout per lane with automatic cancellation |
24 | | -//! - **Retry policies**: Exponential backoff, fixed delay, or custom retry strategies |
25 | | -//! - **Dead letter queue**: Capture permanently failed commands for inspection and replay |
26 | | -//! - **Persistent storage**: Optional pluggable storage backend (LocalStorage included) |
27 | | -//! - **Graceful shutdown**: Drain pending commands before shutdown with timeout |
28 | | -//! |
29 | | -//! ### Phase 3: Scalability |
30 | | -//! - **Multi-core parallelism**: Automatic CPU core detection and parallel processing |
31 | | -//! - **Queue partitioning**: Distribute commands across workers (round-robin, hash-based, custom) |
32 | | -//! - **Rate limiting**: Token bucket and sliding window rate limiters per lane |
33 | | -//! - **Priority boosting**: Deadline-based automatic priority adjustment |
34 | | -//! - **Distributed queue**: Pluggable interface for multi-machine processing |
35 | | -//! |
36 | | -//! ### Phase 4: Observability |
37 | | -//! - **Metrics collection**: Local in-memory metrics with pluggable backend support |
38 | | -//! - **Latency histograms**: Track command execution and wait time with percentiles (p50, p90, p95, p99) |
39 | | -//! - **Queue depth alerts**: Configurable warning and critical thresholds |
40 | | -//! - **Latency alerts**: Monitor and alert on command execution latency |
41 | | -//! - **Prometheus/OpenTelemetry ready**: Implement MetricsBackend trait for external systems |
| 16 | +//! | Feature | Default | Dependencies | Description | |
| 17 | +//! |---------|---------|-------------|-------------| |
| 18 | +//! | `metrics` | ✅ | — | `MetricsBackend` trait, `LocalMetrics`, latency histograms | |
| 19 | +//! | `monitoring` | ✅ | `metrics` | `AlertManager`, `QueueMonitor` with depth/latency thresholds | |
| 20 | +//! | `telemetry` | ✅ | `opentelemetry`, `dashmap` | OpenTelemetry spans and `OtelMetricsBackend` | |
| 21 | +//! | `distributed` | ✅ | `num_cpus` | Partitioning, rate limiting, priority boosting, `DistributedQueue` | |
42 | 22 | //! |
43 | 23 | //! ## Quick Start |
44 | 24 | //! |
45 | 25 | //! ```rust,ignore |
46 | 26 | //! use a3s_lane::{QueueManagerBuilder, EventEmitter, Command, Result}; |
47 | 27 | //! use async_trait::async_trait; |
48 | 28 | //! |
49 | | -//! // Define a command |
50 | | -//! struct MyCommand { |
51 | | -//! data: String, |
52 | | -//! } |
| 29 | +//! struct MyCommand { data: String } |
53 | 30 | //! |
54 | 31 | //! #[async_trait] |
55 | 32 | //! impl Command for MyCommand { |
56 | 33 | //! async fn execute(&self) -> Result<serde_json::Value> { |
57 | 34 | //! Ok(serde_json::json!({"processed": self.data})) |
58 | 35 | //! } |
59 | | -//! |
60 | | -//! fn command_type(&self) -> &str { |
61 | | -//! "my_command" |
62 | | -//! } |
| 36 | +//! fn command_type(&self) -> &str { "my_command" } |
63 | 37 | //! } |
64 | 38 | //! |
65 | 39 | //! #[tokio::main] |
66 | | -//! async fn main() -> anyhow::Result<()> { |
67 | | -//! // Create event emitter |
68 | | -//! let emitter = EventEmitter::new(100); |
69 | | -//! |
70 | | -//! // Build queue manager with default lanes |
71 | | -//! let manager = QueueManagerBuilder::new(emitter) |
| 40 | +//! async fn main() -> Result<()> { |
| 41 | +//! let manager = QueueManagerBuilder::new(EventEmitter::new(100)) |
72 | 42 | //! .with_default_lanes() |
73 | 43 | //! .build() |
74 | 44 | //! .await?; |
75 | 45 | //! |
76 | | -//! // Start the scheduler |
77 | 46 | //! manager.start().await?; |
78 | 47 | //! |
79 | | -//! // Submit a command |
80 | | -//! let cmd = Box::new(MyCommand { data: "hello".to_string() }); |
81 | | -//! let rx = manager.submit("query", cmd).await?; |
82 | | -//! |
83 | | -//! // Wait for result |
| 48 | +//! let rx = manager.submit("query", Box::new(MyCommand { data: "hello".into() })).await?; |
84 | 49 | //! let result = rx.await??; |
85 | 50 | //! println!("Result: {}", result); |
86 | | -//! |
87 | 51 | //! Ok(()) |
88 | 52 | //! } |
89 | 53 | //! ``` |
90 | | -//! |
91 | | -//! ## Lane Priority Model |
92 | | -//! |
93 | | -//! | Lane | Priority | Default Max Concurrency | Use Case | |
94 | | -//! |------|----------|------------------------|----------| |
95 | | -//! | system | 0 (highest) | 5 | System-level operations | |
96 | | -//! | control | 1 | 3 | Control commands (pause, resume, cancel) | |
97 | | -//! | query | 2 | 10 | Read-only queries | |
98 | | -//! | session | 3 | 5 | Session management | |
99 | | -//! | skill | 4 | 3 | Skill/tool execution | |
100 | | -//! | prompt | 5 (lowest) | 2 | LLM prompt processing | |
101 | | -//! |
102 | | -//! ## Examples |
103 | | -//! |
104 | | -//! See the `examples/` directory for comprehensive examples: |
105 | | -//! - `basic_usage.rs` - Simple command submission and result handling |
106 | | -//! - `reliability.rs` - Timeout, retry policies, DLQ, graceful shutdown |
107 | | -//! - `observability.rs` - Metrics collection, latency histograms, alerts |
108 | | -//! - `scalability.rs` - Rate limiting, priority boosting, partitioning |
109 | 54 |
|
110 | | -pub mod alerts; |
111 | | -pub mod boost; |
| 55 | +// Core modules (always compiled) |
112 | 56 | pub mod config; |
113 | | -pub mod distributed; |
114 | 57 | pub mod dlq; |
115 | 58 | pub mod error; |
116 | 59 | pub mod event; |
117 | 60 | pub mod manager; |
118 | | -pub mod metrics; |
119 | | -pub mod monitor; |
120 | | -pub mod partition; |
121 | 61 | pub mod queue; |
122 | | -pub mod ratelimit; |
123 | 62 | pub mod retry; |
124 | 63 | pub mod storage; |
| 64 | + |
| 65 | +// Feature-gated modules |
| 66 | +#[cfg(feature = "metrics")] |
| 67 | +pub mod metrics; |
| 68 | +#[cfg(feature = "monitoring")] |
| 69 | +pub mod alerts; |
| 70 | +#[cfg(feature = "monitoring")] |
| 71 | +pub mod monitor; |
| 72 | +#[cfg(feature = "telemetry")] |
125 | 73 | pub mod telemetry; |
| 74 | +#[cfg(feature = "distributed")] |
| 75 | +pub mod boost; |
| 76 | +#[cfg(feature = "distributed")] |
| 77 | +pub mod partition; |
| 78 | +#[cfg(feature = "distributed")] |
| 79 | +pub mod ratelimit; |
| 80 | +#[cfg(feature = "distributed")] |
| 81 | +pub mod distributed; |
126 | 82 |
|
127 | | -// Re-export main types |
128 | | -pub use alerts::{Alert, AlertLevel, AlertManager, LatencyAlertConfig, QueueDepthAlertConfig}; |
129 | | -pub use boost::{PriorityBoostConfig, PriorityBooster}; |
| 83 | +// Core re-exports |
130 | 84 | pub use config::LaneConfig; |
131 | | -pub use distributed::{ |
132 | | - CommandEnvelope, CommandResult, DistributedQueue, LocalDistributedQueue, WorkerId, WorkerPool, |
133 | | -}; |
134 | 85 | pub use dlq::{DeadLetter, DeadLetterQueue}; |
135 | 86 | pub use error::{LaneError, Result}; |
136 | 87 | pub use event::{EventEmitter, EventPayload, EventStream, LaneEvent}; |
137 | 88 | pub use manager::{QueueManager, QueueManagerBuilder}; |
| 89 | +pub use queue::{ |
| 90 | + lane_ids, priorities, Command, CommandId, CommandQueue, JsonCommand, Lane, LaneId, LaneStatus, |
| 91 | + Priority, |
| 92 | +}; |
| 93 | +pub use retry::RetryPolicy; |
| 94 | +pub use storage::{LocalStorage, Storage, StoredCommand, StoredDeadLetter}; |
| 95 | + |
| 96 | +// Feature-gated re-exports |
| 97 | +#[cfg(feature = "metrics")] |
138 | 98 | pub use metrics::{ |
139 | 99 | metric_names, HistogramPercentiles, HistogramStats, LocalMetrics, MetricsBackend, |
140 | 100 | MetricsSnapshot, QueueMetrics, |
141 | 101 | }; |
| 102 | +#[cfg(feature = "monitoring")] |
| 103 | +pub use alerts::{Alert, AlertLevel, AlertManager, LatencyAlertConfig, QueueDepthAlertConfig}; |
| 104 | +#[cfg(feature = "monitoring")] |
142 | 105 | pub use monitor::{MonitorConfig, QueueMonitor}; |
| 106 | +#[cfg(feature = "telemetry")] |
| 107 | +pub use telemetry::OtelMetricsBackend; |
| 108 | +#[cfg(feature = "distributed")] |
| 109 | +pub use boost::{PriorityBoostConfig, PriorityBooster}; |
| 110 | +#[cfg(feature = "distributed")] |
| 111 | +pub use distributed::{ |
| 112 | + CommandEnvelope, CommandResult, DistributedQueue, LocalDistributedQueue, WorkerId, WorkerPool, |
| 113 | +}; |
| 114 | +#[cfg(feature = "distributed")] |
143 | 115 | pub use partition::{ |
144 | 116 | CustomPartitioner, HashPartitioner, PartitionConfig, PartitionId, PartitionStrategy, |
145 | 117 | Partitioner, RoundRobinPartitioner, |
146 | 118 | }; |
147 | | -pub use queue::{ |
148 | | - lane_ids, priorities, Command, CommandId, CommandQueue, JsonCommand, Lane, LaneId, LaneStatus, |
149 | | - Priority, |
150 | | -}; |
| 119 | +#[cfg(feature = "distributed")] |
151 | 120 | pub use ratelimit::{RateLimitConfig, RateLimiter, SlidingWindowLimiter, TokenBucketLimiter}; |
152 | | -pub use retry::RetryPolicy; |
153 | | -pub use storage::{LocalStorage, Storage, StoredCommand, StoredDeadLetter}; |
154 | | -pub use telemetry::OtelMetricsBackend; |
155 | 121 |
|
156 | 122 | use serde::{Deserialize, Serialize}; |
157 | 123 | use std::collections::HashMap; |
|
0 commit comments