aster_forge_cloud_files_windows/error.rs
1//! Structured Windows adapter failures.
2
3use thiserror::Error;
4
5/// Result type returned by the Windows cloud-files adapter.
6pub type Result<T> = std::result::Result<T, WindowsCloudFilesError>;
7
8/// Product-neutral classifications for Windows-specific mapping and native-call failures.
9#[derive(Debug, Error)]
10pub enum WindowsCloudFilesError {
11 /// The encoded CFAPI file identity exceeded the documented 4 KiB boundary.
12 #[error("CFAPI file identity is {actual} bytes, exceeding the {maximum}-byte limit")]
13 FileIdentityTooLarge {
14 /// Encoded byte length.
15 actual: usize,
16 /// Maximum accepted byte length.
17 maximum: usize,
18 },
19 /// The encoded sync-root identity exceeded the documented 64 KiB boundary.
20 #[error("CFAPI sync-root identity is {actual} bytes, exceeding the {maximum}-byte limit")]
21 SyncRootIdentityTooLarge {
22 /// Encoded byte length.
23 actual: usize,
24 /// Maximum accepted byte length.
25 maximum: usize,
26 },
27 /// An encoded identity envelope was malformed or used an unsupported format version.
28 #[error("invalid CFAPI file identity: {reason}")]
29 InvalidFileIdentity {
30 /// Stable adapter-level reason suitable for logs and tests.
31 reason: &'static str,
32 },
33 /// An encoded sync-root identity envelope was malformed or unsupported.
34 #[error("invalid CFAPI sync-root identity: {reason}")]
35 InvalidSyncRootIdentity {
36 /// Stable adapter-level reason suitable for logs and tests.
37 reason: &'static str,
38 },
39 /// A product-neutral Forge cloud-files value or hydration contract was invalid.
40 #[error(transparent)]
41 Core(#[from] aster_forge_cloud_files_core::CloudFilesCoreError),
42 /// The supplied identity described another item.
43 #[error("CFAPI file identity does not match the placeholder item")]
44 IdentityItemMismatch,
45 /// The required root file identity belonged to another namespace/root scope.
46 #[error("CFAPI root file identity does not match the sync-root scope")]
47 RootFileIdentityScopeMismatch,
48 /// A provider-facing registration string violated the CFAPI contract.
49 #[error("invalid CFAPI {field}: {reason}")]
50 InvalidRegistrationString {
51 /// Registration field name.
52 field: &'static str,
53 /// Stable reason suitable for logs and tests.
54 reason: &'static str,
55 },
56 /// A zero provider GUID would delegate identity generation to display text.
57 #[error("CFAPI provider id must be a stable non-zero GUID")]
58 EmptyProviderId,
59 /// Hydration or registration policies contradicted each other.
60 #[error("invalid CFAPI sync-root policy: {reason}")]
61 InvalidSyncRootPolicy {
62 /// Stable policy conflict reason.
63 reason: &'static str,
64 },
65 /// A requested policy needs a newer CFAPI platform integration level.
66 #[error(
67 "CFAPI feature {feature} requires integration 0x{required:x}, current integration is 0x{actual:x}"
68 )]
69 UnsupportedPlatformIntegration {
70 /// Feature or policy requiring the newer integration.
71 feature: &'static str,
72 /// Minimum integration number.
73 required: u32,
74 /// Detected integration number.
75 actual: u32,
76 },
77 /// The sync-root path was empty or otherwise unsuitable for registration.
78 #[error("invalid CFAPI sync-root path: {reason}")]
79 InvalidSyncRootPath {
80 /// Stable path validation reason.
81 reason: &'static str,
82 },
83 /// A windows-rs native structure size could not fit the CFAPI `u32` field.
84 #[error("native CFAPI structure size for {structure} exceeds u32")]
85 NativeStructureSizeOverflow {
86 /// Native structure name.
87 structure: &'static str,
88 },
89 /// A Windows placeholder name was not a valid single path component.
90 #[error("invalid Windows placeholder name: {reason}")]
91 InvalidPlaceholderName {
92 /// Stable adapter-level reason suitable for logs and tests.
93 reason: &'static str,
94 },
95 /// Core item metadata could not be represented as a Windows placeholder.
96 #[error("invalid Windows placeholder metadata: {reason}")]
97 InvalidPlaceholderMetadata {
98 /// Stable adapter-level reason suitable for logs and tests.
99 reason: &'static str,
100 },
101 /// A file size could not be represented by the signed CFAPI metadata field.
102 #[error("placeholder size {size} exceeds the CFAPI signed 64-bit file-size boundary")]
103 FileSizeTooLarge {
104 /// Unsigned core file size.
105 size: u64,
106 },
107 /// A Windows path contained an embedded NUL and therefore could not become a wide C string.
108 #[error("Windows path contains an embedded NUL")]
109 EmbeddedNul,
110 /// A placeholder batch exceeded the count representable by CFAPI.
111 #[error("placeholder batch contains more entries than CFAPI can represent")]
112 PlaceholderBatchTooLarge,
113 /// A callback snapshot contained malformed scalar, range, identity, or owned-string data.
114 #[error("invalid CFAPI callback snapshot: {reason}")]
115 InvalidCallbackSnapshot {
116 /// Stable adapter-level reason suitable for logs and tests.
117 reason: &'static str,
118 },
119 /// A detached callback request was asked to perform a native CFAPI terminal operation.
120 #[error("detached CFAPI callback request has no native completion authority")]
121 MissingNativeCompletionAuthority,
122 /// Hydrated bytes could not be represented as one valid CFAPI transfer operation.
123 #[error("invalid CFAPI fetch-data transfer: {reason}")]
124 InvalidFetchTransfer {
125 /// Stable adapter-level reason suitable for logs and tests.
126 reason: &'static str,
127 },
128 /// Product-neutral hydration coordination or backend work failed.
129 #[error(transparent)]
130 Hydration(#[from] aster_forge_cloud_files_core::HydrationError),
131 /// A callback or completion belonged to another platform session generation.
132 #[error("stale CFAPI connection generation: expected {expected}, received {actual}")]
133 StaleConnectionGeneration {
134 /// Generation owned by the active connection.
135 expected: u64,
136 /// Generation captured by the callback or completion.
137 actual: u64,
138 },
139 /// The active connection lifecycle rejected a new callback.
140 #[error("CFAPI connection is not accepting callbacks in state {state:?}")]
141 ConnectionNotAccepting {
142 /// Current product-neutral session state.
143 state: aster_forge_cloud_files_core::SessionState,
144 },
145 /// The requested connection lifecycle transition skipped a required state.
146 #[error("invalid CFAPI connection transition from {from:?} to {to:?}")]
147 InvalidConnectionTransition {
148 /// Current product-neutral session state.
149 from: aster_forge_cloud_files_core::SessionState,
150 /// Requested product-neutral session state.
151 to: aster_forge_cloud_files_core::SessionState,
152 },
153 /// The active callback counter exceeded the host address space.
154 #[error("CFAPI active callback count overflow")]
155 ActiveCallbackCountOverflow,
156 /// The process-local active hydration waiter identity space was exhausted.
157 #[error("CFAPI active fetch waiter identity exhausted")]
158 ActiveFetchWaiterIdOverflow,
159 /// The active hydration waiter counter exceeded the host address space.
160 #[error("CFAPI active fetch waiter count overflow")]
161 ActiveFetchWaiterCountOverflow,
162 /// A CFAPI progress value was outside the representable or monotonic range.
163 #[error("invalid CFAPI provider progress: {reason}")]
164 InvalidProviderProgress {
165 /// Stable adapter-level reason suitable for logs and tests.
166 reason: &'static str,
167 },
168 /// The CFAPI callback watchdog configuration was not a usable positive duration.
169 #[error("invalid CFAPI callback watchdog timeout: {reason}")]
170 InvalidWatchdogTimeout {
171 /// Stable adapter-level reason suitable for logs and tests.
172 reason: &'static str,
173 },
174 /// A pending fetch exceeded the local watchdog deadline.
175 #[error("CFAPI fetch-data callback watchdog timed out")]
176 FetchDataWatchdogTimeout,
177 /// A native CFAPI operation failed.
178 #[cfg(windows)]
179 #[error("CFAPI operation failed: {0}")]
180 Native(#[from] windows::core::Error),
181}