pub struct MessageReceipt { /* private fields */ }Expand description
Shared receipt for a message operation; it can query state, request cancellation, or wait for the local write to complete.
Receipt clones observe the same operation, and dropping a receipt does not automatically cancel a submitted message. A successful local write does not mean that the peer received or processed it; use a request interface when an application response is required.
Implementations§
Source§impl MessageReceipt
impl MessageReceipt
Sourcepub fn retry_report(&self) -> RetryReport
pub fn retry_report(&self) -> RetryReport
Snapshot of the raw message operation’s attempts, transport writes and final stop reason. The report remains stable after completion and is shared by receipt clones.
Sourcepub fn id(&self) -> OperationId
pub fn id(&self) -> OperationId
Returns this message operation’s identifier, shared by receipt clones and retries of the operation.
§Use cases
Correlate application logs with the operation_id in task events, or index pending items
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
directly as an on-wire business request ID.
§Example
use open_net::{ws::Sender, Result};
async fn log_submission(sender: &Sender) -> Result<()> {
let receipt = sender.enqueue("report:ready").await?;
println!(
"Send operation {} for session {}",
receipt.id(),
receipt.session_id()
);
receipt.written().await
}Sourcepub fn session_id(&self) -> SessionId
pub fn session_id(&self) -> SessionId
Returns the logical session identifier that owns this message operation.
§Use cases
Use this value to route a send result back to the correct business session when receipts from several sessions are collected together. It does not change if the session later reconnects or ends, and it does not identify the physical connection used for this write.
§Example
use open_net::{ws::Sender, Result};
async fn check_receipt_owner(sender: &Sender) -> Result<()> {
let receipt = sender.enqueue("status:ready").await?;
println!(
"Receipt session: {}, sender session: {}",
receipt.session_id(),
sender.session_id(),
);
receipt.written().await
}Sourcepub fn state(&self) -> Result<OperationSnapshot>
pub fn state(&self) -> Result<OperationSnapshot>
Reads the current operation snapshot, including its phase, delivery evidence, and any determined final result.
§Use cases
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
point-in-time read and does not lock in later results. Use delivery as delivery evidence;
phase alone cannot establish that the peer received the message. Use Self::written
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.
§Example
use open_net::{ws::MessageReceipt, Result};
fn show_progress(receipt: &MessageReceipt) -> Result<()> {
let snapshot = receipt.state()?;
println!(
"Phase: {:?}; delivery evidence: {:?}",
snapshot.phase, snapshot.delivery
);
if let Some(result) = snapshot.result {
println!("Final result: {result:?}");
}
Ok(())
}Sourcepub fn cancel(&self) -> Result<TerminationOutcome>
pub fn cancel(&self) -> Result<TerminationOutcome>
Requests cancellation of this message operation and returns the actual outcome after racing with completion, failure, and other terminal states.
§Use cases
Any receipt clone can request cancellation when a user withdraws a pending send or its
business data expires. TerminationOutcome::TerminatedBeforeWrite means cancellation
took effect before business data was written. TerminationOutcome::DeliveryUnknown means the data may have reached the peer and cannot be retracted.
TerminationOutcome::AlreadyFinished means a terminal state already existed and this
request changed nothing. An Ok return by itself does not mean cancellation succeeded or
that transport or callback tasks have exited. An ordinary message is finished once its write succeeds, so later cancellation returns AlreadyFinished; the shared
TerminatedAfterWrite variant is for request operations waiting for a response and is not reached by ordinary messages.
§Example
use open_net::{
ws::{MessageReceipt, TerminationOutcome},
Result,
};
fn withdraw_message(receipt: &MessageReceipt) -> Result<()> {
match receipt.cancel()? {
TerminationOutcome::TerminatedBeforeWrite => println!("Canceled before writing"),
TerminationOutcome::DeliveryUnknown => {
println!("Delivery may have occurred; reconcile in the application")
}
TerminationOutcome::AlreadyFinished => println!("Operation had already finished"),
// Request-only variant of the shared enum; ordinary messages never wait for a response.
TerminationOutcome::TerminatedAfterWrite => {
println!("Terminated after confirmed write")
}
}
Ok(())
}Sourcepub async fn written(&self) -> Result<()>
pub async fn written(&self) -> Result<()>
Waits for this message’s local WebSocket write to complete, returning the corresponding error if the operation previously failed.
§Use cases
Suitable for confirming the local write in another task after enqueueing, then updating progress or advancing subsequent sends. Multiple receipt clones can wait concurrently, and an already completed result can be awaited repeatedly. This method does not wait for a server response or business processing, and it does not submit an uncommitted reservation.
Dropping the waiting future only stops this wait; it does not cancel the message. This
method has no separate timeout parameter. To bound the total time including queueing and
reconnection, configure SendOptions::deadline before submission. A write error may leave delivery uncertain; use the delivery evidence in Self::state to handle it.
§Example
use open_net::{ws::Sender, Result};
async fn publish_and_track(sender: &Sender) -> Result<()> {
let receipt = sender.enqueue("report:ready").await?;
let observer = receipt.clone();
receipt.written().await?;
observer.written().await?; // The successful result of the same operation can be read again.
println!("Operation {} finished local writing", observer.id());
Ok(())
}