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}