Enum Error 

#[non_exhaustive]
pub enum Error {
    Closed,
    NotConnected,
    AlreadyConnected,
    NoProtocols,
    NoTransport,
    Rejected {
        key: String,
    },
    Unsubscribed,
    UnsupportedSubprotocol {
        negotiated: String,
        offered: Vec<String>,
    },
    Disconnected {
        reason: Option<DisconnectReason>,
        reconnect: bool,
    },
    GaveUp {
        attempts: u32,
        last: Box<Error>,
    },
    Stale {
        after: Duration,
    },
    Handshake {
        status: StatusCode,
    },
    Close {
        code: u16,
        reason: String,
    },
    MessageTooBig {
        size: usize,
        limit: usize,
    },
    Transport(Arc<dyn Error + Send + Sync>),
    Headers(Arc<dyn Error + Send + Sync>),
    InvalidHeader {
        name: String,
        source: Arc<Error>,
    },
    DataNotAnObject {
        action: String,
    },
    Json(Arc<Error>),
}

Everything a caller can get back from a cable. It is Clone because a client that stopped for good hands the same failure to everyone who asks it afterwards.

Which method returns what:

• build: InvalidHeader, NoTransport.
• connect: AlreadyConnected, then whatever stopped the client: Closed, NoProtocols, UnsupportedSubprotocol, Disconnected, GaveUp or an error ClientBuilder::stop_on_error called terminal.
• subscribe: NotConnected before connect, Rejected, or whatever stopped the client.
• perform, send and unsubscribe: Closed, NotConnected, Transport, DataNotAnObject and Json.
• Subscription::err: Unsubscribed, Rejected, or whatever stopped the client.
• Message::decode: Json.

The built-in transport reports three of its failures by name, for a caller that wants to act on them rather than read them: Handshake, Close and MessageTooBig. Anything else a transport hits arrives as Transport, and whatever a HeaderProvider failed on as Headers; both keep the original error, and cause hands it back for an application to recognize with downcast_ref.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Closed

The client was closed, or nothing holds it any more. A client that stopped on its own hands out what stopped it instead.

NotConnected

A command couldn’t be sent because the connection is down, or up but not yet welcomed. Subscriptions recover on their own; a perform or send that hits this is lost and has to be sent again. subscribe before connect gets it too.

AlreadyConnected

connect was called on a client that is already running.

NoProtocols

The protocol list was replaced with nothing, so there is nothing to offer the server.

NoTransport

No transport was given and the websocket feature that supplies the built-in one is off, so there is nothing to dial with.

Rejected

The channel’s subscribed method rejected the subscription. key is the identifier as the server knows it, Identifier::key.

Fields

key: String

The identifier the server turned down.

Unsubscribed

What Subscription::err reports after unsubscribe.

UnsupportedSubprotocol

The server negotiated a subprotocol none of the client’s protocols speak, none at all, or the actioncable-unsupported sentinel that says it speaks none of what was offered. Reconnecting won’t fix that, so the client stops.

Fields

negotiated: String

What the server named, empty when it named nothing.

offered: Vec<String>

The subprotocols that were offered, most preferred first.

Disconnected

The server sent a disconnect frame. reason is None when the frame named none, and reconnect is what the frame said about coming back: the client stops on a disconnect that says not to, and dials again on one that says to.

Fields

reason: Option<DisconnectReason>

Why the server hung up, as it spelled it.

reconnect: bool

Whether the server expects the client back.

GaveUp

As many connection attempts failed in a row as ClientBuilder::max_attempts allows, so the client stopped. A welcome resets the count, so this bounds one outage rather than the client’s lifetime.

Fields

attempts: u32

How many attempts failed in a row.

last: Box<Error>

What the last of them failed on.

Stale

The connection went quiet for longer than ClientBuilder::stale_after. The server beats a ping every three seconds, so silence means the connection is dead; it is dropped and redialed.

Fields

after: Duration

How long the client waited.

Handshake

The server answered the upgrade request with something other than 101 Switching Protocols. status tells a redirect from a refusal, and prints as the whole status line.

Fields

status: StatusCode

What the server answered instead.

Close

The server closed the connection with a close frame. code is the status code it carried, 1005 when it carried none, and reason the text after it, if any.

Fields

code: u16

RFC 6455’s close code.

reason: String

What the frame said, empty when it said nothing.

MessageTooBig

The server sent a message larger than the transport allows. It is refused as soon as its length is known, before any of it is read in, and the connection is failed.

Fields

size: usize

The size the frame claimed.

limit: usize

The largest message this transport accepts.

Transport(Arc<dyn Error + Send + Sync>)

The transport failed to dial, read or write. A failed dial or read is redialed and only logged; a failed write comes back from the perform, send or unsubscribe that asked for it, and the connection is dropped and redialed.

Headers(Arc<dyn Error + Send + Sync>)

The header provider couldn’t produce headers for a dial. That dial is turned down and the client tries again on its backoff.

InvalidHeader

A header given to the builder is not a valid HTTP header.

Fields

name: String

The header that was refused.

source: Arc<Error>

What http said about it.

DataNotAnObject

The data given to perform encodes to something other than a JSON object, which is the only shape Rails will route to an action.

Fields

action: String

The action the data was for.

Json(Arc<Error>)

A message didn’t decode into the type asked for, data for perform or send didn’t encode, or a frame wasn’t the JSON the protocol expects.

Implementations

impl Error

pub fn transport(source: impl Error + Send + Sync + 'static) -> Error

Wraps a transport’s own error, for Transport and Conn implementations.

pub fn headers(source: impl Error + Send + Sync + 'static) -> Error

Wraps whatever stopped a HeaderProvider from answering.

pub fn cause(&self) -> Option<&(dyn Error + Send + Sync + 'static)>

The error underneath this one, as the transport or the header provider handed it over, for a caller that wants to recognize its own with downcast_ref:

let error = Error::headers(SignedOut);

assert!(error.cause().is_some_and(|cause| cause.is::<SignedOut>()));

GaveUp hands back what the last attempt failed on, since that is the error the caller was waiting out. Everything else has no error underneath it and answers None.

This is here rather than left to source because the wrapped error is held behind an Arc, and a source walk hands back the Arc rather than what is in it. source still prints the chain; cause is what downcast_ref works on.

Trait Implementations

impl Clone for Error

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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, __formatter: &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<Error> for Error

fn from(source: Error) -> Error

Converts to this type from the input type.