Skip to main content

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}