Struct ClientBuilder 

pub struct ClientBuilder { /* private fields */ }

Configures a Client. Nothing touches the network until Client::connect.

Implementations

impl ClientBuilder

pub fn transport(self, transport: impl Transport + 'static) -> ClientBuilder

Sets the transport: one of your own, or the built-in WebSocketTransport configured differently. Without it build uses WebSocketTransport::default(), and with the websocket feature off this is the only way to get a client at all.

pub fn protocols(self, protocols: Vec<Arc<dyn Protocol>>) -> ClientBuilder

Sets the protocols offered during the handshake, most preferred first, replacing the default of V1Json. The server picks one of them and the client speaks it for the rest of the connection.

pub fn prefer_protocols( self, protocols: Vec<Arc<dyn Protocol>>, ) -> ClientBuilder

Offers protocols ahead of the ones already there, so preferring a new protocol doesn’t mean restating the ones to fall back to.

pub fn header(self, name: &str, value: &str) -> ClientBuilder

Sets a header on the upgrade request. An Action Cable server authorizes that request, so this is where a session cookie or an API token goes. A name or value that isn’t a valid HTTP header, one carrying a newline say, fails build.

pub fn cookie(self, cookie: &str) -> ClientBuilder

Shorthand for one Cookie header.

pub fn origin(self, origin: &str) -> ClientBuilder

Sets the Origin header. Rails compares it against the host it serves on and turns down anything else, a request carrying no Origin at all included, so by default it is derived from the cable URL: wss://example.com/cable sends https://example.com. A server behind a proxy that terminates TLS sees a different scheme than the URL says and needs this.

pub fn header_provider( self, provider: impl HeaderProvider + 'static, ) -> ClientBuilder

Asks provider for headers on every dial, laid over the ones set here. For a credential that expires; see HeaderProvider.

pub fn stop_on_error( self, terminal: impl Fn(&Error) -> bool + Send + Sync + 'static, ) -> ClientBuilder

Recognizes the connection errors that dialing again cannot repair. The predicate sees every one of them — a header provider that refused, a dial that failed, a connection that died — and returning true stops the client with that error instead of reconnecting. Error::cause hands back the application’s own error, for downcast_ref to recognize:

let client = Client::builder("wss://example.com/cable")
    .stop_on_error(|error| error.cause().is_some_and(|cause| cause.is::<SignedOut>()));

It runs on the connection’s task and must return promptly.

pub fn stale_after(self, after: Duration) -> ClientBuilder

How long a connection may go without a frame before it counts as dead. The server beats every three seconds; the default is six, so two missed beats.

pub fn backoff(self, initial: Duration, longest: Duration) -> ClientBuilder

The reconnect delay. It starts at initial, doubles per failed attempt up to longest, and is spread with jitter. Defaults to a second and half a minute.

pub fn max_attempts(self, attempts: u32) -> ClientBuilder

How many connection attempts may fail in a row before the client stops with Error::GaveUp. A welcome resets the count, so this bounds an outage rather than the client’s lifetime. Zero, the default, keeps dialing until Client::close.

pub fn subscribe_retry(self, retry: Duration) -> ClientBuilder

How often an unconfirmed subscribe command is resent. Defaults to half a second, like the JavaScript client’s guarantor.

pub fn message_buffer(self, messages: usize) -> ClientBuilder

How many messages a subscription buffers before it starts dropping them. Defaults to 64, and applies to every subscription on the client.

pub fn build(self) -> Result<Client, Error>

Fails on a header that isn’t valid HTTP, reported here rather than where it was given so the chain of setters stays plain, and on having no transport to dial with.