qubit-fs 0.2.0

Provider-neutral synchronous and asynchronous filesystem abstraction for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
// facade tests.
//! Typed synchronous write failure.

use std::error::Error;
use std::fmt::Display;
use std::fmt::Formatter;
use std::fmt::Result as FmtResult;

use crate::error::FsError;
use crate::write::WriteFailureState;

/// Write error paired with provider-confirmed publication progress.
///
/// # Examples
///
/// ```rust
/// use qubit_fs::error::{FsError, FsErrorKind, FsOperation};
/// use qubit_fs::write::{WriteFailure, WriteFailureState};
///
/// let failure = WriteFailure::new(
///     FsError::new(FsErrorKind::Io, FsOperation::Write, "failed"),
///     WriteFailureState::NotPublished,
/// );
/// assert_eq!(WriteFailureState::NotPublished, failure.state());
/// ```
#[derive(Debug)]
pub struct WriteFailure {
    /// Contextual filesystem error returned by the write attempt.
    error: FsError,
    /// Provider-confirmed publication and recovery state.
    state: WriteFailureState,
}

impl WriteFailure {
    /// Creates a typed write failure.
    ///
    /// # Parameters
    /// - `error`: Underlying filesystem failure.
    /// - `state`: Confirmed publication and recovery state.
    ///
    /// # Returns
    /// A failure preserving both the cause and recovery contract.
    #[inline]
    #[must_use]
    pub fn new(error: FsError, state: WriteFailureState) -> Self {
        Self { error, state }
    }

    /// Returns provider-confirmed publication progress.
    ///
    /// # Returns
    /// The recovery state for this commit attempt.
    #[inline]
    #[must_use]
    pub const fn state(&self) -> WriteFailureState {
        self.state
    }

    /// Returns the underlying filesystem error.
    ///
    /// # Returns
    /// The error with operation, path, provider, and source context.
    #[inline]
    #[must_use]
    pub const fn error(&self) -> &FsError {
        &self.error
    }

    /// Consumes this failure and returns the underlying filesystem error.
    ///
    /// # Returns
    /// The owned filesystem error.
    #[inline]
    #[must_use]
    pub fn into_error(self) -> FsError {
        self.error
    }

    /// Splits this facade failure into its causal error and state.
    #[inline]
    #[must_use]
    pub fn into_parts(self) -> (FsError, WriteFailureState) {
        (self.error, self.state)
    }
}

impl Display for WriteFailure {
    #[inline]
    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
        write!(formatter, "write {:?}: {}", self.state, self.error)
    }
}

impl Error for WriteFailure {
    #[inline]
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        Some(&self.error)
    }
}