twilight_gateway/
error.rs

1//! Errors returned by gateway operations.
2
3#[cfg(any(feature = "zlib-stock", feature = "zlib-simd", feature = "zstd"))]
4pub use crate::compression::{CompressionError, CompressionErrorType};
5
6use std::{
7    error::Error,
8    fmt::{Debug, Display, Formatter, Result as FmtResult},
9};
10
11/// Sending a command over a channel failed.
12#[derive(Debug)]
13pub struct ChannelError {
14    /// Type of error.
15    pub(crate) kind: ChannelErrorType,
16    /// Source error if available.
17    pub(crate) source: Option<Box<dyn Error + Send + Sync>>,
18}
19
20impl ChannelError {
21    /// Immutable reference to the type of error that occurred.
22    #[must_use = "retrieving the type has no effect if left unused"]
23    pub const fn kind(&self) -> &ChannelErrorType {
24        &self.kind
25    }
26
27    /// Consume the error, returning the source error if there is any.
28    #[must_use = "consuming the error and retrieving the source has no effect if left unused"]
29    pub fn into_source(self) -> Option<Box<dyn Error + Send + Sync>> {
30        self.source
31    }
32
33    /// Consume the error, returning the owned error type and the source error.
34    #[must_use = "consuming the error into its parts has no effect if left unused"]
35    pub fn into_parts(self) -> (ChannelErrorType, Option<Box<dyn Error + Send + Sync>>) {
36        (self.kind, None)
37    }
38}
39
40impl Display for ChannelError {
41    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
42        match self.kind {
43            ChannelErrorType::Closed => f.write_str("tried sending over a closed channel"),
44        }
45    }
46}
47
48impl Error for ChannelError {
49    fn source(&self) -> Option<&(dyn Error + 'static)> {
50        self.source
51            .as_ref()
52            .map(|source| &**source as &(dyn Error + 'static))
53    }
54}
55
56/// Type of [`ChannelError`] that occurred.
57#[derive(Debug)]
58#[non_exhaustive]
59pub enum ChannelErrorType {
60    /// Tried sending over a closed channel.
61    Closed,
62}
63
64/// Failure when fetching the recommended number of shards to use from Discord's
65/// REST API.
66#[cfg(feature = "twilight-http")]
67#[derive(Debug)]
68pub struct StartRecommendedError {
69    /// Type of error.
70    pub(crate) kind: StartRecommendedErrorType,
71    /// Source error if available.
72    pub(crate) source: Option<Box<dyn Error + Send + Sync>>,
73}
74
75#[cfg(feature = "twilight-http")]
76impl StartRecommendedError {
77    /// Immutable reference to the type of error that occurred.
78    #[must_use = "retrieving the type has no effect if left unused"]
79    pub const fn kind(&self) -> &StartRecommendedErrorType {
80        &self.kind
81    }
82
83    /// Consume the error, returning the source error if there is any.
84    #[must_use = "consuming the error and retrieving the source has no effect if left unused"]
85    pub fn into_source(self) -> Option<Box<dyn Error + Send + Sync>> {
86        self.source
87    }
88
89    /// Consume the error, returning the owned error type and the source error.
90    #[must_use = "consuming the error into its parts has no effect if left unused"]
91    pub fn into_parts(
92        self,
93    ) -> (
94        StartRecommendedErrorType,
95        Option<Box<dyn Error + Send + Sync>>,
96    ) {
97        (self.kind, None)
98    }
99}
100
101#[cfg(feature = "twilight-http")]
102impl Display for StartRecommendedError {
103    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
104        match self.kind {
105            StartRecommendedErrorType::Deserializing => {
106                f.write_str("payload isn't a recognized type")
107            }
108            StartRecommendedErrorType::Request => f.write_str("request failed to complete"),
109        }
110    }
111}
112
113#[cfg(feature = "twilight-http")]
114impl Error for StartRecommendedError {
115    fn source(&self) -> Option<&(dyn Error + 'static)> {
116        self.source
117            .as_ref()
118            .map(|source| &**source as &(dyn Error + 'static))
119    }
120}
121
122/// Type of [`StartRecommendedError`] that occurred.
123#[cfg(feature = "twilight-http")]
124#[derive(Debug)]
125pub enum StartRecommendedErrorType {
126    /// Received gateway event failed to be deserialized.
127    ///
128    /// The message payload is likely an unrecognized type that is not yet
129    /// supported.
130    Deserializing,
131    /// Requesting recommended shards from Discord's REST API failed.
132    ///
133    /// May be due to something such as a network or authentication issue.
134    Request,
135}
136
137/// Receiving the next Websocket message failed.
138#[derive(Debug)]
139pub struct ReceiveMessageError {
140    /// Type of error.
141    pub(crate) kind: ReceiveMessageErrorType,
142    /// Source error if available.
143    pub(crate) source: Option<Box<dyn Error + Send + Sync>>,
144}
145
146impl ReceiveMessageError {
147    /// Immutable reference to the type of error that occurred.
148    #[must_use = "retrieving the type has no effect if left unused"]
149    pub const fn kind(&self) -> &ReceiveMessageErrorType {
150        &self.kind
151    }
152
153    /// Consume the error, returning the source error if there is any.
154    #[must_use = "consuming the error and retrieving the source has no effect if left unused"]
155    pub fn into_source(self) -> Option<Box<dyn Error + Send + Sync>> {
156        self.source
157    }
158
159    /// Consume the error, returning the owned error type and the source error.
160    #[must_use = "consuming the error into its parts has no effect if left unused"]
161    pub fn into_parts(
162        self,
163    ) -> (
164        ReceiveMessageErrorType,
165        Option<Box<dyn Error + Send + Sync>>,
166    ) {
167        (self.kind, None)
168    }
169
170    /// Shortcut to create a new error for a message compression error.
171    #[cfg(any(feature = "zlib-stock", feature = "zlib-simd", feature = "zstd"))]
172    pub(crate) fn from_compression(source: CompressionError) -> Self {
173        Self {
174            kind: ReceiveMessageErrorType::Compression,
175            source: Some(Box::new(source)),
176        }
177    }
178}
179
180impl Display for ReceiveMessageError {
181    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
182        match &self.kind {
183            #[cfg(any(feature = "zlib-stock", feature = "zlib-simd", feature = "zstd"))]
184            ReceiveMessageErrorType::Compression => {
185                f.write_str("binary message could not be decompressed")
186            }
187            ReceiveMessageErrorType::Deserializing { event } => {
188                f.write_str("gateway event could not be deserialized: event=")?;
189                f.write_str(event)
190            }
191            ReceiveMessageErrorType::Reconnect => f.write_str("failed to reconnect to the gateway"),
192        }
193    }
194}
195
196impl Error for ReceiveMessageError {
197    fn source(&self) -> Option<&(dyn Error + 'static)> {
198        self.source
199            .as_ref()
200            .map(|source| &**source as &(dyn Error + 'static))
201    }
202}
203
204/// Type of [`ReceiveMessageError`] that occurred.
205#[derive(Debug)]
206#[non_exhaustive]
207pub enum ReceiveMessageErrorType {
208    /// Binary message could not be decompressed.
209    ///
210    /// The associated error downcasts to [`CompressionError`].
211    #[cfg(any(feature = "zlib-stock", feature = "zlib-simd", feature = "zstd"))]
212    Compression,
213    /// Gateway event could not be deserialized.
214    Deserializing {
215        /// Gateway event.
216        ///
217        /// Note that the `simd-json` feature may slightly modify the event.
218        event: String,
219    },
220    /// Shard failed to reconnect to the gateway.
221    Reconnect,
222}
223
224#[cfg(test)]
225mod tests {
226    use super::{ReceiveMessageError, ReceiveMessageErrorType};
227    use static_assertions::assert_impl_all;
228    use std::{error::Error, fmt::Debug};
229
230    assert_impl_all!(ReceiveMessageErrorType: Debug, Send, Sync);
231    assert_impl_all!(ReceiveMessageError: Error, Send, Sync);
232
233    #[test]
234    fn receive_message_error_display() {
235        let messages: [(ReceiveMessageErrorType, &str); 3] = [
236            (
237                ReceiveMessageErrorType::Compression,
238                "binary message could not be decompressed",
239            ),
240            (
241                ReceiveMessageErrorType::Deserializing {
242                    event: r#"{"t":null,"s":null,"op":10,"d":{"heartbeat_interval":41250,"_trace":["[\"gateway-prd-us-east1-b-0568\",{\"micros\":0.0}]"]}}"#.to_owned(),
243                },
244                r#"gateway event could not be deserialized: event={"t":null,"s":null,"op":10,"d":{"heartbeat_interval":41250,"_trace":["[\"gateway-prd-us-east1-b-0568\",{\"micros\":0.0}]"]}}"#,
245            ),
246            (
247                ReceiveMessageErrorType::Reconnect,
248                "failed to reconnect to the gateway",
249            ),
250        ];
251
252        for (kind, message) in messages {
253            let error = ReceiveMessageError { kind, source: None };
254
255            assert_eq!(error.to_string(), message);
256        }
257    }
258}
twilight_gateway/error.rs

twilight_gateway/
error.rs
