Function connect_ws 

pub async fn connect_ws(
    ws_url: &str,
    auth_header: Option<AuthHeader<'_>>,
) -> Result<WsSession, ClientError>

Open a JMAP WebSocket connection (RFC 8887).

ws_url must come from the session document’s WebSocket capability URL (always a wss:// endpoint).

auth_header is an optional (header-name, header-value) pair injected into the WebSocket upgrade request. Pass None when the server does not require authentication headers on the WebSocket handshake.

Returns ClientError::InvalidArgument if the URL scheme is not wss://. jmap-chat-wss-guide.md: “Clients MUST always connect to wss://, never ws://. … clients MUST reject any URL that does not begin with wss:// rather than downgrading the connection.” Plaintext ws:// (local test rigs, examples) requires the explicit opt-in connect_ws_allow_plaintext.

The returned WsSession provides WsSession::next_frame for receiving events. The caller is responsible for reconnecting after disconnect with exponential backoff.

Uses DEFAULT_WS_MAX_MESSAGE_BYTES as the per-message / per-frame cap. Callers that need a different cap should use connect_ws_with_limit or crate::JmapClient::connect_ws_session (which reads ClientConfig::max_ws_message).

Security

The auth_header value is a credential and must not be logged or echoed back to other systems. Treat it with the same care as a BearerAuth token.