Errors and logging

The Error type and its ErrorKind variants, what each phase of a connection and each call can fail with, and how to log the client.

Every fallible operation returns Result<_, dxn_signalr::Error>: new, start, connect, connect_with, invoke, send, pause, resume, InvocationContext::argument and complete, the ReconnectionHandler methods and StatefulReconnectConfig::new. A stream reports the error that ended it through ManualStream::error().

Error is cheap to clone (one failure ends many pending calls), Send + Sync + 'static, and implements std::error::Error, so it works with ?, Box<dyn std::error::Error>, anyhow and thiserror. Branch on Error::kind(); the accessors return the structured fields of the kinds that carry them.

ErrorKind, TimeoutOperation, CloseReason and HttpVersion are #[non_exhaustive], so a match needs a wildcard arm. Error::is_transient() is true for timeouts, network and transport failures, negotiate answers 408, 429 and 5xx, and proxy failures without a status or with 408, 429 or 5xx (not refused credentials or a denied target): retrying the same operation later can succeed.

Display is stable, human-readable and redacted when the error is built: it never contains bearer tokens, access_token values, Authorization values or credentials in URLs. server_message() is the exception. It returns the server’s text verbatim, like the .NET client’s HubException.Message, so treat it as any other server-provided text when you log it. Branch on kinds and fields, never on message text.

#Handling errors

use std::time::Duration;

use dxn_signalr::{CloseReason, Error, ErrorKind, SignalRClient, TimeoutOperation};

async fn connect(host: &str) -> Result<SignalRClient, Error> {
    let result = SignalRClient::connect_with(host, "chat", |c| {
        c.with_connect_timeout(Duration::from_secs(5));
    })
    .await;
    if let Err(error) = &result {
        match error.kind() {
            ErrorKind::Authentication => eprintln!("sign in again ({:?})", error.status()),
            ErrorKind::Negotiate if error.status() == Some(404) => eprintln!("no hub at that path"),
            ErrorKind::Timeout if error.timeout_operation() == Some(TimeoutOperation::Negotiate) => {
                eprintln!("the server did not answer negotiate within {:?}", error.timeout())
            }
            ErrorKind::Configuration => {
                eprintln!("fix {}", error.setting().unwrap_or("the configuration"))
            }
            _ if error.is_transient() => eprintln!("try again later: {error}"),
            _ => eprintln!("cannot connect: {error}"),
        }
    }
    result
}

async fn total(client: &mut SignalRClient) -> Option<i32> {
    match client.invoke::<i32>("Total".to_string()).await {
        Ok(total) => Some(total),
        Err(error) => {
            match (error.kind(), error.close_reason()) {
                (ErrorKind::Hub, _) => {
                    eprintln!("the hub failed: {}", error.server_message().unwrap_or(""))
                }
                (ErrorKind::Serialization, _) => eprintln!("Total returned something other than an i32"),
                (ErrorKind::ConnectionClosed, Some(CloseReason::Server)) => {
                    eprintln!("the server ended the connection: {:?}", error.server_message())
                }
                _ => eprintln!("Total failed: {error}"),
            }
            None
        }
    }
}

#Failures by phase

#Before any I/O

new (and so connect) returns a Configuration error at once when the configuration cannot work; setting() names what to change. Liveness durations are never rejected.

#Negotiation and transport

#Calls

#Logging

The crate logs through the log facade under the dxn_signalr target. Install any logger to see it. Natively, with env_logger:

fn init_logging() {
    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("dxn_signalr=info"))
        .init();
}

In the browser use console_log::init_with_level(log::Level::Info); see Browser and WebAssembly.

Stateful reconnect logs its sequencing at debug under the dxn_signalr::stateful target, without payloads. Every record starts with generation=<n>, the physical connection it belongs to. Enable it alone to diagnose a resume:

RUST_LOG=dxn_signalr::stateful=debug

#Next

Troubleshooting starts from a symptom and finds the cause.