Client

Transports and proxies

Polling, websocket and upgrade; HTTP proxies from the builder or the environment; the shared HTTP client.

Transports

use socketio_next::{ClientBuilder, TransportType};

let client = ClientBuilder::new(url)
    .transport_type(TransportType::Websocket)
    .connect()
    .await?;
TransportTypesocket.io-client transportsWhat
Any (default)["polling", "websocket"]polling, upgraded to websocket when the server offers it; stays on polling when the upgrade fails
Polling["polling"]long-polling only, never tries the websocket
Websocket["websocket"]websocket from the start
WebsocketUpgrade—polling, then the upgrade must succeed (UpgradeUnavailable / UpgradeFailed otherwise)

The polling and websocket handshakes are bounded by the timeout; a blackholed websocket falls back to polling with Any. link_info().transport shows the transport in use.

Proxies

Polling requests and the websocket go through the same HTTP proxy:

  • the one given to proxy("http://user:pass@host:port");
  • else the environment's: HTTPS_PROXY for https / wss, HTTP_PROXY for http / ws, ALL_PROXY, minus NO_PROXY (domains, IPs, CIDR and *);
  • no_proxy() turns proxies off for both transports.

The websocket uses a CONNECT tunnel with basic auth from the proxy URL's user info. Both transports take the same decision (the websocket uses the matcher reqwest uses for polling). Only http:// proxies are spoken for the websocket: an https:// or SOCKS proxy is a ProxyFailed error, never a silent direct connection.

The environment is read once, when the client is built, and that decision holds for its life.

If a crate in your build enables reqwest's system-proxy feature (macOS / Windows system settings), only polling sees those settings. Call proxy(..) or no_proxy() to make both transports agree.

Environment proxies apply to ws:// too: a proxy that only allows CONNECT to port 443 then refuses the websocket, and with TransportType::Any the client stays on polling.

Redirects

Redirects are never followed (engine.io does not use them): a 3xx is an HttpStatus error.

One HTTP client per client

The handshake, the polls and the POSTs of one client share one reqwest client (its connection pool and, with the cookies feature, its cookie jar) across reconnects. Long-poll GETs fail after pingInterval + pingTimeout; POSTs have no total bound, so a large upload is not cut by the heartbeat.

Cookies

With the cookies feature each client has a cookie jar: cookies set by polling answers go back on later requests and on the websocket handshake. Load balancers that pin sessions by cookie (sticky sessions) need it; without it a reconnect may land on a node that does not know the session (HttpStatus { status: 400, message: "Session ID unknown" }).