open_net/api/ws/send.rs
1use super::{
2 dispatch, Message, OperationId, OperationSnapshot, SendOptions, SessionId, TerminationOutcome,
3};
4use crate::module::ws_client::{
5 operation_control::OperationControl, session_runtime::SessionRuntime,
6};
7use crate::{EnqueueError, Result};
8use std::fmt;
9use std::sync::Arc;
10use std::time::Instant;
11
12/// Entry point for sending messages, permanently bound to the session that created it; clones
13/// continue to share that session.
14///
15/// Obtain a sender from [`super::Session::sender`] and distribute it to multiple application
16/// tasks. The application must still retain the original [`super::Session`]: dropping the
17/// session cancels it, and retaining a sender cannot prevent shutdown. The sender remains
18/// usable after that session reconnects; a newly created session requires a new sender.
19///
20/// Use [`Self::send`] when only the local write result matters, [`Self::enqueue`] when the
21/// operation must be tracked or cancelled separately, and [`Self::try_enqueue`] when waiting
22/// for queue capacity is not possible. Configure per-message priority, deadlines, and related
23/// settings through [`Self::message`].
24#[derive(Clone)]
25pub struct Sender {
26 /// Shared runtime state, send queue, and operation manager for the owning session.
27 pub(crate) runtime: Arc<SessionRuntime>,
28}
29impl Sender {
30 /// Returns the logical session identifier to which this sender is bound.
31 ///
32 /// # Use cases
33 ///
34 /// Associate application logs and send receipts with the correct session when several sessions run in parallel. Cloning the sender or reconnecting the same session does not
35 /// change this identifier; it does not identify any particular physical connection.
36 ///
37 /// # Example
38 ///
39 /// ```no_run
40 /// use open_net::ws::Session;
41 ///
42 /// fn log_sender(session: &Session) {
43 /// let sender = session.sender();
44 /// println!(
45 /// "Sender session: {}, owner session: {}",
46 /// sender.session_id(),
47 /// session.id(),
48 /// );
49 /// }
50 /// ```
51 pub fn session_id(&self) -> SessionId {
52 self.runtime.id
53 }
54 /// Checks whether the owning session has been cancelled or terminated, or the client has requested shutdown.
55 ///
56 /// # Use cases
57 ///
58 /// Quickly decide whether to stop producing messages before constructing more work for a
59 /// finished session. A `false` result does not mean that the session is currently connected:
60 /// it may still be connecting or waiting to reconnect. Initiating a graceful session close
61 /// does not guarantee an immediate `true`; wait for the session close result to confirm that
62 /// it has ended. The session can still close between this check and a send, so always handle errors returned by the sending methods.
63 ///
64 /// # Example
65 ///
66 /// ```no_run
67 /// use open_net::{ws::Sender, Result};
68 ///
69 /// async fn publish_status(sender: &Sender) -> Result<()> {
70 /// if sender.is_closed() {
71 /// return Ok(()); // The session has ended; stop this status update.
72 /// }
73 /// sender.send("status:online").await?;
74 /// Ok(())
75 /// }
76 /// ```
77 pub fn is_closed(&self) -> bool {
78 self.runtime.is_closed()
79 }
80 /// Creates a builder holding the message body, initially using [`SendOptions::default`].
81 ///
82 /// This method only constructs the message; it does not reserve queue capacity or send it.
83 /// Strings become text messages, while byte slices, `Vec<u8>`, and similar values become binary messages. A [`Message`] can also be supplied explicitly.
84 ///
85 /// # Use cases
86 ///
87 /// When a message needs a custom priority, enqueue timeout, disconnection policy, or cancellation group, create a builder first, then configure it with
88 /// [`MessageBuilder::options`] and choose whether to send or reserve its resources.
89 ///
90 /// # Example
91 ///
92 /// ```no_run
93 /// use open_net::{
94 /// ws::{Priority, SendOptions, Sender},
95 /// Result,
96 /// };
97 /// use std::time::Duration;
98 ///
99 /// async fn publish_alert(sender: &Sender) -> Result<()> {
100 /// sender
101 /// .message("alert:temperature-high")
102 /// .options(SendOptions {
103 /// priority: Priority::High,
104 /// enqueue_timeout: Some(Duration::from_secs(1)),
105 /// ..Default::default()
106 /// })
107 /// .send()
108 /// .await
109 /// }
110 /// ```
111 pub fn message(&self, message: impl Into<Message>) -> MessageBuilder {
112 MessageBuilder {
113 sender: self.clone(),
114 message: message.into(),
115 options: SendOptions::default(),
116 admission_started: None,
117 }
118 }
119 /// Uses the default sending policy, waits for the message to be queued, and waits for the local WebSocket write to complete.
120 ///
121 /// Equivalent to `self.message(message).send().await`. By default, sending is rejected when
122 /// disconnected, capacity shortages are awaited without a separate enqueue timeout, and each write attempt has a 10-second limit with no retry. Success confirms only the local
123 /// write; it does not confirm that the server received or processed the message.
124 ///
125 /// # Use cases
126 ///
127 /// Suitable for simple sequential flows such as status notifications or chat messages, where the next step follows the local write. Errors such as disconnection, session
128 /// closure, or a write timeout are returned directly. This interface does not retain a failed message for retrieval; use [`Self::enqueue`] when enqueue failures must preserve
129 /// the message or the operation must be cancelled explicitly.
130 ///
131 /// # Example
132 ///
133 /// ```no_run
134 /// use open_net::error::ReceiveError;
135 /// use open_net::network::{NetworkConfig, NetworkStatusPolicy, TlsConfig};
136 /// use open_net::subscription::{CallbackContext, Subscription};
137 /// use open_net::ws::{
138 /// ConnectOptions, ConnectionEvent, ConnectionEventKind, ConnectionSnapshot, HeartbeatConfig,
139 /// IncomingMessage, Message, RetryDecision, TaskEvent, TaskEventOptions, TcpKeepaliveConfig,
140 /// WebSocketClientConfig,
141 /// };
142 /// use open_net::{HeaderValue, OpenNet, OpenNetConfig};
143 /// use open_net::tls::CryptoProvider;
144 /// use std::sync::Arc;
145 /// use std::thread;
146 /// use std::time::Duration;
147 ///
148 /// # const WS_BASE_URL: &str = "wss://example.com/api/ws";
149 /// # async fn example() -> open_net::Result<()> {
150 /// let provider: Arc<CryptoProvider> =
151 /// Arc::new(rustls_openssl::default_provider());
152 /// let network = NetworkConfig::default()
153 /// .with_network_status_policy(NetworkStatusPolicy::Ignore)
154 /// .with_tls(TlsConfig::default().with_crypto_provider(Arc::clone(&provider)));
155 /// let net = OpenNet::new_with_config(
156 /// OpenNetConfig::default()
157 /// .with_runtime_worker_threads(2)
158 /// .with_network_config(network.clone()),
159 /// )?;
160 /// let mut config = WebSocketClientConfig::default();
161 /// config.queues.normal.max_items = 128;
162 /// config.queues.urgent.max_items = 32;
163 /// config.requests.max_pending = 128;
164 /// config.frames.max_message_size = Some(8 * 1024 * 1024);
165 /// config.frames.data_frame_payload_size = Some(32 * 1024); // Large messages are framed automatically.
166 /// config.tcp.nodelay = true;
167 /// config.tcp.keepalive = Some(TcpKeepaliveConfig::default());
168 /// // The SDK handles Ping/Pong; the application does not need to emulate PB heartbeats with control frames.
169 /// config.heartbeat = Some(HeartbeatConfig {
170 /// interval: Duration::from_secs(20),
171 /// pong_timeout: Duration::from_secs(45),
172 /// ..HeartbeatConfig::default()
173 /// });
174 /// config.close_timeout = Duration::from_secs(2);
175 /// config.validate()?;
176 ///
177 /// // Explicitly override the client network configuration here; the default is direct access,
178 /// // and wss uses the default trusted root certificates.
179 /// // Other creation methods: net.create_ws_client(CLIENT_NAME).await?;
180 /// // net.create_ws_client_with_config(CLIENT_NAME, config).await?.
181 /// let client = net
182 /// .create_ws_client_with_network_config("ws_1_thread_name", config, network)
183 /// .await?;
184 /// let _shared = net.get_ws_client("ws_1_thread_name")?; // Like clone(), this points to the same client.
185 ///
186 /// let mut options = ConnectOptions::new(WS_BASE_URL);
187 /// options.headers.insert(
188 /// "authorization",
189 /// HeaderValue::from_static("Bearer example-token"),
190 /// );
191 /// options
192 /// .headers
193 /// .insert("x-client-name", HeaderValue::from_static("demo"));
194 ///
195 /// let current_thread = thread::current();
196 /// // A-thread_name: main, thread_id: ThreadId(1)
197 /// println!(
198 /// "A-thread_name: {}, thread_id: {:?}",
199 /// current_thread.name().map_or("unnamed", |name| name),
200 /// current_thread.id()
201 /// );
202 /// let mut session = client.connect(options).await?;
203 ///
204 /// // Keep subscription handles alive until the function returns; dropping a handle unsubscribes it.
205 /// let _state_subscription: Subscription = session.on_state(
206 /// |context: CallbackContext, state: open_net::Result<ConnectionSnapshot>| match state {
207 /// Ok(state) => {
208 /// let current_thread = thread::current();
209 /// // thread_name: open-net-ws-status-0, thread_id: ThreadId(18)
210 /// println!(
211 /// "State callback[{}]: {state:?}, thread_name: {}, thread_id: {:?}",
212 /// context.id(),
213 /// current_thread.name().map_or("unnamed", |name| name),
214 /// current_thread.id()
215 /// );
216 /// }
217 /// Err(error) => {
218 /// eprintln!("Failed to receive state[{}]: {error}", context.id())
219 /// }
220 /// },
221 /// )?;
222 ///
223 /// let callback_sender = session.sender();
224 /// let _message_subscription: Subscription = session.on_message(
225 /// move |context: CallbackContext, message: Result<IncomingMessage, ReceiveError>| {
226 /// match message {
227 /// Ok(message) => {
228 /// // thread_name: open-net-ws-data-callback, thread_id: ThreadId(20)
229 /// let current_thread = thread::current();
230 /// let kind = match message.message() {
231 /// Some(Message::Text(_)) => "text",
232 /// Some(Message::Binary(_)) => "binary",
233 /// None => "control",
234 /// };
235 /// // Log SDK identities and payload sizes; explicit body getters return original data.
236 /// println!(
237 /// "Message callback[{}]: client={} session={} connection={} kind={} message_bytes={:?}, thread_name: {}, thread_id: {:?}",
238 /// context.id(),
239 /// message.client_id(),
240 /// message.session_id(),
241 /// message.connection_id(),
242 /// kind,
243 /// message.message().map(Message::len),
244 /// current_thread.name().map_or("unnamed", |name| name),
245 /// current_thread.id()
246 /// );
247 /// }
248 /// Err(error) => {
249 /// println!("message_subscription->error: {}", error);
250 /// }
251 /// }
252 /// },
253 /// )?;
254 ///
255 /// let _event_subscription: Subscription = session.on_event(
256 /// |context: CallbackContext, event: Result<ConnectionEvent, ReceiveError>| match event {
257 /// Ok(event) => {
258 /// // thread_name: open-net-ws-events-1, thread_id: ThreadId(22)
259 /// let current_thread = thread::current();
260 /// println!(
261 /// "Connection event[{}] #{}: client={} session={} at={:?}, thread_name: {}, thread_id: {:?}",
262 /// context.id(),
263 /// event.sequence,
264 /// event.client_id,
265 /// event.session_id,
266 /// event.occurred_at,
267 /// current_thread.name().map_or("unnamed", |name| name),
268 /// current_thread.id());
269 /// // on_event records lifecycle events; observe immediate states such as network waits through on_state.
270 /// match event.kind {
271 /// ConnectionEventKind::AttemptStarted { attempt } => {
272 /// println!(
273 /// " Starting connection attempt: cycle={} attempt={} (initial connection or retry)",
274 /// attempt.cycle_id, attempt.attempt_id
275 /// );
276 /// }
277 /// ConnectionEventKind::Established { connection } => {
278 /// println!(
279 /// " Connection established: connection={} cycle={} attempt={} connected_at={:?}",
280 /// connection.connection_id,
281 /// connection.cycle_id,
282 /// connection.attempt_id,
283 /// connection.connected_at
284 /// );
285 /// }
286 /// ConnectionEventKind::AttemptFailed {
287 /// attempt,
288 /// error,
289 /// retry,
290 /// ..
291 /// } => {
292 /// eprintln!(
293 /// " Connection attempt failed: cycle={} attempt={} kind={:?} stage={:?} error={error}",
294 /// attempt.cycle_id,
295 /// attempt.attempt_id,
296 /// error.kind(),
297 /// error.context().stage
298 /// );
299 /// match retry {
300 /// RetryDecision::Scheduled { after } => {
301 /// println!(
302 /// " Retry scheduled: trying to connect again after a backoff of {} ms",
303 /// after.as_millis()
304 /// );
305 /// }
306 /// RetryDecision::Stop => {
307 /// println!(" Stopping retries; waiting for the session-closed event");
308 /// }
309 /// }
310 /// }
311 /// ConnectionEventKind::Disconnected { connection, end } => {
312 /// // A single connection can disconnect and still reconnect; Closed marks the end of the session.
313 /// println!(
314 /// " Connection disconnected: connection={} reason={:?} io_end={:?}",
315 /// connection.connection_id, end.reason, end.io_end
316 /// );
317 /// if let Some(close) = end.peer_close {
318 /// println!(
319 /// " Peer close information: code={:?} reason_len={}",
320 /// close.code, close.reason.len()
321 /// );
322 /// }
323 /// if let Some(error) = end.error {
324 /// eprintln!(" Disconnection error: kind={:?} error={error}", error.kind());
325 /// }
326 /// }
327 /// ConnectionEventKind::Closed { result } => match result {
328 /// Ok(end) => {
329 /// println!(" Session closed; will not reconnect: reason={:?}", end.reason);
330 /// if let Some(last) = end.last_connection {
331 /// println!(" Last connection end information: {last:?}");
332 /// }
333 /// }
334 /// Err(error) => {
335 /// eprintln!(
336 /// " Session ended unexpectedly; will not reconnect: kind={:?} error={error}",
337 /// error.kind()
338 /// );
339 /// }
340 /// },
341 /// // ConnectionEventKind is marked non_exhaustive to support future event variants.
342 /// other => println!(" Other connection event: {other:?}"),
343 /// }
344 /// }
345 /// Err(error) => eprintln!(" Failed to receive connection event[{}]: {error}", context.id()),
346 /// },
347 /// )?;
348 ///
349 /// let _task_subscription: Subscription = session.on_task(
350 /// TaskEventOptions::default(),
351 /// |context: CallbackContext, event: Result<TaskEvent, ReceiveError>| match event {
352 /// Ok(event) => {
353 /// // thread_name: open-net-task-events-1-0, thread_id: ThreadId(23)
354 /// let current_thread = thread::current();
355 /// // Phase, delivery evidence, cause, and result classify the operation without its original input.
356 /// let result = event.result.as_ref().map_err(|error| error.kind());
357 /// println!(
358 /// "Task callback[{}]: client={} session={} operation={} phase={:?} delivery={:?} cause={:?} result={:?}, thread_name: {}, thread_id: {:?}",
359 /// context.id(),
360 /// event.client_id,
361 /// event.session_id,
362 /// event.operation_id,
363 /// event.phase,
364 /// event.delivery,
365 /// event.cause,
366 /// result,
367 /// current_thread.name().map_or("unnamed", |name| name),
368 /// current_thread.id()
369 /// );
370 /// }
371 /// Err(error) => eprintln!("Failed to receive task event[{}]: {error}", context.id()),
372 /// },
373 /// )?;
374 ///
375 /// let sender = session.sender();
376 ///
377 /// // Omit the code for building the PB protocol
378 /// let message = Message::text("demo:message");
379 /// sender.send(message).await?;
380 ///
381 /// thread::sleep(Duration::from_secs(15));
382 ///
383 /// let shutdown = client.shutdown().await; // Permanently closes the client; no clone can reconnect.
384 /// let destroy = net.destroy_ws_client("ws_1_thread_name").await; // Also removes the registered name from the engine.
385 /// println!(
386 /// "Client closed={}, shutdown={shutdown:?}, destroy={destroy:?}",
387 /// client.is_shutdown()
388 /// );
389 /// shutdown?;
390 /// destroy?;
391 /// # Ok(())
392 /// # }
393 /// ```
394 pub async fn send(&self, message: impl Into<Message>) -> Result<()> {
395 self.message(message).send().await
396 }
397 /// Uses the default sending policy, waits for capacity, and returns a trackable receipt as soon as the message is submitted.
398 ///
399 /// Success means only that the message was enqueued; use [`MessageReceipt::written`] to wait for the local write. Capacity covers both the send queue and resources needed for
400 /// subscribed operation events, so a slow consumer can create backpressure. By default no
401 /// enqueue timeout is set and sending is rejected while disconnected; use [`Self::message`] to change these policies.
402 ///
403 /// # Use cases
404 ///
405 /// Suitable when production and completion tracking are separate: the producer continues after submission while another task retains the receipt to query status or cancel. A
406 /// failed [`EnqueueError`] retains the converted [`Message`]; use [`EnqueueError::into_parts`] to recover the body and decide whether to cache, discard, or resubmit it later.
407 ///
408 /// # Example
409 ///
410 /// ```no_run
411 /// use open_net::{
412 /// ws::{Message, MessageReceipt, Sender},
413 /// Result,
414 /// };
415 ///
416 /// async fn enqueue_report(
417 /// sender: &Sender,
418 /// pending: &mut Vec<MessageReceipt>,
419 /// unsent: &mut Vec<Message>,
420 /// ) -> Result<()> {
421 /// match sender.enqueue("report:ready").await {
422 /// Ok(receipt) => pending.push(receipt), // Wait for written() later as a group.
423 /// Err(failure) => {
424 /// let (message, error) = failure.into_parts();
425 /// unsent.push(message); // Preserve the body that was never enqueued.
426 /// return Err(error);
427 /// }
428 /// }
429 /// Ok(())
430 /// }
431 /// ```
432 pub async fn enqueue(
433 &self,
434 message: impl Into<Message>,
435 ) -> std::result::Result<MessageReceipt, EnqueueError<Message>> {
436 self.message(message).enqueue().await.map_err(|error| {
437 let (builder, error) = error.into_parts();
438 EnqueueError::new(builder.message, error)
439 })
440 }
441 /// Attempts to enqueue immediately with the default sending policy, without waiting for capacity or write completion.
442 ///
443 /// Returns [`crate::error::ErrorKind::QueueFull`] when queue or operation-event resources are temporarily exhausted. It can also fail because the client is disconnected, the
444 /// session is closed, the message is too large, or for other reasons. The converted message
445 /// is retained on failure. This synchronous entry point does not require the calling thread to enter a Tokio runtime, but the client worker tasks must remain alive.
446 ///
447 /// # Use cases
448 ///
449 /// Suitable for UI events, synchronous callbacks, and collection paths that cannot wait for
450 /// backpressure. The application can cache or coalesce messages when the queue is full; do not treat every error as queue-full and retry unconditionally.
451 ///
452 /// # Example
453 ///
454 /// ```no_run
455 /// use open_net::{error::ErrorKind, ws::{Message, MessageReceipt, Sender}, Result};
456 ///
457 /// fn submit_sample(
458 /// sender: &Sender,
459 /// backlog: &mut Vec<Message>,
460 /// ) -> Result<Option<MessageReceipt>> {
461 /// match sender.try_enqueue("temperature:24") {
462 /// Ok(receipt) => Ok(Some(receipt)),
463 /// Err(failure) if failure.error().kind() == ErrorKind::QueueFull => {
464 /// backlog.push(failure.into_inner()); // The application controls cache bounds and retry timing.
465 /// Ok(None)
466 /// }
467 /// Err(failure) => Err(failure.into_error()),
468 /// }
469 /// }
470 /// ```
471 pub fn try_enqueue(
472 &self,
473 message: impl Into<Message>,
474 ) -> std::result::Result<MessageReceipt, EnqueueError<Message>> {
475 self.message(message).try_enqueue().map_err(|error| {
476 let (builder, error) = error.into_parts();
477 EnqueueError::new(builder.message, error)
478 })
479 }
480}
481impl fmt::Debug for Sender {
482 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
483 f.debug_struct("Sender")
484 .field("session_id", &self.session_id())
485 .field("closed", &self.is_closed())
486 .finish()
487 }
488}
489
490/// Holds a message and its sending options; both can be recovered from an enqueue error.
491///
492/// The builder does not send by itself; resources are requested only when a send, enqueue, or
493/// prepare method is called. Dropping an unused builder only drops the message body.
494#[must_use]
495#[derive(Debug)]
496pub struct MessageBuilder {
497 /// Sending entry point for the session that owns the message.
498 sender: Sender,
499 /// Message content held by this builder until submission.
500 message: Message,
501 /// Queue, priority, timeout, and cancellation policies for this send.
502 options: SendOptions,
503 /// Time of the first enqueue admission attempt; `None` before admission or after options are reset.
504 admission_started: Option<Instant>,
505}
506impl MessageBuilder {
507 /// Replaces all sending options for this message and resets the enqueue-wait start time.
508 ///
509 /// This method only stores the options; validity is checked when resources are actually requested. Calling it again replaces every previous setting rather than merging fields.
510 /// An absolute `deadline` supplied in the options is not moved forward automatically.
511 ///
512 /// # Use cases
513 ///
514 /// Set a priority, timeout, cancellation group, or disconnect-wait policy for one message
515 /// without affecting other messages. After recovering a builder from an enqueue error, call this again only when the application intentionally needs a new enqueue-wait budget.
516 /// `WaitForReconnect` lets an unsent message wait for a connection, but does not enable the session's reconnection policy by itself.
517 ///
518 /// # Example
519 ///
520 /// ```no_run
521 /// use open_net::{
522 /// ws::{DisconnectedPolicy, SendOptions, Sender},
523 /// Result,
524 /// };
525 /// use std::time::{Duration, Instant};
526 ///
527 /// async fn publish_latest_state(sender: &Sender) -> Result<()> {
528 /// sender
529 /// .message("state:active")
530 /// .options(SendOptions {
531 /// disconnected: DisconnectedPolicy::WaitForReconnect,
532 /// enqueue_timeout: Some(Duration::from_secs(2)),
533 /// deadline: Some(Instant::now() + Duration::from_secs(15)),
534 /// ..Default::default()
535 /// })
536 /// .send()
537 /// .await
538 /// }
539 /// ```
540 pub fn options(mut self, options: SendOptions) -> Self {
541 self.options = options;
542 self.admission_started = None;
543 self
544 }
545 /// Enqueues the message according to the configured policy and waits for its local WebSocket write to complete.
546 ///
547 /// # Use cases
548 ///
549 /// Suitable for sequential workflows that customize one message but do not need to manage a
550 /// receipt separately. Enqueue and write failures are returned as [`crate::NetError`]; the builder and message are not returned with the error. Success does not mean that the
551 /// server processed the message; use the session request interface when a protocol response is required.
552 ///
553 /// Once the message has been submitted, dropping this method's waiting future does not retract the send. To cancel explicitly, configure a cancellation group or use
554 /// [`Self::enqueue`] to obtain a receipt and then call [`MessageReceipt::cancel`].
555 ///
556 /// # Example
557 ///
558 /// ```no_run
559 /// use open_net::{
560 /// ws::{SendOptions, Sender},
561 /// Result,
562 /// };
563 /// use std::time::{Duration, Instant};
564 ///
565 /// async fn publish_with_deadline(sender: &Sender) -> Result<()> {
566 /// sender
567 /// .message("status:ready")
568 /// .options(SendOptions {
569 /// deadline: Some(Instant::now() + Duration::from_secs(5)),
570 /// ..Default::default()
571 /// })
572 /// .send()
573 /// .await?;
574 /// Ok(())
575 /// }
576 /// ```
577 pub async fn send(self) -> Result<()> {
578 self.enqueue()
579 .await
580 .map_err(EnqueueError::into_error)?
581 .written()
582 .await
583 }
584 /// Waits for resources according to the configured policy, submits the message, and returns a receipt without waiting for the write to complete.
585 ///
586 /// When capacity is unavailable, waits asynchronously subject to `enqueue_timeout`, the
587 /// overall `deadline`, cancellation, and session state. A failed [`EnqueueError`] retains the
588 /// complete builder, including the message, options, and the start time of the first resource
589 /// attempt; retrying that builder directly does not restore a full enqueue-timeout budget.
590 ///
591 /// # Use cases
592 ///
593 /// Suitable when a send needs a custom priority or deadline while another task tracks the
594 /// write. Use [`Self::prepare`] when resources should be reserved first and sending should be allowed only after local business state has been recorded.
595 ///
596 /// # Example
597 ///
598 /// ```no_run
599 /// use open_net::{
600 /// ws::{MessageReceipt, Priority, SendOptions, Sender},
601 /// Result,
602 /// };
603 /// use std::time::Duration;
604 ///
605 /// async fn queue_alert(sender: &Sender) -> Result<MessageReceipt> {
606 /// let receipt = sender
607 /// .message("alert:disk-low")
608 /// .options(SendOptions {
609 /// priority: Priority::High,
610 /// enqueue_timeout: Some(Duration::from_millis(500)),
611 /// ..Default::default()
612 /// })
613 /// .enqueue()
614 /// .await?;
615 /// println!("Enqueued operation: {}", receipt.id());
616 /// Ok(receipt) // The caller can await receipt.written() later.
617 /// }
618 /// ```
619 pub async fn enqueue(mut self) -> std::result::Result<MessageReceipt, EnqueueError<Self>> {
620 match self.admit(true).await.and_then(PreparedMessage::commit) {
621 Ok(receipt) => Ok(receipt),
622 Err(error) => Err(EnqueueError::new(self, error)),
623 }
624 }
625 /// Attempts to enqueue immediately under the configured policy, without waiting for send resources.
626 ///
627 /// Unlike [`Self::enqueue`], returns [`crate::error::ErrorKind::QueueFull`] immediately when
628 /// resources are unavailable; all other validation, cancellation, and deadline rules still apply. Failure retains the complete builder and the initial enqueue timestamp, so
629 /// asynchronous enqueue can continue waiting. This method does not require the calling thread to enter a Tokio runtime.
630 ///
631 /// # Use cases
632 ///
633 /// Suitable for paths that try a fast submission first and, on backpressure, either wait or
634 /// hand the work to an application scheduler. Retrying the recovered builder preserves its priority and other settings; the message need not be reconstructed.
635 ///
636 /// # Example
637 ///
638 /// ```no_run
639 /// use open_net::{error::ErrorKind, ws::{SendOptions, Sender}, Result};
640 /// use std::time::Duration;
641 ///
642 /// async fn submit_or_wait(sender: &Sender) -> Result<()> {
643 /// let builder = sender.message("report:ready").options(SendOptions {
644 /// enqueue_timeout: Some(Duration::from_secs(1)), ..Default::default()
645 /// });
646 /// let receipt = match builder.try_enqueue() {
647 /// Ok(receipt) => receipt,
648 /// Err(failure) if failure.error().kind() == ErrorKind::QueueFull => {
649 /// // Continue the original one-second enqueue budget instead of resetting it on every retry.
650 /// failure.into_inner().enqueue().await?
651 /// }
652 /// Err(failure) => return Err(failure.into_error()),
653 /// };
654 /// receipt.written().await
655 /// }
656 /// ```
657 pub fn try_enqueue(mut self) -> std::result::Result<MessageReceipt, EnqueueError<Self>> {
658 match self.try_admit().and_then(PreparedMessage::commit) {
659 Ok(receipt) => Ok(receipt),
660 Err(error) => Err(EnqueueError::new(self, error)),
661 }
662 }
663 /// Waits for and reserves send resources, returning a message that has not yet been submitted to the writer.
664 ///
665 /// Uses the same resource-wait, timeout, and cancellation policies as [`Self::enqueue`], but
666 /// requires a subsequent call to [`PreparedMessage::commit`] to send. On failure, the complete
667 /// builder can be recovered. On success, a receipt can be obtained first; dropping the [`PreparedMessage`] directly cancels the operation and releases the reserved resources.
668 ///
669 /// # Use cases
670 ///
671 /// Suitable for recording local tracking state by operation ID or performing a final business-condition check before the message can be written. The reservation consumes
672 /// capacity, so commit or drop it promptly. The overall deadline and cancellation remain active; a successful reservation therefore does not guarantee that a later commit will
673 /// succeed. `enqueue_timeout` limits only the wait to acquire resources, not the interval between a successful reservation and commit.
674 ///
675 /// # Example
676 ///
677 /// ```no_run
678 /// use open_net::{ws::Sender, Result};
679 ///
680 /// async fn publish_if_needed(sender: &Sender, still_needed: bool) -> Result<()> {
681 /// let prepared = sender.message("refresh:inventory").prepare().await?;
682 /// println!(
683 /// "Registered operation before sending: {}",
684 /// prepared.receipt().id()
685 /// );
686 /// if !still_needed {
687 /// drop(prepared); // It was not submitted, so this message will not be written.
688 /// return Ok(());
689 /// }
690 /// let receipt = prepared.commit()?;
691 /// receipt.written().await
692 /// }
693 /// ```
694 pub async fn prepare(mut self) -> std::result::Result<PreparedMessage, EnqueueError<Self>> {
695 match self.admit(true).await {
696 Ok(prepared) => Ok(prepared),
697 Err(error) => Err(EnqueueError::new(self, error)),
698 }
699 }
700 /// Attempts to reserve send resources immediately, without waiting for capacity or submitting the message.
701 ///
702 /// Returns [`crate::error::ErrorKind::QueueFull`] when resources are unavailable; all other validation, cancellation, and deadline rules are the same as for [`Self::prepare`].
703 /// Failure retains the complete builder and its original admission timestamp. After success,
704 /// call [`PreparedMessage::commit`] or drop the reservation to cancel the operation. This synchronous method does not require the calling thread to enter a Tokio runtime.
705 ///
706 /// # Use cases
707 ///
708 /// Suitable for optional reporting from a synchronous callback: record and submit only when
709 /// resources are immediately available, otherwise skip this report. A failed builder can also be handed to an application scheduler for retry when resources become available.
710 ///
711 /// # Example
712 ///
713 /// ```no_run
714 /// use open_net::{
715 /// error::ErrorKind,
716 /// ws::{MessageReceipt, Sender},
717 /// Result,
718 /// };
719 ///
720 /// fn submit_optional_report(sender: &Sender) -> Result<Option<MessageReceipt>> {
721 /// let prepared = match sender.message("metrics:snapshot").try_prepare() {
722 /// Ok(prepared) => prepared,
723 /// Err(failure) if failure.error().kind() == ErrorKind::QueueFull => {
724 /// return Ok(None); // This sample may be skipped without blocking the callback.
725 /// }
726 /// Err(failure) => return Err(failure.into_error()),
727 /// };
728 /// println!(
729 /// "Registered operation before commit: {}",
730 /// prepared.receipt().id()
731 /// );
732 /// Ok(Some(prepared.commit()?))
733 /// }
734 /// ```
735 pub fn try_prepare(mut self) -> std::result::Result<PreparedMessage, EnqueueError<Self>> {
736 match self.try_admit() {
737 Ok(prepared) => Ok(prepared),
738 Err(error) => Err(EnqueueError::new(self, error)),
739 }
740 }
741 async fn admit(&mut self, wait: bool) -> Result<PreparedMessage> {
742 let started = *self.admission_started.get_or_insert_with(Instant::now);
743 let admission = dispatch::prepare(
744 &self.sender.runtime,
745 &self.message,
746 &self.options,
747 started,
748 None,
749 wait,
750 )
751 .await?;
752 Ok(PreparedMessage::new(admission))
753 }
754 fn try_admit(&mut self) -> Result<PreparedMessage> {
755 let started = *self.admission_started.get_or_insert_with(Instant::now);
756 let admission = dispatch::try_prepare(
757 &self.sender.runtime,
758 &self.message,
759 &self.options,
760 started,
761 None,
762 )?;
763 Ok(PreparedMessage::new(admission))
764 }
765}
766
767/// Shared receipt for a message operation; it can query state, request cancellation, or wait for
768/// the local write to complete.
769///
770/// Receipt clones observe the same operation, and dropping a receipt does not automatically cancel
771/// a submitted message. A successful local write does not mean that the peer received or processed
772/// it; use a request interface when an application response is required.
773#[must_use]
774#[derive(Clone)]
775pub struct MessageReceipt {
776 /// Message operation observed and controlled by all clones of its receipt.
777 core: Arc<OperationControl>,
778}
779impl MessageReceipt {
780 /// Returns the `WsMessage` diagnostic reference for this local message operation.
781 ///
782 /// The SDK allocates the observation during message admission and binds it to
783 /// the operation shared by receipt clones. It can include admission, queue,
784 /// local write, and retry observations. Successful local writing is not proof
785 /// of peer receipt or application processing, and this report does not invent
786 /// an application response boundary for a raw message.
787 ///
788 /// `None` means no report was allocated, for example because collection was
789 /// Off/dormant, WebSocket was excluded, the owner was unavailable, or a
790 /// diagnostic budget prevented collection. Reading it does not activate
791 /// diagnostics or wait for delivery. Use the owning engine's
792 /// `QualityDoctor::lookup` to inspect retained evidence; the reference does
793 /// not pin history or guarantee that every observation was retained.
794 #[cfg(feature = "quality-doctor")]
795 pub fn quality_ref(&self) -> Option<crate::api::quality::QualityReportRef> {
796 self.core.quality_ref()
797 }
798 /// Snapshot of the raw message operation's attempts, transport writes and final stop reason.
799 /// The report remains stable after completion and is shared by receipt clones.
800 pub fn retry_report(&self) -> crate::api::retry::RetryReport {
801 self.core.retry_report()
802 }
803
804 /// Returns this message operation's identifier, shared by receipt clones and retries of the operation.
805 ///
806 /// # Use cases
807 ///
808 /// Correlate application logs with the `operation_id` in task events, or index pending items
809 /// in a user interface. Operation IDs are allocated within their session; records spanning sessions should also retain the session and client identities. Do not use this value
810 /// directly as an on-wire business request ID.
811 ///
812 /// # Example
813 ///
814 /// ```no_run
815 /// use open_net::{ws::Sender, Result};
816 ///
817 /// async fn log_submission(sender: &Sender) -> Result<()> {
818 /// let receipt = sender.enqueue("report:ready").await?;
819 /// println!(
820 /// "Send operation {} for session {}",
821 /// receipt.id(),
822 /// receipt.session_id()
823 /// );
824 /// receipt.written().await
825 /// }
826 /// ```
827 pub fn id(&self) -> OperationId {
828 self.core.id()
829 }
830 /// Returns the logical session identifier that owns this message operation.
831 ///
832 /// # Use cases
833 ///
834 /// Use this value to route a send result back to the correct business session when receipts
835 /// from several sessions are collected together. It does not change if the session later
836 /// reconnects or ends, and it does not identify the physical connection used for this write.
837 ///
838 /// # Example
839 ///
840 /// ```no_run
841 /// use open_net::{ws::Sender, Result};
842 ///
843 /// async fn check_receipt_owner(sender: &Sender) -> Result<()> {
844 /// let receipt = sender.enqueue("status:ready").await?;
845 /// println!(
846 /// "Receipt session: {}, sender session: {}",
847 /// receipt.session_id(),
848 /// sender.session_id(),
849 /// );
850 /// receipt.written().await
851 /// }
852 /// ```
853 pub fn session_id(&self) -> SessionId {
854 self.core.session_id()
855 }
856 /// Reads the current operation snapshot, including its phase, delivery evidence, and any determined final result.
857 ///
858 /// # Use cases
859 ///
860 /// Useful for displaying progress such as “queued”, “writing”, or “finished”, or for diagnosing whether a failed message may already have been written. A snapshot is only a
861 /// point-in-time read and does not lock in later results. Use `delivery` as delivery evidence;
862 /// `phase` alone cannot establish that the peer received the message. Use [`Self::written`]
863 /// when completion must be awaited. The outer `Result` reports whether the read succeeded; the operation's own outcome is stored in the snapshot's `result`.
864 ///
865 /// # Example
866 ///
867 /// ```no_run
868 /// use open_net::{ws::MessageReceipt, Result};
869 ///
870 /// fn show_progress(receipt: &MessageReceipt) -> Result<()> {
871 /// let snapshot = receipt.state()?;
872 /// println!(
873 /// "Phase: {:?}; delivery evidence: {:?}",
874 /// snapshot.phase, snapshot.delivery
875 /// );
876 /// if let Some(result) = snapshot.result {
877 /// println!("Final result: {result:?}");
878 /// }
879 /// Ok(())
880 /// }
881 /// ```
882 pub fn state(&self) -> Result<OperationSnapshot> {
883 self.core.snapshot()
884 }
885 /// Requests cancellation of this message operation and returns the actual outcome after racing with completion, failure, and other terminal states.
886 ///
887 /// # Use cases
888 ///
889 /// Any receipt clone can request cancellation when a user withdraws a pending send or its
890 /// business data expires. [`TerminationOutcome::TerminatedBeforeWrite`] means cancellation
891 /// took effect before business data was written. [`TerminationOutcome::DeliveryUnknown`] means the data may have reached the peer and cannot be retracted.
892 /// [`TerminationOutcome::AlreadyFinished`] means a terminal state already existed and this
893 /// request changed nothing. An `Ok` return by itself does not mean cancellation succeeded or
894 /// that transport or callback tasks have exited. An ordinary message is finished once its write succeeds, so later cancellation returns `AlreadyFinished`; the shared
895 /// `TerminatedAfterWrite` variant is for request operations waiting for a response and is not reached by ordinary messages.
896 ///
897 /// # Example
898 ///
899 /// ```no_run
900 /// use open_net::{
901 /// ws::{MessageReceipt, TerminationOutcome},
902 /// Result,
903 /// };
904 ///
905 /// fn withdraw_message(receipt: &MessageReceipt) -> Result<()> {
906 /// match receipt.cancel()? {
907 /// TerminationOutcome::TerminatedBeforeWrite => println!("Canceled before writing"),
908 /// TerminationOutcome::DeliveryUnknown => {
909 /// println!("Delivery may have occurred; reconcile in the application")
910 /// }
911 /// TerminationOutcome::AlreadyFinished => println!("Operation had already finished"),
912 /// // Request-only variant of the shared enum; ordinary messages never wait for a response.
913 /// TerminationOutcome::TerminatedAfterWrite => {
914 /// println!("Terminated after confirmed write")
915 /// }
916 /// }
917 /// Ok(())
918 /// }
919 /// ```
920 pub fn cancel(&self) -> Result<TerminationOutcome> {
921 self.core.cancel()
922 }
923 /// Waits for this message's local WebSocket write to complete, returning the corresponding error if the operation previously failed.
924 ///
925 /// # Use cases
926 ///
927 /// Suitable for confirming the local write in another task after enqueueing, then updating
928 /// progress or advancing subsequent sends. Multiple receipt clones can wait concurrently,
929 /// and an already completed result can be awaited repeatedly. This method does not wait for
930 /// a server response or business processing, and it does not submit an uncommitted reservation.
931 ///
932 /// Dropping the waiting future only stops this wait; it does not cancel the message. This
933 /// method has no separate timeout parameter. To bound the total time including queueing and
934 /// reconnection, configure `SendOptions::deadline` before submission. A write error may leave delivery uncertain; use the delivery evidence in [`Self::state`] to handle it.
935 ///
936 /// # Example
937 ///
938 /// ```no_run
939 /// use open_net::{ws::Sender, Result};
940 ///
941 /// async fn publish_and_track(sender: &Sender) -> Result<()> {
942 /// let receipt = sender.enqueue("report:ready").await?;
943 /// let observer = receipt.clone();
944 /// receipt.written().await?;
945 /// observer.written().await?; // The successful result of the same operation can be read again.
946 /// println!("Operation {} finished local writing", observer.id());
947 /// Ok(())
948 /// }
949 /// ```
950 pub async fn written(&self) -> Result<()> {
951 self.core.written().await.map(|_| ())
952 }
953}
954impl fmt::Debug for MessageReceipt {
955 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
956 f.debug_struct("MessageReceipt")
957 .field("id", &self.id())
958 .field("session_id", &self.session_id())
959 .field("state", &self.state())
960 .finish()
961 }
962}
963
964/// Message with send resources reserved but not yet submitted; dropping it directly cancels the
965/// operation.
966///
967/// Created by [`MessageBuilder::prepare`] or [`MessageBuilder::try_prepare`]. The reservation
968/// consumes send capacity; call [`Self::commit`] promptly after recording local state, or drop it
969/// directly when the application abandons the send. Cancellation, session termination, or the
970/// overall deadline can invalidate the reservation.
971#[must_use]
972pub struct PreparedMessage {
973 /// Manages the queue reservation and cancellation cleanup while it is unsubmitted.
974 admission: dispatch::Admission,
975 /// Receipt used to observe the same message operation before and after submission.
976 receipt: MessageReceipt,
977}
978impl PreparedMessage {
979 fn new(admission: dispatch::Admission) -> Self {
980 let receipt = MessageReceipt {
981 core: admission.control.clone(),
982 };
983 Self { admission, receipt }
984 }
985 /// Borrows the reserved message's receipt, which can query its ID, observe state, or request cancellation before submission.
986 ///
987 /// # Use cases
988 ///
989 /// Clone the receipt into a local tracking table or pass it to another observer before the
990 /// message can be written. It refers to the same operation before and after submission; a
991 /// receipt clone neither submits the message nor extends the reservation's lifetime. If the
992 /// reservation is dropped, retained receipts observe its cancellation or existing terminal state.
993 ///
994 /// # Example
995 ///
996 /// ```no_run
997 /// use open_net::{ws::Sender, Result};
998 ///
999 /// async fn observe_before_commit(sender: &Sender) -> Result<()> {
1000 /// let prepared = sender.message("report:ready").prepare().await?;
1001 /// let observer = prepared.receipt().clone();
1002 /// println!("Operation ID before commit: {}", observer.id());
1003 /// let committed = prepared.commit()?;
1004 /// println!("Operation ID after commit: {}", committed.id());
1005 /// observer.written().await
1006 /// }
1007 /// ```
1008 pub fn receipt(&self) -> &MessageReceipt {
1009 &self.receipt
1010 }
1011 /// Consumes the reservation, submits the message to the send queue, and returns a receipt for the same operation.
1012 ///
1013 /// This method completes synchronously: it does not wait for capacity or a network write and
1014 /// does not require the calling thread to enter a Tokio runtime. The operation is still checked for validity at submission; cancellation, closure, or expiration of the overall
1015 /// deadline can cause failure. Failure returns only [`crate::NetError`]; the reservation and message body are not returned.
1016 ///
1017 /// # Use cases
1018 ///
1019 /// Use after local tracking has been recorded and business conditions have been confirmed,
1020 /// allowing the reserved message to enter send scheduling. Success means submission only;
1021 /// wait for [`MessageReceipt::written`] to confirm the local write. Consuming `self` ensures
1022 /// that one reservation can be submitted only once; this does not provide exactly-once processing by the server.
1023 ///
1024 /// # Example
1025 ///
1026 /// ```no_run
1027 /// use open_net::{ws::{MessageReceipt, OperationId, Sender}, Result};
1028 /// use std::collections::HashMap;
1029 ///
1030 /// fn register_and_commit(
1031 /// sender: &Sender,
1032 /// pending: &mut HashMap<OperationId, MessageReceipt>, // This table serves the current session only.
1033 /// ) -> Result<MessageReceipt> {
1034 /// let prepared = sender.message("refresh:inventory").try_prepare()?;
1035 /// let id = prepared.receipt().id();
1036 /// pending.insert(id, prepared.receipt().clone());
1037 /// match prepared.commit() {
1038 /// Ok(receipt) => Ok(receipt),
1039 /// Err(error) => {
1040 /// pending.remove(&id); // Submission failed; remove the local record registered earlier.
1041 /// Err(error)
1042 /// }
1043 /// }
1044 /// }
1045 /// ```
1046 pub fn commit(mut self) -> Result<MessageReceipt> {
1047 self.admission.commit()?;
1048 Ok(self.receipt.clone())
1049 }
1050}
1051impl fmt::Debug for PreparedMessage {
1052 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1053 f.debug_struct("PreparedMessage")
1054 .field("receipt", &self.receipt)
1055 .finish()
1056 }
1057}