Skip to main content

qubit_fs/write/
async_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::AsyncFileWriter;
15use crate::write::RejectedAsyncWriter;
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/// Recovery values come from an operation through `recovery` or
24/// `take_recovery`. This mutable-borrow helper leaves ownership with the
25/// caller if abort fails.
26///
27/// # Examples
28///
29/// The caller supplies a retained recovery value from an operation.
30///
31/// ```rust
32/// use qubit_fs::error::FsResult;
33/// use qubit_fs::write::{AsyncWriterRecovery, WriteAbortOutcome};
34///
35/// async fn abort_retained(
36///     recovery: &mut AsyncWriterRecovery,
37/// ) -> FsResult<WriteAbortOutcome> {
38///     match recovery {
39///         AsyncWriterRecovery::Opened(writer) => writer.abort_async().await,
40///         AsyncWriterRecovery::Rejected(writer) => writer.abort_async().await,
41///     }
42/// }
43/// ```
44#[must_use]
45pub enum AsyncWriterRecovery {
46    /// A validated writer retained for explicit recovery.
47    Opened(
48        /// Validated writer that can perform writes, publication, or recovery.
49        Box<AsyncFileWriter>,
50    ),
51    /// A provider session whose returned identity failed validation.
52    Rejected(
53        /// Rejected provider session restricted to explicit cleanup.
54        RejectedAsyncWriter,
55    ),
56}
57
58impl AsyncWriterRecovery {
59    /// Borrows a validated writer, or returns None for a rejected session.
60    #[inline]
61    pub(crate) fn opened(&self) -> Option<&AsyncFileWriter> {
62        match self {
63            Self::Opened(writer) => Some(writer),
64            Self::Rejected(_) => None,
65        }
66    }
67
68    /// Mutably borrows a validated writer, or returns None for a rejected
69    /// session.
70    #[inline]
71    pub(crate) fn opened_mut(&mut self) -> Option<&mut AsyncFileWriter> {
72        match self {
73            Self::Opened(writer) => Some(writer),
74            Self::Rejected(_) => None,
75        }
76    }
77}
78
79impl Debug for AsyncWriterRecovery {
80    /// Formats the variant without exposing provider session internals.
81    /// # Parameters
82    /// - `formatter`: Formatter receiving the diagnostic representation.
83    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
84        formatter.write_str(match self {
85            Self::Opened(_) => "AsyncWriterRecovery::Opened",
86            Self::Rejected(_) => "AsyncWriterRecovery::Rejected",
87        })
88    }
89}