qubit_fs/write/
write_failure.rs

1// =============================================================================
2//    Copyright (c) 2025 - 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8// facade tests.
9//! Typed synchronous write failure.
10
11use std::error::Error;
12use std::fmt::Display;
13use std::fmt::Formatter;
14use std::fmt::Result as FmtResult;
15
16use crate::error::FsError;
17use crate::write::WriteFailureState;
18
19/// Write error paired with provider-confirmed publication progress.
20///
21/// # Examples
22///
23/// ```rust
24/// use qubit_fs::error::{FsError, FsErrorKind, FsOperation};
25/// use qubit_fs::write::{WriteFailure, WriteFailureState};
26///
27/// let failure = WriteFailure::new(
28///     FsError::new(FsErrorKind::Io, FsOperation::Write, "failed"),
29///     WriteFailureState::NotPublished,
30/// );
31/// assert_eq!(WriteFailureState::NotPublished, failure.state());
32/// ```
33#[derive(Debug)]
34pub struct WriteFailure {
35    /// Contextual filesystem error returned by the write attempt.
36    error: FsError,
37    /// Provider-confirmed publication and recovery state.
38    state: WriteFailureState,
39}
40
41impl WriteFailure {
42    /// Creates a typed write failure.
43    ///
44    /// # Parameters
45    /// - `error`: Underlying filesystem failure.
46    /// - `state`: Confirmed publication and recovery state.
47    ///
48    /// # Returns
49    /// A failure preserving both the cause and recovery contract.
50    #[inline]
51    #[must_use]
52    pub fn new(error: FsError, state: WriteFailureState) -> Self {
53        Self { error, state }
54    }
55
56    /// Returns provider-confirmed publication progress.
57    ///
58    /// # Returns
59    /// The recovery state for this commit attempt.
60    #[inline]
61    #[must_use]
62    pub const fn state(&self) -> WriteFailureState {
63        self.state
64    }
65
66    /// Returns the underlying filesystem error.
67    ///
68    /// # Returns
69    /// The error with operation, path, provider, and source context.
70    #[inline]
71    #[must_use]
72    pub const fn error(&self) -> &FsError {
73        &self.error
74    }
75
76    /// Consumes this failure and returns the underlying filesystem error.
77    ///
78    /// # Returns
79    /// The owned filesystem error.
80    #[inline]
81    #[must_use]
82    pub fn into_error(self) -> FsError {
83        self.error
84    }
85
86    /// Splits this facade failure into its causal error and state.
87    #[inline]
88    #[must_use]
89    pub fn into_parts(self) -> (FsError, WriteFailureState) {
90        (self.error, self.state)
91    }
92}
93
94impl Display for WriteFailure {
95    #[inline]
96    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
97        write!(formatter, "write {:?}: {}", self.state, self.error)
98    }
99}
100
101impl Error for WriteFailure {
102    #[inline]
103    fn source(&self) -> Option<&(dyn Error + 'static)> {
104        Some(&self.error)
105    }
106}
qubit_fs/write/write_failure.rs

qubit_fs/write/
write_failure.rs
