aster_forge_cloud_files_core/
error.rs

1//! Error types for the cloud-files core model.
2
3/// Result type returned by cloud-files core validation and capability operations.
4pub type Result<T> = std::result::Result<T, CloudFilesCoreError>;
5
6/// Product-neutral failures produced while validating core values and capability intersections.
7#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
8pub enum CloudFilesCoreError {
9    /// An opaque identity, revision, cursor, or digest field was empty.
10    #[error("{field} must not be empty")]
11    EmptyValue {
12        /// Stable field classification suitable for product-side error mapping.
13        field: &'static str,
14    },
15    /// An encoded native identity exceeded the active platform limit.
16    #[error("native identity is {actual_bytes} bytes, exceeding the {max_bytes}-byte limit")]
17    NativeIdentityTooLarge {
18        /// Actual encoded identity size.
19        actual_bytes: usize,
20        /// Maximum accepted size for the active platform adapter.
21        max_bytes: usize,
22    },
23    /// Two range-alignment constraints could not be combined without overflow.
24    #[error("range alignment intersection overflowed for {left} and {right}")]
25    AlignmentIntersectionOverflow {
26        /// Left alignment in bytes.
27        left: u64,
28        /// Right alignment in bytes.
29        right: u64,
30    },
31    /// A backend or adapter omitted an invariant required by the core identity contract.
32    #[error("required cloud-files capability is missing: {capability}")]
33    MissingRequiredCapability {
34        /// Stable capability name suitable for diagnostics and tests.
35        capability: &'static str,
36    },
37    /// An item combined root, parent, kind, or content fields in an invalid shape.
38    #[error("invalid cloud item shape: {reason}")]
39    InvalidItemShape {
40        /// Stable validation reason suitable for deterministic contract tests.
41        reason: &'static str,
42    },
43    /// A byte range used a zero length or overflowed its end position.
44    #[error("invalid byte range: {reason}")]
45    InvalidByteRange {
46        /// Stable validation reason suitable for deterministic contract tests.
47        reason: &'static str,
48    },
49    /// Backend content bytes did not satisfy the revision or range request contract.
50    #[error("invalid content response: {reason}")]
51    InvalidContentResponse {
52        /// Stable validation reason suitable for deterministic contract tests.
53        reason: &'static str,
54    },
55    /// A mutation intent omitted required state or combined incompatible fields.
56    #[error("invalid mutation intent: {reason}")]
57    InvalidMutationIntent {
58        /// Stable validation reason suitable for deterministic contract tests.
59        reason: &'static str,
60    },
61    /// A durable mutation record attempted an invalid state transition.
62    #[error("invalid mutation transition: {reason}")]
63    InvalidMutationTransition {
64        /// Stable validation reason suitable for deterministic contract tests.
65        reason: &'static str,
66    },
67    /// A session generation used zero, which is reserved for the absence of a session.
68    #[error("session generation must be non-zero")]
69    InvalidSessionGeneration,
70    /// A local-content generation used zero, which is reserved for the absence of a snapshot.
71    #[error("local content generation must be non-zero")]
72    InvalidLocalContentGeneration,
73    /// Content storage ownership, range coverage, leases, or materialization state was invalid.
74    #[error("invalid content storage state: {reason}")]
75    InvalidContentStorageState {
76        /// Stable validation reason suitable for deterministic contract tests.
77        reason: &'static str,
78    },
79    /// An eviction record attempted an invalid durable transition or physical effect.
80    #[error("invalid content eviction transition: {reason}")]
81    InvalidContentEvictionTransition {
82        /// Stable validation reason suitable for deterministic contract tests.
83        reason: &'static str,
84    },
85    /// A provider-cache write attempted an invalid durable transition.
86    #[error("invalid content cache write transition: {reason}")]
87    InvalidContentCacheWriteTransition {
88        /// Stable validation reason suitable for deterministic contract tests.
89        reason: &'static str,
90    },
91    /// A resumable content upload attempted an invalid request or durable transition.
92    #[error("invalid content upload transition: {reason}")]
93    InvalidContentUploadTransition {
94        /// Stable validation reason suitable for deterministic contract tests.
95        reason: &'static str,
96    },
97}
98
99impl CloudFilesCoreError {
100    pub(crate) const fn empty(field: &'static str) -> Self {
101        Self::EmptyValue { field }
102    }
103
104    pub(crate) const fn invalid_item(reason: &'static str) -> Self {
105        Self::InvalidItemShape { reason }
106    }
107
108    pub(crate) const fn invalid_byte_range(reason: &'static str) -> Self {
109        Self::InvalidByteRange { reason }
110    }
111
112    pub(crate) const fn invalid_content_response(reason: &'static str) -> Self {
113        Self::InvalidContentResponse { reason }
114    }
115
116    pub(crate) const fn invalid_mutation_intent(reason: &'static str) -> Self {
117        Self::InvalidMutationIntent { reason }
118    }
119
120    pub(crate) const fn invalid_mutation_transition(reason: &'static str) -> Self {
121        Self::InvalidMutationTransition { reason }
122    }
123
124    pub(crate) const fn invalid_content_storage(reason: &'static str) -> Self {
125        Self::InvalidContentStorageState { reason }
126    }
127
128    pub(crate) const fn invalid_content_eviction(reason: &'static str) -> Self {
129        Self::InvalidContentEvictionTransition { reason }
130    }
131
132    pub(crate) const fn invalid_content_cache_write(reason: &'static str) -> Self {
133        Self::InvalidContentCacheWriteTransition { reason }
134    }
135
136    pub(crate) const fn invalid_content_upload(reason: &'static str) -> Self {
137        Self::InvalidContentUploadTransition { reason }
138    }
139}
aster_forge_cloud_files_core/error.rs

aster_forge_cloud_files_core/
error.rs
