eidetica/backend/

errors.rs

//! Database error types for the Eidetica backend.
//!
//! This module defines structured error types for database operations,
//! providing better error context and type safety compared to string-based errors.

use thiserror::Error;

use crate::entry::ID;

/// Errors that can occur during database operations.
///
/// # Stability
///
/// - New variants may be added in minor versions (enum is `#[non_exhaustive]`)
/// - Existing variants will not be removed in minor versions
/// - Field additions/changes require a major version bump
/// - Helper methods like `is_*()` provide stable APIs
#[non_exhaustive]
#[derive(Debug, Error)]
pub enum BackendError {
    /// Another Eidetica backend already owns this storage namespace.
    #[error(
        "Eidetica storage `{namespace}` is already owned; connect through the owning Eidetica service instead"
    )]
    StorageAlreadyOwned {
        /// Credential-free description of the storage namespace.
        namespace: String,
    },
    /// The backend does not cache Store state as records.
    #[error("Store-state records are not supported by this backend")]
    StoreStateStorageUnsupported,

    /// A staging token does not identify a private unpublished build.
    #[error("Invalid or expired Store-state staging token")]
    InvalidStoreStateStagingToken,

    /// A Store-state view does not identify a published record set.
    ///
    /// The record set was cleared after the view was minted, or the view never
    /// identified a published record set. This is never a missing key or an
    /// empty page: reads against a live view still report those as
    /// `None` and empty pages.
    #[error("Store-state view is not ready (cleared or never published)")]
    InvalidStoreStateView,

    /// A published record set cannot be changed after publication.
    #[error("Published derived Store state is immutable")]
    StoreStateNamespaceImmutable,

    /// One encoded record cannot fit in a protocol frame.
    #[error("Store-state record is too large for the service protocol ({encoded_bytes} bytes)")]
    RecordTooLarge {
        /// Encoded record size rejected before transmission.
        encoded_bytes: usize,
    },

    /// Entry not found by ID.
    #[error("Entry not found: {id}")]
    EntryNotFound {
        /// The ID of the entry that was not found
        id: ID,
    },

    /// Entry failed structural validation.
    #[error("Entry {entry_id} failed validation: {reason}")]
    EntryValidationFailed {
        /// The ID of the entry that failed validation
        entry_id: ID,
        /// The reason for validation failure
        reason: String,
    },

    /// Verification status not found for entry.
    #[error("Verification status not found for entry: {id}")]
    VerificationStatusNotFound {
        /// The ID of the entry whose verification status was not found
        id: ID,
    },

    /// Entry is not part of the specified tree.
    #[error("Entry {entry_id} is not in tree {tree_id}")]
    EntryNotInTree {
        /// The ID of the entry
        entry_id: ID,
        /// The ID of the tree
        tree_id: ID,
    },

    /// Entry is not part of the specified subtree.
    #[error("Entry {entry_id} is not in subtree {subtree} of tree {tree_id}")]
    EntryNotInSubtree {
        /// The ID of the entry
        entry_id: ID,
        /// The ID of the tree
        tree_id: ID,
        /// The name of the subtree
        subtree: String,
    },

    /// Cycle detected in DAG structure.
    #[error("Cycle detected in DAG while traversing from {entry_id}")]
    CycleDetected {
        /// The entry ID where cycle was detected
        entry_id: ID,
    },

    /// No common ancestor found for given entries.
    ///
    /// This engine never produces this error: `find_merge_base` reports
    /// disjoint histories as `Ok(None)` (the empty-base merge) rather than
    /// failing. The variant is kept because peers running older versions
    /// still emit it over the service wire (see the decode table in
    /// `service::error`), and removing an existing variant is a breaking
    /// change.
    #[error("No common ancestor found for entries: {entry_ids:?}")]
    NoCommonAncestor {
        /// The entry IDs that have no common ancestor
        entry_ids: Vec<ID>,
    },

    /// Empty entry list provided where non-empty list required.
    #[error("No entry IDs provided for {operation}")]
    EmptyEntryList {
        /// The operation that required a non-empty list
        operation: String,
    },

    /// Data corruption detected during height calculation.
    #[error("Height calculation corruption: {reason}")]
    HeightCalculationCorruption {
        /// Description of the corruption detected
        reason: String,
    },

    /// Private key not found.
    #[error("Private key not found: {key_name}")]
    PrivateKeyNotFound {
        /// The name of the private key that was not found
        key_name: String,
    },

    /// Serialization failed.
    #[error("Serialization failed")]
    SerializationFailed {
        /// The underlying serialization error
        #[source]
        source: serde_json::Error,
    },

    /// Deserialization failed.
    #[error("Deserialization failed")]
    DeserializationFailed {
        /// The underlying deserialization error
        #[source]
        source: serde_json::Error,
    },

    /// File I/O error.
    #[error("File I/O error")]
    FileIo {
        /// The underlying I/O error
        #[source]
        source: std::io::Error,
    },

    /// CRDT cache operation failed.
    #[error("CRDT cache operation failed: {reason}")]
    CrdtCacheError {
        /// Description of the cache operation failure
        reason: String,
    },

    /// Database integrity violation detected.
    #[error("Database integrity violation: {reason}")]
    TreeIntegrityViolation {
        /// Description of the integrity violation
        reason: String,
    },

    /// Invalid tree reference or tree ID.
    #[error("Invalid tree reference: {tree_id}")]
    InvalidTreeReference {
        /// The invalid tree ID
        tree_id: ID,
    },

    /// Database state inconsistency detected.
    #[error("Database state inconsistency: {reason}")]
    StateInconsistency {
        /// Description of the state inconsistency
        reason: String,
    },

    /// Cache miss or cache corruption.
    #[error("Cache operation failed: {reason}")]
    CacheError {
        /// Description of the cache error
        reason: String,
    },

    /// SQL database error (sqlx).
    #[cfg(any(feature = "sqlite", feature = "postgres"))]
    #[error("SQL error: {reason}")]
    SqlxError {
        /// Description of the SQL error
        reason: String,
        /// The underlying sqlx error, if available
        #[source]
        source: Option<sqlx::Error>,
    },
}

impl BackendError {
    /// Check if this error indicates a resource was not found.
    pub fn is_not_found(&self) -> bool {
        matches!(
            self,
            BackendError::EntryNotFound { .. }
                | BackendError::VerificationStatusNotFound { .. }
                | BackendError::PrivateKeyNotFound { .. }
        )
    }

    /// Check if this error indicates a data integrity issue.
    pub fn is_integrity_error(&self) -> bool {
        matches!(
            self,
            BackendError::EntryValidationFailed { .. }
                | BackendError::CycleDetected { .. }
                | BackendError::HeightCalculationCorruption { .. }
                | BackendError::TreeIntegrityViolation { .. }
                | BackendError::StateInconsistency { .. }
        )
    }

    /// Check if this error is related to I/O operations.
    pub fn is_io_error(&self) -> bool {
        #[cfg(any(feature = "sqlite", feature = "postgres"))]
        if matches!(self, BackendError::SqlxError { .. }) {
            return true;
        }
        matches!(
            self,
            BackendError::FileIo { .. }
                | BackendError::SerializationFailed { .. }
                | BackendError::DeserializationFailed { .. }
        )
    }

    /// Check if this error is related to SQL database operations.
    #[cfg(any(feature = "sqlite", feature = "postgres"))]
    pub fn is_sql_error(&self) -> bool {
        matches!(self, BackendError::SqlxError { .. })
    }

    /// Check if this error is related to cache operations.
    pub fn is_cache_error(&self) -> bool {
        matches!(
            self,
            BackendError::CrdtCacheError { .. } | BackendError::CacheError { .. }
        )
    }

    /// Check if this error indicates a logical inconsistency.
    pub fn is_logical_error(&self) -> bool {
        matches!(
            self,
            BackendError::EntryNotInTree { .. }
                | BackendError::EntryNotInSubtree { .. }
                | BackendError::NoCommonAncestor { .. }
                | BackendError::EmptyEntryList { .. }
        )
    }

    /// Whether this error means the backend does not cache Store state as
    /// records.
    ///
    /// Only [`BackendError::StoreStateStorageUnsupported`] reports this. Every
    /// other failure — invalid tokens, invalid views, storage I/O — is genuine
    /// and must propagate, never fall back.
    pub fn is_unsupported_store_state(&self) -> bool {
        matches!(self, BackendError::StoreStateStorageUnsupported)
    }

    /// Whether this error means a Store-state view no longer identifies a
    /// published record set (cleared after minting, or never published).
    pub fn is_invalid_store_state_view(&self) -> bool {
        matches!(self, BackendError::InvalidStoreStateView)
    }

    /// Get the entry ID if this error is about a specific entry.
    pub fn entry_id(&self) -> Option<&ID> {
        match self {
            BackendError::EntryNotFound { id }
            | BackendError::VerificationStatusNotFound { id }
            | BackendError::EntryValidationFailed { entry_id: id, .. }
            | BackendError::CycleDetected { entry_id: id }
            | BackendError::EntryNotInTree { entry_id: id, .. }
            | BackendError::EntryNotInSubtree { entry_id: id, .. } => Some(id),
            _ => None,
        }
    }

    /// Get the tree ID if this error is about a specific tree.
    pub fn tree_id(&self) -> Option<&ID> {
        match self {
            BackendError::EntryNotInTree { tree_id, .. }
            | BackendError::EntryNotInSubtree { tree_id, .. }
            | BackendError::InvalidTreeReference { tree_id } => Some(tree_id),
            _ => None,
        }
    }
}

// Conversion from DatabaseError to the main Error type
impl From<BackendError> for crate::Error {
    fn from(err: BackendError) -> Self {
        // Use the new structured Backend variant
        crate::Error::Backend(Box::new(err))
    }
}

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

    #[test]
    fn test_error_helpers() {
        let err = BackendError::EntryNotFound {
            id: ID::from_bytes("test-entry"),
        };
        assert!(err.is_not_found());
        assert_eq!(err.entry_id(), Some(&ID::from_bytes("test-entry")));

        let err = BackendError::CycleDetected {
            entry_id: ID::from_bytes("cycle-entry"),
        };
        assert!(err.is_integrity_error());
        assert_eq!(err.entry_id(), Some(&ID::from_bytes("cycle-entry")));

        let err = BackendError::FileIo {
            source: std::io::Error::new(std::io::ErrorKind::NotFound, "test"),
        };
        assert!(err.is_io_error());

        let err = BackendError::CacheError {
            reason: "test".to_string(),
        };
        assert!(err.is_cache_error());

        let err = BackendError::EmptyEntryList {
            operation: "test".to_string(),
        };
        assert!(err.is_logical_error());
    }

    #[test]
    fn test_error_conversion() {
        let db_err = BackendError::EntryNotFound {
            id: ID::from_bytes("test"),
        };
        let err: crate::Error = db_err.into();
        match err {
            crate::Error::Backend(e) => match *e {
                BackendError::EntryNotFound { id } => {
                    assert_eq!(id, ID::from_bytes("test"))
                }
                _ => panic!("Unexpected error variant"),
            },
            _ => panic!("Unexpected error variant"),
        }
    }
}