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}