obj/

error.rs

//! Error-code enum + `obj_strerror`.
//!
//! Every fallible C entry point returns [`obj_error_t`] — a signed
//! `int32_t` because C99 has no `uint32_t`-typed enum constants in
//! the language proper (cbindgen emits a typedef + a set of
//! `#define`-style constants).
//!
//! The mapping from [`obj_engine::Error`] to one of these codes lives in
//! [`error_to_code`]. The match is exhaustive: if [`obj_engine::Error`]
//! gains a variant, the build fails until the mapping is updated —
//! power-of-ten Rule 7 plus a `#[non_exhaustive]` catch-all that
//! collapses unknown variants into the most defensive ([`OBJ_ERR_CORRUPTION`]).

use core::ffi::c_char;

/// Numeric type carried by `obj_error_t`. Aliased so the cbindgen
/// header emits `typedef int32_t obj_error_t;` rather than a bare
/// `int32_t` everywhere.
pub type obj_error_t = i32;

/// Operation succeeded.
pub const OBJ_OK: obj_error_t = 0;

/// Caller passed an invalid argument: a null handle / out-pointer
/// where one is required, a non-UTF-8 path or collection name, a
/// length that exceeds the documented maximum, etc.
pub const OBJ_ERR_INVALID_ARG: obj_error_t = 1;

/// Underlying I/O / syscall failure: file open, read, write, fsync,
/// directory enumeration, lock acquisition syscall.
pub const OBJ_ERR_IO: obj_error_t = 2;

/// Content-level corruption: a page CRC mismatch, malformed
/// catalog row, schema-version-from-future, B-tree invariant
/// violated, etc.
pub const OBJ_ERR_CORRUPTION: obj_error_t = 3;

/// A lock could not be acquired inside the configured timeout —
/// another transaction holds the writer mutex / cross-process
/// writer byte, or the in-process pager mutex was poisoned.
pub const OBJ_ERR_BUSY: obj_error_t = 4;

/// The requested record / index entry / collection was not found.
/// Iterators also return this when exhausted (see
/// `obj_iter_next` docs).
pub const OBJ_ERR_NOT_FOUND: obj_error_t = 5;

/// An integrity check completed and found violations. Distinct
/// from [`OBJ_ERR_CORRUPTION`] which is the hard fail-closed shape
/// emitted by individual operations; [`OBJ_ERR_INTEGRITY`] is the
/// soft "the report has failures" shape returned by aggregate
/// diagnostic calls.
pub const OBJ_ERR_INTEGRITY: obj_error_t = 6;

/// Operation is not supported in this build / for this database
/// (e.g. `obj_backup_to` on an in-memory database, an attempt to
/// mutate an attached read-only attachment, an unimplemented
/// schema migration).
pub const OBJ_ERR_UNSUPPORTED: obj_error_t = 7;

/// A C string handed across the FFI boundary was not valid UTF-8.
/// Distinct from [`OBJ_ERR_INVALID_ARG`] because UTF-8 issues are
/// frequent enough on user paths / index names to merit their own
/// signal.
pub const OBJ_ERR_UTF8: obj_error_t = 8;

/// Highest reserved code in the obj-defined range. Future error
/// codes must stay `<= OBJ_ERR_RESERVED_MAX`; this allows
/// downstream callers to reliably distinguish obj-emitted codes
/// from any they may layer on top.
pub const OBJ_ERR_RESERVED_MAX: obj_error_t = 1023;

/// Static null-terminated message used by [`obj_strerror`]. The
/// strings carry an embedded `\0` terminator so they can be
/// returned as `*const c_char` directly.
struct ErrorEntry {
    /// The associated code.
    code: obj_error_t,
    /// NUL-terminated UTF-8 bytes.
    msg: &'static [u8],
}

const ERROR_TABLE: &[ErrorEntry] = &[
    ErrorEntry {
        code: OBJ_OK,
        msg: b"OK\0",
    },
    ErrorEntry {
        code: OBJ_ERR_INVALID_ARG,
        msg: b"invalid argument\0",
    },
    ErrorEntry {
        code: OBJ_ERR_IO,
        msg: b"i/o error\0",
    },
    ErrorEntry {
        code: OBJ_ERR_CORRUPTION,
        msg: b"corruption detected\0",
    },
    ErrorEntry {
        code: OBJ_ERR_BUSY,
        msg: b"lock busy\0",
    },
    ErrorEntry {
        code: OBJ_ERR_NOT_FOUND,
        msg: b"not found\0",
    },
    ErrorEntry {
        code: OBJ_ERR_INTEGRITY,
        msg: b"integrity check failed\0",
    },
    ErrorEntry {
        code: OBJ_ERR_UNSUPPORTED,
        msg: b"operation not supported\0",
    },
    ErrorEntry {
        code: OBJ_ERR_UTF8,
        msg: b"invalid UTF-8\0",
    },
];

/// Default fallback when [`obj_strerror`] is called with an
/// unknown code. The leading `unknown:` prefix is stable enough
/// for grep-driven diagnostics.
const UNKNOWN_ERR: &[u8] = b"unknown obj_error_t\0";

/// Map an [`obj_engine::Error`] variant onto an [`obj_error_t`] code.
///
/// The match is exhaustive over the public `obj_engine::Error` enum at
/// compile time so any future variant addition fails to compile
/// here, forcing the C-ABI mapping to stay in lockstep — power-of-
/// ten Rule 7.
///
/// `#[non_exhaustive]` on `obj_engine::Error` means we must keep a final
/// catch-all arm. The defensive choice is [`OBJ_ERR_CORRUPTION`]:
/// callers who treat unknown codes as "stop and investigate" stay
/// safe even if obj-core grows a new fail-closed variant before
/// the mapping is updated.
#[must_use]
// Clippy `match_same_arms` would collapse the explicit per-
// variant arms into the wildcard, but the explicit structure
// IS the design — each new `obj_engine::Error` variant should fail to
// compile here until a maintainer decides where it slots into the
// C-ABI taxonomy. Power-of-ten Rule 7.
#[allow(clippy::match_same_arms)] // explicit variant enumeration is the design.
pub(crate) fn error_to_code(err: &obj_engine::Error) -> obj_error_t {
    use obj_engine::Error;
    match err {
        Error::Io(_) => OBJ_ERR_IO,
        Error::Corruption { .. }
        | Error::WalCorruption { .. }
        | Error::InvalidFormat { .. }
        | Error::BTreeDepthExceeded { .. }
        | Error::BTreeInvariantViolated { .. }
        | Error::CollectionIdMismatch { .. } => OBJ_ERR_CORRUPTION,
        Error::InvalidArgument(_)
        | Error::BTreeKeyTooLarge { .. }
        | Error::BTreeValueTooLarge { .. }
        | Error::BTreeKeyExists
        | Error::BTreeScanLimitExceeded { .. }
        | Error::DocumentTooLarge { .. }
        | Error::SortBufferExceeded { .. }
        | Error::SortKeyEncode { .. }
        | Error::DistinctCountExceeded { .. }
        | Error::IndexFieldMissing { .. }
        | Error::IndexFieldTypeMismatch { .. }
        | Error::IndexKindMismatch { .. }
        | Error::IndexKeyPathsMismatch { .. }
        | Error::UniqueConstraintViolation { .. }
        | Error::EachIndexTooLarge { .. }
        | Error::SchemaTypeMismatch { .. }
        | Error::SchemaDepthExceeded { .. }
        | Error::DynamicPathNotMap { .. } => OBJ_ERR_INVALID_ARG,
        Error::Codec(_) => OBJ_ERR_CORRUPTION,
        Error::Busy { .. } => OBJ_ERR_BUSY,
        Error::CollectionNotFound { .. }
        | Error::DocumentNotFound { .. }
        | Error::IndexNotFound { .. }
        | Error::IndexNotUnique { .. }
        | Error::CollectionNamespaceUnknown { .. } => OBJ_ERR_NOT_FOUND,
        Error::CollectionAlreadyExists { .. }
        | Error::IdSpaceExhausted { .. }
        | Error::ReadOnly { .. }
        | Error::SchemaMigrationNotImplemented { .. }
        | Error::SchemaVersionFromFuture { .. }
        | Error::SchemaNotRegistered { .. }
        | Error::BackupNotSupportedForMemoryPager
        | Error::AttachedDatabaseIsReadOnly { .. } => OBJ_ERR_UNSUPPORTED,
        Error::BackupDestinationExists { .. }
        | Error::AttachmentAlreadyExists { .. }
        | Error::AttachmentNotReadable { .. } => OBJ_ERR_IO,
        // `Error` is `#[non_exhaustive]`; future variants collapse
        // to the most defensive code so a C caller still sees
        // "this is bad, stop" rather than `OBJ_OK`.
        _ => OBJ_ERR_CORRUPTION,
    }
}

/// Return a static C string describing `code`. Never returns NULL.
///
/// # Safety
///
/// The returned pointer points into the read-only data segment of
/// the loaded library; it has `'static` lifetime and MUST NOT be
/// freed. It is safe to read until the dynamic library is
/// unloaded.
#[no_mangle]
pub unsafe extern "C" fn obj_strerror(code: obj_error_t) -> *const c_char {
    for entry in ERROR_TABLE {
        if entry.code == code {
            return entry.msg.as_ptr().cast::<c_char>();
        }
    }
    UNKNOWN_ERR.as_ptr().cast::<c_char>()
}