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