Skip to main content

open_net/api/ws/
operation.rs

1use crate::Result;
2
3/// Point-in-time snapshot of a send or request operation.
4///
5/// Processing phase and delivery evidence describe different facts. An operation with an
6/// uncertain write may be requeued, and a final failure does not prove that the peer saw no data.
7///
8/// SDK snapshots carry a result only in [`OperationPhase::Finished`]. Reading a snapshot does not
9/// win termination races; completion, cancellation, and expiry still compete for one terminal state.
10#[derive(Clone, Debug)]
11pub struct OperationSnapshot {
12    /// Current processing phase, independent of peer receipt.
13    pub phase: OperationPhase,
14    /// Strongest confirmed delivery evidence across all write attempts.
15    pub delivery: DeliveryEvidence,
16    /// Final success or error; `None` for an unfinished SDK snapshot.
17    pub result: Option<Result<TaskSuccess>>,
18}
19
20/// Current operation phase; does not itself prove peer delivery.
21#[derive(Clone, Copy, Debug, Eq, PartialEq)]
22pub enum OperationPhase {
23    /// Waiting for bounded send capacity or event capacity.
24    WaitingForCapacity,
25    /// Capacity is reserved; submission is required before writing can begin.
26    Prepared,
27    /// Submitted and queued for writing, including requeued retries.
28    Queued,
29    /// Writer is processing; this phase alone proves no bytes were sent.
30    Writing,
31    /// A tracked request is waiting for its final protocol response.
32    AwaitingResponse,
33    /// A success or failure has become the operation's sole terminal result.
34    Finished,
35}
36
37/// Strongest delivery evidence confirmed across write attempts.
38#[derive(Clone, Copy, Debug, Eq, PartialEq)]
39pub enum DeliveryEvidence {
40    /// No attempt has started writing business data to the transport.
41    NotStarted,
42    /// Data may have reached the peer, but delivery is unconfirmed.
43    ///
44    /// Retries do not reset this to `NotStarted`; retrying a non-idempotent operation may be unsafe.
45    Unknown,
46    /// Local WebSocket write completed, without peer-response confirmation.
47    Written,
48    /// A matching final response confirms delivery, possibly before local flush completion.
49    ResponseConfirmed,
50}
51
52/// Successful terminal result category.
53#[derive(Clone, Copy, Debug, Eq, PartialEq)]
54pub enum TaskSuccess {
55    /// An untracked message completed local WebSocket writing.
56    Written,
57    /// A tracked request received its matching final protocol response.
58    ///
59    /// Correlation succeeded; this does not mean the peer accepted the business request.
60    ResponseReceived,
61}
62
63/// Result of racing cancellation or expiry against operation completion.
64///
65/// Describes the effective termination decision rather than an earlier snapshot. Transport and
66/// callback tasks may still be shutting down when the terminating call returns.
67#[derive(Clone, Copy, Debug, Eq, PartialEq)]
68pub enum TerminationOutcome {
69    /// Termination won before any business data could be written.
70    TerminatedBeforeWrite,
71    /// Writing was confirmed and termination won while awaiting a response.
72    TerminatedAfterWrite,
73    /// Termination won, but operation data may have reached the peer.
74    DeliveryUnknown,
75    /// Another terminal result already won; this call changes nothing.
76    AlreadyFinished,
77}
78
79/// Delivery evidence that ends a request's write wait.
80#[derive(Clone, Copy, Debug, Eq, PartialEq)]
81pub enum WriteOutcome {
82    /// Local WebSocket writing completed.
83    Written,
84    /// A matching final response confirmed delivery before local writing completed.
85    ///
86    /// A later flush failure cannot overturn the successful response, but the failed physical
87    /// connection must still terminate.
88    ResponseConfirmed,
89}