Struct FsError 

pub struct FsError { /* private fields */ }

Provider-neutral filesystem error with operation and path context.

Debug and Display never expand the retained source error because a lower-level SDK or transport diagnostic may contain credentials. Debug reports only whether a source exists; explicit diagnostic code may inspect it through Error::source. The message supplied by constructors must already be scrubbed of secret material.

Examples

use qubit_fs::Path;
use qubit_fs::error::FsError;
use qubit_fs::error::FsErrorKind;
use qubit_fs::error::FsOperation;

let path = Path::parse("/reports/latest.csv")?;
let error = FsError::new(FsErrorKind::NotFound, FsOperation::Stat, "object missing")
    .with_path(path.clone());
assert_eq!(FsErrorKind::NotFound, error.kind());
assert_eq!(Some(&path), error.path());

Implementations

impl FsError

pub fn new(kind: FsErrorKind, operation: FsOperation, message: &str) -> Self

Creates a filesystem error without path or provider context.

Parameters

• kind: Provider-neutral error category.
• operation: Operation that produced the error.
• message: Human-readable diagnostic message that must not contain credentials or other secret material.

Returns

New filesystem error.

pub fn with_source<E>( kind: FsErrorKind, operation: FsOperation, message: &str, source: E, ) -> Self

where E: Error + Send + Sync + 'static,

Creates a filesystem error that wraps a lower-level source error.

Parameters

• kind: Provider-neutral error category.
• operation: Operation that produced the error.
• message: Human-readable diagnostic message that must not contain credentials or other secret material.
• source: Lower-level error to preserve. Its formatting may contain secrets and is therefore never expanded by this type’s Debug or Display implementation.

Returns

New filesystem error with source context.

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

Adds primary path context.

Parameters

• path: Concrete path where the operation failed. For a two-path operation this may be either request path; use Self::target to identify the destination.

Returns

Updated filesystem error.

pub fn with_operation(self, operation: FsOperation) -> Self

Rebinds the error to the public operation that was requested.

This is useful for convenience operations implemented through another primitive, such as exists implemented through stat, while retaining all path, provider, capability, and source context.

Parameters

• operation: Public operation whose failure is being returned.

Returns

Updated filesystem error.

pub fn with_target(self, target: impl Into<Path>) -> Self

Adds secondary target path context.

Parameters

• target: Destination path of a two-path operation.

Returns

Updated filesystem error.

pub fn with_failure_path(self, path: impl Into<Path>) -> Self

Adds the concrete source entry where a structured operation failed.

pub fn with_failure_target(self, target: impl Into<Path>) -> Self

Adds the concrete destination entry where a structured operation failed.

pub fn with_provider(self, provider: impl Display) -> Self

Adds provider context.

Parameters

• provider: Canonical provider id involved in the operation.

Returns

Updated filesystem error.

pub fn with_required_capability(self, capability: FileSystemCapability) -> Self

Adds the capability required by an unsupported or unmet request.

Parameters

• capability: Stable capability required by the request.

Returns

Updated filesystem error.

pub fn with_effect_state(self, effect_state: FsEffectState) -> Self

Adds the strongest known external effect of the failed operation.

Parameters

• effect_state - Provider-neutral effect state proven by the provider.

Returns

Updated filesystem error.

pub fn invalid_path(operation: FsOperation, message: &str) -> Self

Creates an invalid-path error.

Parameters

• operation: Operation that rejected the path.
• message: Human-readable reason.

Returns

Invalid-path filesystem error.

pub fn from_io(error: Error, operation: FsOperation) -> Self

Wraps a byte-stream error with filesystem operation context.

Parameters

• error: Lower-level stream error.
• operation: Filesystem operation in progress when it occurred.

Returns

A filesystem error retaining error as its source.

pub fn kind(&self) -> FsErrorKind

Returns the provider-neutral error category.

Returns

Error category.

pub fn operation(&self) -> FsOperation

Returns the operation that produced this error.

Returns

The provider-neutral operation identifier.

pub fn path(&self) -> Option<&Path>

Returns the primary path associated with this error.

Returns

The path when one was attached.

pub fn target(&self) -> Option<&Path>

Returns the secondary target path associated with this error.

Returns

The target path when one was attached.

pub fn failure_path(&self) -> Option<&Path>

Returns the concrete source entry where the operation failed.

Returns

The structured source path when one was attached for copy, rename, or similar multi-path operations.

pub fn failure_target(&self) -> Option<&Path>

Returns the concrete destination entry where the operation failed.

Returns

The structured destination path when one was attached for copy, rename, or similar multi-path operations.

pub fn provider(&self) -> Option<&str>

Returns the provider associated with this error.

Returns

The canonical provider id when one was attached.

pub fn required_capability(&self) -> Option<FileSystemCapability>

Returns the required capability associated with this error.

Returns

The capability when the error describes unsupported functionality or an unmet semantic requirement.

pub fn effect_state(&self) -> Option<FsEffectState>

Returns the strongest known external effect of the failed operation.

Returns

Some when a provider proved an effect state, or None when the error carries no effect-state claim.

pub fn has_indeterminate_effect(&self) -> bool

Returns whether the operation’s external effect cannot be determined.

pub fn into_io_error(self) -> Error

Converts this filesystem error into a byte-stream error.

The complete FsError is retained as the io::Error source so callers crossing the open/stream boundary do not lose provider, operation, or path context.

Returns

An I/O error with a corresponding standard category.

Trait Implementations

impl Debug for FsError

fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.

impl Display for FsError

fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.

impl Error for FsError

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.