nautilus_network/websocket/
config.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//! Configuration for WebSocket client connections.
17//!
18//! # Reconnection Strategy
19//!
20//! The default configuration uses unlimited reconnection attempts (`reconnect_max_attempts: None`).
21//! This is intentional for trading systems because:
22//! - Venues may be down for extended periods but eventually recover.
23//! - Exponential backoff already prevents resource waste.
24//! - Automatic recovery can be useful when manual intervention is not desirable.
25//!
26//! Use `Some(n)` primarily for testing, development, or non-critical connections.
27
28use std::fmt::Debug;
29
30/// Configuration for WebSocket client connections.
31///
32/// This struct contains only static configuration settings. Runtime callbacks
33/// (message handler, ping handler) are passed separately to `connect()`.
34///
35/// # Connection Modes
36///
37/// ## Handler Mode
38///
39/// - Use with [`crate::websocket::WebSocketClient::connect`].
40/// - Pass a message handler to `connect()` to receive messages via callback.
41/// - Client spawns internal task to read messages and call handler.
42/// - Supports automatic reconnection with exponential backoff.
43/// - Reconnection config fields (`reconnect_*`) are active.
44/// - Best for long-lived connections, Python bindings, callback-based APIs.
45///
46/// ## Stream Mode
47///
48/// - Use with [`crate::websocket::WebSocketClient::connect_stream`].
49/// - Returns a [`MessageReader`](super::types::MessageReader) stream for the caller to read from.
50/// - **Does NOT support automatic reconnection** (reader owned by caller).
51/// - Reconnection config fields are ignored.
52/// - On disconnect, client transitions to CLOSED state and caller must manually reconnect.
53#[cfg_attr(
54    feature = "python",
55    pyo3::pyclass(module = "nautilus_trader.core.nautilus_pyo3.network", from_py_object)
56)]
57#[cfg_attr(
58    feature = "python",
59    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.network")
60)]
61#[derive(Clone, Debug, bon::Builder)]
62pub struct WebSocketConfig {
63    /// The URL to connect to.
64    pub url: String,
65    /// The default headers.
66    #[builder(default)]
67    pub headers: Vec<(String, String)>,
68    /// The optional heartbeat interval (seconds).
69    pub heartbeat: Option<u64>,
70    /// The optional heartbeat message.
71    pub heartbeat_msg: Option<String>,
72    /// The timeout (milliseconds) for reconnection attempts.
73    /// **Note**: Only applies to handler mode. Ignored in stream mode.
74    pub reconnect_timeout_ms: Option<u64>,
75    /// The initial reconnection delay (milliseconds) for reconnects.
76    /// **Note**: Only applies to handler mode. Ignored in stream mode.
77    pub reconnect_delay_initial_ms: Option<u64>,
78    /// The maximum reconnect delay (milliseconds) for exponential backoff.
79    /// **Note**: Only applies to handler mode. Ignored in stream mode.
80    pub reconnect_delay_max_ms: Option<u64>,
81    /// The exponential backoff factor for reconnection delays.
82    /// **Note**: Only applies to handler mode. Ignored in stream mode.
83    pub reconnect_backoff_factor: Option<f64>,
84    /// The maximum jitter (milliseconds) added to reconnection delays.
85    /// **Note**: Only applies to handler mode. Ignored in stream mode.
86    pub reconnect_jitter_ms: Option<u64>,
87    /// The maximum number of reconnection attempts before giving up.
88    /// **Note**: Only applies to handler mode. Ignored in stream mode.
89    /// - `None`: Unlimited reconnection attempts (default, recommended for production).
90    /// - `Some(n)`: After n failed attempts, transition to CLOSED state.
91    pub reconnect_max_attempts: Option<u32>,
92    /// The idle timeout (milliseconds) for the read task.
93    /// When set, the read task will break and trigger reconnection if no data
94    /// is received within this duration. Useful for detecting silently dead
95    /// connections where the server stops sending without closing.
96    /// **Note**: Only applies to handler mode. Ignored in stream mode.
97    pub idle_timeout_ms: Option<u64>,
98}
nautilus_network/websocket/config.rs

nautilus_network/websocket/
config.rs
