Skip to main content

qubit_fs/write/
writer_recovery.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//! Ownership retained after an aggregate write or copy failure.
9
10use std::fmt::Debug;
11use std::fmt::Formatter;
12use std::fmt::Result as FmtResult;
13
14use crate::write::FileWriter;
15use crate::write::RejectedWriter;
16
17/// A retained session that is either validated or restricted to explicit
18/// cleanup.
19///
20/// Matching the variant is required before performing recovery. A rejected
21/// session cannot write or publish data. This value does not describe the
22/// historical publication state; use the failure snapshot for that fact.
23///
24/// # Examples
25///
26/// ```rust
27/// use qubit_fs::error::FsResult;
28/// use qubit_fs::write::WriteAllFailure;
29///
30/// fn clean_up(failure: &mut WriteAllFailure) -> FsResult<()> {
31///     if let Some(recovery) = failure.recovery_mut() {
32///         match recovery {
33///             qubit_fs::write::WriterRecovery::Opened(writer) => {
34///                 writer.abort()?;
35///             }
36///             qubit_fs::write::WriterRecovery::Rejected(writer) => {
37///                 writer.abort()?;
38///             }
39///         }
40///     }
41///     Ok(())
42/// }
43/// ```
44#[must_use]
45pub enum WriterRecovery {
46    /// A validated writer retained for explicit recovery.
47    Opened(
48        /// Validated writer that can perform writes, publication, or recovery.
49        Box<FileWriter>,
50    ),
51    /// A provider session whose returned identity failed validation.
52    Rejected(
53        /// Rejected provider session restricted to explicit cleanup.
54        RejectedWriter,
55    ),
56}
57
58impl Debug for WriterRecovery {
59    /// Formats the variant without exposing provider session internals.
60    /// # Parameters
61    /// - `formatter`: Formatter receiving the diagnostic representation.
62    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
63        formatter.write_str(match self {
64            Self::Opened(_) => "WriterRecovery::Opened",
65            Self::Rejected(_) => "WriterRecovery::Rejected",
66        })
67    }
68}