icydb 0.252.11

//! Module: error
//!
//! Responsibility: public typed error payloads and facade error category mapping.
//! Does not own: internal error construction or accepted constraint authority.
//! Boundary: maps core diagnostics to canister-facing Candid error records.

#[cfg(test)]
mod tests;

use std::fmt;

use candid::CandidType;
use icydb_core::db::QueryError;
use icydb_core::error::{ErrorOrigin as CoreErrorOrigin, InternalError};
use serde::Deserialize;

use crate::db::DatabaseBootstrapError;

pub use icydb_core::error::{
    ConstraintValidationFindingOutput, ConstraintValuePath, ConstraintValuePathComponent,
};

//
// DiagnosticFact
//

/// One bounded numeric parameter attached to a public IcyDB error.
///
/// The leaf error code owns the reason. Facts contain only production-safe
/// numeric parameters interpreted together with that code.
#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq)]
pub struct DiagnosticFact {
    tag: u8,
    value: u64,
}

impl DiagnosticFact {
    const fn from_numeric(tag: icydb_diagnostic_code::DiagnosticFactTag, value: u64) -> Self {
        Self {
            tag: tag.raw(),
            value,
        }
    }

    /// Return the stable numeric fact-tag identity.
    #[must_use]
    pub const fn tag(&self) -> u8 {
        self.tag
    }

    /// Return the numeric fact value.
    #[must_use]
    pub const fn value(&self) -> u64 {
        self.value
    }
}

//
// QueryFieldDiagnostic
//

/// One bounded rejected query-field reference attached to a planning error.
#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
pub struct QueryFieldDiagnostic {
    role: u8,
    field: String,
}

impl QueryFieldDiagnostic {
    fn from_core(role: icydb_diagnostic_code::QueryFieldRole, field: &str) -> Self {
        Self {
            role: role.raw(),
            field: field.to_owned(),
        }
    }

    /// Return the raw compact role identity.
    #[must_use]
    pub const fn role(&self) -> u8 {
        self.role
    }

    /// Return the known typed role, or `None` for malformed decoded context.
    #[must_use]
    pub const fn known_role(&self) -> Option<icydb_diagnostic_code::QueryFieldRole> {
        icydb_diagnostic_code::QueryFieldRole::known(self.role)
    }

    /// Borrow the exact post-normalization rejected field reference.
    #[must_use]
    pub const fn field(&self) -> &str {
        self.field.as_str()
    }
}

//
// Error
//

#[cfg_attr(doc, doc = "Error\n\nPublic error payload.")]
#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
pub struct Error {
    code: u16,
    class: u8,
    origin: u8,
    facts: Vec<DiagnosticFact>,
    query_field: Option<QueryFieldDiagnostic>,
}

impl Error {
    /// Build a compact public error from one diagnostic code and origin.
    #[must_use]
    pub const fn from_code(
        code: icydb_diagnostic_code::DiagnosticCode,
        origin: ErrorOrigin,
    ) -> Self {
        Self::from_error_code(code.error_code(), origin)
    }

    /// Build a public error from one numeric wire code and origin.
    #[must_use]
    pub const fn from_error_code(
        code: icydb_diagnostic_code::ErrorCode,
        origin: ErrorOrigin,
    ) -> Self {
        Self {
            code: code.raw(),
            class: code.class().wire_code(),
            origin: origin.wire_code(),
            facts: Vec::new(),
            query_field: None,
        }
    }

    /// Build a compact public error from one public category and origin.
    ///
    /// This helper keeps generated endpoint code concise while the wire
    /// payload itself remains code/detail-first.
    #[must_use]
    pub const fn from_kind(kind: ErrorKind, origin: ErrorOrigin) -> Self {
        let code = kind.diagnostic_code();
        let error_code =
            icydb_diagnostic_code::ErrorCode::from_parts(code, Some(kind.diagnostic_detail()));

        Self::from_error_code(error_code, origin)
    }

    /// Build a compact public runtime-boundary error.
    #[must_use]
    pub const fn from_runtime_boundary(
        boundary: icydb_diagnostic_code::RuntimeBoundaryCode,
        origin: ErrorOrigin,
    ) -> Self {
        let detail = icydb_diagnostic_code::DiagnosticDetail::RuntimeBoundary { boundary };
        let error_code =
            icydb_diagnostic_code::ErrorCode::from_parts(detail.diagnostic_code(), Some(detail));

        Self::from_error_code(error_code, origin)
    }

    /// Build a compact public error from a full diagnostic payload.
    #[must_use]
    pub fn from_diagnostic(diagnostic: icydb_diagnostic_code::Diagnostic) -> Self {
        Self::from_error_code(diagnostic.error_code(), diagnostic.origin().into())
    }

    fn from_internal_error(err: &InternalError) -> Self {
        Self::from_diagnostic_and_facts(err.diagnostic(), err.diagnostic_facts())
    }

    pub(crate) fn from_diagnostic_and_facts(
        diagnostic: icydb_diagnostic_code::Diagnostic,
        facts: Vec<(icydb_diagnostic_code::DiagnosticFactTag, u64)>,
    ) -> Self {
        Self::from_diagnostic_facts_and_query_field(diagnostic, facts, None)
    }

    fn from_diagnostic_facts_and_query_field(
        diagnostic: icydb_diagnostic_code::Diagnostic,
        facts: Vec<(icydb_diagnostic_code::DiagnosticFactTag, u64)>,
        query_field: Option<(icydb_diagnostic_code::QueryFieldRole, &str)>,
    ) -> Self {
        if icydb_diagnostic_code::validate_known_diagnostic_fact_schema(
            diagnostic.error_code(),
            facts.as_slice(),
        )
        .is_err()
        {
            return Self::from_kind(
                ErrorKind::Runtime(RuntimeErrorKind::InvariantViolation),
                diagnostic.origin().into(),
            );
        }

        if let Some((role, field)) = query_field
            && icydb_diagnostic_code::validate_query_field_schema(
                diagnostic.error_code(),
                role.raw(),
                field,
            )
            .is_err()
        {
            return Self::from_kind(
                ErrorKind::Runtime(RuntimeErrorKind::InvariantViolation),
                diagnostic.origin().into(),
            );
        }

        let mut error = Self::from_diagnostic(diagnostic);
        error.facts = facts
            .into_iter()
            .map(|(tag, value)| DiagnosticFact::from_numeric(tag, value))
            .collect();
        error.query_field =
            query_field.map(|(role, field)| QueryFieldDiagnostic::from_core(role, field));
        error
    }

    /// Return the compact diagnostic code.
    #[must_use]
    pub const fn code(&self) -> icydb_diagnostic_code::ErrorCode {
        icydb_diagnostic_code::ErrorCode::from_raw(self.code)
    }

    /// Return the broad compact diagnostic class.
    #[must_use]
    pub const fn class(&self) -> icydb_diagnostic_code::ErrorClass {
        match icydb_diagnostic_code::ErrorClass::from_wire_code(self.class) {
            Some(class) => class,
            None => self.code().class(),
        }
    }

    /// Return the diagnostic origin.
    #[must_use]
    pub const fn origin(&self) -> ErrorOrigin {
        ErrorOrigin::from_wire_code(self.origin)
    }

    /// Return compact diagnostic identity for this error.
    #[must_use]
    pub fn diagnostic(&self) -> icydb_diagnostic_code::Diagnostic {
        self.code().diagnostic(self.origin().into())
    }

    /// Return the compact diagnostic code for this error.
    #[must_use]
    pub const fn diagnostic_code(&self) -> icydb_diagnostic_code::DiagnosticCode {
        self.code().diagnostic_code()
    }

    /// Borrow the bounded numeric facts carried by this error.
    #[must_use]
    pub const fn facts(&self) -> &[DiagnosticFact] {
        self.facts.as_slice()
    }

    /// Borrow the raw optional query-field context.
    #[must_use]
    pub const fn query_field(&self) -> Option<&QueryFieldDiagnostic> {
        self.query_field.as_ref()
    }

    /// Validate and borrow the optional query-field context.
    ///
    /// Decoded client data remains untrusted until this check succeeds.
    pub fn validated_query_field(
        &self,
    ) -> Result<
        Option<(icydb_diagnostic_code::QueryFieldRole, &str)>,
        icydb_diagnostic_code::QueryFieldSchemaMismatch,
    > {
        let Some(context) = self.query_field.as_ref() else {
            return Ok(None);
        };
        let role = icydb_diagnostic_code::validate_query_field_schema(
            self.code(),
            context.role,
            context.field.as_str(),
        )?;

        Ok(Some((role, context.field.as_str())))
    }

    pub(crate) fn core_facts(
        &self,
    ) -> Option<Vec<(icydb_diagnostic_code::DiagnosticFactTag, u64)>> {
        self.facts
            .iter()
            .map(|fact| {
                icydb_diagnostic_code::DiagnosticFactTag::known(fact.tag)
                    .map(|tag| (tag, fact.value))
            })
            .collect()
    }
}

impl From<InternalError> for Error {
    fn from(err: InternalError) -> Self {
        Self::from_internal_error(&err)
    }
}

impl From<QueryError> for Error {
    fn from(err: QueryError) -> Self {
        Self::from_diagnostic_facts_and_query_field(
            err.diagnostic(),
            err.diagnostic_facts(),
            err.query_field_context(),
        )
    }
}

impl From<DatabaseBootstrapError> for Error {
    fn from(_err: DatabaseBootstrapError) -> Self {
        Self::from_kind(
            ErrorKind::Runtime(RuntimeErrorKind::Internal),
            ErrorOrigin::Runtime,
        )
    }
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "E{}", self.code)
    }
}

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

#[cfg_attr(doc, doc = "ErrorKind\n\nPublic error category.")]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ErrorKind {
    Query(QueryErrorKind),

    /// Runtime failure.
    Runtime(RuntimeErrorKind),
}

impl ErrorKind {
    /// Return the compact diagnostic code for this public error category.
    #[must_use]
    pub const fn diagnostic_code(self) -> icydb_diagnostic_code::DiagnosticCode {
        match self {
            Self::Query(kind) => kind.diagnostic_code(),
            Self::Runtime(kind) => kind.diagnostic_code(),
        }
    }

    const fn diagnostic_detail(self) -> icydb_diagnostic_code::DiagnosticDetail {
        match self {
            Self::Query(kind) => icydb_diagnostic_code::DiagnosticDetail::QueryKind {
                kind: kind.diagnostic_kind(),
            },
            Self::Runtime(kind) => icydb_diagnostic_code::DiagnosticDetail::RuntimeKind {
                kind: kind.diagnostic_kind(),
            },
        }
    }
}

#[cfg_attr(doc, doc = "RuntimeErrorKind\n\nPublic runtime error class.")]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum RuntimeErrorKind {
    Corruption,
    IncompatiblePersistedFormat,
    InvariantViolation,
    Conflict,
    NotFound,
    Unsupported,
    Internal,
}

impl RuntimeErrorKind {
    /// Return the compact diagnostic code for this runtime category.
    #[must_use]
    pub const fn diagnostic_code(self) -> icydb_diagnostic_code::DiagnosticCode {
        match self {
            Self::Corruption => icydb_diagnostic_code::DiagnosticCode::RuntimeCorruption,
            Self::IncompatiblePersistedFormat => {
                icydb_diagnostic_code::DiagnosticCode::RuntimeIncompatiblePersistedFormat
            }
            Self::InvariantViolation => {
                icydb_diagnostic_code::DiagnosticCode::RuntimeInvariantViolation
            }
            Self::Conflict => icydb_diagnostic_code::DiagnosticCode::RuntimeConflict,
            Self::NotFound => icydb_diagnostic_code::DiagnosticCode::RuntimeNotFound,
            Self::Unsupported => icydb_diagnostic_code::DiagnosticCode::RuntimeUnsupported,
            Self::Internal => icydb_diagnostic_code::DiagnosticCode::RuntimeInternal,
        }
    }

    const fn diagnostic_kind(self) -> icydb_diagnostic_code::RuntimeErrorKind {
        match self {
            Self::Corruption => icydb_diagnostic_code::RuntimeErrorKind::Corruption,
            Self::IncompatiblePersistedFormat => {
                icydb_diagnostic_code::RuntimeErrorKind::IncompatiblePersistedFormat
            }
            Self::InvariantViolation => icydb_diagnostic_code::RuntimeErrorKind::InvariantViolation,
            Self::Conflict => icydb_diagnostic_code::RuntimeErrorKind::Conflict,
            Self::NotFound => icydb_diagnostic_code::RuntimeErrorKind::NotFound,
            Self::Unsupported => icydb_diagnostic_code::RuntimeErrorKind::Unsupported,
            Self::Internal => icydb_diagnostic_code::RuntimeErrorKind::Internal,
        }
    }
}

#[cfg_attr(doc, doc = "QueryErrorKind\n\nPublic query error class.")]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum QueryErrorKind {
    /// Validation failed.
    Validate,

    /// Intent validation failed.
    Intent,

    /// Planning failed.
    Plan,

    /// Pagination lacked ordering.
    UnorderedPagination,

    /// Continuation cursor was invalid.
    InvalidContinuationCursor,

    /// No rows matched.
    NotFound,

    /// More than one row matched.
    NotUnique,
}

impl QueryErrorKind {
    /// Return the compact diagnostic code for this query category.
    #[must_use]
    pub const fn diagnostic_code(self) -> icydb_diagnostic_code::DiagnosticCode {
        match self {
            Self::Validate => icydb_diagnostic_code::DiagnosticCode::QueryValidate,
            Self::Intent => icydb_diagnostic_code::DiagnosticCode::QueryIntent,
            Self::Plan => icydb_diagnostic_code::DiagnosticCode::QueryPlan,
            Self::UnorderedPagination => {
                icydb_diagnostic_code::DiagnosticCode::QueryUnorderedPagination
            }
            Self::InvalidContinuationCursor => {
                icydb_diagnostic_code::DiagnosticCode::QueryInvalidContinuationCursor
            }
            Self::NotFound => icydb_diagnostic_code::DiagnosticCode::QueryNotFound,
            Self::NotUnique => icydb_diagnostic_code::DiagnosticCode::QueryNotUnique,
        }
    }

    const fn diagnostic_kind(self) -> icydb_diagnostic_code::QueryErrorKind {
        match self {
            Self::Validate => icydb_diagnostic_code::QueryErrorKind::Validate,
            Self::Intent => icydb_diagnostic_code::QueryErrorKind::Intent,
            Self::Plan => icydb_diagnostic_code::QueryErrorKind::Plan,
            Self::UnorderedPagination => icydb_diagnostic_code::QueryErrorKind::UnorderedPagination,
            Self::InvalidContinuationCursor => {
                icydb_diagnostic_code::QueryErrorKind::InvalidContinuationCursor
            }
            Self::NotFound => icydb_diagnostic_code::QueryErrorKind::NotFound,
            Self::NotUnique => icydb_diagnostic_code::QueryErrorKind::NotUnique,
        }
    }
}

#[cfg_attr(doc, doc = "ErrorOrigin\n\nPublic error origin.")]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ErrorOrigin {
    Cursor,
    Executor,
    Identity,
    Index,
    Interface,
    Planner,
    Query,
    Recovery,
    Response,
    Runtime,
    Serialize,
    Store,
}

impl ErrorOrigin {
    const fn wire_code(self) -> u8 {
        match self {
            Self::Cursor => icydb_diagnostic_code::ErrorOrigin::Cursor.wire_code(),
            Self::Executor => icydb_diagnostic_code::ErrorOrigin::Executor.wire_code(),
            Self::Identity => icydb_diagnostic_code::ErrorOrigin::Identity.wire_code(),
            Self::Index => icydb_diagnostic_code::ErrorOrigin::Index.wire_code(),
            Self::Interface => icydb_diagnostic_code::ErrorOrigin::Interface.wire_code(),
            Self::Planner => icydb_diagnostic_code::ErrorOrigin::Planner.wire_code(),
            Self::Query => icydb_diagnostic_code::ErrorOrigin::Query.wire_code(),
            Self::Recovery => icydb_diagnostic_code::ErrorOrigin::Recovery.wire_code(),
            Self::Response => icydb_diagnostic_code::ErrorOrigin::Response.wire_code(),
            Self::Runtime => icydb_diagnostic_code::ErrorOrigin::Runtime.wire_code(),
            Self::Serialize => icydb_diagnostic_code::ErrorOrigin::Serialize.wire_code(),
            Self::Store => icydb_diagnostic_code::ErrorOrigin::Store.wire_code(),
        }
    }

    const fn from_wire_code(code: u8) -> Self {
        match icydb_diagnostic_code::ErrorOrigin::from_wire_code(code) {
            icydb_diagnostic_code::ErrorOrigin::Cursor => Self::Cursor,
            icydb_diagnostic_code::ErrorOrigin::Executor => Self::Executor,
            icydb_diagnostic_code::ErrorOrigin::Identity => Self::Identity,
            icydb_diagnostic_code::ErrorOrigin::Index => Self::Index,
            icydb_diagnostic_code::ErrorOrigin::Interface => Self::Interface,
            icydb_diagnostic_code::ErrorOrigin::Planner => Self::Planner,
            icydb_diagnostic_code::ErrorOrigin::Query => Self::Query,
            icydb_diagnostic_code::ErrorOrigin::Recovery => Self::Recovery,
            icydb_diagnostic_code::ErrorOrigin::Response => Self::Response,
            icydb_diagnostic_code::ErrorOrigin::Runtime => Self::Runtime,
            icydb_diagnostic_code::ErrorOrigin::Serialize => Self::Serialize,
            icydb_diagnostic_code::ErrorOrigin::Store => Self::Store,
        }
    }
}

impl From<CoreErrorOrigin> for ErrorOrigin {
    fn from(origin: CoreErrorOrigin) -> Self {
        match origin {
            CoreErrorOrigin::Cursor => Self::Cursor,
            CoreErrorOrigin::Executor => Self::Executor,
            CoreErrorOrigin::Identity => Self::Identity,
            CoreErrorOrigin::Index => Self::Index,
            CoreErrorOrigin::Interface => Self::Interface,
            CoreErrorOrigin::Planner => Self::Planner,
            CoreErrorOrigin::Query => Self::Query,
            CoreErrorOrigin::Recovery => Self::Recovery,
            CoreErrorOrigin::Response => Self::Response,
            CoreErrorOrigin::Serialize => Self::Serialize,
            CoreErrorOrigin::Store => Self::Store,
        }
    }
}

impl From<ErrorOrigin> for icydb_diagnostic_code::ErrorOrigin {
    fn from(origin: ErrorOrigin) -> Self {
        match origin {
            ErrorOrigin::Cursor => Self::Cursor,
            ErrorOrigin::Executor => Self::Executor,
            ErrorOrigin::Identity => Self::Identity,
            ErrorOrigin::Index => Self::Index,
            ErrorOrigin::Interface => Self::Interface,
            ErrorOrigin::Planner => Self::Planner,
            ErrorOrigin::Query => Self::Query,
            ErrorOrigin::Recovery => Self::Recovery,
            ErrorOrigin::Response => Self::Response,
            ErrorOrigin::Runtime => Self::Runtime,
            ErrorOrigin::Serialize => Self::Serialize,
            ErrorOrigin::Store => Self::Store,
        }
    }
}

impl From<icydb_diagnostic_code::ErrorOrigin> for ErrorOrigin {
    fn from(origin: icydb_diagnostic_code::ErrorOrigin) -> Self {
        match origin {
            icydb_diagnostic_code::ErrorOrigin::Cursor => Self::Cursor,
            icydb_diagnostic_code::ErrorOrigin::Executor => Self::Executor,
            icydb_diagnostic_code::ErrorOrigin::Identity => Self::Identity,
            icydb_diagnostic_code::ErrorOrigin::Index => Self::Index,
            icydb_diagnostic_code::ErrorOrigin::Interface => Self::Interface,
            icydb_diagnostic_code::ErrorOrigin::Planner => Self::Planner,
            icydb_diagnostic_code::ErrorOrigin::Query => Self::Query,
            icydb_diagnostic_code::ErrorOrigin::Recovery => Self::Recovery,
            icydb_diagnostic_code::ErrorOrigin::Response => Self::Response,
            icydb_diagnostic_code::ErrorOrigin::Runtime => Self::Runtime,
            icydb_diagnostic_code::ErrorOrigin::Serialize => Self::Serialize,
            icydb_diagnostic_code::ErrorOrigin::Store => Self::Store,
        }
    }
}