Crate polyoxide_ws

Expand description

§polyoxide-ws

The WebSocket kit the polyoxide socket clients share. Each block here was carried as a copy by every socket crate (five of them); this crate holds the one copy, and each venue keeps only what is its own.

ensure_crypto_provider installs the process-default rustls provider a tokio-tungstenite connect needs.
Backoff is the reconnect delay schedule.
Timing holds a supervised connection’s ping, staleness, backoff, connect and rotation timings, timing_setters! gives a builder its setters, and next_wait is the wait until the first deadline.
WsError is the one socket error, read through its Kind. polyoxide_venue::impl_ws_classification! classifies it in the venue crate that wraps it.
SocketTransport is how a connection is dialled, giving a BoxSocket and reporting its Capabilities; TungsteniteTransport is the native one, and transport_setters! gives a builder its runtime and socket_transport setters.
connect opens a connection within a timeout, connect_over upgrades a TCP connection a venue opened itself, with_timeout bounds a venue’s own connect, and retrying_can_fix says whether a reconnect can help after one failed.
Connection is the bare tier: one connection as a Stream of its frames in a Mode, with the server’s close captured, and requests correlated with their answers through Correlated.
Supervisor runs one supervised connection for a venue’s Protocol: pings on the wall clock, staleness, reconnect with backoff and a replay of the membership, rotation, outage markers, and membership changes through a MembershipHandle, yielding a Supervised stream.

tungstenite is re-exported, so a venue names Message and CloseFrame through this crate rather than depending on it.

On wasm32 the kit builds no TLS or TCP stack: its transport is the browser’s WebSocket, connect_over and the scripted test server are host-only, and the test-server feature turns on nothing.

Behind the test-server feature, the doc-hidden test_server module holds the scripted local server and the helpers the offline suites share. It is for tests, not consumers.

The crate depends on neither polyoxide-core nor polyoxide-venue, and builds no HTTP or signing stack, so a credential-free feed built on it stays light (AD-2). It logs under the polyoxide_ws target and never installs a subscriber.

Re-exports§

pub use tungstenite;

Macros§

timing_setters: Generates the timing setters a supervised builder offers, each writing the builder’s timing field, a Timing.
transport_setters: Generates the transport setters a socket builder offers, each writing a field of the builder: runtime(Arc<dyn Runtime>) writes self.runtime, an Option<Arc<dyn polyoxide_rt::Runtime>>, and socket_transport(Arc<dyn SocketTransport>) writes self.socket_transport, an Option<Arc<dyn SocketTransport>>.

Structs§

Backoff: The reconnect delay schedule: doubling from an initial delay to a ceiling, and back to the start after a connection that delivered something.
Capabilities: What a SocketTransport can do.
Connection: One open connection, as a Stream of its frames.
MembershipHandle: Changes the membership of a running Supervised.
Supervised: A supervised connection: a Stream of the protocol’s events, and of the errors it skips past or stops on, that survives drops, stalls and rotations by reconnecting and replaying its membership.
Supervisor: Starts a supervised connection for a Protocol.
Timing: The timings a supervised connection runs on.
TungsteniteTransport: The native transport: tokio-tungstenite over TCP, with TLS from rustls.
WsError: A WebSocket failure: a transport error, a refused upgrade, a server close, or one of the kit’s own timeouts.

Enums§

Correlated: What a frame read while a request awaits its answer is, as the caller’s matcher reads it.
Decoded: What one frame decodes to.
Kind: What kind of failure a WsError is.
Mode: Which frames a Connection yields.
Offline: What becomes of a membership change made while no connection is up.
Outage: Why a connection went down, for Protocol::disconnected, which owns it, so a protocol’s marker can carry the error.
Queue: The queue between the task and the consumer.
Recovery: What to do after a failure.

Constants§

DEFAULT_CONNECT_TIMEOUT: How long one connection attempt may take unless a venue says otherwise: the TCP connect, the TLS handshake and the WebSocket upgrade together.
MIN_BACKOFF: The shortest delay. Zero would never grow, so a dead host would be retried on every timer tick.
PING_UNSUPPORTED: The message of the Kind::Unsupported error a transport that sends no ping frames (a browser’s) gives for a ping: a caller that refuses a ping before sending it builds its error from this text, so the refusal reads the same as the transport’s own.

Traits§

Protocol: A venue’s socket protocol, as the Supervisor drives it.
SocketIo: An open connection as the kit reads and writes it: a stream of frames and a sink for them, both failing with tungstenite’s error.
SocketTransport: How a WebSocket connection is dialled.

Functions§

connect: Open a connection through the target’s default SocketTransport and runtime, giving up after timeout.
connect_over: Upgrade a TCP connection the caller opened itself: the TLS handshake when request is a wss:// URL, then the WebSocket upgrade.
default_socket_transport: The transport a socket uses when none is injected: TungsteniteTransport on a host target and WebSocketTransport on wasm32.
ensure_crypto_provider: Make sure rustls has a default CryptoProvider before a connection opens.
next_wait: The wait until the first of several deadlines falls due.
retrying_can_fix: Whether reconnecting can help after a connect failed this way.
with_timeout: Run a caller’s own connect future, giving up after timeout with Kind::ConnectTimeout.

Type Aliases§

BoxSocket: An open connection, boxed: what a SocketTransport returns and Connection reads.