Skip to main content

MessageReceipt

Struct MessageReceipt 

Source
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

Source

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.

Source

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
}
Source

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
}
Source

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(())
}
Source

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(())
}
Source

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(())
}

Trait Implementations§

Source§

impl Clone for MessageReceipt

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for MessageReceipt

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more