1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
use super::{ClientId, ConnectOptions, JournalOptions, Session, WebSocketClientConfig};
use crate::module::ws_client::ws_client_inner::WSClientInner;
use crate::{network::NetworkConfig, LogType, Result};
use std::{fmt, sync::Arc};
/// Shared entry point for WebSocket clients, used to create sessions, query configuration, and close the client.
///
/// # Example
///
/// ```no_run
/// use open_net::{
/// network::{NetworkConfig, TlsConfig},
/// tls::CryptoProvider,
/// ws::WebSocketClient,
/// OpenNet, Result,
/// };
/// use std::sync::Arc;
///
/// # async fn example() -> Result<()> {
/// // Choose and add a rustls 0.23 provider in the application crate.
/// let provider: Arc<CryptoProvider> =
/// Arc::new(rustls_openssl::default_provider());
/// let network = NetworkConfig::default()
/// .with_tls(TlsConfig::default().with_crypto_provider(provider));
/// let net = OpenNet::new_with_network_config(network)?;
/// let client: WebSocketClient = net.create_ws_client("market-feed").await?;
/// println!("Client id: {}", client.id());
/// client.shutdown().await?;
/// net.destroy_ws_client("market-feed").await?;
/// # Ok(())
/// # }
/// ```
#[derive(Clone)]
pub struct WebSocketClient {
/// Configuration, session management, and shutdown state common to all client clones.
pub(crate) inner: Arc<WSClientInner>,
}
impl WebSocketClient {
pub(crate) fn from_inner(inner: Arc<WSClientInner>) -> Self {
Self { inner }
}
/// Returns the identity of the current WebSocket client instance.
///
/// # Use cases
///
/// When an application maintains multiple server connections, it can use this
/// identifier in logs, metrics, and session indexes alongside
/// [`Session::client_id`] and the `client_id` field in connection events.
/// The identifier is allocated within the current process. All clones of a
/// client share it, and creating a session or reconnecting does not change it.
/// It is not a server-assigned user ID and must not be used as a persistent
/// business key across process restarts.
///
/// # Example
///
/// ```
/// use open_net::ws::WebSocketClient;
///
/// fn log_client(client: &WebSocketClient) {
/// let worker_client = client.clone();
/// println!(
/// "Preparing to process business messages from clients {} and {}",
/// client.id(),
/// worker_client.id(),
/// );
/// }
/// ```
pub fn id(&self) -> ClientId {
self.inner.id()
}
/// Borrows the WebSocket configuration determined when the client was created.
///
/// # Use cases
///
/// Use this snapshot when diagnosing queue backpressure, message-size
/// limits, heartbeat behavior, or shutdown timing. It can also be cloned as
/// the starting point for another client configuration.
/// The returned reference is read-only, and the configuration remains fixed
/// for the client's lifetime, including reconnects. Changing a clone does
/// not affect this client. The target address, handshake headers, and
/// reconnect policy are supplied by [`ConnectOptions`] for each session.
///
/// # Example
///
/// ```
/// use open_net::ws::{WebSocketClient, WebSocketClientConfig};
///
/// fn config_for_another_client(client: &WebSocketClient) -> WebSocketClientConfig {
/// let current = client.config();
/// println!(
/// "Normal sending queue can hold up to {} messages",
/// current.queues.normal.max_items
/// );
///
/// // Pass the adjusted configuration to OpenNet::create_ws_client_with_config.
/// let mut next = current.clone();
/// next.queues.normal.max_items = 2048;
/// next
/// }
/// ```
pub fn config(&self) -> &WebSocketClientConfig {
self.inner.config()
}
/// Borrows the actual proxy, TLS, and network state policies adopted by the current client.
///
/// # Use cases
///
/// Use this snapshot to determine which policy a client uses when the engine
/// has a default configuration and the client may have an override. It can
/// be cloned and adjusted for another client. The returned value is either
/// the inherited engine configuration or the complete per-client replacement.
/// All sessions and reconnects use this immutable policy; it describes the
/// configured behavior, not whether the live network is currently reachable.
///
/// # Example
///
/// ```
/// use open_net::network::{NetworkConfig, ProxyConfig};
/// use open_net::ws::WebSocketClient;
///
/// fn direct_config_for_another_client(client: &WebSocketClient) -> NetworkConfig {
/// let current = client.network_config();
/// println!(
/// "Network status policy: {:?}",
/// current.network_status_policy()
/// );
///
/// // Keep current TLS and network state policies, only change to direct for new clients.
/// // Pass the return value to OpenNet::create_ws_client_with_network_config.
/// current.clone().with_proxy(ProxyConfig::direct())
/// }
/// ```
pub fn network_config(&self) -> &NetworkConfig {
self.inner.network_config()
}
/// Create a session and wait for the session to establish a usable WebSocket connection before returning.
///
/// # Use cases
///
/// Use this method when startup must establish a connection before the
/// application sends subscriptions or other business messages. `options`
/// may be a `ws://` or `wss://` address or a [`ConnectOptions`] value that
/// sets authentication headers, timeouts, receive options, and reconnect policy.
/// Use [`Self::start_session`] when the session must be available before the
/// connection completes, when the attempt may be cancelled, or when a full
/// connection journal is required.
///
/// This is equivalent to `start_session(options, None)` followed by
/// [`Session::wait_connected`], so it does not create an independent
/// connection journal. The default policy may retry an initial failure, and
/// `connect_timeout` bounds the total wait for the first connection; one
/// failed handshake therefore need not fail immediately. Later
/// disconnections continue to follow the session's reconnect policy, and a
/// successful return does not guarantee that the connection remains usable.
///
/// Hold the returned [`Session`] for as long as the session is needed:
/// dropping it requests session cancellation even if a client or sender
/// clone remains. Cancelling the future returned by this method also drops
/// its internally created session and requests cancellation; cleanup may
/// continue in the background.
///
/// # Errors
///
/// Errors during session creation are the same as [`Self::start_session`].
/// If the session times out while connecting, encounters a non-retryable
/// handshake error, exhausts its retry budget, or is shut down while this
/// method waits, the corresponding error is returned.
///
/// # Example
///
/// ```no_run
/// use open_net::{
/// network::{NetworkConfig, TlsConfig},
/// tls::CryptoProvider,
/// ws::ConnectOptions,
/// OpenNet, Result,
/// };
/// use std::sync::Arc;
/// use std::time::Duration;
///
/// # async fn example() -> Result<()> {
/// let provider: Arc<CryptoProvider> =
/// Arc::new(rustls_openssl::default_provider());
/// let net = OpenNet::new_with_network_config(
/// NetworkConfig::default()
/// .with_tls(TlsConfig::default().with_crypto_provider(provider)),
/// )?;
/// let client = net.create_ws_client("market-feed").await?;
/// let mut options = ConnectOptions::new("wss://example.com/stream");
/// options.connect_timeout = Some(Duration::from_secs(15));
///
/// let session = client.connect(options).await?;
/// // The connection has succeeded; keep holding the session while the
/// // subscription is active.
/// session
/// .sender()
/// .send(r#"{"op":"subscribe","topic":"prices"}"#)
/// .await?;
///
/// // Close the session when the work is complete; the client can create
/// // another session afterward.
/// session.close().await?;
/// net.destroy_ws_client("market-feed").await?;
/// # Ok(())
/// # }
/// ```
pub async fn connect(&self, options: impl Into<ConnectOptions>) -> Result<Session> {
let options = options.into();
crate::log_s!(LogType::WSC; "connect", "options", format!("{:?}", options));
let session = self.start_session(options, None).await?;
session.wait_connected().await?;
Ok(session)
}
/// Submit the connection task and return after the background work task receives the session without waiting for the handshake to succeed.
///
/// # Use cases
///
/// Use this method to display a connecting state immediately, provide a
/// cancel action, install state monitoring, or record the first handshake
/// and later reconnect attempts. After it returns, use
/// [`Session::watch_state`] to observe state, [`Session::cancel`] to request
/// cancellation, or [`Session::wait_connected`] to await a usable connection.
/// A successful return means only that the session was admitted; subsequent
/// connection attempts may still fail.
///
/// # Parameters and lifecycle
///
/// - `options`: Target address or complete connection configuration. The
/// connection process follows its timeout and reconnect policies. A
/// message inbox is created by default; use [`Session::take_messages`]
/// to receive messages that arrive early.
/// - `journal`: With `Some`, creates a bounded connection journal before the
/// first attempt. Retrieve it with [`Session::take_journal`] and consume
/// it continuously; a full journal can block later connection attempts.
/// With `None`, no journal is created, but state observation and the
/// history-limited [`Session::subscribe_events`] stream remain available.
///
/// Each client (including all clones) can only have one outstanding session at a time.
/// Each client, including all clones, can have only one outstanding session.
/// To change the target, first call [`Session::close`] on the old session and
/// wait for completion. If using `cancel`, also wait for [`Session::closed`].
/// The returned session owns the lifecycle and must remain held; retaining
/// only a sender or receiver does not prevent cancellation when the owner is dropped.
///
/// # Errors
///
/// Returns [`crate::error::ErrorKind::InvalidConfig`] for invalid options,
/// [`crate::error::ErrorKind::SessionAlreadyExists`] when another session
/// is still active, and [`crate::error::ErrorKind::Closed`] after client
/// shutdown has been requested. Resource exhaustion, a command wait that
/// exceeds the initial connection budget, or engine shutdown may also fail
/// admission. Connection errors after this method returns are reported by
/// the session's wait and observation interfaces.
///
/// # Example
///
/// ```no_run
/// use open_net::{ws::{JournalOptions, WebSocketClient}, Result};
///
/// async fn connect_with_journal(client: &WebSocketClient) -> Result<()> {
/// let mut session = client.start_session(
/// "wss://example.com/stream",
/// Some(JournalOptions::default()),
/// ).await?;
///
/// let journal = session.take_journal().ok_or_else(|| {
/// open_net::NetError::from(open_net::error::ErrorKind::InvalidConfig)
/// })?;
/// // The callback continues to consume logs; keep the subscription handle alive to avoid log accumulation while waiting for a connection.
/// let _journal_subscription = journal.into_callback(|_, event| {
/// match event {
/// Ok(event) => println!("Session {}: {:?}", event.session_id, event.kind),
/// Err(error) => eprintln!("Failed to receive connection log: {error:?}"),
/// }
/// })?;
///
/// let connection = session.wait_connected().await?;
/// println!("Physical connection {} is ready", connection.connection_id);
/// session.sender().send("hello").await?;
/// session.close().await?;
/// Ok(())
/// }
/// ```
pub async fn start_session(
&self,
options: impl Into<ConnectOptions>,
journal: Option<JournalOptions>,
) -> Result<Session> {
let options = options.into();
crate::log_s!(LogType::WSC; "start_session", "options|journal", format!("{:?}", options), format!("{:?}", journal));
self.inner.start_session(options, journal).await
}
/// Determine whether the client has received a shutdown request.
///
/// # Use cases
///
/// Use this check before scheduling work during application shutdown or
/// while reusing a client handle. The state is shared by all clones and is
/// permanent once `true`; an ordinary disconnect, automatic reconnect, or
/// end of one session does not set it.
///
/// Returning `true` does not mean that the background cleanup has been completed; call [`Self::shutdown`] when you need to wait for completion.
/// `true` does not mean that cleanup has finished; call [`Self::shutdown`]
/// when completion must be awaited. `false` does not mean that a usable
/// connection exists, and another task may request shutdown immediately,
/// so connection and send errors must still be handled after this check.
///
/// # Example
///
/// ```
/// use open_net::ws::WebSocketClient;
///
/// fn show_client_lifecycle(client: &WebSocketClient) {
/// if client.is_shutdown() {
/// println!("Client {} is shutting down or has been shut down, stopping scheduling new tasks", client.id());
/// } else {
/// println!("Client {} has not been closed; the connection status needs to be queried from Session", client.id());
/// }
/// }
/// ```
pub fn is_shutdown(&self) -> bool {
self.inner.is_shutdown()
}
/// Close the client permanently and wait for the background work tasks to finish cleaning up.
///
/// # Use cases
///
/// Use this method when the application exits, logs an account out, or will
/// no longer use the client. It stops connection and reconnect attempts,
/// ends the current session, and cleans up queues, pending requests, and
/// client-level subscriptions. All clones observe the shutdown, and no new
/// session can be created after completion. To close only the current
/// session while retaining the client, use [`Session::close`].
///
/// This operation is idempotent and may be called concurrently; calls made
/// after cleanup completes return success immediately.
/// Closing does not guarantee that all queued messages have been written out, nor does it guarantee that the server has processed previously sent data.
/// If the application needs delivery or business confirmation, wait for the
/// relevant receipt or response before calling this method.
/// After the shutdown request is issued, the client will not resume operation even if the wait is canceled.
///
/// This method does not remove the client name registration in the engine; if you still need to release the registration and reuse the name,
/// Calling [`crate::OpenNet::destroy_ws_client`] also closes the client.
///
/// # Errors
///
/// Returns [`crate::error::ErrorKind::EngineDropped`] if the background
/// command channel exits before cleanup is reported complete.
///
/// # Example
///
/// ```no_run
/// use open_net::{ws::WebSocketClient, Result};
///
/// async fn stop_background_client(client: &WebSocketClient) -> Result<()> {
/// let worker_client = client.clone();
/// // Complete the business sending and response waiting that need to be reserved before calling.
/// client.shutdown().await?;
/// println!("Worker shutdown requested: {}", worker_client.is_shutdown());
///
/// // Multiple components can also be cleaned separately; here they will be returned successfully.
/// worker_client.shutdown().await?;
/// Ok(())
/// }
/// ```
pub async fn shutdown(&self) -> Result<()> {
crate::log_s!(LogType::WSC; "shutdown");
self.inner.shutdown().await
}
}
impl fmt::Debug for WebSocketClient {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("WebSocketClient")
.field("id", &self.id())
.field("shutdown", &self.is_shutdown())
.finish()
}
}