Skip to main content

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//! Typed synchronous write failure.
9
10use std::error::Error;
11use std::fmt::Display;
12use std::fmt::Formatter;
13use std::fmt::Result as FmtResult;
14
15use crate::error::FsError;
16use crate::write::WriteFailureState;
17
18/// Write error paired with provider-confirmed publication progress.
19///
20/// # Examples
21///
22/// ```rust
23/// use qubit_fs::error::{FsError, FsErrorKind, FsOperation};
24/// use qubit_fs::write::{WriteFailure, WriteFailureState};
25///
26/// let failure = WriteFailure::new(
27///     FsError::new(FsErrorKind::Io, FsOperation::Write, "failed"),
28///     WriteFailureState::NotPublished,
29/// );
30/// assert_eq!(WriteFailureState::NotPublished, failure.state());
31/// ```
32#[derive(Debug)]
33#[must_use = "inspect the write failure and its recovery state"]
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    pub fn new(error: FsError, state: WriteFailureState) -> Self {
52        Self { error, state }
53    }
54
55    /// Returns provider-confirmed publication progress.
56    ///
57    /// # Returns
58    /// The recovery state for this commit attempt.
59    #[inline]
60    pub const fn state(&self) -> WriteFailureState {
61        self.state
62    }
63
64    /// Returns the underlying filesystem error.
65    ///
66    /// # Returns
67    /// The error with operation, path, provider, and source context.
68    #[inline]
69    #[must_use = "inspect the underlying filesystem error"]
70    pub const fn error(&self) -> &FsError {
71        &self.error
72    }
73
74    /// Consumes this failure and returns the underlying filesystem error.
75    ///
76    /// # Returns
77    /// The owned filesystem error.
78    #[inline]
79    pub fn into_error(self) -> FsError {
80        self.error
81    }
82
83    /// Splits this facade failure into its causal error and state.
84    #[must_use = "inspect the filesystem error and recovery state"]
85    #[inline]
86    pub fn into_parts(self) -> (FsError, WriteFailureState) {
87        (self.error, self.state)
88    }
89}
90
91impl Display for WriteFailure {
92    /// Formats the publication state together with its cause.
93    /// # Parameters
94    /// - `formatter`: Formatter receiving the diagnostic representation.
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    /// Returns the provider or facade error that caused the write failure.
103    #[inline]
104    fn source(&self) -> Option<&(dyn Error + 'static)> {
105        Some(&self.error)
106    }
107}