From 31942477beb7034a5487632c90daace0831b496d Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Tue, 25 Aug 2026 18:51:51 +0530 Subject: [PATCH 1/2] =?UTF-8?q?feat:=20migrate=20storage=20call=20sites=20?= =?UTF-8?q?to=20STG-0xx=20error=20codes=20=E2=80=94=20#277=20(3/6)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Part of #359 (STG sub-issue of the #277 structured error codes rollout). Migrates bail!/anyhow! call sites in src/storage/{mod,persistent_facts, btree,btree_v6,packed_pages}.rs and src/storage/backend/file.rs to bail_coded!/err_coded! with their real STG-0xx codes, matched against the 27 documented codes in docs/ERROR_REFERENCE.md. - All 27 ErrorCode::StgNNN variants + REGISTRY entries added to src/error.rs. - docs/ERROR_REFERENCE.md's STG section "Error text" lines rewritten from one-off example values to canonical {}-placeholder templates so they byte-match REGISTRY (verified by the existing sync test). - FileBackend::open_with no longer collapses a more specific header-parse failure (e.g. bad magic number) into the generic STG-010: it now propagates an existing CodedError in the chain as-is, falling back to STG-010 only for a genuinely uncoded failure. - Two bail! sites with no matching documented STG code ("Header checksum mismatch", into_backend's multiple-owners precondition) deliberately left uncoded (INT-000) rather than assigned an undocumented code. - Regression tests: 6 integration tests against the public Minigraf::open() API (tests/error_codes_storage_test.rs) plus unit tests inside the storage modules for codes only reachable below the (crate-private) storage module boundary. Not covered by a dedicated test: STG-011 (guarded by a debug_assert! that always fires first under `cargo test`), the 8 arithmetic-overflow guards STG-017–024, and STG-027 (needs an unlockable filesystem no CI runner provides) — all three categories are documented as "should not occur under normal operation" and are covered by the registry↔doc sync test. toward #277 Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01P7e4uTBWtM8fMZiPZc4bCw --- CHANGELOG.md | 28 +++ docs/ERROR_REFERENCE.md | 34 ++-- src/error.rs | 282 ++++++++++++++++++++++++++++-- src/storage/backend/file.rs | 66 +++---- src/storage/btree.rs | 32 +++- src/storage/btree_v6.rs | 69 +++++++- src/storage/mod.rs | 86 ++++++--- src/storage/packed_pages.rs | 36 +++- src/storage/persistent_facts.rs | 162 ++++++++++++++--- tests/error_codes_storage_test.rs | 138 +++++++++++++++ 10 files changed, 800 insertions(+), 133 deletions(-) create mode 100644 tests/error_codes_storage_test.rs diff --git a/CHANGELOG.md b/CHANGELOG.md index 02c3fcd2b5..aa939e5899 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -86,6 +86,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 string-matches error output is affected, including the interactive REPL's printed error messages and all 7 language-binding repos (Python, Node, WASM, Java, Android, Swift, C). +- **Storage/file-format errors now surface their real `STG-0xx` code** (#359, + part of #277's rollout): all 27 documented `STG-0xx` codes are wired up + across `src/storage/{mod,persistent_facts,btree,btree_v6,packed_pages}.rs` + and `src/storage/backend/file.rs` — header validation (`STG-001`–`STG-009`), + header re-read failures (`STG-010`), on-disk B+tree/packed-page corruption + (`STG-011`–`STG-015`), a poisoned backend mutex (`STG-016`), page-count + arithmetic overflow guards (`STG-017`–`STG-024`), and the three lock + conflict errors (`STG-025`–`STG-027`). `docs/ERROR_REFERENCE.md`'s STG + section's "Error text" lines were rewritten from one-off example values to + canonical `{}`-placeholder templates so they byte-for-byte match the + `REGISTRY` entries the sync test checks against. + `FileBackend::open_with` no longer collapses a more specific header-parse + failure (e.g. a bad magic number) into the generic `STG-010` — it now + propagates a `CodedError` already present in the chain as-is, only falling + back to `STG-010` for a genuinely uncoded (e.g. raw I/O) failure. + Not covered by a dedicated regression test: `STG-011`'s call site is + guarded by a `debug_assert!` that always fires first in a debug/test + build, so it's release-build-only and unreachable under `cargo test`; the + 8 arithmetic-overflow guards (`STG-017`–`STG-024`) and `STG-027` (a + filesystem that refuses locking outright — no CI runner provides one) are + covered by the registry↔doc sync test and code review but have no + dedicated trigger test, consistent with their own "should not occur under + normal operation" documentation. Two `bail!` sites with no matching + documented `STG` code ("Header checksum mismatch", reached on a genuine + on-disk corruption of an otherwise-valid header, and `into_backend`'s + multiple-owners precondition) were deliberately left uncoded (`INT-000`) + rather than assigned an undocumented code — left for the final API+INT + audit PR. ### Bug fixes diff --git a/docs/ERROR_REFERENCE.md b/docs/ERROR_REFERENCE.md index e039d41e19..e600b596bf 100644 --- a/docs/ERROR_REFERENCE.md +++ b/docs/ERROR_REFERENCE.md @@ -1620,7 +1620,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-001 Invalid header: too short -**Error text**: `Invalid header: too short (got 12 bytes, need 64)` +**Error text**: `Invalid header: too short (got {} bytes, need 64)` **Cause**: The `.graph` file is truncated — shorter than the minimum header size. Happens if the file was partially written (e.g. a crash during the initial `save()`) or if a non-Minigraf file was passed by mistake. @@ -1642,7 +1642,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-003 Invalid v4/v5/v6 header too short -**Error text**: `Invalid v4/v5/v6 header: expected at least 72 bytes, got 40` +**Error text**: `Invalid v4/v5/v6 header: expected at least 72 bytes, got {}` **Cause**: A file identified as format version 4, 5, or 6 is too short to hold a valid header of that version. The file is truncated at the header. @@ -1653,7 +1653,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-004 Invalid v6 header too short -**Error text**: `Invalid v6 header: expected 80 bytes, got 64` +**Error text**: `Invalid v6 header: expected 80 bytes, got {}` **Cause**: A file identified as format version 6 is shorter than the required 80-byte v6 header. The file is truncated. @@ -1664,7 +1664,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-005 Invalid v7 header too short -**Error text**: `Invalid v7 header: expected 84 bytes, got 80` +**Error text**: `Invalid v7 header: expected 84 bytes, got {}` **Cause**: A file identified as format version 7 (current format) is shorter than the required 84-byte header. The file is truncated. @@ -1675,7 +1675,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-006 Unsupported format version -**Error text**: `Unsupported format version: 8 (supported: 1-7)` +**Error text**: `Unsupported format version: {} (supported: 1-{})` **Cause**: The file was written by a newer version of Minigraf than is currently installed. The format version number in the header is outside the range this library can read. @@ -1697,7 +1697,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-008 eavt_root_page must be less than page_count -**Error text**: `eavt_root_page (500) must be less than page_count (100)` +**Error text**: `eavt_root_page ({}) must be less than page_count ({})` **Cause**: The EAVT B+tree root page index in the header points beyond the file's page count. The header is internally inconsistent — a sign of file corruption. @@ -1708,7 +1708,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-009 fact_page_count cannot exceed page_count -**Error text**: `fact_page_count (200) cannot exceed page_count (100)` +**Error text**: `fact_page_count ({}) cannot exceed page_count ({})` **Cause**: The fact page count in the header is larger than the total page count. The header is internally inconsistent. @@ -1719,7 +1719,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-010 Failed to read header from existing file -**Error text**: `Failed to read header from existing file: permission denied` +**Error text**: `Failed to read header from existing file: {}` **Cause**: A low-level I/O error prevented reading the file header. Common causes: file permissions, file moved or deleted between open and read, disk I/O error. @@ -1741,7 +1741,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-012 Expected index page at page N -**Error text**: `Expected index page at page 42` +**Error text**: `Expected index page at page {}` **Cause**: The B+tree traversal expected an index page at a specific page number, but the page found has a different type tag. This indicates index corruption or file truncation. @@ -1752,7 +1752,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-013 range_scan expected leaf -**Error text**: `range_scan: expected leaf at page_id=87` +**Error text**: `range_scan: expected leaf at page_id={}` **Cause**: A range scan of the B+tree expected a leaf page at a given position but found a non-leaf page. Indicates corruption of the B+tree structure. @@ -1763,7 +1763,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-014 Expected packed page type -**Error text**: `Expected packed page (0x02), got 0x01` +**Error text**: `Expected packed page (0x02), got 0x{}` **Cause**: A page expected to contain packed facts has a different page type tag. Indicates that the page layout in the file does not match the header's page allocation records. @@ -1774,7 +1774,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-015 Record extends beyond page boundary -**Error text**: `Record at slot 14 extends beyond page boundary` +**Error text**: `Record at slot {} extends beyond page boundary` **Cause**: A fact record at the given slot in a packed-facts page extends past the 4KB page boundary. This indicates corruption of the page's internal offset table. @@ -1829,7 +1829,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-020 Fact index exceeds u16::MAX -**Error text**: `fact index 65536 exceeds u16::MAX` +**Error text**: `fact index {} exceeds u16::MAX` **Cause**: The number of facts on a single packed page exceeded 65535 (u16::MAX). This is a theoretical limit that should not be reached in practice — a single 4KB page holds roughly 20–30 facts. @@ -1862,7 +1862,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-023 Page index exceeds u64::MAX -**Error text**: `page index 18446744073709551616 exceeds u64::MAX` +**Error text**: `page index {} exceeds u64::MAX` **Cause**: A page index computation produced a value larger than u64::MAX. This is practically unreachable — would require a database with more pages than u64 can represent. @@ -1886,7 +1886,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-025 Database already open in this process -**Error text**: `Database is already open in this process ({path}). A second handle on one file would give each its own page table and corrupt both — reuse the existing handle instead. \`Minigraf\` is cheap to clone and all clones share the same database.` +**Error text**: `Database is already open in this process ({}). A second handle on one file would give each its own page table and corrupt both — reuse the existing handle instead. `Minigraf` is cheap to clone and all clones share the same database.` **Cause**: This process already holds an open handle on this file. Two `FileBackend` instances on one file each cache their own `header.page_count`, allocate new pages from that count, and bounds-check reads against it, so the two page tables diverge and produce intermittent `Page N out of bounds` errors. @@ -1900,7 +1900,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-026 Database locked by another process -**Error text**: `Database is locked by another process ({path}). The lock is held on the file itself and is released automatically when the holding process exits, so there is no lock file to clean up.` +**Error text**: `Database is locked by another process ({}). The lock is held on the file itself and is released automatically when the holding process exits, so there is no lock file to clean up.` **Cause**: Another process holds the kernel file lock on this `.graph` file. Minigraf is single-writer: one process at a time. This is reported only after a bounded retry (up to ~375ms) rules out a transient `fork`-related false positive — see the Unreleased CHANGELOG entry on the bounded retry. @@ -1915,7 +1915,7 @@ See the [file format section in README](../README.md#file-format) for version hi ### STG-027 Filesystem does not support file locking -**Error text**: `Failed to lock database at {path}: {e}. This filesystem does not support file locking (common on NFSv3 without lockd, and on some FUSE mounts). Set \`allow_unlocked\` in \`OpenOptions\` to open anyway — that accepts the risk that concurrent writers corrupt the file.` +**Error text**: `Failed to lock database at {}: {}. This filesystem does not support file locking (common on NFSv3 without lockd, and on some FUSE mounts). Set `allow_unlocked` in `OpenOptions` to open anyway — that accepts the risk that concurrent writers corrupt the file.` **Cause**: The underlying filesystem rejected the lock outright. Common on NFSv3 mounts with no `lockd` running, and on some FUSE filesystems. Because the file must exist before it can be locked, this refusal can leave a 0-byte `.graph` file behind; the next open sees `is_new` and initialises normally. diff --git a/src/error.rs b/src/error.rs index eb60bb7772..9cbf25f7a1 100644 --- a/src/error.rs +++ b/src/error.rs @@ -36,6 +36,33 @@ pub enum ErrorCategory { #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub(crate) enum ErrorCode { Int000, + Stg001, + Stg002, + Stg003, + Stg004, + Stg005, + Stg006, + Stg007, + Stg008, + Stg009, + Stg010, + Stg011, + Stg012, + Stg013, + Stg014, + Stg015, + Stg016, + Stg017, + Stg018, + Stg019, + Stg020, + Stg021, + Stg022, + Stg023, + Stg024, + Stg025, + Stg026, + Stg027, } /// Single source of truth: (code, code string, message template, category). @@ -43,12 +70,176 @@ pub(crate) enum ErrorCode { /// The message template is verified against `docs/ERROR_REFERENCE.md`'s /// "Error text" lines by the sync test in this module (added once real /// codes exist in a follow-up category PR — see the design spec). -pub(crate) const REGISTRY: &[(ErrorCode, &str, &str, ErrorCategory)] = &[( - ErrorCode::Int000, - "INT-000", - "unclassified internal error: {}", - ErrorCategory::Internal, -)]; +pub(crate) const REGISTRY: &[(ErrorCode, &str, &str, ErrorCategory)] = &[ + ( + ErrorCode::Int000, + "INT-000", + "unclassified internal error: {}", + ErrorCategory::Internal, + ), + ( + ErrorCode::Stg001, + "STG-001", + "Invalid header: too short (got {} bytes, need 64)", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg002, + "STG-002", + "Invalid magic number: not a .graph file", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg003, + "STG-003", + "Invalid v4/v5/v6 header: expected at least 72 bytes, got {}", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg004, + "STG-004", + "Invalid v6 header: expected 80 bytes, got {}", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg005, + "STG-005", + "Invalid v7 header: expected 84 bytes, got {}", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg006, + "STG-006", + "Unsupported format version: {} (supported: 1-{})", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg007, + "STG-007", + "page_count must be greater than 0", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg008, + "STG-008", + "eavt_root_page ({}) must be less than page_count ({})", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg009, + "STG-009", + "fact_page_count ({}) cannot exceed page_count ({})", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg010, + "STG-010", + "Failed to read header from existing file: {}", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg011, + "STG-011", + "internal page has no children", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg012, + "STG-012", + "Expected index page at page {}", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg013, + "STG-013", + "range_scan: expected leaf at page_id={}", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg014, + "STG-014", + "Expected packed page (0x02), got 0x{}", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg015, + "STG-015", + "Record at slot {} extends beyond page boundary", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg016, + "STG-016", + "backend mutex poisoned", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg017, + "STG-017", + "page count overflow computing index_start", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg018, + "STG-018", + "page count overflow computing next_free", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg019, + "STG-019", + "page count overflow computing new_fact_start", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg020, + "STG-020", + "fact index {} exceeds u16::MAX", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg021, + "STG-021", + "page id overflow in checksum computation", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg022, + "STG-022", + "page id overflow writing fact pages", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg023, + "STG-023", + "page index {} exceeds u64::MAX", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg024, + "STG-024", + "pending fact count exceeds u64::MAX", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg025, + "STG-025", + "Database is already open in this process ({}). A second handle on one file would give each its own page table and corrupt both — reuse the existing handle instead. `Minigraf` is cheap to clone and all clones share the same database.", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg026, + "STG-026", + "Database is locked by another process ({}). The lock is held on the file itself and is released automatically when the holding process exits, so there is no lock file to clean up.", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg027, + "STG-027", + "Failed to lock database at {}: {}. This filesystem does not support file locking (common on NFSv3 without lockd, and on some FUSE mounts). Set `allow_unlocked` in `OpenOptions` to open anyway — that accepts the risk that concurrent writers corrupt the file.", + ErrorCategory::Storage, + ), +]; pub(crate) fn registry_entry(code: ErrorCode) -> (&'static str, &'static str, ErrorCategory) { let entry = REGISTRY.iter().find(|(c, ..)| *c == code); @@ -79,7 +270,6 @@ pub(crate) fn registry_entry(code: ErrorCode) -> (&'static str, &'static str, Er /// /// Not `std::fmt`-based: the template is runtime data pulled from [`REGISTRY`], /// and `format!` requires a compile-time string literal. -#[allow(dead_code)] // unused until the PRS category PR wires up real call sites pub(crate) fn format_template(template: &str, args: &[&dyn fmt::Display]) -> String { let placeholder_count = template.matches("{}").count(); debug_assert_eq!( @@ -115,7 +305,6 @@ pub(crate) struct CodedError { } impl CodedError { - #[allow(dead_code)] // unused until the PRS category PR wires up real call sites pub(crate) fn new(code: ErrorCode, args: &[&dyn fmt::Display]) -> Self { let (_, template, _) = registry_entry(code); CodedError { @@ -142,7 +331,6 @@ impl std::error::Error for CodedError {} /// `bail_coded!(ErrorCode::Prs001)` for a static message, or /// `bail_coded!(ErrorCode::Prs002, ch)` to fill the template's `{}` /// placeholders positionally. A drop-in replacement for `anyhow::bail!`. -#[allow(unused_macros)] // unused until the PRS category PR wires up real call sites macro_rules! bail_coded { ($code:expr $(,)?) => { return Err(::anyhow::Error::new($crate::error::CodedError::new($code, &[]))) @@ -159,7 +347,6 @@ macro_rules! bail_coded { /// /// For use where an `anyhow::Error` value is needed directly, e.g. /// `.ok_or_else(|| err_coded!(ErrorCode::Api009))`. -#[allow(unused_macros)] // unused until the PRS category PR wires up real call sites macro_rules! err_coded { ($code:expr $(,)?) => { ::anyhow::Error::new($crate::error::CodedError::new($code, &[])) @@ -172,9 +359,7 @@ macro_rules! err_coded { }; } -#[allow(unused_imports)] // unused until the PRS category PR wires up real call sites pub(crate) use bail_coded; -#[allow(unused_imports)] // unused until the PRS category PR wires up real call sites pub(crate) use err_coded; /// The error type returned from Minigraf's public API. @@ -280,9 +465,7 @@ mod tests { /// error — the real exhaustiveness guarantee `registry_entry`'s /// `debug_assert!` cannot provide on its own (it's compiled out in /// release builds, and `registry_is_a_subset_of_error_reference_doc` - /// only walks `REGISTRY`, not `ErrorCode`). Necessarily small today - /// since `ErrorCode` has just one variant, but the structure is what - /// matters for the PRS category PR that adds ~79 more. + /// only walks `REGISTRY`, not `ErrorCode`). #[test] fn every_error_code_variant_has_a_registry_entry() { fn assert_has_registry_entry(code: ErrorCode) { @@ -297,8 +480,73 @@ mod tests { ); } - match ErrorCode::Int000 { - ErrorCode::Int000 => assert_has_registry_entry(ErrorCode::Int000), + // No `_` arm: adding a new `ErrorCode` variant without listing it + // here is a compile error, which is the actual exhaustiveness + // guarantee this test provides. + fn exhaustive(code: ErrorCode) { + match code { + ErrorCode::Int000 + | ErrorCode::Stg001 + | ErrorCode::Stg002 + | ErrorCode::Stg003 + | ErrorCode::Stg004 + | ErrorCode::Stg005 + | ErrorCode::Stg006 + | ErrorCode::Stg007 + | ErrorCode::Stg008 + | ErrorCode::Stg009 + | ErrorCode::Stg010 + | ErrorCode::Stg011 + | ErrorCode::Stg012 + | ErrorCode::Stg013 + | ErrorCode::Stg014 + | ErrorCode::Stg015 + | ErrorCode::Stg016 + | ErrorCode::Stg017 + | ErrorCode::Stg018 + | ErrorCode::Stg019 + | ErrorCode::Stg020 + | ErrorCode::Stg021 + | ErrorCode::Stg022 + | ErrorCode::Stg023 + | ErrorCode::Stg024 + | ErrorCode::Stg025 + | ErrorCode::Stg026 + | ErrorCode::Stg027 => assert_has_registry_entry(code), + } + } + + for code in [ + ErrorCode::Int000, + ErrorCode::Stg001, + ErrorCode::Stg002, + ErrorCode::Stg003, + ErrorCode::Stg004, + ErrorCode::Stg005, + ErrorCode::Stg006, + ErrorCode::Stg007, + ErrorCode::Stg008, + ErrorCode::Stg009, + ErrorCode::Stg010, + ErrorCode::Stg011, + ErrorCode::Stg012, + ErrorCode::Stg013, + ErrorCode::Stg014, + ErrorCode::Stg015, + ErrorCode::Stg016, + ErrorCode::Stg017, + ErrorCode::Stg018, + ErrorCode::Stg019, + ErrorCode::Stg020, + ErrorCode::Stg021, + ErrorCode::Stg022, + ErrorCode::Stg023, + ErrorCode::Stg024, + ErrorCode::Stg025, + ErrorCode::Stg026, + ErrorCode::Stg027, + ] { + exhaustive(code); } } diff --git a/src/storage/backend/file.rs b/src/storage/backend/file.rs index 60e6b36ba3..7ce64df37e 100644 --- a/src/storage/backend/file.rs +++ b/src/storage/backend/file.rs @@ -1,4 +1,5 @@ /// File-based storage backend for native platforms. +use crate::error::{ErrorCode, bail_coded}; use crate::storage::{FileHeader, PAGE_SIZE, StorageBackend}; use anyhow::Result; use std::fs::{File, OpenOptions}; @@ -236,32 +237,13 @@ impl FileBackend { PathGuard(Some(canonical)) } LockOutcome::Held if already_open_here(&canonical) => { - anyhow::bail!( - "Database is already open in this process ({}). A second handle \ - on one file would give each its own page table and corrupt both \ - — reuse the existing handle instead. `Minigraf` is cheap to clone \ - and all clones share the same database.", - path.display() - ); + bail_coded!(ErrorCode::Stg025, path.display()); } LockOutcome::Held => { - anyhow::bail!( - "Database is locked by another process ({}). The lock is held on \ - the file itself and is released automatically when the holding \ - process exits, so there is no lock file to clean up.", - path.display() - ); + bail_coded!(ErrorCode::Stg026, path.display()); } LockOutcome::Unsupported(e) => { - anyhow::bail!( - "Failed to lock database at {}: {}. This filesystem does not \ - support file locking (common on NFSv3 without lockd, and on some \ - FUSE mounts). Set `allow_unlocked` in `OpenOptions` to open \ - anyway — that accepts the risk that concurrent writers corrupt \ - the file.", - path.display(), - e - ); + bail_coded!(ErrorCode::Stg027, path.display(), e); } LockOutcome::ProceedUnlocked => { // There is no kernel lock in this arm, so the registry is not @@ -271,13 +253,7 @@ impl FileBackend { // path. See `claim_unlocked_path` for why the check and // insert must be one atomic operation. if !claim_unlocked_path(&canonical) { - anyhow::bail!( - "Database is already open in this process ({}). A second handle \ - on one file would give each its own page table and corrupt both \ - — reuse the existing handle instead. `Minigraf` is cheap to clone \ - and all clones share the same database.", - path.display() - ); + bail_coded!(ErrorCode::Stg025, path.display()); } PathGuard(Some(canonical)) } @@ -295,12 +271,17 @@ impl FileBackend { match Self::read_header(&mut file) { Ok(header) => header, Err(e) => { - // File has content but header is invalid - this is a real error - anyhow::bail!( - "Failed to read header from existing file (size={}): {}", - file_len, - e - ); + // File has content but header is invalid - this is a real error. + // If `e` already carries a more specific code (e.g. STG-002 for a + // bad magic number, raised inside `FileHeader::from_bytes`/ + // `validate`), propagate it as-is rather than burying it under + // the generic STG-010 label — `read_header` never wraps with + // `.context()`, so a coded error from deeper down comes back + // here unmodified and downcasts directly. + if e.downcast_ref::().is_some() { + return Err(e); + } + bail_coded!(ErrorCode::Stg010, e); } } } else { @@ -603,11 +584,20 @@ mod tests { let result = FileBackend::open(&db_path); let elapsed = start.elapsed(); - // (a) a real cross-process lock is still refused. - let msg = match result { + // (a) a real cross-process lock is still refused, with the coded + // STG-026 error (#359). + let (msg, code) = match result { Ok(_) => panic!("a genuinely cross-process lock must be refused"), - Err(e) => e.to_string(), + Err(e) => { + let msg = e.to_string(); + let code = crate::error::MinigrafError::from(e).code().to_string(); + (msg, code) + } }; + assert_eq!( + code, "STG-026", + "cross-process lock conflict must be STG-026" + ); // (b) the retry budget is bounded: this must fail in roughly the // ~375ms budget, NOT hang for the holder's full 3s hold. The 2s bound diff --git a/src/storage/btree.rs b/src/storage/btree.rs index 306cac90b2..e98615cfff 100644 --- a/src/storage/btree.rs +++ b/src/storage/btree.rs @@ -33,6 +33,7 @@ //! //! Phase 6.1 uses these only for save/load. In-memory BTreeMaps handle queries. +use crate::error::{ErrorCode, bail_coded}; use anyhow::Result; use std::collections::BTreeMap; @@ -169,7 +170,7 @@ fn read_blob(backend: &dyn StorageBackend, start_page_id: u64) -> Result anyhow::anyhow!("btree read_blob: page index 0 out of bounds (page {page_id})") })?; if page_byte != PAGE_TYPE_INDEX { - anyhow::bail!("Expected index page at page {}", page_id); + bail_coded!(ErrorCode::Stg012, page_id); } let chunk_len = u32::from_le_bytes( page.get(5..9) @@ -424,4 +425,33 @@ mod tests { // Ensure the return value is sane. assert!(root >= 2); } + + // ══ #359: STG-012 regression test ═════════════════════════════════════ + + /// A non-first page of a multi-page index blob whose type byte has been + /// corrupted (page found is not `PAGE_TYPE_INDEX`) must surface as the + /// coded STG-012, not a generic error. + #[test] + fn read_blob_corrupted_non_first_page_returns_stg_012() { + let mut backend = MemoryBackend::new(); + let mut map = BTreeMap::new(); + // Enough entries to span at least 2 pages (see + // test_large_eavt_roundtrip_multi_leaf above). + for i in 0u128..150 { + let (k, v) = eavt_entry(i, ":attr", i as u64 + 1); + map.insert(k, v); + } + let next = write_eavt_index(&map, &mut backend, 1).unwrap(); + assert!(next > 2, "150 entries must span multiple pages"); + + // Corrupt page 2's type byte (the second page of the blob starting + // at page 1) so it no longer reads as PAGE_TYPE_INDEX. + let mut corrupt_page = backend.read_page(2).unwrap(); + corrupt_page[0] = 0x00; + backend.write_page(2, &corrupt_page).unwrap(); + + let err = read_eavt_index(1, &backend).expect_err("corrupted page must fail to read"); + let coded: crate::error::MinigrafError = err.into(); + assert_eq!(coded.code(), "STG-012"); + } } diff --git a/src/storage/btree_v6.rs b/src/storage/btree_v6.rs index 699d840395..6fc7eaf648 100644 --- a/src/storage/btree_v6.rs +++ b/src/storage/btree_v6.rs @@ -4,6 +4,7 @@ //! `build_btree` does a bulk-build (write-all-leaves, then internal levels //! bottom-up). Range scans traverse the tree through the cache. +use crate::error::{ErrorCode, bail_coded}; use crate::storage::cache::PageCache; use crate::storage::index::FactRef; use crate::storage::{PAGE_SIZE, StorageBackend}; @@ -116,7 +117,7 @@ fn write_internal_page( debug_assert_eq!(child_ids.len(), sep_bytes.len() + 1); // Defensive check: empty child_ids would cause panic on .last() if child_ids.is_empty() { - anyhow::bail!("internal page has no children"); + bail_coded!(ErrorCode::Stg011); } let key_count = u16::try_from(sep_bytes.len()) .map_err(|_| anyhow!("too many sep keys: {}", sep_bytes.len()))?; @@ -555,7 +556,7 @@ where .copied() .ok_or_else(|| anyhow!("empty page at page_id={leaf_id}"))?; if page_type != PAGE_TYPE_LEAF { - anyhow::bail!("range_scan: expected leaf at page_id={}", leaf_id); + bail_coded!(ErrorCode::Stg013, leaf_id); } let next_leaf = read_u64_at(&page[..], 4)?; let entries: Vec<(K, FactRef)> = read_leaf_entries(&page[..])?; @@ -1099,6 +1100,70 @@ mod tests { ); } + // ══ #359: STG-0xx regression tests ═══════════════════════════════════ + // + // STG-011 ("internal page has no children") is guarded by + // `debug_assert_eq!(child_ids.len(), sep_bytes.len() + 1)` immediately + // above the `bail_coded!` call site in `write_internal_page`, and no + // combination of arguments satisfies that assertion when `child_ids` is + // empty (`sep_bytes.len() + 1` can never be `0`). So under `cargo + // test`'s debug build, the `debug_assert!` always panics first, + // preempting the bail entirely -- this call site is only live as a + // release-build defensive guard and isn't reachable from a normal test + // build. No dedicated regression test for STG-011 as a result. + + /// A leaf's `next_leaf` chain pointer corrupted to point at a non-leaf + /// page must surface as the coded STG-013 when `range_scan` follows it, + /// not a generic error. `find_leaf_for_key`'s own traversal only + /// validates the *first* leaf it lands on; a corrupted `next_leaf` on a + /// later page in a multi-leaf scan is caught by `range_scan`'s own + /// per-page check. + #[test] + fn range_scan_corrupted_next_leaf_pointer_returns_stg_013() { + let mut backend = MemoryBackend::new(); + let cache = PageCache::new(512); + // Enough entries with long keys to force a multi-leaf tree with an + // internal-node root (mirrors test_build_btree_leaf_next_pointers_form_chain). + let entries = (0u128..100).map(|n| make_eavt(n, ":verylongattributename", n as u64 + 1)); + let ser = btree_entries(entries).unwrap(); + let (root, _) = build_btree(ser.into_iter(), &mut backend, &cache, 1).unwrap(); + + let root_page = cache.get_or_load(root, &backend).unwrap(); + assert_eq!( + root_page[0], PAGE_TYPE_INTERNAL, + "100 long-key entries must produce an internal-node root for this test to be valid" + ); + + // Find the leftmost leaf by following first children down from root. + let mut leaf_pid = root; + loop { + let p = cache.get_or_load(leaf_pid, &backend).unwrap(); + if p[0] == PAGE_TYPE_LEAF { + break; + } + leaf_pid = read_u64_at(&p[..], 12).unwrap(); + } + + // Corrupt the leftmost leaf's next_leaf pointer (bytes 4..12) to + // point at the internal-node root instead of the next real leaf. + let mut leaf_bytes = backend.read_page(leaf_pid).unwrap(); + leaf_bytes[4..12].copy_from_slice(&root.to_le_bytes()); + backend.write_page(leaf_pid, &leaf_bytes).unwrap(); + cache.invalidate(leaf_pid); + + let start = EavtKey { + entity: Uuid::from_u128(0), + attribute: String::new(), + valid_from: i64::MIN, + valid_to: i64::MIN, + tx_count: 0, + }; + let err = range_scan::(root, &start, None, &backend, &cache) + .expect_err("following a next_leaf pointer into a non-leaf page must fail"); + let coded: crate::error::MinigrafError = err.into(); + assert_eq!(coded.code(), "STG-013"); + } + #[test] fn test_on_disk_index_reader_range_scan_eavt() { use crate::storage::CommittedIndexReader; diff --git a/src/storage/mod.rs b/src/storage/mod.rs index c7a94f1f09..93e3c63bcf 100644 --- a/src/storage/mod.rs +++ b/src/storage/mod.rs @@ -13,6 +13,7 @@ pub mod index; pub mod packed_pages; pub mod persistent_facts; +use crate::error::{ErrorCode, bail_coded}; use anyhow::Result; /// Read a 4-byte little-endian u32 from `bytes` at `offset`. @@ -200,10 +201,7 @@ impl FileHeader { // Both v3 (64 bytes) and v4/v5/v6 (72+ bytes) must pass at least 64-byte // validation before the version field is read. if bytes.len() < 64 { - anyhow::bail!( - "Invalid header: too short (got {} bytes, need 64)", - bytes.len() - ); + bail_coded!(ErrorCode::Stg001, bytes.len()); } let mut magic = [0u8; 4]; @@ -214,7 +212,7 @@ impl FileHeader { ); if magic != MAGIC_NUMBER { - anyhow::bail!("Invalid magic number: not a .graph file"); + bail_coded!(ErrorCode::Stg002); } let version = read_u32_le(bytes, 4)?; @@ -245,15 +243,12 @@ impl FileHeader { // v4, v5, v6: need at least 72 bytes if bytes.len() < 72 { - anyhow::bail!( - "Invalid v4/v5/v6 header: expected at least 72 bytes, got {}", - bytes.len() - ); + bail_coded!(ErrorCode::Stg003, bytes.len()); } let fact_page_count = if version >= 6 { if bytes.len() < 80 { - anyhow::bail!("Invalid v6 header: expected 80 bytes, got {}", bytes.len()); + bail_coded!(ErrorCode::Stg004, bytes.len()); } read_u64_le(bytes, 72)? } else { @@ -262,7 +257,7 @@ impl FileHeader { let header_checksum = if version >= 7 { if bytes.len() < 84 { - anyhow::bail!("Invalid v7 header: expected 84 bytes, got {}", bytes.len()); + bail_coded!(ErrorCode::Stg005, bytes.len()); } read_u32_le(bytes, 80)? } else { @@ -305,29 +300,17 @@ impl FileHeader { anyhow::bail!("Invalid magic number"); } if self.version < 1 || self.version > FORMAT_VERSION { - anyhow::bail!( - "Unsupported format version: {} (supported: 1-{})", - self.version, - FORMAT_VERSION - ); + bail_coded!(ErrorCode::Stg006, self.version, FORMAT_VERSION); } // Validate logical relationships if self.page_count == 0 { - anyhow::bail!("page_count must be greater than 0"); + bail_coded!(ErrorCode::Stg007); } if self.eavt_root_page != 0 && self.eavt_root_page >= self.page_count { - anyhow::bail!( - "eavt_root_page ({}) must be less than page_count ({})", - self.eavt_root_page, - self.page_count - ); + bail_coded!(ErrorCode::Stg008, self.eavt_root_page, self.page_count); } if self.fact_page_count > self.page_count { - anyhow::bail!( - "fact_page_count ({}) cannot exceed page_count ({})", - self.fact_page_count, - self.page_count - ); + bail_coded!(ErrorCode::Stg009, self.fact_page_count, self.page_count); } Ok(()) } @@ -610,4 +593,53 @@ mod tests { h.version = 5; assert!(h.validate().is_ok()); } + + // ══ #359: STG-0xx regression tests ═══════════════════════════════════ + // + // STG-001/003/004/005 guard byte lengths (<64/<72/<80/<84) that the + // production `FileBackend` path never actually produces -- it always + // hands `FileHeader::from_bytes` a full `PAGE_SIZE` (4096-byte) buffer, + // whatever the real file's length beyond the minimum one page. These + // codes are only reachable by calling `FileHeader::from_bytes` directly + // with a short slice, which `storage` being crate-private makes + // possible only from inside the crate -- hence unit tests here rather + // than an integration test against the public `Minigraf` API. + + #[test] + fn from_bytes_too_short_returns_stg_001() { + let bytes = vec![0u8; 10]; // < 64 bytes + let err = FileHeader::from_bytes(&bytes).expect_err("10 bytes is too short"); + let coded: crate::error::MinigrafError = err.into(); + assert_eq!(coded.code(), "STG-001"); + } + + #[test] + fn from_bytes_v4_too_short_returns_stg_003() { + let mut bytes = vec![0u8; 70]; // >= 64, < 72 + bytes[0..4].copy_from_slice(b"MGRF"); + bytes[4..8].copy_from_slice(&4u32.to_le_bytes()); // version = 4 + let err = FileHeader::from_bytes(&bytes).expect_err("70 bytes is too short for v4"); + let coded: crate::error::MinigrafError = err.into(); + assert_eq!(coded.code(), "STG-003"); + } + + #[test] + fn from_bytes_v6_too_short_returns_stg_004() { + let mut bytes = vec![0u8; 75]; // >= 72, < 80 + bytes[0..4].copy_from_slice(b"MGRF"); + bytes[4..8].copy_from_slice(&6u32.to_le_bytes()); // version = 6 + let err = FileHeader::from_bytes(&bytes).expect_err("75 bytes is too short for v6"); + let coded: crate::error::MinigrafError = err.into(); + assert_eq!(coded.code(), "STG-004"); + } + + #[test] + fn from_bytes_v7_too_short_returns_stg_005() { + let mut bytes = vec![0u8; 82]; // >= 80, < 84 + bytes[0..4].copy_from_slice(b"MGRF"); + bytes[4..8].copy_from_slice(&7u32.to_le_bytes()); // version = 7 + let err = FileHeader::from_bytes(&bytes).expect_err("82 bytes is too short for v7"); + let coded: crate::error::MinigrafError = err.into(); + assert_eq!(coded.code(), "STG-005"); + } } diff --git a/src/storage/packed_pages.rs b/src/storage/packed_pages.rs index febeee99a0..b5fae80bc3 100644 --- a/src/storage/packed_pages.rs +++ b/src/storage/packed_pages.rs @@ -19,6 +19,7 @@ //! Overflow pages (`page_type = 0x03`) are reserved for future use. //! The `next_page` field is always written as 0 in Phase 6.2. +use crate::error::{ErrorCode, bail_coded}; use crate::graph::types::Fact; use crate::storage::index::FactRef; use crate::storage::{PAGE_SIZE, StorageBackend}; @@ -165,7 +166,7 @@ pub fn read_slot(page: &[u8], slot: u16) -> Result { .first() .ok_or_else(|| anyhow::anyhow!("packed page empty"))?; if page_type != PAGE_TYPE_PACKED { - anyhow::bail!("Expected packed page (0x02), got 0x{:02x}", page_type); + bail_coded!(ErrorCode::Stg014, format!("{:02x}", page_type)); } let b2 = *page .get(2) @@ -200,7 +201,7 @@ pub fn read_slot(page: &[u8], slot: u16) -> Result { let offset = usize::from(u16::from_le_bytes([db0, db1])); let length = usize::from(u16::from_le_bytes([db2, db3])); if offset.saturating_add(length) > PAGE_SIZE { - anyhow::bail!("Record at slot {} extends beyond page boundary", slot); + bail_coded!(ErrorCode::Stg015, slot); } let fact: Fact = postcard::from_bytes( page.get(offset..offset.saturating_add(length)) @@ -426,4 +427,35 @@ mod tests { let result = pack_facts(&[fact], 1); assert!(result.is_err(), "oversized fact must return Err, not panic"); } + + // ══ #359: STG-0xx regression tests ═══════════════════════════════════ + + /// A page whose type byte is not `PAGE_TYPE_PACKED` must surface as the + /// coded STG-014, not a generic error. + #[test] + fn read_slot_wrong_page_type_returns_stg_014() { + let facts = vec![make_fact(1)]; + let (mut pages, _) = pack_facts(&facts, 1).unwrap(); + pages[0][0] = 0x01; // corrupt: not PAGE_TYPE_PACKED (0x02) + let err = read_slot(&pages[0], 0).expect_err("wrong page type must fail to read"); + let coded: crate::error::MinigrafError = err.into(); + assert_eq!(coded.code(), "STG-014"); + } + + /// A record directory entry whose `offset + length` extends past the + /// page boundary must surface as the coded STG-015, not a generic + /// error. + #[test] + fn read_slot_record_beyond_page_boundary_returns_stg_015() { + let facts = vec![make_fact(1)]; + let (mut pages, _) = pack_facts(&facts, 1).unwrap(); + // Directory entry 0 is at bytes 12..16 (offset u16 LE, length u16 LE). + // Corrupt the length field so offset + length > PAGE_SIZE. + pages[0][14] = 0xFF; + pages[0][15] = 0xFF; + let err = read_slot(&pages[0], 0) + .expect_err("a record extending past the page boundary must fail to read"); + let coded: crate::error::MinigrafError = err.into(); + assert_eq!(coded.code(), "STG-015"); + } } diff --git a/src/storage/persistent_facts.rs b/src/storage/persistent_facts.rs index 7b7fd0dd8e..fdad0923f1 100644 --- a/src/storage/persistent_facts.rs +++ b/src/storage/persistent_facts.rs @@ -1,3 +1,4 @@ +use crate::error::{ErrorCode, bail_coded, err_coded}; use crate::graph::FactStorage; /// Persistent fact storage that integrates StorageBackend with Datalog facts. /// @@ -84,7 +85,7 @@ impl crate::storage::CommittedFactReader let backend = self .backend .lock() - .map_err(|_| anyhow::anyhow!("backend mutex poisoned"))?; + .map_err(|_| err_coded!(ErrorCode::Stg016))?; crate::storage::packed_pages::read_all_from_pages(&*backend, 1, n) } @@ -183,7 +184,7 @@ impl PersistentFactStorage { let b = persistent .backend .lock() - .map_err(|_| anyhow::anyhow!("backend mutex poisoned"))?; + .map_err(|_| err_coded!(ErrorCode::Stg016))?; (b.is_new(), b.page_count()?) }; if !is_new_backend || page_count > 1 { @@ -208,7 +209,7 @@ impl PersistentFactStorage { let backend = self .backend .lock() - .map_err(|_| anyhow::anyhow!("backend mutex poisoned"))?; + .map_err(|_| err_coded!(ErrorCode::Stg016))?; let header_page = backend.read_page(0)?; let h = FileHeader::from_bytes(&header_page)?; h.validate()?; @@ -285,7 +286,7 @@ impl PersistentFactStorage { let backend = self .backend .lock() - .map_err(|_| anyhow::anyhow!("backend mutex poisoned"))?; + .map_err(|_| err_coded!(ErrorCode::Stg016))?; let stored = header.index_checksum; // Total data pages: pages 1 through page_count-1 (everything except header) let total_data_pages = header.page_count.saturating_sub(1); @@ -324,7 +325,7 @@ impl PersistentFactStorage { let backend = self .backend .lock() - .map_err(|_| anyhow::anyhow!("backend mutex poisoned"))?; + .map_err(|_| err_coded!(ErrorCode::Stg016))?; crate::storage::packed_pages::read_all_from_pages(&*backend, 1, num_fact_pages)? }; // Re-pack to derive correct FactRefs (same deterministic layout as on disk) @@ -341,11 +342,11 @@ impl PersistentFactStorage { // Build v6 B+tree indexes directly let index_start = 1u64 .checked_add(num_fact_pages) - .ok_or_else(|| anyhow::anyhow!("page count overflow computing index_start"))?; + .ok_or_else(|| err_coded!(ErrorCode::Stg017))?; let mut backend = self .backend .lock() - .map_err(|_| anyhow::anyhow!("backend mutex poisoned"))?; + .map_err(|_| err_coded!(ErrorCode::Stg016))?; let (eavt_root, next1) = build_btree( btree_entries(eavt_entries.into_iter())?.into_iter(), &mut *backend, @@ -416,7 +417,7 @@ impl PersistentFactStorage { let backend = self .backend .lock() - .map_err(|_| anyhow::anyhow!("backend mutex poisoned"))?; + .map_err(|_| err_coded!(ErrorCode::Stg016))?; let current_header_bytes = backend.read_page(0)?; let current_header = FileHeader::from_bytes(¤t_header_bytes)?; let computed = compute_header_checksum_from_bytes(¤t_header_bytes); @@ -453,7 +454,7 @@ impl PersistentFactStorage { let backend = self .backend .lock() - .map_err(|_| anyhow::anyhow!("backend mutex poisoned"))?; + .map_err(|_| err_coded!(ErrorCode::Stg016))?; let mut loaded: usize = 0; let mut skipped: usize = 0; for page_id in 1..page_count { @@ -499,7 +500,7 @@ impl PersistentFactStorage { let backend = self .backend .lock() - .map_err(|_| anyhow::anyhow!("backend mutex poisoned"))?; + .map_err(|_| err_coded!(ErrorCode::Stg016))?; let header_page = backend.read_page(0)?; let header = FileHeader::from_bytes(&header_page)?; let page_count = header.page_count; @@ -594,7 +595,7 @@ impl PersistentFactStorage { let backend = self .backend .lock() - .map_err(|_| anyhow::anyhow!("backend mutex poisoned"))?; + .map_err(|_| err_coded!(ErrorCode::Stg016))?; // Just verify we can read the page - actual validation happens via checksum if backend.read_page(1).is_ok() { num_fact_pages @@ -618,7 +619,7 @@ impl PersistentFactStorage { let backend = self .backend .lock() - .map_err(|_| anyhow::anyhow!("backend mutex poisoned"))?; + .map_err(|_| err_coded!(ErrorCode::Stg016))?; let total_data_pages = header.page_count.saturating_sub(1); let full = compute_page_checksum(&*backend, 1, total_data_pages)?; if full == header.index_checksum { @@ -634,7 +635,7 @@ impl PersistentFactStorage { let backend = self .backend .lock() - .map_err(|_| anyhow::anyhow!("backend mutex poisoned"))?; + .map_err(|_| err_coded!(ErrorCode::Stg016))?; let e = if header.eavt_root_page > 0 { read_eavt_index(header.eavt_root_page, &*backend)? } else { @@ -662,7 +663,7 @@ impl PersistentFactStorage { let backend = self .backend .lock() - .map_err(|_| anyhow::anyhow!("backend mutex poisoned"))?; + .map_err(|_| err_coded!(ErrorCode::Stg016))?; crate::storage::packed_pages::read_all_from_pages( &*backend, 1, @@ -675,8 +676,7 @@ impl PersistentFactStorage { let mut avet_map = std::collections::BTreeMap::new(); let mut vaet_map = std::collections::BTreeMap::new(); for (i, fact) in all_facts.iter().enumerate() { - let slot_index = u16::try_from(i) - .map_err(|_| anyhow::anyhow!("fact index {i} exceeds u16::MAX"))?; + let slot_index = u16::try_from(i).map_err(|_| err_coded!(ErrorCode::Stg020, i))?; let fr = FactRef { page_id: 1, slot_index, @@ -732,7 +732,7 @@ impl PersistentFactStorage { let mut backend = self .backend .lock() - .map_err(|_| anyhow::anyhow!("backend mutex poisoned"))?; + .map_err(|_| err_coded!(ErrorCode::Stg016))?; // Use the actual end of fact pages as the start for new index pages, NOT // header.page_count — that field comes from the (possibly untrusted) file // on disk and may be a huge fuzz-crafted value that causes build_btree to @@ -740,7 +740,7 @@ impl PersistentFactStorage { // over billions of pages. let next_free = 1u64 .checked_add(validated_num_fact_pages) - .ok_or_else(|| anyhow::anyhow!("page count overflow computing next_free"))?; + .ok_or_else(|| err_coded!(ErrorCode::Stg018))?; let (eavt_root, next_free2) = build_btree( btree_entries(eavt.into_iter())?.into_iter(), @@ -837,7 +837,7 @@ impl PersistentFactStorage { match Arc::try_unwrap(backend_arc) { Ok(mutex) => Ok(mutex .into_inner() - .map_err(|_| anyhow::anyhow!("backend mutex poisoned"))?), + .map_err(|_| err_coded!(ErrorCode::Stg016))?), Err(_) => Err(anyhow::anyhow!( "into_backend: backend Arc has multiple owners" )), @@ -855,17 +855,17 @@ impl PersistentFactStorage { let mut backend = self .backend .lock() - .map_err(|_| anyhow::anyhow!("backend mutex poisoned"))?; + .map_err(|_| err_coded!(ErrorCode::Stg016))?; let old_fact_page_count = self.committed_fact_pages.load(Ordering::SeqCst); let new_fact_start = 1u64 .checked_add(old_fact_page_count) - .ok_or_else(|| anyhow::anyhow!("page count overflow computing new_fact_start"))?; + .ok_or_else(|| err_coded!(ErrorCode::Stg019))?; let curr_header = match backend.read_page(0) { Ok(bytes) => FileHeader::from_bytes(&bytes)?, Err(_) if backend.is_new() => FileHeader::new(), - Err(e) => anyhow::bail!("Failed to read header from existing file: {}", e), + Err(e) => bail_coded!(ErrorCode::Stg010, e), }; // Stream committed B+tree entries BEFORE writing new pages that may overlap @@ -896,11 +896,10 @@ impl PersistentFactStorage { // ── Step B: pack pending facts as new appended pages ──────────────────── let (new_pages, new_fact_refs) = pack_facts(&pending_facts, new_fact_start)?; for (i, page_data) in new_pages.iter().enumerate() { - let page_offset = - u64::try_from(i).map_err(|_| anyhow::anyhow!("page index {i} exceeds u64::MAX"))?; + let page_offset = u64::try_from(i).map_err(|_| err_coded!(ErrorCode::Stg023, i))?; let page_id = new_fact_start .checked_add(page_offset) - .ok_or_else(|| anyhow::anyhow!("page id overflow writing fact pages"))?; + .ok_or_else(|| err_coded!(ErrorCode::Stg022))?; backend.write_page(page_id, page_data)?; } let new_pages_len = u64::try_from(new_pages.len()) @@ -921,7 +920,7 @@ impl PersistentFactStorage { // ── Step D: merge committed + pending entries, build new B+trees ───────── let index_start = 1u64 .checked_add(new_total_fact_pages) - .ok_or_else(|| anyhow::anyhow!("page count overflow computing index_start"))?; + .ok_or_else(|| err_coded!(ErrorCode::Stg017))?; let eavt_ser = if !committed_eavt.is_empty() { btree_entries(merge_sorted_vecs(committed_eavt, pending_eavt))? @@ -973,8 +972,8 @@ impl PersistentFactStorage { // ── Step E: write header (last write = crash-safe boundary) ───────────── let mut header = FileHeader::new(); // version=7 header.page_count = next4; - let pending_len = u64::try_from(pending_facts.len()) - .map_err(|_| anyhow::anyhow!("pending fact count exceeds u64::MAX"))?; + let pending_len = + u64::try_from(pending_facts.len()).map_err(|_| err_coded!(ErrorCode::Stg024))?; header.node_count = curr_header .node_count .checked_add(pending_len) @@ -1114,7 +1113,7 @@ fn compute_page_checksum( for i in 0..num_pages { let page_id = first_page .checked_add(i) - .ok_or_else(|| anyhow::anyhow!("page id overflow in checksum computation"))?; + .ok_or_else(|| err_coded!(ErrorCode::Stg021))?; let page = backend.read_page(page_id)?; hasher.update(&page); } @@ -2170,6 +2169,111 @@ mod tests { drop(backend); } + // ══ #359: STG-0xx regression tests ═══════════════════════════════════ + + /// A poisoned backend mutex (a previous operation panicked while + /// holding the lock) must surface as the coded STG-016, not a generic + /// error. + #[test] + fn save_with_poisoned_backend_mutex_returns_stg_016() { + let mut pfs = PersistentFactStorage::new(MemoryBackend::new(), 16).unwrap(); + let alice = Uuid::new_v4(); + pfs.storage() + .transact( + vec![( + alice, + ":name".to_string(), + Value::String("Alice".to_string()), + )], + None, + ) + .unwrap(); + pfs.mark_dirty(); + + // Poison the backend mutex by panicking while holding it. + let backend = pfs.backend.clone(); + let handle = std::thread::spawn(move || { + let _guard = backend.lock().unwrap(); + panic!("deliberate poison for STG-016 regression test"); + }); + let _ = handle.join(); + + let err = pfs + .save() + .expect_err("save on a poisoned backend mutex must fail"); + let coded: crate::error::MinigrafError = err.into(); + assert_eq!(coded.code(), "STG-016"); + assert_eq!(coded.category(), crate::error::ErrorCategory::Storage); + } + + /// A backend that reports an existing (non-new) file but then fails to + /// re-read the header at `save()` time (e.g. a transient disk I/O + /// error) must surface as the coded STG-010, not a generic error. + /// `read_page(0)` is allowed to succeed exactly once, so `load()` (run + /// from `PersistentFactStorage::new()`, since `is_new()` is false) + /// completes normally; the failure is injected only for the *second* + /// `read_page(0)` call, which `save()` makes. + struct FlakyHeaderBackend { + inner: MemoryBackend, + read_page_0_calls: std::sync::atomic::AtomicU32, + } + + impl StorageBackend for FlakyHeaderBackend { + fn write_page(&mut self, page_id: u64, data: &[u8]) -> Result<()> { + self.inner.write_page(page_id, data) + } + fn read_page(&self, page_id: u64) -> Result> { + if page_id == 0 { + let calls = self + .read_page_0_calls + .fetch_add(1, std::sync::atomic::Ordering::SeqCst); + if calls >= 1 { + anyhow::bail!("simulated disk read failure"); + } + } + self.inner.read_page(page_id) + } + fn sync(&mut self) -> Result<()> { + self.inner.sync() + } + fn page_count(&self) -> Result { + self.inner.page_count() + } + fn close(&mut self) -> Result<()> { + self.inner.close() + } + fn backend_name(&self) -> &'static str { + "flaky-header-test" + } + fn is_new(&self) -> bool { + false + } + } + + #[test] + fn save_with_unreadable_existing_header_returns_stg_010() { + let mut inner = MemoryBackend::new(); + // A valid, empty v7 header so `load()` (triggered by `is_new() == + // false`) succeeds cleanly on the first `read_page(0)` call. + let mut header_page = FileHeader::new().to_bytes(); + header_page.resize(PAGE_SIZE, 0); + inner.write_page(0, &header_page).unwrap(); + + let backend = FlakyHeaderBackend { + inner, + read_page_0_calls: std::sync::atomic::AtomicU32::new(0), + }; + let mut pfs = PersistentFactStorage::new(backend, 16).unwrap(); + pfs.mark_dirty(); + + let err = pfs + .save() + .expect_err("save must fail when the header becomes unreadable"); + let coded: crate::error::MinigrafError = err.into(); + assert_eq!(coded.code(), "STG-010"); + assert_eq!(coded.category(), crate::error::ErrorCategory::Storage); + } + // ══ #214 fault-injection unit tests ══════════════════════════════════ mod fault_injection_tests { diff --git a/tests/error_codes_storage_test.rs b/tests/error_codes_storage_test.rs new file mode 100644 index 0000000000..9920ac06bc --- /dev/null +++ b/tests/error_codes_storage_test.rs @@ -0,0 +1,138 @@ +//! Regression tests for #359 (STG-0xx storage error codes, part of the #277 +//! structured error codes rollout): asserts that specific `STG-NNN` codes +//! come back through the public `Minigraf::open()` API for corrupt/invalid +//! `.graph` files, not just a generic error. +//! +//! Only covers codes reachable through the public API by constructing +//! byte-level `.graph` files directly (the `storage` module itself is +//! crate-private, so these tests cannot call `FileHeader`/`StorageBackend` +//! directly — see the unit tests inside `src/storage/*.rs` for codes that +//! are only reachable at that lower level). + +use minigraf::{ErrorCategory, Minigraf}; +use std::io::Write; + +/// Unique scratch directory per test run so parallel tests never collide. +fn scratch_dir(name: &str) -> std::path::PathBuf { + let dir = + std::env::temp_dir().join(format!("minigraf_stg_test_{}_{}", name, std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).unwrap(); + dir +} + +fn write_file(path: &std::path::Path, bytes: &[u8]) { + let mut f = std::fs::File::create(path).unwrap(); + f.write_all(bytes).unwrap(); +} + +/// A minimal, valid v7 header prefix (magic + version + page_count), padded +/// to a full 4096-byte page with the given `patch` applied on top. +fn header_page(patch: impl FnOnce(&mut [u8])) -> Vec { + let mut bytes = vec![0u8; 4096]; + bytes[0..4].copy_from_slice(b"MGRF"); + bytes[4..8].copy_from_slice(&7u32.to_le_bytes()); // version = 7 + bytes[8..16].copy_from_slice(&1u64.to_le_bytes()); // page_count = 1 + patch(&mut bytes); + bytes +} + +#[test] +fn open_bad_magic_number_returns_stg_002() { + let dir = scratch_dir("bad_magic"); + let path = dir.join("bad.graph"); + // A full page of non-MGRF bytes. + write_file(&path, &vec![0xAAu8; 4096]); + + let err = match Minigraf::open(&path) { + Ok(_) => panic!("opening a file with a bad magic number should fail"), + Err(e) => e, + }; + assert_eq!(err.code(), "STG-002"); + assert_eq!(err.category(), ErrorCategory::Storage); +} + +#[test] +fn open_unsupported_version_returns_stg_006() { + let dir = scratch_dir("bad_version"); + let path = dir.join("bad.graph"); + let bytes = header_page(|b| { + b[4..8].copy_from_slice(&99u32.to_le_bytes()); // version = 99 + }); + write_file(&path, &bytes); + + let err = match Minigraf::open(&path) { + Ok(_) => panic!("opening a file with an unsupported version should fail"), + Err(e) => e, + }; + assert_eq!(err.code(), "STG-006"); + assert_eq!(err.category(), ErrorCategory::Storage); +} + +#[test] +fn open_zero_page_count_returns_stg_007() { + let dir = scratch_dir("zero_pages"); + let path = dir.join("bad.graph"); + let bytes = header_page(|b| { + b[8..16].copy_from_slice(&0u64.to_le_bytes()); // page_count = 0 + }); + write_file(&path, &bytes); + + let err = match Minigraf::open(&path) { + Ok(_) => panic!("opening a file with page_count=0 should fail"), + Err(e) => e, + }; + assert_eq!(err.code(), "STG-007"); + assert_eq!(err.category(), ErrorCategory::Storage); +} + +#[test] +fn open_eavt_root_page_out_of_bounds_returns_stg_008() { + let dir = scratch_dir("eavt_oob"); + let path = dir.join("bad.graph"); + let bytes = header_page(|b| { + // eavt_root_page (bytes 32..40) >= page_count (1) is invalid. + b[32..40].copy_from_slice(&5u64.to_le_bytes()); + }); + write_file(&path, &bytes); + + let err = match Minigraf::open(&path) { + Ok(_) => panic!("opening a file with eavt_root_page >= page_count should fail"), + Err(e) => e, + }; + assert_eq!(err.code(), "STG-008"); + assert_eq!(err.category(), ErrorCategory::Storage); +} + +#[test] +fn open_fact_page_count_exceeds_page_count_returns_stg_009() { + let dir = scratch_dir("fact_pc_oob"); + let path = dir.join("bad.graph"); + let bytes = header_page(|b| { + // fact_page_count (bytes 72..80, v6+) > page_count (1) is invalid. + b[72..80].copy_from_slice(&5u64.to_le_bytes()); + }); + write_file(&path, &bytes); + + let err = match Minigraf::open(&path) { + Ok(_) => panic!("opening a file with fact_page_count > page_count should fail"), + Err(e) => e, + }; + assert_eq!(err.code(), "STG-009"); + assert_eq!(err.category(), ErrorCategory::Storage); +} + +#[test] +fn second_open_in_same_process_returns_stg_025() { + let dir = scratch_dir("dup_open"); + let path = dir.join("dup.graph"); + + let first = Minigraf::open(&path).expect("first open should succeed"); + let err = match Minigraf::open(&path) { + Ok(_) => panic!("a second handle in the same process must be refused"), + Err(e) => e, + }; + assert_eq!(err.code(), "STG-025"); + assert_eq!(err.category(), ErrorCategory::Storage); + drop(first); +} From ee480d356f59b35bdd8a0321eab161ec48ee52a3 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Wed, 26 Aug 2026 01:15:13 +0530 Subject: [PATCH 2/2] perf(error): shrink CodedError/ErrorCode binary-size footprint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Drop derive(Debug) on ErrorCode: with the registry growing to 130 variants across #277's six category PRs, the generated per-variant match arm is pure binary-size cost with no runtime use — nothing formats an ErrorCode with {:?}. - Hand-write CodedError's Debug impl instead of deriving it, reusing the already-formatted message and the stable code string rather than requiring ErrorCode: Debug. - Mark CodedError::new #[cold]/#[inline(never)]: error construction is the cold path at every bail_coded!/err_coded! call site (currently ~50, eventually ~250+), so keep the registry lookup + format_template call out of line instead of duplicating it inline per call site. Toward the binary-size pressure from #277 (see #367's raise of the CI budget from 1MB to ~1.2MB for the full context). Part of #277 --- src/error.rs | 48 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/src/error.rs b/src/error.rs index fdf099df14..8c923156fa 100644 --- a/src/error.rs +++ b/src/error.rs @@ -33,7 +33,16 @@ pub enum ErrorCategory { /// it resolves to via [`REGISTRY`] is public (through [`MinigrafError::code`]). /// Kept internal so this enum is free to be reorganized without breaking any /// downstream `match`. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] +/// +/// Deliberately does NOT derive `Debug`: this enum's variant count tracks +/// every documented error code (130 once all six #277 category PRs land), +/// and a derived `Debug` impl generates a per-variant string-literal match +/// arm that's pure binary-size cost with no runtime use anywhere in this +/// crate (nothing formats an `ErrorCode` with `{:?}` — [`CodedError`]'s own +/// hand-written `Debug` below only needs the already-formatted `message` +/// and the code string, not this enum). Keeps the project's <1MB binary +/// size goal (see PHILOSOPHY.md) affordable as the registry grows. +#[derive(Clone, Copy, PartialEq, Eq)] pub(crate) enum ErrorCode { Int000, Stg001, @@ -340,13 +349,23 @@ pub(crate) fn format_template(template: &str, args: &[&dyn fmt::Display]) -> Str /// plumbing (`?`, `.context()`) unchanged. Recovered at the public API /// boundary by [`MinigrafError::from`]`(anyhow::Error)` walking the error /// chain for the first `CodedError` via `downcast_ref`. -#[derive(Debug)] pub(crate) struct CodedError { code: ErrorCode, message: String, } impl CodedError { + /// `#[cold]`/`#[inline(never)]`: `bail_coded!`/`err_coded!` expand to a + /// call to this at every one of the (currently ~50, eventually ~250+ + /// once all six #277 category PRs land) error call sites across the + /// crate. Error construction is by definition the cold path, so forcing + /// it out of line keeps the lookup + `format_template` call from being + /// duplicated inline at each one — pure binary-size cost for a path + /// that, unlike the argument-array construction immediately at the call + /// site (which still inlines, and is cheap), has no per-call-site + /// specialization to gain from inlining. + #[cold] + #[inline(never)] pub(crate) fn new(code: ErrorCode, args: &[&dyn fmt::Display]) -> Self { let (_, template, _) = registry_entry(code); CodedError { @@ -366,6 +385,21 @@ impl fmt::Display for CodedError { } } +// Hand-written rather than `#[derive(Debug)]`: a derive would require +// `ErrorCode: Debug`, which is deliberately not implemented (see the +// binary-size comment on `ErrorCode`). `std::error::Error` only requires +// `Debug` to exist, not that it echo every field, so this reuses the +// already-formatted `message` plus the stable code string instead. +impl fmt::Debug for CodedError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + let (code_str, ..) = registry_entry(self.code); + f.debug_struct("CodedError") + .field("code", &code_str) + .field("message", &self.message) + .finish() + } +} + impl std::error::Error for CodedError {} /// Return early with a coded, `anyhow`-compatible error. @@ -627,7 +661,10 @@ mod tests { let coded = err .downcast_ref::() .expect("expected a CodedError"); - assert_eq!(coded.code(), ErrorCode::Int000); + assert!( + coded.code() == ErrorCode::Int000, + "expected ErrorCode::Int000" + ); assert_eq!(coded.to_string(), "unclassified internal error: boom"); } @@ -637,7 +674,10 @@ mod tests { let coded = err .downcast_ref::() .expect("expected a CodedError"); - assert_eq!(coded.code(), ErrorCode::Int000); + assert!( + coded.code() == ErrorCode::Int000, + "expected ErrorCode::Int000" + ); } #[test]