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//! - [`connect`] opens a connection within a timeout, [`connect_over`]
17//! upgrades a TCP connection a venue opened itself, [`with_timeout`] bounds
18//! a venue's own connect, and [`retrying_can_fix`] says whether a
19//! reconnect can help after one failed.
20//! - [`Connection`] is the bare tier: one connection as a `Stream` of its
21//! frames in a [`Mode`], with the server's close captured, and requests
22//! correlated with their answers through [`Correlated`].
23//! - [`Supervisor`] runs one supervised connection for a venue's
24//! [`Protocol`]: pings on the wall clock, staleness, reconnect with backoff
25//! and a replay of the membership, rotation, outage markers, and membership
26//! changes through a [`MembershipHandle`], yielding a [`Supervised`] stream.
27//!
28//! [`tungstenite`] is re-exported, so a venue names `Message` and
29//! `CloseFrame` through this crate rather than depending on it.
30//!
31//! Behind the `test-server` feature, the doc-hidden `test_server` module holds
32//! the scripted local server and the helpers the offline suites share. It is
33//! for tests, not consumers.
34//!
35//! The crate depends on neither `polyoxide-core` nor `polyoxide-venue`, and
36//! builds no HTTP or signing stack, so a credential-free feed built on it
37//! stays light (AD-2). It logs under the `polyoxide_ws` target and never
38//! installs a subscriber.
39
40#![warn(missing_docs)]
41
42#[cfg(doctest)]
43#[doc = include_str!("../README.md")]
44struct ReadmeDoctests;
45
46mod backoff;
47mod bare;
48mod connect;
49mod error;
50mod request;
51mod supervisor;
52#[cfg(any(test, feature = "test-server"))]
53#[doc(hidden)]
54pub mod test_server;
55mod timing;
56mod tls;
57
58pub use backoff::{Backoff, MIN_BACKOFF};
59pub use bare::{Connection, Mode};
60pub use connect::{
61 connect, connect_over, retrying_can_fix, with_timeout, Socket, DEFAULT_CONNECT_TIMEOUT,
62};
63pub use error::{Kind, WsError};
64pub use request::Correlated;
65pub use supervisor::{
66 Decoded, MembershipHandle, Offline, Outage, Protocol, Queue, Recovery, Supervised, Supervisor,
67};
68pub use timing::{next_wait, Timing};
69pub use tls::ensure_crypto_provider;
70/// The WebSocket library the kit is built on, re-exported so a venue names
71/// its types (`Message`, `CloseFrame`, `http`) through this crate.
72pub use tokio_tungstenite::tungstenite;