Struct Error 

pub struct Error { /* private fields */ }

Available on crate feature web03 only.

Error type for the WebSocket service.

Errors are delivered to request, channel and broadcast callbacks, and to the connection-wide handler set with ServiceBuilder::on_error. Use the accessors below to tell what failed instead of matching on the text produced by Display, which is meant for humans and may change:

• is_not_connected - the request was never sent, since there was no open connection or channel to send it over. It is safe to send it again once the connection is open.
• is_connection_lost - the request was sent, or about to be, but the connection closed before a response arrived. The server may or may not have handled it.
• is_cancelled - the request was replaced by another one before it was answered.
• as_server_error - the server answered with an error, such as one returned by its handler. If the handler failed with a typed error, server_error decodes it.
• is_decode - something received could not be decoded, such as a response which does not match the expected type.

Anything else, such as a failure in the browser APIs, only carries a message.

Examples

use musli_web::web::Error;

fn describe(error: &Error) -> String {
    if error.is_not_connected() {
        String::from("Not connected, try again later")
    } else if error.is_connection_lost() {
        String::from("Connection lost, the request may not have been handled")
    } else if let Some(message) = error.as_server_error() {
        format!("The server said: {message}")
    } else {
        error.to_string()
    }
}

let error = Error::message("Something else");
assert_eq!(describe(&error), "Something else");

Implementations

impl Error

pub fn is_empty_packet(&self) -> bool

Check if the error is caused by an empty packet.

An empty packet is also a decode error.

Examples

use musli_web::web::{Error, RawPacket};

let packet = RawPacket::empty();
let e = packet.decode::<u32>().unwrap_err();

assert!(e.is_empty_packet());
assert!(e.is_decode());

pub fn is_not_connected(&self) -> bool

Check if the request was never sent, since there was no open connection or channel to send it over.

This is the error a request or channel gets when it is sent before the connection is open, after the Service has been dropped, or over a Channel which is not open. Since the server never saw the request, it is safe to send it again once the connection is open, see Handle::on_state_change.

Examples

use musli_web::web::Error;

let error = Error::message("Something else");
assert!(!error.is_not_connected());

pub fn is_connection_lost(&self) -> bool

Check if the connection closed before a response to the request arrived.

Unlike is_not_connected, the request was sent, or was being sent, so the server may or may not have handled it. This is the error every pending request gets when the connection closes or when the Service is dropped.

pub fn is_cancelled(&self) -> bool

Check if the request was cancelled before it was answered, since another request took its place.

pub fn as_server_error(&self) -> Option<&str>

Check if the error is a server error, and if so return the message reported by the server.

Server errors are produced by a Handler which returns an error or which does not support the request or broadcast being made. The message is returned as the server sent it, without the Server error: prefix that Display adds.

This is the message of a typed error too.

pub fn server_error<'de, T>(&'de self) -> Result<Option<T>, Error>

where T: DecodeBody<'de>,

Decode the typed error the server answered with.

A handler which fails with a ws::TypedError<E> sends E encoded in the body format of the connection, see Errors. This decodes it back as T, which should be the same type as E or one which is compatible with it, typically from an API crate shared with the server.

Returns Ok(None) if this is not a server error, or if it is one which carries no typed error, such as a handler error which is plain text or an error the server produced on its own for a request it does not support. Those still have a message, see as_server_error.

Errors

Errors if the typed error does not decode as T. The returned error is a decode error.

Examples

use musli::{Decode, Encode};
use musli_web::web::Error;

#[derive(Debug, PartialEq, Encode, Decode)]
enum ServerError {
    NotFound,
    Forbidden,
}

fn describe(error: &Error) -> String {
    match error.server_error::<ServerError>() {
        Ok(Some(ServerError::NotFound)) => String::from("No such thing"),
        Ok(Some(ServerError::Forbidden)) => String::from("Not allowed"),
        // NB: Not a typed error, or not one we understand.
        Ok(None) | Err(..) => error.to_string(),
    }
}

let error = Error::message("Something else");
assert_eq!(error.server_error::<ServerError>().unwrap(), None);
assert_eq!(describe(&error), "Something else");

pub fn is_decode(&self) -> bool

Check if the error is caused by something received which could not be decoded.

This covers a response or broadcast whose body does not decode as the requested type, an empty packet, a frame from the server whose header, error message or format could not be decoded, and a typed error which does not decode as the requested type.

Examples

use musli_web::web::RawPacket;

let packet = RawPacket::empty();
let e = packet.decode::<u32>().unwrap_err();

assert!(e.is_decode());

pub fn message(message: impl Display) -> Self

Format a WebSocket error consisting of a message.

None of the accessors on Error match an error constructed this way.

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<JsValue> for Error

fn from(error: JsValue) -> Self

Converts to this type from the input type.