Skip to main content

qubit_fs_testkit/
contract_async_copy_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//! Copy operation 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::copy::AsyncCopyFailure;
17use qubit_fs::copy::AsyncCopyOperation;
18use qubit_fs::error::FsError;
19
20/// Retains a copy 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/// When an asynchronous copy check reports a failure, retrieve the retained
31/// operation from its source chain and inspect the filesystem error:
32///
33/// ```
34/// use std::error::Error;
35///
36/// use qubit_fs::error::FsError;
37/// use qubit_fs::error::FsErrorKind;
38/// use qubit_fs_testkit::AsyncFileSystemContractSuite;
39/// use qubit_fs_testkit::AsyncFileSystemFixture;
40/// use qubit_fs_testkit::ContractAsyncCopyFailure;
41/// use qubit_fs_testkit::ContractCheckId;
42/// use qubit_fs_testkit::ContractSource;
43///
44/// fn inspect_error(failure: &ContractAsyncCopyFailure) {
45///     let original_error: &FsError = failure.error();
46///     assert!(!original_error.to_string().is_empty());
47/// }
48/// ```
49#[must_use]
50pub struct ContractAsyncCopyFailure {
51    /// Preserves the original error and the partial copy statistics.
52    failure: AsyncCopyFailure,
53    /// Retains the copy operation after admission, when one is available.
54    operation: Option<AsyncCopyOperation>,
55}
56
57impl ContractAsyncCopyFailure {
58    /// Pairs a failure with the operation that owns its recovery session.
59    ///
60    /// # Parameters
61    ///
62    /// - `failure`: The immutable failure snapshot to retain.
63    /// - `operation`: The admitted operation, when request admission succeeded.
64    ///
65    /// # Returns
66    ///
67    /// A wrapper that retains the failure and optional operation together.
68    pub(crate) fn new(failure: AsyncCopyFailure, operation: Option<AsyncCopyOperation>) -> Self {
69        Self { failure, operation }
70    }
71
72    /// Returns the original filesystem error.
73    #[inline]
74    pub const fn error(&self) -> &FsError {
75        self.failure.error()
76    }
77
78    /// Returns the failure's publication state and partial transfer statistics
79    /// snapshot.
80    #[inline]
81    pub const fn failure(&self) -> &AsyncCopyFailure {
82        &self.failure
83    }
84
85    /// Borrows the operation if request admission succeeded.
86    #[inline]
87    pub const fn operation(&self) -> Option<&AsyncCopyOperation> {
88        self.operation.as_ref()
89    }
90
91    /// Borrows the operation for explicit recovery writer transfer or
92    /// inspection.
93    #[inline]
94    pub fn operation_mut(&mut self) -> Option<&mut AsyncCopyOperation> {
95        self.operation.as_mut()
96    }
97
98    /// Transfers the failure snapshot and optional operation to the caller.
99    ///
100    /// # Returns
101    ///
102    /// The immutable failure facts and the operation when request admission
103    /// succeeded.
104    #[must_use = "retain the failure and operation for inspection or recovery"]
105    pub fn into_parts(self) -> (AsyncCopyFailure, Option<AsyncCopyOperation>) {
106        (self.failure, self.operation)
107    }
108}
109
110impl Debug for ContractAsyncCopyFailure {
111    /// Formats a stable summary without invoking provider error formatting.
112    ///
113    /// # Parameters
114    ///
115    /// - `formatter`: Destination for the stable summary.
116    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
117        formatter
118            .debug_struct("ContractAsyncCopyFailure")
119            .field("has_operation", &self.operation.is_some())
120            .finish_non_exhaustive()
121    }
122}
123
124impl Display for ContractAsyncCopyFailure {
125    /// Formats a stable description of the retained copy failure.
126    ///
127    /// # Parameters
128    ///
129    /// - `formatter`: Destination for the failure description.
130    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
131        formatter.write_str("copy operation failed; original failure and available operation retained")
132    }
133}
134
135impl Error for ContractAsyncCopyFailure {
136    /// Exposes the retained copy failure as the standard error source.
137    fn source(&self) -> Option<&(dyn Error + 'static)> {
138        Some(&self.failure)
139    }
140}