//! Error codes and error values emitted by the core crate.

use std::fmt::{Display, Formatter};

use crate::request::DownloadId;

/// Standard result type returned by core APIs.
pub type Result<T> = std::result::Result<T, CoreError>;

/// Stable error categories for mapping runtime failures to RPC-facing codes.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ErrorCode {
    /// The requested operation is not supported by the current implementation.
    Unsupported,
    /// The supplied download id does not resolve to a tracked request group.
    UnknownDownload,
    /// The requested state transition is not valid for the current runtime state.
    InvalidState,
    /// The runtime is shutting down and cannot accept the requested operation.
    ShutdownInProgress,
    /// A required persistence or storage action failed.
    StorageUnavailable,
}

/// Concrete errors returned by the core engine and state surfaces.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum CoreError {
    /// The referenced download id is not present in the registry.
    UnknownDownloadId(DownloadId),
    /// The caller requested a feature that is not yet implemented.
    UnsupportedOperation(&'static str),
    /// The caller requested an invalid state transition or runtime action.
    InvalidState(&'static str),
    /// Shutdown has started and the runtime is no longer accepting work.
    ShutdownInProgress,
    /// Session or control-file storage was unavailable.
    StorageUnavailable(&'static str),
}

impl CoreError {
    /// Returns the stable error code associated with this error value.
    #[must_use]
    pub const fn code(&self) -> ErrorCode {
        match self {
            Self::UnknownDownloadId(_) => ErrorCode::UnknownDownload,
            Self::UnsupportedOperation(_) => ErrorCode::Unsupported,
            Self::InvalidState(_) => ErrorCode::InvalidState,
            Self::ShutdownInProgress => ErrorCode::ShutdownInProgress,
            Self::StorageUnavailable(_) => ErrorCode::StorageUnavailable,
        }
    }
}

impl Display for CoreError {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::UnknownDownloadId(gid) => write!(f, "unknown download id: {gid}"),
            Self::UnsupportedOperation(msg) => write!(f, "unsupported operation: {msg}"),
            Self::InvalidState(msg) => write!(f, "invalid runtime state: {msg}"),
            Self::ShutdownInProgress => write!(f, "engine shutdown is in progress"),
            Self::StorageUnavailable(msg) => write!(f, "storage unavailable: {msg}"),
        }
    }
}

impl std::error::Error for CoreError {}