saorsa-core 0.20.0

// Copyright (c) 2025 Saorsa Labs Limited

// This software is dual-licensed under:
// - GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)
// - Commercial License
//
// For AGPL-3.0 license, see LICENSE-AGPL-3.0
// For commercial licensing, contact: david@saorsalabs.com
//
// Unless required by applicable law or agreed to in writing, software
// distributed under these licenses is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public License for more details.

// You should have received a copy of the GNU Affero General Public License
// along with this program. If not, see <https://www.gnu.org/licenses/>.

//! Comprehensive error handling framework for P2P Foundation
//!
//! This module provides a zero-panic error handling system designed to replace 568 unwrap() calls
//! throughout the codebase with proper error propagation and context.
//!
//! # Features
//!
//! - **Type-safe error hierarchy**: Custom error types for all subsystems
//! - **Zero-cost abstractions**: Optimized for performance with Cow<'static, str>
//! - **Context propagation**: Rich error context without heap allocations
//! - **Structured logging**: JSON-based error reporting for production monitoring
//! - **Anyhow integration**: Seamless integration for application-level errors
//! - **Recovery patterns**: Built-in retry and circuit breaker support
//!
//! # Usage Examples
//!
//! ## Basic Error Handling
//!
//! ```rust,ignore
//! use saorsa_core::error::{P2PError, P2pResult};
//! use std::net::SocketAddr;
//!
//! fn connect_to_peer(addr: SocketAddr) -> P2pResult<()> {
//!     // Use proper error propagation instead of unwrap()
//!     // socket.connect(addr).map_err(|e| P2PError::Network(...))?;
//!     Ok(())
//! }
//! ```
//!
//! ## Adding Context
//!
//! ```rust,ignore
//! use saorsa_core::error::{P2PError, P2pResult};
//! use saorsa_core::error::ErrorContext;
//!
//! fn load_config(path: &str) -> P2pResult<String> {
//!     std::fs::read_to_string(path)
//!         .context("Failed to read config file")
//! }
//! ```
//!
//! ## Structured Error Logging
//!
//! ```rust,ignore
//! use saorsa_core::error::P2PError;
//!
//! fn handle_error(err: P2PError) {
//!     // Log with tracing
//!     tracing::error!("Error occurred: {}", err);
//! }
//! ```
//!
//! ## Migration from unwrap()
//!
//! ```rust,ignore
//! use saorsa_core::error::P2PError;
//!
//! // Before:
//! // let value = some_operation().unwrap();
//!
//! // After - use ? operator with proper error types:
//! // let value = some_operation()?;
//!
//! // For Option types:
//! // let value = some_option.ok_or_else(|| P2PError::Internal("Missing value".into()))?;
//! ```

use std::borrow::Cow;
use std::io;
use std::net::SocketAddr;
use std::time::Duration;
use thiserror::Error;

// Metrics imports would go here when implemented
// #[cfg(feature = "metrics")]
// use prometheus::{IntCounterVec, register_int_counter_vec};

/// Core error type for the P2P Foundation library
#[derive(Debug, Error)]
pub enum P2PError {
    // Network errors
    #[error("Network error: {0}")]
    Network(#[from] NetworkError),

    // DHT errors
    #[error("DHT error: {0}")]
    Dht(#[from] DhtError),

    // Identity errors
    #[error("Identity error: {0}")]
    Identity(#[from] IdentityError),

    // Cryptography errors
    #[error("Cryptography error: {0}")]
    Crypto(#[from] CryptoError),

    // State management errors (locks, data integrity, file I/O)
    #[error("State error: {0}")]
    State(#[from] StateError),

    // Transport errors
    #[error("Transport error: {0}")]
    Transport(#[from] TransportError),

    // Security errors
    #[error("Security error: {0}")]
    Security(#[from] SecurityError),

    // Bootstrap errors
    #[error("Bootstrap error: {0}")]
    Bootstrap(#[from] BootstrapError),

    // Generic IO error
    #[error("IO error: {0}")]
    Io(#[from] io::Error),

    // Serialization/Deserialization errors
    #[error("Serialization error: {0}")]
    Serialization(Cow<'static, str>),

    // Validation errors
    #[error("Validation error: {0}")]
    Validation(Cow<'static, str>),

    // Timeout errors
    #[error("Operation timed out after {0:?}")]
    Timeout(Duration),

    // Resource exhaustion
    #[error("Resource exhausted: {0}")]
    ResourceExhausted(Cow<'static, str>),

    // Generic internal error
    #[error("Internal error: {0}")]
    Internal(Cow<'static, str>),

    // Encoding errors
    #[error("Encoding error: {0}")]
    Encoding(Cow<'static, str>),

    // Record too large errors
    #[error("Record too large: {0} bytes (max 512)")]
    RecordTooLarge(usize),

    // Time-related error
    #[error("Time error")]
    TimeError,

    // Invalid input parameter
    #[error("Invalid input: {0}")]
    InvalidInput(String),

    // WebRTC bridge errors
    #[error("WebRTC error: {0}")]
    WebRtcError(String),

    // Trust system errors
    #[error("Trust error: {0}")]
    Trust(Cow<'static, str>),
}

impl From<crate::identity::peer_id::PeerIdParseError> for P2PError {
    fn from(err: crate::identity::peer_id::PeerIdParseError) -> Self {
        P2PError::Identity(IdentityError::InvalidPeerId(Cow::Owned(err.to_string())))
    }
}

/// Network-related errors
#[derive(Debug, Error)]
pub enum NetworkError {
    #[error("Connection failed to {addr}: {reason}")]
    ConnectionFailed {
        addr: SocketAddr,
        reason: Cow<'static, str>,
    },

    #[error("Connection closed unexpectedly for peer: {peer_id}")]
    ConnectionClosed { peer_id: Cow<'static, str> },

    #[error("Invalid network address: {0}")]
    InvalidAddress(Cow<'static, str>),

    #[error("Peer not found: {0}")]
    PeerNotFound(Cow<'static, str>),

    #[error("Peer blocked (trust below threshold): {0}")]
    PeerBlocked(crate::PeerId),

    #[error("Peer disconnected - peer: {peer}, reason: {reason}")]
    PeerDisconnected { peer: crate::PeerId, reason: String },

    #[error("Network timeout")]
    Timeout,

    #[error("Too many connections")]
    TooManyConnections,

    #[error("Protocol error: {0}")]
    ProtocolError(Cow<'static, str>),

    #[error("Operation cancelled (peer blocked): {0}")]
    OperationCancelled(crate::PeerId),

    #[error("Bind error: {0}")]
    BindError(Cow<'static, str>),
}

/// DHT-related errors
#[derive(Debug, Error)]
pub enum DhtError {
    #[error("Key not found: {0}")]
    KeyNotFound(Cow<'static, str>),

    #[error("Store operation failed: {0}")]
    StoreFailed(Cow<'static, str>),

    #[error("Invalid key format: {0}")]
    InvalidKey(Cow<'static, str>),

    #[error("Routing table full")]
    RoutingTableFull,

    #[error("No suitable peers found")]
    NoPeersFound,

    #[error("Query timeout")]
    QueryTimeout,

    #[error("Routing error: {0}")]
    RoutingError(Cow<'static, str>),

    #[error("Operation failed: {0}")]
    OperationFailed(Cow<'static, str>),

    #[error("Insufficient peers: {0}")]
    InsufficientPeers(Cow<'static, str>),
}

/// Identity-related errors
#[derive(Debug, Error)]
pub enum IdentityError {
    #[error("Invalid three-word address: {0}")]
    InvalidThreeWordAddress(Cow<'static, str>),

    #[error("Identity not found: {0}")]
    IdentityNotFound(Cow<'static, str>),

    #[error("Identity already exists: {0}")]
    IdentityExists(Cow<'static, str>),

    #[error("Invalid signature")]
    InvalidSignature,

    #[error("Invalid canonical bytes")]
    InvalidCanonicalBytes,

    #[error("Membership conflict")]
    MembershipConflict,

    #[error("Missing group key")]
    MissingGroupKey,

    #[error("Website root update refused")]
    WebsiteRootUpdateRefused,

    #[error("Key derivation failed: {0}")]
    KeyDerivationFailed(Cow<'static, str>),

    #[error("Permission denied")]
    PermissionDenied,

    #[error("Identity mismatch: expected {expected} but peer authenticated as {actual}")]
    IdentityMismatch {
        expected: Cow<'static, str>,
        actual: Cow<'static, str>,
    },

    #[error("Invalid peer ID: {0}")]
    InvalidPeerId(Cow<'static, str>),

    #[error("Invalid format: {0}")]
    InvalidFormat(Cow<'static, str>),

    #[error("System time error: {0}")]
    SystemTime(Cow<'static, str>),

    #[error("Not found: {0}")]
    NotFound(Cow<'static, str>),

    #[error("Verification failed: {0}")]
    VerificationFailed(Cow<'static, str>),

    #[error("Insufficient entropy")]
    InsufficientEntropy,

    #[error("Access denied: {0}")]
    AccessDenied(Cow<'static, str>),
}

/// Cryptography-related errors
#[derive(Debug, Error)]
pub enum CryptoError {
    #[error("Encryption failed: {0}")]
    EncryptionFailed(Cow<'static, str>),

    #[error("Decryption failed: {0}")]
    DecryptionFailed(Cow<'static, str>),

    #[error("Invalid key length: expected {expected}, got {actual}")]
    InvalidKeyLength { expected: usize, actual: usize },

    #[error("Signature verification failed")]
    SignatureVerificationFailed,

    #[error("Key generation failed: {0}")]
    KeyGenerationFailed(Cow<'static, str>),

    #[error("Invalid public key")]
    InvalidPublicKey,

    #[error("Invalid private key")]
    InvalidPrivateKey,

    #[error("HKDF expansion failed: {0}")]
    HkdfError(Cow<'static, str>),
}

/// State management errors (lock failures, data integrity, file I/O)
#[derive(Debug, Error)]
pub enum StateError {
    #[error("Database error: {0}")]
    Database(Cow<'static, str>),

    #[error("Disk full")]
    DiskFull,

    #[error("Corrupt data: {0}")]
    CorruptData(Cow<'static, str>),

    #[error("Storage path not found: {0}")]
    PathNotFound(Cow<'static, str>),

    #[error("Permission denied: {0}")]
    PermissionDenied(Cow<'static, str>),

    #[error("Lock acquisition failed")]
    LockFailed,

    #[error("Lock poisoned: {0}")]
    LockPoisoned(Cow<'static, str>),

    #[error("File not found: {0}")]
    FileNotFound(Cow<'static, str>),

    #[error("Corruption detected: {0}")]
    CorruptionDetected(Cow<'static, str>),
}

/// Transport-related errors
#[derive(Debug, Error)]
pub enum TransportError {
    #[error("QUIC error: {0}")]
    Quic(Cow<'static, str>),

    #[error("TCP error: {0}")]
    Tcp(Cow<'static, str>),

    #[error("Invalid transport configuration: {0}")]
    InvalidConfig(Cow<'static, str>),

    #[error("Transport not supported: {0}")]
    NotSupported(Cow<'static, str>),

    #[error("Stream error: {0}")]
    StreamError(Cow<'static, str>),

    #[error("Certificate error: {0}")]
    CertificateError(Cow<'static, str>),

    #[error("Setup failed: {0}")]
    SetupFailed(Cow<'static, str>),

    #[error("Connection failed to {addr}: {reason}")]
    ConnectionFailed {
        addr: SocketAddr,
        reason: Cow<'static, str>,
    },

    #[error("Bind error: {0}")]
    BindError(Cow<'static, str>),

    #[error("Accept failed: {0}")]
    AcceptFailed(Cow<'static, str>),

    #[error("Not listening")]
    NotListening,

    #[error("Not initialized")]
    NotInitialized,
}

/// Security-related errors
#[derive(Debug, Error)]
pub enum SecurityError {
    #[error("Authentication failed")]
    AuthenticationFailed,

    #[error("Authorization denied")]
    AuthorizationDenied,

    #[error("Invalid credentials")]
    InvalidCredentials,

    #[error("Certificate error: {0}")]
    CertificateError(Cow<'static, str>),

    #[error("Encryption failed: {0}")]
    EncryptionFailed(Cow<'static, str>),

    #[error("Decryption failed: {0}")]
    DecryptionFailed(Cow<'static, str>),

    #[error("Invalid key: {0}")]
    InvalidKey(Cow<'static, str>),

    #[error("Signature verification failed: {0}")]
    SignatureVerificationFailed(Cow<'static, str>),

    #[error("Key generation failed: {0}")]
    KeyGenerationFailed(Cow<'static, str>),

    #[error("Authorization failed: {0}")]
    AuthorizationFailed(Cow<'static, str>),
}

/// Bootstrap-related errors
#[derive(Debug, Error)]
pub enum BootstrapError {
    #[error("No bootstrap nodes available")]
    NoBootstrapNodes,

    #[error("Bootstrap failed: {0}")]
    BootstrapFailed(Cow<'static, str>),

    #[error("Invalid bootstrap node: {0}")]
    InvalidBootstrapNode(Cow<'static, str>),

    #[error("Bootstrap timeout")]
    BootstrapTimeout,

    #[error("Cache error: {0}")]
    CacheError(Cow<'static, str>),

    #[error("Invalid data: {0}")]
    InvalidData(Cow<'static, str>),

    #[error("Rate limited: {0}")]
    RateLimited(Cow<'static, str>),
}

/// Geographic validation errors for connection rejection
#[derive(Debug, Error, Clone)]
pub enum GeoRejectionError {
    #[error("Peer from blocked region: {0}")]
    BlockedRegion(String),

    #[error("Geographic diversity violation in region {region} (ratio: {current_ratio:.1}%)")]
    DiversityViolation { region: String, current_ratio: f64 },
}

/// Geographic enforcement mode
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum GeoEnforcementMode {
    /// Strict mode - reject connections that violate rules
    #[default]
    Strict,
}

/// Configuration for geographic diversity enforcement
#[derive(Debug, Clone)]
pub struct GeographicConfig {
    /// Maximum ratio of peers from a single region (default: 0.4 = 40%)
    pub max_single_region_ratio: f64,
    /// Regions to outright block
    pub blocked_regions: Vec<String>,
    /// Enforcement mode
    pub enforcement_mode: GeoEnforcementMode,
}

impl Default for GeographicConfig {
    fn default() -> Self {
        Self {
            max_single_region_ratio: 0.4,
            blocked_regions: Vec::new(),
            enforcement_mode: GeoEnforcementMode::Strict,
        }
    }
}

/// Result type alias for P2P operations
pub type P2pResult<T> = Result<T, P2PError>;

/// Helper functions for error creation
impl P2PError {
    /// Create a network connection error
    pub fn connection_failed(addr: SocketAddr, reason: impl Into<String>) -> Self {
        P2PError::Network(NetworkError::ConnectionFailed {
            addr,
            reason: reason.into().into(),
        })
    }

    /// Create a timeout error
    pub fn timeout(duration: Duration) -> Self {
        P2PError::Timeout(duration)
    }

    /// Create a validation error
    pub fn validation(msg: impl Into<Cow<'static, str>>) -> Self {
        P2PError::Validation(msg.into())
    }

    /// Create an internal error
    pub fn internal(msg: impl Into<Cow<'static, str>>) -> Self {
        P2PError::Internal(msg.into())
    }
}

/// Logging integration for errors
impl P2PError {
    /// Log error with appropriate level
    pub fn log(&self) {
        use tracing::{error, warn};

        match self {
            P2PError::Network(NetworkError::Timeout) | P2PError::Timeout(_) => warn!("{}", self),

            P2PError::Validation(_) => warn!("{}", self),

            _ => error!("{}", self),
        }
    }

    /// Log error with context
    pub fn log_with_context(&self, context: &str) {
        use tracing::error;
        error!("{}: {}", context, self);
    }
}

// ===== Conversion implementations =====

impl From<serde_json::Error> for P2PError {
    fn from(err: serde_json::Error) -> Self {
        P2PError::Serialization(err.to_string().into())
    }
}

impl From<postcard::Error> for P2PError {
    fn from(err: postcard::Error) -> Self {
        P2PError::Serialization(err.to_string().into())
    }
}

impl From<std::net::AddrParseError> for P2PError {
    fn from(err: std::net::AddrParseError) -> Self {
        P2PError::Network(NetworkError::InvalidAddress(err.to_string().into()))
    }
}

impl From<tokio::time::error::Elapsed> for P2PError {
    fn from(_: tokio::time::error::Elapsed) -> Self {
        P2PError::Network(NetworkError::Timeout)
    }
}

impl From<crate::adaptive::AdaptiveNetworkError> for P2PError {
    fn from(err: crate::adaptive::AdaptiveNetworkError) -> Self {
        use crate::adaptive::AdaptiveNetworkError;
        match err {
            AdaptiveNetworkError::Network(io_err) => P2PError::Io(io_err),
            AdaptiveNetworkError::Serialization(ser_err) => {
                P2PError::Serialization(ser_err.to_string().into())
            }
            AdaptiveNetworkError::Routing(msg) => {
                P2PError::Internal(format!("Routing error: {msg}").into())
            }
            AdaptiveNetworkError::Trust(msg) => {
                P2PError::Internal(format!("Trust error: {msg}").into())
            }
            AdaptiveNetworkError::Learning(msg) => {
                P2PError::Internal(format!("Learning error: {msg}").into())
            }
            AdaptiveNetworkError::Gossip(msg) => {
                P2PError::Internal(format!("Gossip error: {msg}").into())
            }
            AdaptiveNetworkError::Other(msg) => P2PError::Internal(msg.into()),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_error_display() {
        let err =
            P2PError::connection_failed("127.0.0.1:8080".parse().unwrap(), "Connection refused");
        assert_eq!(
            err.to_string(),
            "Network error: Connection failed to 127.0.0.1:8080: Connection refused"
        );
    }

    #[test]
    fn test_timeout_error() {
        let err = P2PError::timeout(Duration::from_secs(30));
        assert_eq!(err.to_string(), "Operation timed out after 30s");
    }

    #[test]
    fn test_crypto_error() {
        let err = P2PError::Crypto(CryptoError::InvalidKeyLength {
            expected: 32,
            actual: 16,
        });
        assert_eq!(
            err.to_string(),
            "Cryptography error: Invalid key length: expected 32, got 16"
        );
    }
}