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.
// =============================================================================
// facade.
//! Provider-side synchronous temporary-resource sessions.

use super::PersistRequest;
use super::SpiPersistFailure;
use crate::error::FsResult;
use crate::temp::PersistOutcome;

/// Provider temporary-resource lifecycle session.
///
/// # Examples
///
/// ```
/// use qubit_fs::error::FsResult;
/// use qubit_fs::spi::TempResourceSpi;
///
/// struct TemporaryResource;
///
/// impl TempResourceSpi for TemporaryResource {
///     fn persist(
///         &mut self,
///         _: qubit_fs::spi::PersistRequest<'_>,
///     ) -> Result<qubit_fs::temp::PersistOutcome, qubit_fs::spi::SpiPersistFailure> {
///         unimplemented!()
///     }
///
///     fn keep(
///         &mut self,
///     ) -> Result<qubit_fs::temp::PersistOutcome, qubit_fs::spi::SpiPersistFailure> {
///         unimplemented!()
///     }
///
///     fn cleanup(&mut self) -> FsResult<()> {
///         Ok(())
///     }
/// }
///
/// let mut resource = TemporaryResource;
/// resource.cleanup()?;
/// # Ok::<(), qubit_fs::FsError>(())
/// ```
pub trait TempResourceSpi: Send {
    /// Persists a temporary resource.
    ///
    /// # Parameters
    /// - `request`: Validated target and persistence requirements.
    ///
    /// # Returns
    /// The confirmed persistence outcome.
    ///
    /// # Errors
    /// Returns provider-confirmed failure and recovery state when persistence
    /// does not complete successfully.
    fn persist(&mut self, request: PersistRequest<'_>) -> Result<PersistOutcome, SpiPersistFailure>;

    /// Publishes the temporary resource to a provider-generated target.
    ///
    /// # Returns
    /// The confirmed publication outcome.
    ///
    /// # Errors
    /// Returns the provider-confirmed failure and recovery state when
    /// publication cannot be completed.
    fn keep(&mut self) -> Result<PersistOutcome, SpiPersistFailure>;

    /// Cleans the temporary source.
    ///
    /// # Returns
    /// `Ok(())` after cleanup is confirmed.
    ///
    /// # Errors
    /// Returns the provider cleanup failure with filesystem context.
    fn cleanup(&mut self) -> FsResult<()>;
}