tungstenite/
error.rs

1//! Error handling.
2
3use std::{io, result, str, string};
4
5use crate::protocol::{frame::coding::Data, Message};
6#[cfg(feature = "handshake")]
7use http::{header::HeaderName, Response};
8use thiserror::Error;
9
10/// Result type of all Tungstenite library calls.
11pub type Result<T, E = Error> = result::Result<T, E>;
12
13/// Possible WebSocket errors.
14#[derive(Error, Debug)]
15pub enum Error {
16    /// WebSocket connection closed normally. This informs you of the close.
17    /// It's not an error as such and nothing wrong happened.
18    ///
19    /// This is returned as soon as the close handshake is finished (we have both sent and
20    /// received a close frame) on the server end and as soon as the server has closed the
21    /// underlying connection if this endpoint is a client.
22    ///
23    /// Thus when you receive this, it is safe to drop the underlying connection.
24    ///
25    /// Receiving this error means that the WebSocket object is not usable anymore and the
26    /// only meaningful action with it is dropping it.
27    #[error("Connection closed normally")]
28    ConnectionClosed,
29    /// Trying to work with already closed connection.
30    ///
31    /// Trying to read or write after receiving `ConnectionClosed` causes this.
32    ///
33    /// As opposed to `ConnectionClosed`, this indicates your code tries to operate on the
34    /// connection when it really shouldn't anymore, so this really indicates a programmer
35    /// error on your part.
36    #[error("Trying to work with closed connection")]
37    AlreadyClosed,
38    /// Input-output error. Apart from WouldBlock, these are generally errors with the
39    /// underlying connection and you should probably consider them fatal.
40    #[error("IO error: {0}")]
41    Io(#[from] io::Error),
42    /// TLS error.
43    ///
44    /// Note that this error variant is enabled unconditionally even if no TLS feature is enabled,
45    /// to provide a feature-agnostic API surface.
46    #[error("TLS error: {0}")]
47    Tls(#[from] TlsError),
48    /// - When reading: buffer capacity exhausted.
49    /// - When writing: your message is bigger than the configured max message size
50    ///   (64MB by default).
51    #[error("Space limit exceeded: {0}")]
52    Capacity(#[from] CapacityError),
53    /// Protocol violation.
54    #[error("WebSocket protocol error: {0}")]
55    Protocol(#[from] ProtocolError),
56    /// Message write buffer is full.
57    #[error("Write buffer is full")]
58    WriteBufferFull(Box<Message>),
59    /// UTF coding error.
60    #[error("UTF-8 encoding error: {0}")]
61    Utf8(String),
62    /// Attack attempt detected.
63    #[error("Attack attempt detected")]
64    AttackAttempt,
65    /// Invalid URL.
66    #[error("URL error: {0}")]
67    Url(#[from] UrlError),
68    /// HTTP error.
69    #[error("HTTP error: {}", .0.status())]
70    #[cfg(feature = "handshake")]
71    Http(Box<Response<Option<Vec<u8>>>>),
72    /// HTTP format error.
73    #[error("HTTP format error: {0}")]
74    #[cfg(feature = "handshake")]
75    HttpFormat(#[from] http::Error),
76}
77
78impl From<str::Utf8Error> for Error {
79    fn from(err: str::Utf8Error) -> Self {
80        Error::Utf8(err.to_string())
81    }
82}
83
84impl From<string::FromUtf8Error> for Error {
85    fn from(err: string::FromUtf8Error) -> Self {
86        Error::Utf8(err.to_string())
87    }
88}
89
90#[cfg(feature = "handshake")]
91impl From<http::header::InvalidHeaderValue> for Error {
92    fn from(err: http::header::InvalidHeaderValue) -> Self {
93        Error::HttpFormat(err.into())
94    }
95}
96
97#[cfg(feature = "handshake")]
98impl From<http::header::InvalidHeaderName> for Error {
99    fn from(err: http::header::InvalidHeaderName) -> Self {
100        Error::HttpFormat(err.into())
101    }
102}
103
104#[cfg(feature = "handshake")]
105impl From<http::header::ToStrError> for Error {
106    fn from(err: http::header::ToStrError) -> Self {
107        Error::Utf8(err.to_string())
108    }
109}
110
111#[cfg(feature = "handshake")]
112impl From<http::uri::InvalidUri> for Error {
113    fn from(err: http::uri::InvalidUri) -> Self {
114        Error::HttpFormat(err.into())
115    }
116}
117
118#[cfg(feature = "handshake")]
119impl From<http::status::InvalidStatusCode> for Error {
120    fn from(err: http::status::InvalidStatusCode) -> Self {
121        Error::HttpFormat(err.into())
122    }
123}
124
125#[cfg(feature = "handshake")]
126impl From<httparse::Error> for Error {
127    fn from(err: httparse::Error) -> Self {
128        match err {
129            httparse::Error::TooManyHeaders => Error::Capacity(CapacityError::TooManyHeaders),
130            e => Error::Protocol(ProtocolError::HttparseError(e)),
131        }
132    }
133}
134
135/// Indicates the specific type/cause of a capacity error.
136#[derive(Error, Debug, PartialEq, Eq, Clone, Copy)]
137pub enum CapacityError {
138    /// Too many headers provided (see [`httparse::Error::TooManyHeaders`]).
139    #[error("Too many headers")]
140    TooManyHeaders,
141    /// Received header is too long.
142    /// Message is bigger than the maximum allowed size.
143    #[error("Message too long: {size} > {max_size}")]
144    MessageTooLong {
145        /// The size of the message.
146        size: usize,
147        /// The maximum allowed message size.
148        max_size: usize,
149    },
150}
151
152/// Indicates the specific type/cause of a subprotocol header error.
153#[derive(Error, Clone, PartialEq, Eq, Debug, Copy)]
154pub enum SubProtocolError {
155    /// The server sent a subprotocol to a client handshake request but none was requested
156    #[error("Server sent a subprotocol but none was requested")]
157    ServerSentSubProtocolNoneRequested,
158
159    /// The server sent an invalid subprotocol to a client handhshake request
160    #[error("Server sent an invalid subprotocol")]
161    InvalidSubProtocol,
162
163    /// The server sent no subprotocol to a client handshake request that requested one or more
164    /// subprotocols
165    #[error("Server sent no subprotocol")]
166    NoSubProtocol,
167}
168
169/// Indicates the specific type/cause of a protocol error.
170#[allow(missing_copy_implementations)]
171#[derive(Error, Debug, PartialEq, Eq, Clone)]
172pub enum ProtocolError {
173    /// Use of the wrong HTTP method (the WebSocket protocol requires the GET method be used).
174    #[error("Unsupported HTTP method used - only GET is allowed")]
175    WrongHttpMethod,
176    /// Wrong HTTP version used (the WebSocket protocol requires version 1.1 or higher).
177    #[error("HTTP version must be 1.1 or higher")]
178    WrongHttpVersion,
179    /// Missing `Connection: upgrade` HTTP header.
180    #[error("No \"Connection: upgrade\" header")]
181    MissingConnectionUpgradeHeader,
182    /// Missing `Upgrade: websocket` HTTP header.
183    #[error("No \"Upgrade: websocket\" header")]
184    MissingUpgradeWebSocketHeader,
185    /// Missing `Sec-WebSocket-Version: 13` HTTP header.
186    #[error("No \"Sec-WebSocket-Version: 13\" header")]
187    MissingSecWebSocketVersionHeader,
188    /// Missing `Sec-WebSocket-Key` HTTP header.
189    #[error("No \"Sec-WebSocket-Key\" header")]
190    MissingSecWebSocketKey,
191    /// Invalid Sec-WebSocket-Key HTTP header value.
192    #[error("Invalid \"Sec-WebSocket-Key\" header value")]
193    InvalidSecWebSocketKey,
194    /// The `Sec-WebSocket-Accept` header is either not present or does not specify the correct key value.
195    #[error("Key mismatch in \"Sec-WebSocket-Accept\" header")]
196    SecWebSocketAcceptKeyMismatch,
197    /// The `Sec-WebSocket-Protocol` header was invalid
198    #[error("SubProtocol error: {0}")]
199    SecWebSocketSubProtocolError(SubProtocolError),
200    /// Garbage data encountered after client request.
201    #[error("Junk after client request")]
202    JunkAfterRequest,
203    /// Custom responses must be unsuccessful.
204    #[error("Custom response must not be successful")]
205    CustomResponseSuccessful,
206    /// Invalid header is passed. Or the header is missing in the request. Or not present at all. Check the request that you pass.
207    #[error("Missing, duplicated or incorrect header {0}")]
208    #[cfg(feature = "handshake")]
209    InvalidHeader(Box<HeaderName>),
210    /// No more data while still performing handshake.
211    #[error("Handshake not finished")]
212    HandshakeIncomplete,
213    /// Wrapper around a [`httparse::Error`] value.
214    #[error("httparse error: {0}")]
215    #[cfg(feature = "handshake")]
216    HttparseError(#[from] httparse::Error),
217    /// Not allowed to send after having sent a closing frame.
218    #[error("Sending after closing is not allowed")]
219    SendAfterClosing,
220    /// Remote sent data after sending a closing frame.
221    #[error("Remote sent after having closed")]
222    ReceivedAfterClosing,
223    /// Reserved bits in frame header are non-zero.
224    #[error("Reserved bits are non-zero")]
225    NonZeroReservedBits,
226    /// The server must close the connection when an unmasked frame is received.
227    #[error("Received an unmasked frame from client")]
228    UnmaskedFrameFromClient,
229    /// The client must close the connection when a masked frame is received.
230    #[error("Received a masked frame from server")]
231    MaskedFrameFromServer,
232    /// Control frames must not be fragmented.
233    #[error("Fragmented control frame")]
234    FragmentedControlFrame,
235    /// Control frames must have a payload of 125 bytes or less.
236    #[error("Control frame too big (payload must be 125 bytes or less)")]
237    ControlFrameTooBig,
238    /// Type of control frame not recognised.
239    #[error("Unknown control frame type: {0}")]
240    UnknownControlFrameType(u8),
241    /// Type of data frame not recognised.
242    #[error("Unknown data frame type: {0}")]
243    UnknownDataFrameType(u8),
244    /// Received a continue frame despite there being nothing to continue.
245    #[error("Continue frame but nothing to continue")]
246    UnexpectedContinueFrame,
247    /// Received data while waiting for more fragments.
248    #[error("While waiting for more fragments received: {0}")]
249    ExpectedFragment(Data),
250    /// Connection closed without performing the closing handshake.
251    #[error("Connection reset without closing handshake")]
252    ResetWithoutClosingHandshake,
253    /// Encountered an invalid opcode.
254    #[error("Encountered invalid opcode: {0}")]
255    InvalidOpcode(u8),
256    /// The payload for the closing frame is invalid.
257    #[error("Invalid close sequence")]
258    InvalidCloseSequence,
259}
260
261/// Indicates the specific type/cause of URL error.
262#[derive(Error, Debug, PartialEq, Eq)]
263pub enum UrlError {
264    /// TLS is used despite not being compiled with the TLS feature enabled.
265    #[error("TLS support not compiled in")]
266    TlsFeatureNotEnabled,
267    /// The URL does not include a host name.
268    #[error("No host name in the URL")]
269    NoHostName,
270    /// Failed to connect with this URL.
271    #[error("Unable to connect to {0}")]
272    UnableToConnect(String),
273    /// Unsupported URL scheme used (only `ws://` or `wss://` may be used).
274    #[error("URL scheme not supported")]
275    UnsupportedUrlScheme,
276    /// The URL host name, though included, is empty.
277    #[error("URL contains empty host name")]
278    EmptyHostName,
279    /// The URL does not include a path/query.
280    #[error("No path/query in URL")]
281    NoPathOrQuery,
282}
283
284/// TLS errors.
285///
286/// Note that even if you enable only the rustls-based TLS support, the error at runtime could still
287/// be `Native`, as another crate in the dependency graph may enable native TLS support.
288#[allow(missing_copy_implementations)]
289#[derive(Error, Debug)]
290#[non_exhaustive]
291pub enum TlsError {
292    /// Native TLS error.
293    #[cfg(feature = "native-tls")]
294    #[error("native-tls error: {0}")]
295    Native(Box<native_tls_crate::Error>),
296    /// Rustls error.
297    #[cfg(feature = "__rustls-tls")]
298    #[error("rustls error: {0}")]
299    Rustls(Box<rustls::Error>),
300    /// DNS name resolution error.
301    #[cfg(feature = "__rustls-tls")]
302    #[error("Invalid DNS name")]
303    InvalidDnsName,
304}
305
306#[cfg(feature = "native-tls")]
307impl From<native_tls_crate::Error> for TlsError {
308    fn from(e: native_tls_crate::Error) -> Self {
309        Self::Native(e.into())
310    }
311}
312
313#[cfg(feature = "__rustls-tls")]
314impl From<rustls::Error> for TlsError {
315    fn from(e: rustls::Error) -> Self {
316        Self::Rustls(e.into())
317    }
318}
319
320#[cfg(test)]
321mod test {
322    #[test]
323    fn error_size() {
324        let size = std::mem::size_of::<crate::Error>();
325        assert!(size <= 32, "Error is large: {size}");
326    }
327
328    #[test]
329    fn tls_error_size() {
330        let size = std::mem::size_of::<crate::error::TlsError>();
331        assert!(size <= 16, "TlsError is large: {size}");
332    }
333
334    #[test]
335    fn protocol_error_size() {
336        let size = std::mem::size_of::<crate::error::ProtocolError>();
337        assert!(size <= 16, "ProtocolError is large: {size}");
338    }
339}
tungstenite/error.rs

tungstenite/
error.rs
