Skip to main content

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}