polyoxide_ws/
lib.rs

1//! # polyoxide-ws
2//!
3//! The WebSocket kit the polyoxide socket clients share. Each block here was
4//! carried as a copy by every socket crate (five of them); this crate holds
5//! the one copy, and each venue keeps only what is its own.
6//!
7//! - [`ensure_crypto_provider`] installs the process-default rustls provider
8//!   a `tokio-tungstenite` connect needs.
9//! - [`Backoff`] is the reconnect delay schedule.
10//! - [`Timing`] holds a supervised connection's ping, staleness, backoff,
11//!   connect and rotation timings, [`timing_setters!`] gives a builder its
12//!   setters, and [`next_wait`] is the wait until the first deadline.
13//! - [`WsError`] is the one socket error, read through its [`Kind`].
14//!   `polyoxide_venue::impl_ws_classification!` classifies it in the venue
15//!   crate that wraps it.
16//! - [`SocketTransport`] is how a connection is dialled, giving a
17//!   [`BoxSocket`] and reporting its [`Capabilities`]; `TungsteniteTransport`
18//!   is the native one, and [`transport_setters!`] gives a builder its
19//!   `runtime` and `socket_transport` setters.
20//! - [`connect`] opens a connection within a timeout, `connect_over`
21//!   upgrades a TCP connection a venue opened itself, [`with_timeout`] bounds
22//!   a venue's own connect, and [`retrying_can_fix`] says whether a
23//!   reconnect can help after one failed.
24//! - [`Connection`] is the bare tier: one connection as a `Stream` of its
25//!   frames in a [`Mode`], with the server's close captured, and requests
26//!   correlated with their answers through [`Correlated`].
27//! - [`Supervisor`] runs one supervised connection for a venue's
28//!   [`Protocol`]: pings on the wall clock, staleness, reconnect with backoff
29//!   and a replay of the membership, rotation, outage markers, and membership
30//!   changes through a [`MembershipHandle`], yielding a [`Supervised`] stream.
31//!
32//! [`tungstenite`] is re-exported, so a venue names `Message` and
33//! `CloseFrame` through this crate rather than depending on it.
34//!
35//! On `wasm32` the kit builds no TLS or TCP stack: its transport is the
36//! browser's `WebSocket`, `connect_over` and the scripted test server are
37//! host-only, and the `test-server` feature turns on nothing.
38//!
39//! Behind the `test-server` feature, the doc-hidden `test_server` module holds
40//! the scripted local server and the helpers the offline suites share. It is
41//! for tests, not consumers.
42//!
43//! The crate depends on neither `polyoxide-core` nor `polyoxide-venue`, and
44//! builds no HTTP or signing stack, so a credential-free feed built on it
45//! stays light (AD-2). It logs under the `polyoxide_ws` target and never
46//! installs a subscriber.
47
48#![warn(missing_docs)]
49
50#[cfg(doctest)]
51#[doc = include_str!("../README.md")]
52struct ReadmeDoctests;
53
54mod backoff;
55mod bare;
56mod browser;
57mod connect;
58mod error;
59mod request;
60mod supervisor;
61#[cfg(all(not(target_arch = "wasm32"), any(test, feature = "test-server")))]
62#[doc(hidden)]
63pub mod test_server;
64mod timing;
65#[cfg(not(target_arch = "wasm32"))]
66mod tls;
67mod transport;
68
69pub use backoff::{Backoff, MIN_BACKOFF};
70pub use bare::{Connection, Mode};
71#[cfg(target_arch = "wasm32")]
72pub use browser::WebSocketTransport;
73pub use browser::PING_UNSUPPORTED;
74#[cfg(not(target_arch = "wasm32"))]
75pub use connect::connect_over;
76pub use connect::{connect, retrying_can_fix, with_timeout, DEFAULT_CONNECT_TIMEOUT};
77pub use error::{Kind, WsError};
78pub use request::Correlated;
79pub use supervisor::{
80    Decoded, MembershipHandle, Offline, Outage, Protocol, Queue, Recovery, Supervised, Supervisor,
81};
82pub use timing::{next_wait, Timing};
83#[cfg(not(target_arch = "wasm32"))]
84pub use tls::ensure_crypto_provider;
85#[cfg(not(target_arch = "wasm32"))]
86pub use transport::TungsteniteTransport;
87pub use transport::{default_socket_transport, BoxSocket, Capabilities, SocketIo, SocketTransport};
88/// The WebSocket library the kit is built on, re-exported so a venue names
89/// its types (`Message`, `CloseFrame`, `http`) through this crate.
90pub use tungstenite;
91
92/// The runtime seam, for `transport_setters!` to name: a crate invoking it
93/// needs no `polyoxide-rt` dependency of its own.
94#[doc(hidden)]
95pub use polyoxide_rt as __rt;
polyoxide_ws/lib.rs

polyoxide_ws/
lib.rs
