Skip to main content

qubit_fs/write/
write_failure_state.rs

1// =============================================================================
2//    Copyright (c) 2025 - 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Recovery states for failed synchronous writes.
9
10/// Provider-confirmed recovery state when a write commit fails.
11///
12/// # Examples
13///
14/// ```rust
15/// use qubit_fs::write::WriteFailureState;
16///
17/// let state = WriteFailureState::RetryableNotPublished;
18/// match state {
19///     WriteFailureState::RetryableNotPublished => println!("retry the commit"),
20///     WriteFailureState::NotPublished => println!("clean up the unpublished target"),
21///     WriteFailureState::Published => println!("preserve the published target; clean up only the session or staging resources"),
22///     WriteFailureState::Indeterminate => println!("resolve publication status"),
23/// }
24/// ```
25///
26/// `Published` means the destination must be preserved; do not retry
27/// publication as though it had failed. Cleanup applies only to resources still
28/// owned by the writer, such as a session or staging data. Successful cleanup
29/// does not roll back the published target.
30#[must_use]
31#[derive(Clone, Copy, Debug, Eq, PartialEq)]
32pub enum WriteFailureState {
33    /// Publication can be retried using the retained session.
34    RetryableNotPublished,
35    /// The target was not published and only cleanup remains possible.
36    NotPublished,
37    /// The target was published and only cleanup remains possible.
38    Published,
39    /// The provider cannot determine whether publication occurred.
40    Indeterminate,
41}