vstorage 0.9.0

Common API for various icalendar/vcard storages.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

use std::backtrace::Backtrace;

pub type Result<T, E = Error> = std::result::Result<T, E>;

/// Variants used to categorise [`Error`] instances.
#[derive(Debug, PartialEq)]
pub enum ErrorKind {
    /// A storage, collection or resource does not exist.
    DoesNotExist,
    /// Referenced resource is not a collection.
    NotACollection,
    /// Referenced resource is not a storage.
    NotAStorage,
    /// Access was denied by the underlying storage.
    AccessDenied,
    /// Generic input / output error.
    Io,
    /// Storage returned invalid data.
    InvalidData,
    /// Input provided is invalid.
    InvalidInput,
    /// Resources is read-only.
    ReadOnly,
    /// Collection is not empty.
    CollectionNotEmpty,
    /// The resource already exists.
    Exists,
    /// A precondition has failed.
    ///
    /// Typically, this error is returned when attempting to operate on an item using a stale
    /// [`crate::Etag`].
    PreconditionFailed,
    /// The requested operation is not possible on this specific instance.
    Unavailable,
    /// Storage implementation does not support a required feature.
    Unsupported,
    /// Uncategorised error.
    ///
    /// Deprecated and should not be used for any new error paths.
    // #[deprecated]
    Uncategorised,
}

impl ErrorKind {
    /// Create a new error of this kind.
    pub fn error<E>(self, source: E) -> Error
    where
        E: Into<Box<dyn std::error::Error + Send + Sync>>,
    {
        Error {
            kind: self,
            source: Some(source.into()),
            backtrace: Backtrace::capture(),
        }
    }

    #[must_use]
    const fn as_str(&self) -> &'static str {
        match self {
            ErrorKind::DoesNotExist => "resource does not exist",
            ErrorKind::NotACollection => "resource exists, but is not a collection",
            ErrorKind::NotAStorage => "resource exists, but is not a storage",
            ErrorKind::AccessDenied => "access to the resource was denied",
            ErrorKind::Io => "input/output error",
            ErrorKind::InvalidData => "operation returned data, but it is not valid",
            ErrorKind::InvalidInput => "input data is invalid",
            ErrorKind::ReadOnly => "the resource is read-only",
            ErrorKind::CollectionNotEmpty => "the collection is not empty",
            ErrorKind::Exists => "resource already exists",
            ErrorKind::PreconditionFailed => "a required condition was not met",
            ErrorKind::Unavailable => "the operation is not possible on this instance",
            ErrorKind::Unsupported => "the operation is not supported",
            ErrorKind::Uncategorised => "uncategorised error",
        }
    }
}

impl std::fmt::Display for ErrorKind {
    fn fmt(&self, fmt: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        fmt.write_str(self.as_str())
    }
}

/// Common error type used by all Storage implementations.
///
/// Use [`ErrorKind`] as an entry point to create new instances.
#[derive(Debug)]
pub struct Error {
    pub(crate) kind: ErrorKind,
    source: Option<Box<dyn std::error::Error + Send + Sync>>,
    backtrace: Backtrace,
}

impl Error {
    /// Return the kind of this error.
    #[must_use]
    pub fn kind(&self) -> &ErrorKind {
        &self.kind
    }

    /// Return the backtrace for this error.
    ///
    /// A backtrace is not always available, see documentation for the [`::std::backtrace`] module.
    pub fn backtrace(&self) -> &Backtrace {
        &self.backtrace
    }
}

impl From<ErrorKind> for Error {
    fn from(kind: ErrorKind) -> Self {
        Error {
            kind,
            source: None,
            backtrace: Backtrace::capture(),
        }
    }
}

impl From<std::io::Error> for Error {
    fn from(value: std::io::Error) -> Self {
        let kind = match value.kind() {
            std::io::ErrorKind::NotFound => ErrorKind::DoesNotExist,
            std::io::ErrorKind::PermissionDenied => ErrorKind::AccessDenied,
            std::io::ErrorKind::AlreadyExists => ErrorKind::Exists,
            std::io::ErrorKind::InvalidInput => ErrorKind::InvalidInput,
            std::io::ErrorKind::InvalidData => ErrorKind::InvalidData,
            _ => ErrorKind::Io,
        };
        Error {
            kind,
            source: Some(value.into()),
            backtrace: Backtrace::capture(),
        }
    }
}

impl std::fmt::Display for Error {
    fn fmt(&self, fmt: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self.source {
            Some(ref s) => write!(fmt, "{}: {}", self.kind, s),
            None => self.kind.fmt(fmt),
        }
    }
}

impl std::error::Error for Error {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match &self.source {
            Some(e) => Some(e.as_ref()),
            None => None,
        }
    }
}