alopex_core/

error.rs

//! Error and Result types for AlopexDB.
use std::path::PathBuf;
use thiserror::Error;

use crate::columnar::error::ColumnarError;

/// A convenience `Result` type.
pub type Result<T> = std::result::Result<T, Error>;

/// The error type for AlopexDB operations.
#[derive(Debug, Error)]
pub enum Error {
    /// The requested key was not found.
    #[error("key not found")]
    NotFound,

    /// The transaction has already been closed (committed or rolled back).
    #[error("transaction is closed")]
    TxnClosed,

    /// Read-only トランザクションで書き込み操作を試みた。
    #[error("transaction is read-only")]
    TxnReadOnly,

    /// A transaction conflict occurred (e.g., optimistic concurrency control failure).
    #[error("transaction conflict")]
    TxnConflict,

    /// An underlying I/O error occurred.
    #[error("io error: {0}")]
    Io(#[from] std::io::Error),

    /// The on-disk format is invalid or corrupted.
    #[error("invalid format: {0}")]
    InvalidFormat(String),

    /// A checksum validation failed.
    #[error("checksum mismatch")]
    ChecksumMismatch,

    /// WAL recovery stopped before completion.
    #[error("recovery incomplete: recovered={recovered_entries}, stop_offset={stop_offset}, reason={reason}")]
    RecoveryIncomplete {
        /// Number of entries recovered before stopping.
        recovered_entries: usize,
        /// Byte offset where recovery stopped.
        stop_offset: u64,
        /// Reason for stopping.
        reason: String,
    },

    /// On-disk segment is corrupted (e.g., checksum failure).
    #[error("corrupted segment {segment_id}: {reason}")]
    CorruptedSegment {
        /// Segment identifier.
        segment_id: u64,
        /// Reason for corruption detection.
        reason: String,
    },

    /// A vector with an unexpected dimension was provided.
    #[error("dimension mismatch: expected {expected}, got {actual}")]
    DimensionMismatch {
        /// Expected dimension.
        expected: usize,
        /// Dimension of the provided vector.
        actual: usize,
    },

    /// A metric that is not supported was requested.
    #[error("unsupported metric: {metric}")]
    UnsupportedMetric {
        /// Name of the unsupported metric.
        metric: String,
    },

    /// A vector value is invalid for the requested operation.
    #[error("invalid vector at index {index}: {reason}")]
    InvalidVector {
        /// Zero-based index of the offending vector.
        index: usize,
        /// Reason for invalidation.
        reason: String,
    },

    /// A filter expression is malformed or unsupported.
    #[error("invalid filter: {0}")]
    InvalidFilter(String),

    /// Memory usage exceeded configured limit.
    #[error("memory limit exceeded: limit={limit}, requested={requested}")]
    MemoryLimitExceeded {
        /// Maximum allowed memory (bytes).
        limit: usize,
        /// Requested memory (bytes) that triggered the limit.
        requested: usize,
    },

    /// A bounded key search inspected its maximum candidate count.
    #[error("search scan budget exceeded: limit={limit}")]
    SearchBudgetExceeded {
        /// Maximum candidate keys permitted for one page.
        limit: usize,
    },

    /// A key search page would exceed its response payload budget.
    #[error("search response size exceeded: limit={limit}, requested={requested}")]
    SearchResponseTooLarge {
        /// Maximum combined key and value bytes.
        limit: usize,
        /// Combined key and value bytes requested so far.
        requested: usize,
    },

    /// A cooperative key search cancellation was observed.
    #[error("key search cancelled")]
    SearchCancelled,

    /// External spill operation failed.
    #[error("spill failed: {reason}")]
    SpillFailed {
        /// Stable failure description.
        reason: String,
    },

    /// A DataFrame scalar cast failed.
    #[error("cast failed: from={from_type}, to={to_type}, reason={reason}")]
    CastFailed {
        /// Source type name.
        from_type: String,
        /// Target type name.
        to_type: String,
        /// Stable failure code.
        reason: String,
    },

    /// The provided path already exists and cannot be overwritten.
    #[error("path exists: {0}")]
    PathExists(PathBuf),

    /// The data directory is already open somewhere else (issue #181).
    ///
    /// Alopex's storage engine has exactly one writer per data directory: the
    /// WAL is a fixed-length ring addressed from an in-memory offset and
    /// SSTable ids come from a process-local counter, so a second writer
    /// overwrites the first one's bytes. Opening therefore takes an OS-level
    /// exclusive lock, and this is what a caller that lost the race sees.
    ///
    /// The message deliberately contains the stable, greppable phrase
    /// `already open by another process`; tests and user-facing tooling match
    /// on that substring rather than on the whole rendering, which varies with
    /// the holder diagnostics (unavailable on Windows — see 裁定 D10).
    #[error(
        "data directory {path} is already open by another process ({holder}); \
         an Alopex database can only be opened by one process at a time — \
         share it through alopex-server instead (lock file: {lock_path})"
    )]
    AlreadyOpen {
        /// The data directory that could not be opened.
        path: PathBuf,
        /// The lock file guarding it.
        lock_path: PathBuf,
        /// Best-effort description of the current holder, or `unknown`.
        holder: String,
    },

    /// An index configuration parameter is invalid.
    #[error("invalid parameter {param}: {reason}")]
    InvalidParameter {
        /// Name of the invalid parameter.
        param: String,
        /// Description of the expected range or constraint.
        reason: String,
    },

    /// An index with the requested name was not found.
    #[error("index not found: {name}")]
    IndexNotFound {
        /// Name of the missing index.
        name: String,
    },

    /// An index failed integrity checks.
    #[error("corrupted index {name}: {reason}")]
    CorruptedIndex {
        /// Name of the corrupted index.
        name: String,
        /// Description of the corruption.
        reason: String,
    },

    /// The stored index version is unsupported by this binary.
    #[error("unsupported index version: found {found}, supported {supported}")]
    UnsupportedIndexVersion {
        /// Version detected in storage.
        found: u32,
        /// Highest supported version.
        supported: u32,
    },

    /// An unknown configuration or runtime option was provided.
    #[error("unknown option: {key}")]
    UnknownOption {
        /// Name of the option.
        key: String,
    },

    /// A column type does not match the expected layout.
    #[error("invalid column type for {column}, expected {expected}")]
    InvalidColumnType {
        /// Column name.
        column: String,
        /// Expected type description.
        expected: String,
    },

    /// The index is busy and cannot serve the requested operation.
    #[error("index busy during {operation}")]
    IndexBusy {
        /// Operation that was attempted.
        operation: String,
    },

    /// Errors originating from columnar components.
    #[error("columnar error: {0}")]
    Columnar(#[from] ColumnarError),

    /// The unified `.alopex` container format rejected a read or write.
    #[error("container format error: {0}")]
    ContainerFormat(#[from] crate::storage::format::FormatError),

    /// An S3 operation failed.
    #[error("S3 error: {0}")]
    S3(String),

    /// Required credentials are missing.
    #[error("missing credentials: {0}")]
    MissingCredentials(String),
}