qubit-fs 0.3.2

Provider-neutral synchronous and asynchronous filesystem abstraction for Rust
Documentation
// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Ownership retained after an aggregate write or copy failure.

use std::fmt::Debug;
use std::fmt::Formatter;
use std::fmt::Result as FmtResult;

use crate::write::AsyncFileWriter;
use crate::write::RejectedAsyncWriter;

/// A retained session that is either validated or restricted to explicit
/// cleanup.
///
/// Matching the variant is required before performing recovery. A rejected
/// session cannot write or publish data. This value does not describe the
/// historical publication state; use the failure snapshot for that fact.
/// Recovery values come from an operation through `recovery` or
/// `take_recovery`. This mutable-borrow helper leaves ownership with the
/// caller if abort fails.
///
/// # Examples
///
/// The caller supplies a retained recovery value from an operation.
///
/// ```rust
/// use qubit_fs::error::FsResult;
/// use qubit_fs::write::{AsyncWriterRecovery, WriteAbortOutcome};
///
/// async fn abort_retained(
///     recovery: &mut AsyncWriterRecovery,
/// ) -> FsResult<WriteAbortOutcome> {
///     match recovery {
///         AsyncWriterRecovery::Opened(writer) => writer.abort_async().await,
///         AsyncWriterRecovery::Rejected(writer) => writer.abort_async().await,
///     }
/// }
/// ```
#[must_use]
pub enum AsyncWriterRecovery {
    /// A validated writer retained for explicit recovery.
    Opened(
        /// Validated writer that can perform writes, publication, or recovery.
        Box<AsyncFileWriter>,
    ),
    /// A provider session whose returned identity failed validation.
    Rejected(
        /// Rejected provider session restricted to explicit cleanup.
        RejectedAsyncWriter,
    ),
}

impl AsyncWriterRecovery {
    /// Borrows a validated writer, or returns None for a rejected session.
    #[inline]
    pub(crate) fn opened(&self) -> Option<&AsyncFileWriter> {
        match self {
            Self::Opened(writer) => Some(writer),
            Self::Rejected(_) => None,
        }
    }

    /// Mutably borrows a validated writer, or returns None for a rejected
    /// session.
    #[inline]
    pub(crate) fn opened_mut(&mut self) -> Option<&mut AsyncFileWriter> {
        match self {
            Self::Opened(writer) => Some(writer),
            Self::Rejected(_) => None,
        }
    }
}

impl Debug for AsyncWriterRecovery {
    /// Formats the variant without exposing provider session internals.
    /// # Parameters
    /// - `formatter`: Formatter receiving the diagnostic representation.
    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
        formatter.write_str(match self {
            Self::Opened(_) => "AsyncWriterRecovery::Opened",
            Self::Rejected(_) => "AsyncWriterRecovery::Rejected",
        })
    }
}