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}