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}