oxigeo_cluster/lib.rs
1//! OxiGeo Cluster - Distributed geospatial processing at scale.
2//!
3//! This crate provides a comprehensive distributed computing framework for geospatial
4//! data processing, including:
5//!
6//! - **Distributed Scheduler**: Work-stealing scheduler with priority queues and dynamic load balancing
7//! - **Task Graph Engine**: DAG-based task dependencies with parallel execution planning
8//! - **Worker Pool Management**: Worker registration, health monitoring, and automatic failover
9//! - **Data Locality Optimization**: Minimize data transfer through intelligent task placement
10//! - **Fault Tolerance**: Task retry, speculative execution, and checkpointing
11//! - **Distributed Cache**: Cache coherency with compression and distributed LRU
12//! - **Data Replication**: Quorum-based reads/writes with automatic re-replication
13//! - **Cluster Coordinator**: Raft-based consensus and leader election
14//! - **Advanced Scheduling**: Gang scheduling, fair-share, deadline-based, and multi-queue scheduling
15//! - **Resource Management**: Quota management, resource reservation, and usage accounting
16//! - **Network Optimization**: Topology-aware scheduling, bandwidth tracking, and congestion control
17//! - **Workflow Engine**: Complex workflow orchestration with conditional execution and loops
18//! - **Autoscaling**: Dynamic cluster sizing based on load metrics and predictive scaling
19//! - **Monitoring & Alerting**: Real-time metrics, custom alerts, and anomaly detection
20//! - **Security & Access Control**: Authentication, RBAC, audit logging, and secret management
21//!
22//! # Examples
23//!
24//! ## Basic Cluster Setup
25//!
26//! ```rust,no_run
27//! use oxigeo_cluster::{Cluster, ClusterBuilder, SchedulerConfig};
28//!
29//! #[tokio::main]
30//! async fn main() -> oxigeo_cluster::Result<()> {
31//! // Create a cluster with default configuration
32//! let cluster = Cluster::new();
33//!
34//! // Start the cluster
35//! cluster.start().await?;
36//!
37//! // Get cluster statistics
38//! let stats = cluster.get_statistics();
39//! println!("Active workers: {}", stats.worker_pool.total_workers);
40//!
41//! // Stop the cluster
42//! cluster.stop().await?;
43//! Ok(())
44//! }
45//! ```
46//!
47//! ## Custom Cluster Configuration
48//!
49//! ```rust,no_run
50//! use oxigeo_cluster::{ClusterBuilder, SchedulerConfig, LoadBalanceStrategy};
51//! use oxigeo_cluster::worker_pool::WorkerPoolConfig;
52//! use std::time::Duration;
53//!
54//! #[tokio::main]
55//! async fn main() -> oxigeo_cluster::Result<()> {
56//! // Configure the scheduler
57//! let scheduler_config = SchedulerConfig {
58//! max_queue_size: 10000,
59//! work_steal_threshold: 10,
60//! scheduling_interval: Duration::from_millis(100),
61//! load_balance_strategy: LoadBalanceStrategy::LeastLoaded,
62//! task_timeout: Duration::from_secs(300),
63//! enable_work_stealing: true,
64//! enable_backpressure: true,
65//! max_concurrent_tasks_per_worker: 1000,
66//! };
67//!
68//! // Configure the worker pool
69//! let worker_config = WorkerPoolConfig {
70//! heartbeat_timeout: Duration::from_secs(30),
71//! health_check_interval: Duration::from_secs(10),
72//! max_unhealthy_duration: Duration::from_secs(120),
73//! min_workers: 1,
74//! max_workers: 100,
75//! };
76//!
77//! // Build the cluster with custom configuration
78//! let cluster = ClusterBuilder::new()
79//! .with_scheduler_config(scheduler_config)
80//! .with_worker_pool_config(worker_config)
81//! .build();
82//!
83//! cluster.start().await?;
84//!
85//! // Your cluster operations here
86//!
87//! cluster.stop().await?;
88//! Ok(())
89//! }
90//! ```
91
92#![deny(missing_docs)]
93#![warn(clippy::all)]
94
95pub mod autoscale;
96pub mod cache_coherency;
97pub mod coordinator;
98pub mod data_locality;
99pub mod error;
100pub mod fault_tolerance;
101pub mod metrics;
102pub mod monitoring;
103pub mod network;
104pub mod replication;
105pub mod resources;
106pub mod scheduler;
107pub mod security;
108pub mod task_graph;
109pub mod transport;
110pub mod worker_pool;
111pub mod workflow;
112
113// Re-export common types
114pub use autoscale::{
115 AutoscaleConfig, AutoscaleStats, Autoscaler, CloudProvider,
116 MetricsSnapshot as AutoscaleMetrics, ScaleDecision, ScaleOutcome, WorkerPoolProvider,
117};
118pub use cache_coherency::{CacheConfig, CacheKey, DistributedCache};
119pub use coordinator::{ClusterCoordinator, CoordinatorConfig, NodeId, NodeRole};
120pub use data_locality::{DataLocalityOptimizer, LocalityConfig, PlacementRecommendation};
121pub use error::{ClusterError, Result};
122pub use fault_tolerance::{
123 // Bulkhead
124 Bulkhead,
125 BulkheadConfig,
126 BulkheadRegistry,
127 BulkheadStats,
128 // Circuit breaker
129 CircuitBreaker,
130 CircuitBreakerConfig,
131 CircuitBreakerRegistry,
132 CircuitBreakerStats,
133 CircuitState,
134 // Timeout management
135 Deadline,
136 // Graceful degradation
137 DegradationConfig,
138 DegradationLevel,
139 DegradationManager,
140 DegradationStats,
141 // Core fault tolerance
142 FaultToleranceConfig,
143 FaultToleranceManager,
144 FaultToleranceStatistics,
145 // Health checks
146 HealthCheck,
147 HealthCheckConfig,
148 HealthCheckManager,
149 HealthCheckResult,
150 HealthCheckStats,
151 HealthStatus,
152 RequestPriority,
153 RetryDecision,
154 TimeoutBudget,
155 TimeoutConfig,
156 TimeoutManager,
157 TimeoutRegistry,
158 TimeoutStats,
159};
160pub use metrics::{ClusterMetrics, MetricsSnapshot, WorkerMetrics};
161pub use monitoring::{Alert, AlertRule, AlertSeverity, MonitoringManager, MonitoringStats};
162pub use network::{BandwidthTracker, CompressionManager, CongestionController, TopologyManager};
163pub use replication::{ReplicaSet, ReplicationConfig, ReplicationManager};
164pub use resources::{AccountingManager, QuotaManager, ReservationManager};
165pub use scheduler::{LoadBalanceStrategy, Scheduler, SchedulerConfig, SchedulerStats};
166pub use security::{Role, SecurityManager, SecurityStats, User};
167pub use task_graph::{ExecutionPlan, ResourceRequirements, Task, TaskGraph, TaskId, TaskStatus};
168pub use transport::{NodeTransport, UnconfiguredTransport, VoteRequest, VoteResponse};
169pub use worker_pool::{
170 SelectionStrategy, Worker, WorkerCapabilities, WorkerCapacity, WorkerId, WorkerPool,
171 WorkerStatus, WorkerUsage,
172};
173pub use workflow::{Workflow, WorkflowEngine, WorkflowExecution, WorkflowStatus};
174
175/// Cluster builder for easy setup.
176///
177/// The builder pattern allows you to customize various aspects of the cluster
178/// before initialization. All configuration is optional; if not specified,
179/// sensible defaults will be used.
180///
181/// # Examples
182///
183/// ```rust
184/// use oxigeo_cluster::{ClusterBuilder, SchedulerConfig, LoadBalanceStrategy};
185/// use std::time::Duration;
186///
187/// let scheduler_config = SchedulerConfig {
188/// max_queue_size: 10000,
189/// work_steal_threshold: 10,
190/// scheduling_interval: Duration::from_millis(100),
191/// load_balance_strategy: LoadBalanceStrategy::RoundRobin,
192/// task_timeout: Duration::from_secs(600),
193/// enable_work_stealing: true,
194/// enable_backpressure: true,
195/// max_concurrent_tasks_per_worker: 500,
196/// };
197///
198/// let cluster = ClusterBuilder::new()
199/// .with_scheduler_config(scheduler_config)
200/// .build();
201/// ```
202pub struct ClusterBuilder {
203 scheduler_config: Option<SchedulerConfig>,
204 worker_pool_config: Option<worker_pool::WorkerPoolConfig>,
205 coordinator_config: Option<CoordinatorConfig>,
206 fault_tolerance_config: Option<FaultToleranceConfig>,
207 locality_config: Option<LocalityConfig>,
208 cache_config: Option<CacheConfig>,
209 replication_config: Option<ReplicationConfig>,
210}
211
212impl ClusterBuilder {
213 /// Create a new cluster builder.
214 pub fn new() -> Self {
215 Self {
216 scheduler_config: None,
217 worker_pool_config: None,
218 coordinator_config: None,
219 fault_tolerance_config: None,
220 locality_config: None,
221 cache_config: None,
222 replication_config: None,
223 }
224 }
225
226 /// Set scheduler configuration.
227 pub fn with_scheduler_config(mut self, config: SchedulerConfig) -> Self {
228 self.scheduler_config = Some(config);
229 self
230 }
231
232 /// Set worker pool configuration.
233 pub fn with_worker_pool_config(mut self, config: worker_pool::WorkerPoolConfig) -> Self {
234 self.worker_pool_config = Some(config);
235 self
236 }
237
238 /// Set coordinator configuration.
239 pub fn with_coordinator_config(mut self, config: CoordinatorConfig) -> Self {
240 self.coordinator_config = Some(config);
241 self
242 }
243
244 /// Set fault tolerance configuration.
245 pub fn with_fault_tolerance_config(mut self, config: FaultToleranceConfig) -> Self {
246 self.fault_tolerance_config = Some(config);
247 self
248 }
249
250 /// Set locality optimizer configuration.
251 pub fn with_locality_config(mut self, config: LocalityConfig) -> Self {
252 self.locality_config = Some(config);
253 self
254 }
255
256 /// Set cache configuration.
257 pub fn with_cache_config(mut self, config: CacheConfig) -> Self {
258 self.cache_config = Some(config);
259 self
260 }
261
262 /// Set replication configuration.
263 pub fn with_replication_config(mut self, config: ReplicationConfig) -> Self {
264 self.replication_config = Some(config);
265 self
266 }
267
268 /// Build the cluster.
269 pub fn build(self) -> Cluster {
270 use std::sync::Arc;
271
272 let task_graph = Arc::new(TaskGraph::new());
273 let metrics = Arc::new(ClusterMetrics::new());
274
275 let worker_pool = Arc::new(if let Some(config) = self.worker_pool_config {
276 WorkerPool::new(config)
277 } else {
278 WorkerPool::with_defaults()
279 });
280
281 let scheduler = Arc::new(if let Some(config) = self.scheduler_config {
282 Scheduler::new(
283 Arc::clone(&task_graph),
284 Arc::clone(&worker_pool),
285 Arc::clone(&metrics),
286 config,
287 )
288 } else {
289 Scheduler::with_defaults(
290 Arc::clone(&task_graph),
291 Arc::clone(&worker_pool),
292 Arc::clone(&metrics),
293 )
294 });
295
296 let coordinator = Arc::new(if let Some(config) = self.coordinator_config {
297 ClusterCoordinator::new(config)
298 } else {
299 ClusterCoordinator::with_defaults()
300 });
301
302 let fault_tolerance = Arc::new(if let Some(config) = self.fault_tolerance_config {
303 FaultToleranceManager::new(config)
304 } else {
305 FaultToleranceManager::with_defaults()
306 });
307
308 let locality_optimizer = Arc::new(if let Some(config) = self.locality_config {
309 DataLocalityOptimizer::new(config)
310 } else {
311 DataLocalityOptimizer::with_defaults()
312 });
313
314 let cache = Arc::new(if let Some(config) = self.cache_config {
315 DistributedCache::new(config)
316 } else {
317 DistributedCache::with_defaults()
318 });
319
320 let replication = Arc::new(if let Some(config) = self.replication_config {
321 ReplicationManager::new(config)
322 } else {
323 ReplicationManager::with_defaults()
324 });
325
326 Cluster {
327 task_graph,
328 worker_pool,
329 scheduler,
330 coordinator,
331 fault_tolerance,
332 locality_optimizer,
333 cache,
334 replication,
335 metrics,
336 }
337 }
338}
339
340impl Default for ClusterBuilder {
341 fn default() -> Self {
342 Self::new()
343 }
344}
345
346/// Complete cluster instance.
347///
348/// The `Cluster` struct provides access to all cluster components including
349/// the task graph, worker pool, scheduler, coordinator, fault tolerance,
350/// data locality optimizer, distributed cache, and replication manager.
351///
352/// # Examples
353///
354/// ```rust,no_run
355/// use oxigeo_cluster::Cluster;
356///
357/// #[tokio::main]
358/// async fn main() -> oxigeo_cluster::Result<()> {
359/// // Create and start a cluster
360/// let cluster = Cluster::new();
361/// cluster.start().await?;
362///
363/// // Access cluster components
364/// let metrics = cluster.metrics.snapshot();
365/// println!("Tasks completed: {}", metrics.tasks_completed);
366///
367/// // Get cluster statistics
368/// let stats = cluster.get_statistics();
369/// println!("Total workers: {}", stats.worker_pool.total_workers);
370///
371/// // Stop the cluster
372/// cluster.stop().await?;
373/// Ok(())
374/// }
375/// ```
376pub struct Cluster {
377 /// Task graph
378 pub task_graph: std::sync::Arc<TaskGraph>,
379
380 /// Worker pool
381 pub worker_pool: std::sync::Arc<WorkerPool>,
382
383 /// Scheduler
384 pub scheduler: std::sync::Arc<Scheduler>,
385
386 /// Coordinator
387 pub coordinator: std::sync::Arc<ClusterCoordinator>,
388
389 /// Fault tolerance manager
390 pub fault_tolerance: std::sync::Arc<FaultToleranceManager>,
391
392 /// Data locality optimizer
393 pub locality_optimizer: std::sync::Arc<DataLocalityOptimizer>,
394
395 /// Distributed cache
396 pub cache: std::sync::Arc<DistributedCache>,
397
398 /// Replication manager
399 pub replication: std::sync::Arc<ReplicationManager>,
400
401 /// Cluster metrics
402 pub metrics: std::sync::Arc<ClusterMetrics>,
403}
404
405impl Cluster {
406 /// Create a new cluster with default configuration.
407 pub fn new() -> Self {
408 ClusterBuilder::new().build()
409 }
410
411 /// Start all cluster components.
412 pub async fn start(&self) -> Result<()> {
413 self.coordinator.start().await?;
414 self.scheduler.start().await?;
415 Ok(())
416 }
417
418 /// Stop all cluster components.
419 pub async fn stop(&self) -> Result<()> {
420 self.scheduler.stop().await?;
421 self.coordinator.stop().await?;
422 Ok(())
423 }
424
425 /// Get cluster-wide statistics.
426 pub fn get_statistics(&self) -> ClusterStatistics {
427 ClusterStatistics {
428 metrics: self.metrics.snapshot(),
429 scheduler: self.scheduler.get_statistics(),
430 worker_pool: self.worker_pool.get_statistics(),
431 coordinator: self.coordinator.get_statistics(),
432 fault_tolerance: self.fault_tolerance.get_statistics(),
433 locality: self.locality_optimizer.get_statistics(),
434 cache: self.cache.get_statistics(),
435 replication: self.replication.get_statistics(),
436 }
437 }
438}
439
440impl Default for Cluster {
441 fn default() -> Self {
442 Self::new()
443 }
444}
445
446/// Cluster-wide statistics.
447#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
448pub struct ClusterStatistics {
449 /// Metrics snapshot
450 pub metrics: MetricsSnapshot,
451
452 /// Scheduler statistics
453 pub scheduler: SchedulerStats,
454
455 /// Worker pool statistics
456 pub worker_pool: worker_pool::WorkerPoolStatistics,
457
458 /// Coordinator statistics
459 pub coordinator: coordinator::CoordinatorStatistics,
460
461 /// Fault tolerance statistics
462 pub fault_tolerance: fault_tolerance::FaultToleranceStatistics,
463
464 /// Locality statistics
465 pub locality: data_locality::LocalityStats,
466
467 /// Cache statistics
468 pub cache: cache_coherency::CacheStats,
469
470 /// Replication statistics
471 pub replication: replication::ReplicationStatistics,
472}