Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

7.1 KB
Raw Blame
//! Error types for RAGFS
//!
//! This module defines all error types used throughout the RAGFS system.
//! We use `thiserror` for structured error definitions to ensure type safety
//! and clear error messages.

use serde_json;
use std::io;

/// Result type alias for RAGFS operations
pub type Result<T> = std::result::Result<T, Error>;

/// Structured failure detail for one backup target in synchronous multi-write fanout.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SyncWriteFailureDetail {
    /// Logical backup backend name.
    pub backend: String,
    /// Stable error kind for programmatic inspection.
    pub kind: String,
    /// Human-readable error message including the original error display text.
    pub message: String,
}

/// Main error type for RAGFS operations
#[derive(Debug, thiserror::Error)]
pub enum Error {
    /// File or directory not found
    #[error("not found: {0}")]
    NotFound(String),

    /// File or directory already exists
    #[error("already exists: {0}")]
    AlreadyExists(String),

    /// Permission denied
    #[error("permission denied: {0}")]
    PermissionDenied(String),

    /// Invalid path
    #[error("invalid path: {0}")]
    InvalidPath(String),

    /// Not a directory
    #[error("not a directory: {0}")]
    NotADirectory(String),

    /// Is a directory (when file operation expected)
    #[error("is a directory: {0}")]
    IsADirectory(String),

    /// Directory not empty
    #[error("directory not empty: {0}")]
    DirectoryNotEmpty(String),

    /// Invalid operation
    #[error("invalid operation: {0}")]
    InvalidOperation(String),

    /// Operation is intentionally unsupported by the current protocol.
    #[error("not supported: {0}")]
    NotSupported(String),

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

    /// Plugin error
    #[error("plugin error: {0}")]
    Plugin(String),

    /// Configuration error
    #[error("configuration error: {0}")]
    Config(String),

    /// Mount point not found
    #[error("mount point not found: {0}")]
    MountPointNotFound(String),

    /// Mount point already exists
    #[error("mount point already exists: {0}")]
    MountPointExists(String),

    /// Serialization error
    #[error("serialization error: {0}")]
    Serialization(String),

    /// Network error
    #[error("network error: {0}")]
    Network(String),

    /// Timeout error
    #[error("operation timed out: {0}")]
    Timeout(String),

    /// Non-blocking operation would block and should be retried by the caller
    #[error("operation would block: {0}")]
    WouldBlock(String),

    /// Preserve acquisition failures so callers can distinguish contention from corruption.
    #[error(transparent)]
    PathLock(#[from] crate::lock::types::PathLockError),

    /// Multi-write synchronous fanout failed to reach the required acknowledgement quorum
    #[error(
        "sync write quorum failed: {succeeded}/{attempted} backups succeeded (required {required}); failures: {failures:?}"
    )]
    SyncWriteQuorum {
        /// Number of backup targets that completed successfully.
        succeeded: usize,
        /// Minimum number of backup acknowledgements required for success.
        required: usize,
        /// Total number of backup targets that were attempted.
        attempted: usize,
        /// Structured failure details for each unsuccessful backup target.
        failures: Vec<SyncWriteFailureDetail>,
    },

    /// Required filesystem context is missing from the current task
    #[error("filesystem context missing: {0}")]
    ContextMissing(String),

    /// Internal error
    #[error("internal error: {0}")]
    Internal(String),
}

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

impl Error {
    /// Create a NotFound error
    pub fn not_found(path: impl Into<String>) -> Self {
        Self::NotFound(path.into())
    }

    /// Create an AlreadyExists error
    pub fn already_exists(path: impl Into<String>) -> Self {
        Self::AlreadyExists(path.into())
    }

    /// Create a PermissionDenied error
    pub fn permission_denied(path: impl Into<String>) -> Self {
        Self::PermissionDenied(path.into())
    }

    /// Create an InvalidPath error
    pub fn invalid_path(path: impl Into<String>) -> Self {
        Self::InvalidPath(path.into())
    }

    /// Create a Plugin error
    pub fn plugin(msg: impl Into<String>) -> Self {
        Self::Plugin(msg.into())
    }

    /// Create a Config error
    pub fn config(msg: impl Into<String>) -> Self {
        Self::Config(msg.into())
    }

    /// Create an Internal error
    pub fn internal(msg: impl Into<String>) -> Self {
        Self::Internal(msg.into())
    }

    /// Create a ContextMissing error
    pub fn context_missing(msg: impl Into<String>) -> Self {
        Self::ContextMissing(msg.into())
    }

    /// Create a Timeout error
    pub fn timeout(msg: impl Into<String>) -> Self {
        Self::Timeout(msg.into())
    }

    /// Create a WouldBlock error
    pub fn would_block(msg: impl Into<String>) -> Self {
        Self::WouldBlock(msg.into())
    }

    /// Return a stable error kind name for structured reporting.
    pub fn kind_name(&self) -> &'static str {
        match self {
            Self::NotFound(_) => "not_found",
            Self::AlreadyExists(_) => "already_exists",
            Self::PermissionDenied(_) => "permission_denied",
            Self::InvalidPath(_) => "invalid_path",
            Self::NotADirectory(_) => "not_a_directory",
            Self::IsADirectory(_) => "is_a_directory",
            Self::DirectoryNotEmpty(_) => "directory_not_empty",
            Self::InvalidOperation(_) => "invalid_operation",
            Self::NotSupported(_) => "not_supported",
            Self::Io(_) => "io",
            Self::Plugin(_) => "plugin",
            Self::Config(_) => "config",
            Self::MountPointNotFound(_) => "mount_point_not_found",
            Self::MountPointExists(_) => "mount_point_exists",
            Self::Serialization(_) => "serialization",
            Self::Network(_) => "network",
            Self::Timeout(_) => "timeout",
            Self::WouldBlock(_) => "would_block",
            Self::PathLock(_) => "path_lock",
            Self::SyncWriteQuorum { .. } => "sync_write_quorum",
            Self::ContextMissing(_) => "context_missing",
            Self::Internal(_) => "internal",
        }
    }

    /// Create an InvalidOperation error
    pub fn invalid_operation(msg: impl Into<String>) -> Self {
        Self::InvalidOperation(msg.into())
    }

    /// Create a NotSupported error.
    pub fn not_supported(msg: impl Into<String>) -> Self {
        Self::NotSupported(msg.into())
    }
}

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

    #[test]
    fn test_error_creation() {
        let err = Error::not_found("/test/path");
        assert!(matches!(err, Error::NotFound(_)));
        assert_eq!(err.to_string(), "not found: /test/path");
    }

    #[test]
    fn test_error_display() {
        let err = Error::permission_denied("/protected");
        assert_eq!(err.to_string(), "permission denied: /protected");
    }
}