rockraft 0.1.6

//! Error handling for RockRaft
//!
//! This module provides a unified error type that hides internal complexity
//! behind a simple, user-facing interface.

use std::error::Error as StdError;
use std::fmt;
use std::fmt::Display;
use std::fmt::Formatter;
use std::io;
use std::result::Result as StdResult;

/// Public error type for RockRaft operations
///
/// This is a deep module: it presents a simple interface (just `is_retryable()`)
/// while internally handling complex error categorization and conversion.
#[derive(Debug)]
pub struct Error {
  kind: ErrorKind,
  source: Option<Box<dyn StdError + Send + Sync>>,
}

impl Error {
  /// Check if this error is retryable
  ///
  /// This is the primary decision point for error handling:
  /// - `true`: Temporary issue (leader election, network glitch), retry the operation
  /// - `false`: Permanent issue (config error, internal bug), don't retry
  pub fn is_retryable(&self) -> bool {
    matches!(self.kind, ErrorKind::Retryable { .. })
  }

  /// Get the error kind
  pub fn kind(&self) -> &ErrorKind {
    &self.kind
  }

  // Internal constructors

  /// Create a retryable error
  pub(crate) fn retryable<E>(source: E) -> Self
  where
    E: StdError + Send + Sync + 'static,
  {
    Self {
      kind: ErrorKind::Retryable {
        reason: RetryReason::Transient,
      },
      source: Some(Box::new(source)),
    }
  }

  /// Create a retryable error with specific reason
  pub(crate) fn retryable_with_reason(reason: RetryReason) -> Self {
    Self {
      kind: ErrorKind::Retryable { reason },
      source: None,
    }
  }

  /// Create a configuration error
  pub(crate) fn config(msg: impl Into<String>) -> Self {
    Self {
      kind: ErrorKind::InvalidConfig(msg.into()),
      source: None,
    }
  }

  /// Create an internal error
  pub(crate) fn internal(msg: impl Into<String>) -> Self {
    Self {
      kind: ErrorKind::Internal(msg.into()),
      source: None,
    }
  }

  /// Create an internal error with source
  pub(crate) fn internal_with_source<E>(msg: impl Into<String>, source: E) -> Self
  where
    E: StdError + Send + Sync + 'static,
  {
    Self {
      kind: ErrorKind::Internal(msg.into()),
      source: Some(Box::new(source)),
    }
  }
}

impl Display for Error {
  fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
    write!(f, "{}", self.kind)?;
    if let Some(ref source) = self.source {
      write!(f, ": {}", source)?;
    }
    Ok(())
  }
}

impl StdError for Error {
  fn source(&self) -> Option<&(dyn StdError + 'static)> {
    self.source.as_ref().map(|s| s.as_ref() as _)
  }
}

/// Error classification - tells users how to handle the error
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ErrorKind {
  /// Temporary error that may resolve on retry
  ///
  /// Examples: leader election in progress, temporary network partition,
  /// connection refused while node is starting up
  Retryable { reason: RetryReason },

  /// Configuration error - check your settings
  ///
  /// Examples: invalid endpoint format, missing required config,
  /// node ID mismatch
  InvalidConfig(String),

  /// Internal error - typically indicates a bug
  ///
  /// Examples: serialization failure, storage corruption,
  /// invariant violation
  Internal(String),
}

impl Display for ErrorKind {
  fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
    match self {
      ErrorKind::Retryable { reason } => write!(f, "retryable error: {}", reason),
      ErrorKind::InvalidConfig(msg) => write!(f, "configuration error: {}", msg),
      ErrorKind::Internal(msg) => write!(f, "internal error: {}", msg),
    }
  }
}

/// Specific reasons for retryable errors
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum RetryReason {
  /// No leader currently elected
  NoLeader,
  /// Leader is changing
  LeaderTransition,
  /// Temporary network issue
  Transient,
  /// Target node is still starting up
  NodeStarting,
}

impl Display for RetryReason {
  fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
    match self {
      RetryReason::NoLeader => write!(f, "no leader available"),
      RetryReason::LeaderTransition => write!(f, "leader transition in progress"),
      RetryReason::Transient => write!(f, "temporary failure"),
      RetryReason::NodeStarting => write!(f, "target node is starting"),
    }
  }
}

/// Result type alias for RockRaft operations
pub type Result<T> = StdResult<T, Error>;

// =============================================================================
// Internal error types - not exported, used for module-internal conversions
// =============================================================================

/// Internal API errors from Raft operations
#[derive(Debug, thiserror::Error, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum ApiError {
  #[error("cannot forward request: {0}")]
  CannotForward(String),

  #[error("forward to leader")]
  ForwardToLeader { leader_id: Option<u64> },
}

impl ApiError {
  /// Check if this API error is retryable
  pub(crate) fn is_retryable(&self) -> bool {
    matches!(
      self,
      ApiError::CannotForward(_) | ApiError::ForwardToLeader { .. }
    )
  }
}

impl From<ApiError> for Error {
  fn from(e: ApiError) -> Self {
    if e.is_retryable() {
      let reason = match &e {
        ApiError::ForwardToLeader { .. } => RetryReason::LeaderTransition,
        _ => RetryReason::Transient,
      };
      Self {
        kind: ErrorKind::Retryable { reason },
        source: None,
      }
    } else {
      Self::internal(e.to_string())
    }
  }
}

// =============================================================================
// Conversions from external error types
// =============================================================================

impl From<io::Error> for Error {
  fn from(e: io::Error) -> Self {
    // IO errors are generally retryable (network issues, etc.)
    Self::retryable(e)
  }
}

impl From<tonic::transport::Error> for Error {
  fn from(e: tonic::transport::Error) -> Self {
    Self::retryable(e)
  }
}

impl From<tonic::Status> for Error {
  fn from(status: tonic::Status) -> Self {
    match status.code() {
      // Unavailable = service temporarily down, retryable
      tonic::Code::Unavailable => Self::retryable_with_reason(RetryReason::Transient),
      // Invalid argument = config issue
      tonic::Code::InvalidArgument => Self::config(status.message()),
      // Everything else = internal error
      _ => Self::internal(format!("gRPC error: {}", status)),
    }
  }
}

impl From<postcard::Error> for Error {
  fn from(e: postcard::Error) -> Self {
    // Serialization errors are typically internal bugs
    Self::internal_with_source("serialization failed", e)
  }
}

// =============================================================================
// Legacy type aliases for backward compatibility during migration
// =============================================================================

/// Deprecated: Use `Error` instead
pub type RockRaftError = Error;

/// Deprecated: Use `Result<T>` instead
pub type RockRaftResult<T> = Result<T>;