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}