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}