saorsa_core/placement/

mod.rs

// Copyright (c) 2025 Saorsa Labs Limited
//
// This file is part of the Saorsa P2P network.
//
// Licensed under the AGPL-3.0 license:
// <https://www.gnu.org/licenses/agpl-3.0.html>

//! Placement Loop & Storage Orchestration System
//!
//! This module implements the core placement system for optimal distribution
//! of erasure-coded shards across the network, integrating EigenTrust reputation,
//! churn prediction, capacity constraints, and diversity rules.
//!
//! ## Core Concepts
//!
//! ### Weighted Selection Algorithm
//!
//! The placement system uses Efraimidis-Spirakis weighted sampling with the formula:
//!
//! ```text
//! w_i = (τ_i^α) * (p_i^β) * (c_i^γ) * d_i
//! ```
//!
//! Where:
//! - `τ_i`: EigenTrust reputation score (0.0-1.0)
//! - `p_i`: Node performance score (0.0-1.0)
//! - `c_i`: Available capacity score (0.0-1.0)
//! - `d_i`: Geographic/network diversity bonus (1.0-2.0)
//! - `α, β, γ`: Configurable weight exponents
//!
//! ### Byzantine Fault Tolerance
//!
//! Implements configurable f-out-of-3f+1 Byzantine fault tolerance:
//! - Tolerates up to f Byzantine (malicious) nodes
//! - Requires minimum 3f+1 nodes for safety
//! - Automatically adjusts replication based on network size
//!
//! ### Geographic Diversity
//!
//! Ensures optimal shard distribution across:
//! - Geographic regions (7 major regions)
//! - Autonomous System Numbers (ASNs)
//! - Network operators and data centers
//!
//! ## Usage Examples
//!
//! ### Basic Placement
//!
//! ```rust,ignore
//! use saorsa_core::placement::{PlacementConfig, PlacementOrchestrator};
//! use std::time::Duration;
//!
//! async fn example() -> Result<(), Box<dyn std::error::Error>> {
//!     // Create placement configuration
//!     let config = PlacementConfig::default();
//!
//!     // Create orchestrator with required components
//!     let orchestrator = PlacementOrchestrator::new(config).await?;
//!
//!     // Start the placement system
//!     orchestrator.start().await?;
//!     Ok(())
//! }
//! ```
//!
//! ### Advanced Configuration
//!
//! ```rust,ignore
//! use saorsa_core::placement::{PlacementConfig, OptimizationWeights};
//!
//! // PlacementConfig uses Default for standard setups
//! // See PlacementConfig documentation for available fields
//! let config = PlacementConfig::default();
//! ```
//!
//! ### Storage Orchestration
//!
//! ```rust,ignore
//! use saorsa_core::placement::PlacementOrchestrator;
//!
//! async fn example() -> Result<(), Box<dyn std::error::Error>> {
//!     // Create orchestrator with default configuration
//!     let orchestrator = PlacementOrchestrator::new(Default::default()).await?;
//!
//!     // Start audit and repair systems
//!     orchestrator.start().await?;
//!     Ok(())
//! }
//! ```
//!
//! ## Architecture
//!
//! The placement system consists of several key components:
//!
//! - **PlacementEngine**: Main orchestrator for placement decisions
//! - **WeightedPlacementStrategy**: Implements the weighted selection algorithm
//! - **StorageOrchestrator**: Manages shard storage and retrieval
//! - **AuditSystem**: Continuous monitoring of shard health
//! - **RepairSystem**: Automatic repair with hysteresis control
//! - **DiversityEnforcer**: Geographic and network diversity constraints
//!
//! ## Performance Characteristics
//!
//! - **Selection Speed**: <1 second for 8-node selection from 1000+ candidates
//! - **Memory Usage**: O(n) where n is candidate node count
//! - **Audit Frequency**: Every 5 minutes with concurrent limits
//! - **Repair Latency**: <1 hour detection, immediate repair initiation
//!
//! ## Security Features
//!
//! - EigenTrust integration for reputation-based selection
//! - Byzantine fault tolerance with configurable parameters
//! - Proof-of-work for DHT records (~18 bits difficulty)
//! - Cryptographic verification of all operations
//! - Secure random selection with cryptographic entropy

pub mod algorithms;
pub mod dht_records;
pub mod errors;
pub mod orchestrator;
pub mod traits;
pub mod types;

// Re-export core types for convenience
pub use algorithms::{DiversityEnforcer, WeightedPlacementStrategy, WeightedSampler};
pub use dht_records::{
    DataPointer, DhtRecord, GroupBeacon, NatType, NodeAd, NodeCapabilities, OsSignature,
    RegisterPointer,
};
pub use errors::{PlacementError, PlacementResult};
pub use orchestrator::{AuditSystem, PlacementOrchestrator, RepairSystem, StorageOrchestrator};
pub use traits::{
    NetworkTopology, NodePerformanceMetrics, PerformanceEstimator, PlacementConstraint,
    PlacementStrategy, PlacementValidator,
};
pub use types::{
    ByzantineTolerance, GeographicLocation, NetworkRegion, OptimizationWeights, PlacementConfig,
    PlacementDecision, PlacementMetrics, ReplicationFactor,
};

use std::collections::HashSet;
use std::time::Instant;

use crate::adaptive::{NodeId, performance::PerformanceMonitor, trust::EigenTrustEngine};

/// Main placement engine that orchestrates the entire placement process
#[derive(Debug)]
pub struct PlacementEngine {
    config: PlacementConfig,
    strategy: Box<dyn PlacementStrategy + Send + Sync>,
}

impl PlacementEngine {
    /// Create new placement engine with default weighted strategy
    pub fn new(config: PlacementConfig) -> Self {
        let strategy = Box::new(algorithms::WeightedPlacementStrategy::new(config.clone()));

        Self { config, strategy }
    }

    /// Create placement engine with custom strategy
    pub fn with_strategy(
        config: PlacementConfig,
        strategy: Box<dyn PlacementStrategy + Send + Sync>,
    ) -> Self {
        Self { config, strategy }
    }

    /// Select optimal nodes for shard placement
    pub async fn select_nodes(
        &mut self,
        available_nodes: &HashSet<NodeId>,
        replication_factor: u8,
        trust_system: &EigenTrustEngine,
        performance_monitor: &PerformanceMonitor,
        node_metadata: &std::collections::HashMap<NodeId, (GeographicLocation, u32, NetworkRegion)>,
    ) -> PlacementResult<PlacementDecision> {
        let start_time = Instant::now();

        // Validate inputs
        if available_nodes.is_empty() {
            return Err(PlacementError::InsufficientNodes {
                required: replication_factor as usize,
                available: 0,
            });
        }

        if replication_factor < self.config.replication_factor.min_value() {
            return Err(PlacementError::InvalidReplicationFactor(replication_factor));
        }

        // Execute placement with timeout using idiomatic tokio::time::timeout
        let mut decision = tokio::time::timeout(
            self.config.placement_timeout,
            self.strategy.select_nodes(
                available_nodes,
                replication_factor,
                trust_system,
                performance_monitor,
                node_metadata,
            ),
        )
        .await
        .map_err(|_| PlacementError::PlacementTimeout)??;

        // Update timing information
        decision.selection_time = start_time.elapsed();

        // Validate against configuration constraints
        self.validate_decision(&decision)?;

        Ok(decision)
    }

    /// Validate placement decision against configuration constraints
    fn validate_decision(&self, decision: &PlacementDecision) -> PlacementResult<()> {
        // Check minimum nodes
        if decision.selected_nodes.len() < self.config.replication_factor.min_value() as usize {
            return Err(PlacementError::InsufficientNodes {
                required: self.config.replication_factor.min_value() as usize,
                available: decision.selected_nodes.len(),
            });
        }

        // Check Byzantine fault tolerance
        let required_for_byzantine = self.config.byzantine_tolerance.required_nodes();
        if decision.selected_nodes.len() < required_for_byzantine {
            return Err(PlacementError::ByzantineToleranceViolation {
                required: required_for_byzantine,
                available: decision.selected_nodes.len(),
            });
        }

        // Check reliability threshold
        if decision.estimated_reliability < 0.8 {
            return Err(PlacementError::ReliabilityTooLow {
                estimated: decision.estimated_reliability,
                minimum: 0.8,
            });
        }

        Ok(())
    }

    /// Get current configuration
    pub fn config(&self) -> &PlacementConfig {
        &self.config
    }

    /// Update configuration
    pub fn update_config(&mut self, config: PlacementConfig) {
        self.config = config;
    }

    /// Get strategy name
    pub fn strategy_name(&self) -> &str {
        self.strategy.name()
    }
}