nautilus_network/websocket/
mod.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! WebSocket transport with runtime backend selection and adapter-facing lifecycle policy.
17//!
18//! # Architecture
19//!
20//! [`WebSocketClient`] coordinates a controller, one serialized writer, an optional heartbeat, and
21//! either a managed reader or a caller-owned stream. Application text and binary sends can await
22//! default or keyed quotas from a shared [`RateLimiter`](crate::ratelimiter::RateLimiter).
23//!
24//! [`client`] manages connection lifecycle and concurrent tasks. [`auth`] coordinates
25//! adapter-driven authentication and optional replay gating, while [`subscription`] records
26//! adapter-driven subscription intent and acknowledgments. [`config`], [`types`], and [`proxy`]
27//! define connection policy and transport boundaries.
28//!
29//! # Operating modes
30//!
31//! [`WebSocketClient`] supports handler and stream modes. Handler mode owns the reader and replaces
32//! it during automatic reconnects. Stream mode returns the reader to the caller and disables
33//! automatic reconnects because the client cannot replace caller-owned state.
34//!
35//! # Liveness
36//!
37//! A configured heartbeat sends either a protocol Ping or a text message at a fixed interval; it
38//! does not imply a response timeout. Handler mode can separately reconnect when no frame arrives
39//! before a heartbeat timeout or when no text or binary application data arrives before the idle
40//! timeout. Ping and Pong reset the frame timeout but not the application-data idle timeout.
41//!
42//! # State reporting and explicit reconnect
43//!
44//! An optional [`crate::SocketStateSink`] publishes ordered `Connected` and `Disconnected`
45//! availability edges for initial connection, transport loss, and recovery. It omits retry attempts
46//! and deliberate shutdown. [`WebSocketReconnectHandle`] lets adapter tasks request transport
47//! replacement without owning the client. Handler mode accepts an active request, invalidates
48//! registered authentication state, and reports the loss before reconnecting; stream mode returns
49//! [`crate::mode::ReconnectRequestOutcome::Unsupported`].
50//!
51//! # Reconnection and sends
52//!
53//! The writer task serializes sends and is the sole owner of the active sink. Ordinary application
54//! sends retain FIFO buffering and replay across reconnects. A control frame belongs to the
55//! connection it was issued on, so a failed Ping, Pong, or Close is dropped instead of replayed.
56//! Ownership-bound sends carry an expected connection epoch and never enter that replay buffer.
57//!
58//! The initial connection has epoch `0`. The writer advances the epoch when it installs a
59//! replacement sink. Epoch-aware handlers receive that epoch on messages from the replacement
60//! reader and on its reconnect notification. Epochs identify transport ownership; they do not
61//! order application authentication or subscription recovery.
62//!
63//! # Transport backends
64//!
65//! The backend-neutral [`Message`](crate::transport::Message) and
66//! [`TransportError`](crate::transport::TransportError) types keep lifecycle code independent of
67//! the concrete library. [`tokio-tungstenite`](https://github.com/snapview/tokio-tungstenite) is
68//! always available. [`sockudo-ws`](https://github.com/sockudo/sockudo-ws) is enabled and selected
69//! by default through the `transport-sockudo` feature. Both accept custom upgrade headers. Proxy
70//! connections use Tungstenite; selecting Sockudo with a proxy falls back to that backend.
71
72pub mod auth;
73pub mod client;
74pub mod config;
75pub mod consts;
76pub mod proxy;
77pub mod subscription;
78pub mod types;
79
80// Re-export main types for convenience
81pub use auth::AuthTracker;
82pub use client::{
83    ReconnectHeaders, WebSocketClient, WebSocketClientInner, WebSocketReconnectHandle,
84};
85pub use config::{InitialConnectRetryPolicy, TransportBackend, WebSocketConfig};
86pub use consts::{AUTHENTICATION_TIMEOUT_SECS, TEXT_PING, TEXT_PONG};
87pub use subscription::{SubscriptionSnapshot, SubscriptionState, split_topic};
88pub use types::{
89    EpochMessageHandler, EpochPingHandler, MessageHandler, MessageReader, PingHandler,
90    channel_epoch_message_handler, channel_message_handler,
91};
nautilus_network/websocket/mod.rs

nautilus_network/websocket/
mod.rs
