Skip to main content

rustfs_storage_api/
error.rs

1// Copyright 2024 RustFS Team
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Stable storage error contracts shared across storage consumers.
16
17/// Result type alias for storage operations.
18pub type StorageResult<T, E = StorageErrorCode> = core::result::Result<T, E>;
19
20/// Error codes for storage operations.
21///
22/// These codes provide a stable, cross-crate error classification
23/// that can be serialized and transmitted between nodes.
24#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
25pub enum StorageErrorCode {
26    Io,
27    FaultyDisk,
28    DiskFull,
29    VolumeNotFound,
30    VolumeExists,
31    FileNotFound,
32    FileVersionNotFound,
33    FileNameTooLong,
34    FileAccessDenied,
35    FileCorrupt,
36    IsNotRegular,
37    VolumeNotEmpty,
38    VolumeAccessDenied,
39    CorruptedFormat,
40    CorruptedBackend,
41    UnformattedDisk,
42    DiskNotFound,
43    DriveIsRoot,
44    FaultyRemoteDisk,
45    DiskAccessDenied,
46    Unexpected,
47    NotImplemented,
48    InvalidArgument,
49    MethodNotAllowed,
50    BucketNotFound,
51    BucketNotEmpty,
52    BucketNameInvalid,
53    ObjectNameInvalid,
54    BucketExists,
55    StorageFull,
56    SlowDown,
57    PrefixAccessDenied,
58    InvalidUploadIDKeyCombination,
59    MalformedUploadID,
60    ObjectNameTooLong,
61    ObjectNamePrefixAsSlash,
62    ObjectNotFound,
63    VersionNotFound,
64    InvalidUploadID,
65    InvalidVersionID,
66    DataMovementOverwriteErr,
67    ObjectExistsAsDirectory,
68    DecommissionNotStarted,
69    InvalidPart,
70    DoneForNow,
71    DecommissionAlreadyRunning,
72    ErasureReadQuorum,
73    ErasureWriteQuorum,
74    NotFirstDisk,
75    FirstDiskWait,
76    ConfigNotFound,
77    TooManyOpenFiles,
78    NoHealRequired,
79    Lock,
80    InsufficientReadQuorum,
81    InsufficientWriteQuorum,
82    PreconditionFailed,
83    EntityTooSmall,
84    EntityTooLarge,
85    InvalidRangeSpec,
86    NotModified,
87    InvalidPartNumber,
88    RebalanceAlreadyRunning,
89    OperationCanceled,
90    NamespaceLockQuorumUnavailable,
91    MaxVersionsExceeded,
92    InconsistentDisk,
93    UnsupportedDisk,
94    DiskNotDir,
95    DiskOngoingReq,
96    PathNotFound,
97    BitrotHashAlgoInvalid,
98    CrossDeviceLink,
99    LessData,
100    MoreData,
101    OutdatedXLMeta,
102    PartMissingOrCorrupt,
103    ShortWrite,
104    SourceStalled,
105    Timeout,
106    InvalidPath,
107    QuotaExceeded,
108    RemoteClientUnavailable,
109    RemoteNotInitialized,
110}
111
112impl StorageErrorCode {
113    pub const fn as_u32(self) -> u32 {
114        match self {
115            Self::Io => 0x01,
116            Self::FaultyDisk => 0x02,
117            Self::DiskFull => 0x03,
118            Self::VolumeNotFound => 0x04,
119            Self::VolumeExists => 0x05,
120            Self::FileNotFound => 0x06,
121            Self::FileVersionNotFound => 0x07,
122            Self::FileNameTooLong => 0x08,
123            Self::FileAccessDenied => 0x09,
124            Self::FileCorrupt => 0x0A,
125            Self::IsNotRegular => 0x0B,
126            Self::VolumeNotEmpty => 0x0C,
127            Self::VolumeAccessDenied => 0x0D,
128            Self::CorruptedFormat => 0x0E,
129            Self::CorruptedBackend => 0x0F,
130            Self::UnformattedDisk => 0x10,
131            Self::DiskNotFound => 0x11,
132            Self::DriveIsRoot => 0x12,
133            Self::FaultyRemoteDisk => 0x13,
134            Self::DiskAccessDenied => 0x14,
135            Self::Unexpected => 0x15,
136            Self::NotImplemented => 0x16,
137            Self::InvalidArgument => 0x17,
138            Self::MethodNotAllowed => 0x18,
139            Self::BucketNotFound => 0x19,
140            Self::BucketNotEmpty => 0x1A,
141            Self::BucketNameInvalid => 0x1B,
142            Self::ObjectNameInvalid => 0x1C,
143            Self::BucketExists => 0x1D,
144            Self::StorageFull => 0x1E,
145            Self::SlowDown => 0x1F,
146            Self::PrefixAccessDenied => 0x20,
147            Self::InvalidUploadIDKeyCombination => 0x21,
148            Self::MalformedUploadID => 0x22,
149            Self::ObjectNameTooLong => 0x23,
150            Self::ObjectNamePrefixAsSlash => 0x24,
151            Self::ObjectNotFound => 0x25,
152            Self::VersionNotFound => 0x26,
153            Self::InvalidUploadID => 0x27,
154            Self::InvalidVersionID => 0x28,
155            Self::DataMovementOverwriteErr => 0x29,
156            Self::ObjectExistsAsDirectory => 0x2A,
157            Self::DecommissionNotStarted => 0x2D,
158            Self::InvalidPart => 0x2E,
159            Self::DoneForNow => 0x2F,
160            Self::DecommissionAlreadyRunning => 0x30,
161            Self::ErasureReadQuorum => 0x31,
162            Self::ErasureWriteQuorum => 0x32,
163            Self::NotFirstDisk => 0x33,
164            Self::FirstDiskWait => 0x34,
165            Self::ConfigNotFound => 0x35,
166            Self::TooManyOpenFiles => 0x36,
167            Self::NoHealRequired => 0x37,
168            Self::Lock => 0x38,
169            Self::InsufficientReadQuorum => 0x39,
170            Self::InsufficientWriteQuorum => 0x3A,
171            Self::PreconditionFailed => 0x3B,
172            Self::EntityTooSmall => 0x3C,
173            Self::EntityTooLarge => 0x56,
174            Self::InvalidRangeSpec => 0x3D,
175            Self::NotModified => 0x3E,
176            Self::InvalidPartNumber => 0x3F,
177            Self::RebalanceAlreadyRunning => 0x40,
178            Self::OperationCanceled => 0x41,
179            Self::NamespaceLockQuorumUnavailable => 0x42,
180            Self::MaxVersionsExceeded => 0x43,
181            Self::InconsistentDisk => 0x44,
182            Self::UnsupportedDisk => 0x45,
183            Self::DiskNotDir => 0x46,
184            Self::DiskOngoingReq => 0x47,
185            Self::PathNotFound => 0x48,
186            Self::BitrotHashAlgoInvalid => 0x49,
187            Self::CrossDeviceLink => 0x4A,
188            Self::LessData => 0x4B,
189            Self::MoreData => 0x4C,
190            Self::OutdatedXLMeta => 0x4D,
191            Self::PartMissingOrCorrupt => 0x4E,
192            Self::ShortWrite => 0x4F,
193            Self::SourceStalled => 0x50,
194            Self::Timeout => 0x51,
195            Self::InvalidPath => 0x52,
196            Self::QuotaExceeded => 0x53,
197            Self::RemoteClientUnavailable => 0x54,
198            Self::RemoteNotInitialized => 0x55,
199        }
200    }
201
202    pub const fn from_u32(code: u32) -> Option<Self> {
203        match code {
204            0x01 => Some(Self::Io),
205            0x02 => Some(Self::FaultyDisk),
206            0x03 => Some(Self::DiskFull),
207            0x04 => Some(Self::VolumeNotFound),
208            0x05 => Some(Self::VolumeExists),
209            0x06 => Some(Self::FileNotFound),
210            0x07 => Some(Self::FileVersionNotFound),
211            0x08 => Some(Self::FileNameTooLong),
212            0x09 => Some(Self::FileAccessDenied),
213            0x0A => Some(Self::FileCorrupt),
214            0x0B => Some(Self::IsNotRegular),
215            0x0C => Some(Self::VolumeNotEmpty),
216            0x0D => Some(Self::VolumeAccessDenied),
217            0x0E => Some(Self::CorruptedFormat),
218            0x0F => Some(Self::CorruptedBackend),
219            0x10 => Some(Self::UnformattedDisk),
220            0x11 => Some(Self::DiskNotFound),
221            0x12 => Some(Self::DriveIsRoot),
222            0x13 => Some(Self::FaultyRemoteDisk),
223            0x14 => Some(Self::DiskAccessDenied),
224            0x15 => Some(Self::Unexpected),
225            0x16 => Some(Self::NotImplemented),
226            0x17 => Some(Self::InvalidArgument),
227            0x18 => Some(Self::MethodNotAllowed),
228            0x19 => Some(Self::BucketNotFound),
229            0x1A => Some(Self::BucketNotEmpty),
230            0x1B => Some(Self::BucketNameInvalid),
231            0x1C => Some(Self::ObjectNameInvalid),
232            0x1D => Some(Self::BucketExists),
233            0x1E => Some(Self::StorageFull),
234            0x1F => Some(Self::SlowDown),
235            0x20 => Some(Self::PrefixAccessDenied),
236            0x21 => Some(Self::InvalidUploadIDKeyCombination),
237            0x22 => Some(Self::MalformedUploadID),
238            0x23 => Some(Self::ObjectNameTooLong),
239            0x24 => Some(Self::ObjectNamePrefixAsSlash),
240            0x25 => Some(Self::ObjectNotFound),
241            0x26 => Some(Self::VersionNotFound),
242            0x27 => Some(Self::InvalidUploadID),
243            0x28 => Some(Self::InvalidVersionID),
244            0x29 => Some(Self::DataMovementOverwriteErr),
245            0x2A => Some(Self::ObjectExistsAsDirectory),
246            0x2D => Some(Self::DecommissionNotStarted),
247            0x2E => Some(Self::InvalidPart),
248            0x2F => Some(Self::DoneForNow),
249            0x30 => Some(Self::DecommissionAlreadyRunning),
250            0x31 => Some(Self::ErasureReadQuorum),
251            0x32 => Some(Self::ErasureWriteQuorum),
252            0x33 => Some(Self::NotFirstDisk),
253            0x34 => Some(Self::FirstDiskWait),
254            0x35 => Some(Self::ConfigNotFound),
255            0x36 => Some(Self::TooManyOpenFiles),
256            0x37 => Some(Self::NoHealRequired),
257            0x38 => Some(Self::Lock),
258            0x39 => Some(Self::InsufficientReadQuorum),
259            0x3A => Some(Self::InsufficientWriteQuorum),
260            0x3B => Some(Self::PreconditionFailed),
261            0x3C => Some(Self::EntityTooSmall),
262            0x56 => Some(Self::EntityTooLarge),
263            0x3D => Some(Self::InvalidRangeSpec),
264            0x3E => Some(Self::NotModified),
265            0x3F => Some(Self::InvalidPartNumber),
266            0x40 => Some(Self::RebalanceAlreadyRunning),
267            0x41 => Some(Self::OperationCanceled),
268            0x42 => Some(Self::NamespaceLockQuorumUnavailable),
269            0x43 => Some(Self::MaxVersionsExceeded),
270            0x44 => Some(Self::InconsistentDisk),
271            0x45 => Some(Self::UnsupportedDisk),
272            0x46 => Some(Self::DiskNotDir),
273            0x47 => Some(Self::DiskOngoingReq),
274            0x48 => Some(Self::PathNotFound),
275            0x49 => Some(Self::BitrotHashAlgoInvalid),
276            0x4A => Some(Self::CrossDeviceLink),
277            0x4B => Some(Self::LessData),
278            0x4C => Some(Self::MoreData),
279            0x4D => Some(Self::OutdatedXLMeta),
280            0x4E => Some(Self::PartMissingOrCorrupt),
281            0x4F => Some(Self::ShortWrite),
282            0x50 => Some(Self::SourceStalled),
283            0x51 => Some(Self::Timeout),
284            0x52 => Some(Self::InvalidPath),
285            0x53 => Some(Self::QuotaExceeded),
286            0x54 => Some(Self::RemoteClientUnavailable),
287            0x55 => Some(Self::RemoteNotInitialized),
288            _ => None,
289        }
290    }
291}
292
293#[cfg(test)]
294mod tests {
295    use super::*;
296
297    const ERROR_CODES: &[(StorageErrorCode, u32)] = &[
298        (StorageErrorCode::Io, 0x01),
299        (StorageErrorCode::FaultyDisk, 0x02),
300        (StorageErrorCode::DiskFull, 0x03),
301        (StorageErrorCode::VolumeNotFound, 0x04),
302        (StorageErrorCode::VolumeExists, 0x05),
303        (StorageErrorCode::FileNotFound, 0x06),
304        (StorageErrorCode::FileVersionNotFound, 0x07),
305        (StorageErrorCode::FileNameTooLong, 0x08),
306        (StorageErrorCode::FileAccessDenied, 0x09),
307        (StorageErrorCode::FileCorrupt, 0x0A),
308        (StorageErrorCode::IsNotRegular, 0x0B),
309        (StorageErrorCode::VolumeNotEmpty, 0x0C),
310        (StorageErrorCode::VolumeAccessDenied, 0x0D),
311        (StorageErrorCode::CorruptedFormat, 0x0E),
312        (StorageErrorCode::CorruptedBackend, 0x0F),
313        (StorageErrorCode::UnformattedDisk, 0x10),
314        (StorageErrorCode::DiskNotFound, 0x11),
315        (StorageErrorCode::DriveIsRoot, 0x12),
316        (StorageErrorCode::FaultyRemoteDisk, 0x13),
317        (StorageErrorCode::DiskAccessDenied, 0x14),
318        (StorageErrorCode::Unexpected, 0x15),
319        (StorageErrorCode::NotImplemented, 0x16),
320        (StorageErrorCode::InvalidArgument, 0x17),
321        (StorageErrorCode::MethodNotAllowed, 0x18),
322        (StorageErrorCode::BucketNotFound, 0x19),
323        (StorageErrorCode::BucketNotEmpty, 0x1A),
324        (StorageErrorCode::BucketNameInvalid, 0x1B),
325        (StorageErrorCode::ObjectNameInvalid, 0x1C),
326        (StorageErrorCode::BucketExists, 0x1D),
327        (StorageErrorCode::StorageFull, 0x1E),
328        (StorageErrorCode::SlowDown, 0x1F),
329        (StorageErrorCode::PrefixAccessDenied, 0x20),
330        (StorageErrorCode::InvalidUploadIDKeyCombination, 0x21),
331        (StorageErrorCode::MalformedUploadID, 0x22),
332        (StorageErrorCode::ObjectNameTooLong, 0x23),
333        (StorageErrorCode::ObjectNamePrefixAsSlash, 0x24),
334        (StorageErrorCode::ObjectNotFound, 0x25),
335        (StorageErrorCode::VersionNotFound, 0x26),
336        (StorageErrorCode::InvalidUploadID, 0x27),
337        (StorageErrorCode::InvalidVersionID, 0x28),
338        (StorageErrorCode::DataMovementOverwriteErr, 0x29),
339        (StorageErrorCode::ObjectExistsAsDirectory, 0x2A),
340        (StorageErrorCode::DecommissionNotStarted, 0x2D),
341        (StorageErrorCode::InvalidPart, 0x2E),
342        (StorageErrorCode::DoneForNow, 0x2F),
343        (StorageErrorCode::DecommissionAlreadyRunning, 0x30),
344        (StorageErrorCode::ErasureReadQuorum, 0x31),
345        (StorageErrorCode::ErasureWriteQuorum, 0x32),
346        (StorageErrorCode::NotFirstDisk, 0x33),
347        (StorageErrorCode::FirstDiskWait, 0x34),
348        (StorageErrorCode::ConfigNotFound, 0x35),
349        (StorageErrorCode::TooManyOpenFiles, 0x36),
350        (StorageErrorCode::NoHealRequired, 0x37),
351        (StorageErrorCode::Lock, 0x38),
352        (StorageErrorCode::InsufficientReadQuorum, 0x39),
353        (StorageErrorCode::InsufficientWriteQuorum, 0x3A),
354        (StorageErrorCode::PreconditionFailed, 0x3B),
355        (StorageErrorCode::EntityTooSmall, 0x3C),
356        (StorageErrorCode::EntityTooLarge, 0x56),
357        (StorageErrorCode::InvalidRangeSpec, 0x3D),
358        (StorageErrorCode::NotModified, 0x3E),
359        (StorageErrorCode::InvalidPartNumber, 0x3F),
360        (StorageErrorCode::RebalanceAlreadyRunning, 0x40),
361        (StorageErrorCode::OperationCanceled, 0x41),
362        (StorageErrorCode::NamespaceLockQuorumUnavailable, 0x42),
363        (StorageErrorCode::QuotaExceeded, 0x53),
364        (StorageErrorCode::RemoteClientUnavailable, 0x54),
365        (StorageErrorCode::RemoteNotInitialized, 0x55),
366    ];
367
368    const DISK_PRESERVATION_ERROR_CODES: &[(StorageErrorCode, u32)] = &[
369        (StorageErrorCode::MaxVersionsExceeded, 0x43),
370        (StorageErrorCode::InconsistentDisk, 0x44),
371        (StorageErrorCode::UnsupportedDisk, 0x45),
372        (StorageErrorCode::DiskNotDir, 0x46),
373        (StorageErrorCode::DiskOngoingReq, 0x47),
374        (StorageErrorCode::PathNotFound, 0x48),
375        (StorageErrorCode::BitrotHashAlgoInvalid, 0x49),
376        (StorageErrorCode::CrossDeviceLink, 0x4A),
377        (StorageErrorCode::LessData, 0x4B),
378        (StorageErrorCode::MoreData, 0x4C),
379        (StorageErrorCode::OutdatedXLMeta, 0x4D),
380        (StorageErrorCode::PartMissingOrCorrupt, 0x4E),
381        (StorageErrorCode::ShortWrite, 0x4F),
382        (StorageErrorCode::SourceStalled, 0x50),
383        (StorageErrorCode::Timeout, 0x51),
384        (StorageErrorCode::InvalidPath, 0x52),
385    ];
386
387    #[test]
388    fn storage_error_codes_roundtrip() {
389        for (error_code, raw_code) in ERROR_CODES.iter().chain(DISK_PRESERVATION_ERROR_CODES) {
390            assert_eq!(error_code.as_u32(), *raw_code);
391            assert_eq!(StorageErrorCode::from_u32(*raw_code), Some(*error_code));
392        }
393    }
394
395    #[test]
396    fn storage_error_disk_preservation_codes_roundtrip() {
397        for (error_code, raw_code) in DISK_PRESERVATION_ERROR_CODES {
398            assert_eq!(error_code.as_u32(), *raw_code);
399            assert_eq!(StorageErrorCode::from_u32(*raw_code), Some(*error_code));
400        }
401    }
402
403    #[test]
404    fn storage_error_code_rejects_unknown_values() {
405        assert_eq!(StorageErrorCode::from_u32(0x00), None);
406        assert_eq!(StorageErrorCode::from_u32(0x2B), None);
407        assert_eq!(StorageErrorCode::from_u32(0x2C), None);
408        assert_eq!(StorageErrorCode::from_u32(0xFF), None);
409    }
410
411    #[test]
412    fn storage_result_defaults_to_error_code() {
413        let success: StorageResult<u8> = Ok(7);
414        let failure: StorageResult<u8> = Err(StorageErrorCode::DiskFull);
415
416        assert_eq!(success, Ok(7));
417        assert_eq!(failure, Err(StorageErrorCode::DiskFull));
418    }
419}