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}