Enum SegmentError 

#[non_exhaustive]
pub enum SegmentError {
    Io {
        site: IoSite,
        source: Error,
    },
    Cbor {
        phase: &'static str,
        path: PathBuf,
        message: String,
    },
    Cipher {
        path: PathBuf,
        message: String,
    },
    Integrity {
        path: PathBuf,
        reason: &'static str,
    },
    Locked {
        path: PathBuf,
    },
}

Errors produced by segment-buffer operations.

Every variant carries the site or path of the segment file involved (when one is in scope), so an operator can act on the failure without spelunking through logs.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Io

Filesystem I/O failure (directory creation, segment read/write, rename, etc.).

Carries the IoSite the failure happened on plus the underlying std::io::Error as source. When ? propagates an io::Error without context, the site is IoSite::Unknown; use with_path (or with_dir) to attach the site at high-value call sites.

Fields

site: IoSite

Which site the I/O failed on. See IoSite for the variants.

source: Error

The underlying io::Error, reachable via std::error::Error::source.

Cbor

CBOR serialization or deserialization of a segment file failed.

Fields

phase: &'static str

Which direction failed: "serialize" (writing) or "deserialize" (reading).

path: PathBuf

Path to the offending segment file.

message: String

Underlying CBOR error message.

Cipher

Cipher encrypt or decrypt of a segment file failed (key mismatch, AEAD tag invalid, cipher misconfiguration).

Fields

path: PathBuf

Path to the offending segment file.

message: String

Underlying cipher error message.

Integrity

Segment file failed an integrity check: truncated, too small for the AEAD nonce, or unrecognized envelope.

Fields

path: PathBuf

Path to the offending segment file.

reason: &'static str

What failed, in one short phrase.

Locked

Another process holds the exclusive single-process lock on the buffer directory. Returned by crate::SegmentBuffer::open when the flock on .segment-buffer.lock cannot be acquired. See AGENTS.md § “Single-process invariant”.

Fields

path: PathBuf

Path of the lock file that was contended (typically <dir>/.segment-buffer.lock).

Implementations

impl SegmentError

pub fn with_path(self, path: impl Into<PathBuf>) -> Self

Attach a segment-file path to an existing SegmentError::Io variant whose site is IoSite::Unknown. Returns the error unchanged for other variants or for Io errors already tagged (Dir or Segment) — the first call site to attach context wins.

Use SegmentError::with_dir for operations on the directory itself (create_dir_all, scan, clean_tmp, dir fsync).

pub fn with_dir(self) -> Self

Tag an IoSite::Unknown Io error as a directory operation. Returns the error unchanged for other variants or for Io errors already tagged (Dir or Segment). Use this at directory-operation call sites (create_dir_all, scan, clean_tmp, dir fsync) so operators can distinguish “the directory itself failed” from “a specific segment file failed.”

Trait Implementations

impl Debug for SegmentError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for SegmentError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for SegmentError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for SegmentError

fn from(source: Error) -> Self

Converts to this type from the input type.