Skip to main content

qubit_fs_testkit/
contract_async_write_failure.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Whole-file write failures paired with their recovery operation.
9
10use std::error::Error;
11use std::fmt::Debug;
12use std::fmt::Display;
13use std::fmt::Formatter;
14use std::fmt::Result as FmtResult;
15
16use qubit_fs::error::FsError;
17use qubit_fs::write::AsyncWriteAllOperation;
18use qubit_fs::write::AsyncWriteAllOperationFailure;
19
20/// Retains a whole-file failure snapshot and its operation, when admitted.
21///
22/// Obtain this value through [`crate::ContractSource::take`] and downcast it.
23/// Admission failures have no operation. Execution failures retain the
24/// operation even when it has no recovery writer. Taking this value transfers
25/// any recovery responsibility to the caller; dropping it does not perform
26/// asynchronous abort. Formatting never invokes a provider formatter.
27///
28/// # Examples
29///
30/// ```
31/// use qubit_fs::error::FsError;
32/// use qubit_fs_testkit::ContractAsyncWriteFailure;
33///
34/// fn inspect_error(failure: &ContractAsyncWriteFailure) -> &FsError {
35///     failure.error()
36/// }
37/// ```
38#[must_use]
39pub struct ContractAsyncWriteFailure {
40    /// Original failure state and accepted byte count captured at failure.
41    failure: AsyncWriteAllOperationFailure,
42    /// Operation retaining any recovery session after execution failure.
43    operation: Option<AsyncWriteAllOperation>,
44}
45
46impl ContractAsyncWriteFailure {
47    /// Returns the original filesystem error retained by the failure snapshot.
48    ///
49    /// # Returns
50    ///
51    /// A borrow of the contextual filesystem error.
52    #[inline]
53    pub const fn error(&self) -> &FsError {
54        self.failure.error()
55    }
56
57    /// Returns the failure's publication state and accepted byte count
58    /// snapshot.
59    ///
60    /// # Returns
61    ///
62    /// A borrow of the immutable failure snapshot.
63    #[must_use = "inspect or retain the write failure snapshot"]
64    #[inline]
65    pub const fn failure(&self) -> &AsyncWriteAllOperationFailure {
66        &self.failure
67    }
68
69    /// Borrows the operation if request admission succeeded.
70    ///
71    /// # Returns
72    ///
73    /// `Some` when the request was admitted and has an operation, or `None`
74    /// when admission failed before an operation was created.
75    #[inline]
76    pub const fn operation(&self) -> Option<&AsyncWriteAllOperation> {
77        self.operation.as_ref()
78    }
79
80    /// Borrows the operation for explicit recovery writer transfer or
81    /// inspection.
82    ///
83    /// # Returns
84    ///
85    /// `Some` when an operation was retained, or `None` when admission failed.
86    #[inline]
87    pub fn operation_mut(&mut self) -> Option<&mut AsyncWriteAllOperation> {
88        self.operation.as_mut()
89    }
90
91    /// Transfers the failure snapshot and optional recovery operation.
92    ///
93    /// # Returns
94    ///
95    /// The failure facts and the operation when request admission succeeded.
96    pub fn into_parts(self) -> (AsyncWriteAllOperationFailure, Option<AsyncWriteAllOperation>) {
97        (self.failure, self.operation)
98    }
99
100    /// Pairs a failure with the operation that owns its recovery session.
101    ///
102    /// # Parameters
103    ///
104    /// - `failure`: The immutable whole-file failure snapshot to retain.
105    /// - `operation`: The admitted operation, when request admission succeeded.
106    ///
107    /// # Returns
108    ///
109    /// A wrapper that preserves the failure and optional operation together.
110    pub(crate) fn new(failure: AsyncWriteAllOperationFailure, operation: Option<AsyncWriteAllOperation>) -> Self {
111        Self { failure, operation }
112    }
113}
114
115impl Debug for ContractAsyncWriteFailure {
116    /// Formats a stable summary without invoking provider error formatting.
117    ///
118    /// # Parameters
119    ///
120    /// - `formatter`: Destination for the stable summary.
121    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
122        formatter
123            .debug_struct("ContractAsyncWriteFailure")
124            .field("has_operation", &self.operation.is_some())
125            .finish_non_exhaustive()
126    }
127}
128
129impl Display for ContractAsyncWriteFailure {
130    /// Formats a stable description of the retained write failure.
131    ///
132    /// # Parameters
133    ///
134    /// - `formatter`: Destination for the failure description.
135    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
136        formatter.write_str("whole-file write failed; original failure and available operation retained")
137    }
138}
139
140impl Error for ContractAsyncWriteFailure {
141    /// Exposes the retained write failure as the standard error source.
142    fn source(&self) -> Option<&(dyn Error + 'static)> {
143        Some(&self.failure)
144    }
145}