qubit_fs_testkit/contract_writer_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//! Original writer errors paired with their still-owned recovery session.
9
10use std::error::Error;
11use std::fmt::Debug;
12use std::fmt::Display;
13use std::fmt::Formatter;
14use std::fmt::Result as FmtResult;
15
16/// A failed streaming operation whose writer remains available for recovery.
17///
18/// # Type Parameters
19///
20/// - `W`: The writer or owning operation retained for explicit recovery.
21///
22/// `W` is the synchronous or asynchronous writer, or an owning asynchronous
23/// write/copy operation retained after a cancellation diagnostic failure.
24/// Obtain this value through [`crate::ContractSource::take`] and downcast to
25/// the concrete type. For `ContractWriterFailure<AsyncWriteAllOperation>` or
26/// `ContractWriterFailure<AsyncCopyOperation>`, `error()` contains the original
27/// diagnostic [`crate::ContractFailure`], and `writer_mut()` exposes the
28/// operation. Call its `take_recovery()` and explicitly abort the returned
29/// writer when recovery is required. Taking the source transfers recovery
30/// responsibility to the caller. Formatting does not inspect the retained
31/// value or invoke a provider error formatter.
32///
33/// # Examples
34///
35/// Downcast the error returned from [`crate::ContractSource::take`] to the
36/// concrete writer failure, then inspect the retained writer:
37///
38/// ```
39/// use qubit_fs_testkit::ContractWriterFailure;
40///
41/// fn inspect_writer<W>(failure: &ContractWriterFailure<W>) -> &W {
42/// failure.writer()
43/// }
44/// ```
45#[must_use]
46pub struct ContractWriterFailure<W> {
47 /// Original typed error retained for inspection and error chaining.
48 error: Box<dyn Error + Send>,
49 /// Writer or owning operation retained for explicit recovery.
50 writer: W,
51}
52
53impl<W> ContractWriterFailure<W> {
54 /// Retains a streaming failure before its writer can leave scope.
55 ///
56 /// # Parameters
57 ///
58 /// - `error`: The original typed error to preserve.
59 /// - `writer`: The still-owned writer or operation to retain.
60 pub(crate) fn new(error: impl Error + Send + 'static, writer: W) -> Self {
61 Self {
62 error: Box::new(error),
63 writer,
64 }
65 }
66
67 /// Returns the original error for typed inspection.
68 #[must_use = "inspect the original error or intentionally ignore it"]
69 #[inline]
70 pub fn error(&self) -> &(dyn Error + Send + 'static) {
71 self.error.as_ref()
72 }
73
74 /// Borrows the retained writer for lifecycle inspection.
75 #[must_use = "inspect the retained recovery writer or intentionally ignore it"]
76 #[inline]
77 pub const fn writer(&self) -> &W {
78 &self.writer
79 }
80
81 /// Borrows the retained writer for explicit recovery or abort.
82 #[must_use = "use the mutable writer reference to recover or abort the writer"]
83 #[inline]
84 pub fn writer_mut(&mut self) -> &mut W {
85 &mut self.writer
86 }
87
88 /// Transfers both the original error and its writer to the caller.
89 #[must_use = "recover or intentionally discard the original error and writer"]
90 pub fn into_parts(self) -> (Box<dyn Error + Send>, W) {
91 (self.error, self.writer)
92 }
93}
94
95impl<W> Debug for ContractWriterFailure<W> {
96 /// Formats a stable summary without invoking the retained error formatter.
97 ///
98 /// # Parameters
99 ///
100 /// - `formatter`: Destination for the stable failure summary.
101 fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
102 formatter.write_str("ContractWriterFailure { writer: retained, error: retained }")
103 }
104}
105
106impl<W> Display for ContractWriterFailure<W> {
107 /// Formats a stable description of the retained streaming failure.
108 ///
109 /// # Parameters
110 ///
111 /// - `formatter`: Destination for the failure description.
112 fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
113 formatter.write_str("streaming writer failed; original error and recovery writer retained")
114 }
115}
116
117impl<W> Error for ContractWriterFailure<W> {
118 /// Exposes the retained original error as the standard error source.
119 fn source(&self) -> Option<&(dyn Error + 'static)> {
120 Some(self.error.as_ref())
121 }
122}