Skip to main content

open_net/api/ws/
task.rs

1use super::{
2    ClientId, ConnectionId, DeliveryEvidence, Message, MessageLane, OperationId, OperationPhase,
3    Request, SessionId, TaskSuccess,
4};
5use crate::{error::ErrorKind, NetError, Result};
6use std::sync::Arc;
7
8/// Terminal event emitted for an admitted message or request operation.
9#[derive(Clone, Debug)]
10pub struct TaskEvent {
11    /// Client that owns the operation.
12    pub client_id: ClientId,
13    /// Logical session that owns the operation.
14    pub session_id: SessionId,
15    /// Identifier of this send or request operation.
16    pub operation_id: OperationId,
17    /// Physical connection associated with the operation, if one was bound.
18    pub connection_id: Option<ConnectionId>,
19    /// Original message or request shared with observers.
20    pub source: TaskSource,
21    /// Send lane used by the operation.
22    pub lane: MessageLane,
23    /// Processing phase immediately before the terminal result became effective.
24    pub phase: OperationPhase,
25    /// Strongest delivery evidence known when the operation ended.
26    pub delivery: DeliveryEvidence,
27    /// Cause that ended the operation.
28    pub cause: TaskEndCause,
29    /// The single effective success or error result; success does not imply business acceptance by the peer.
30    pub result: Result<TaskSuccess>,
31}
32
33/// Original task input shared by cloned events without copying the payload.
34#[derive(Clone)]
35pub enum TaskSource {
36    /// Metadata for a logical request whose wire payload is generated per attempt.
37    /// The factory and idempotency key are deliberately excluded.
38    RequestOperation(Arc<crate::Metadata>),
39    /// A message send that has no response tracking.
40    Message(
41        /// Original message shared by the task and observers.
42        Arc<Message>,
43    ),
44    /// A request whose business response is tracked.
45    Request(
46        /// Original request and metadata shared by the task and observers.
47        Arc<Request>,
48    ),
49}
50
51impl std::fmt::Debug for TaskSource {
52    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
53        match self {
54            Self::Message(message) => f.debug_tuple("Message").field(message).finish(),
55            Self::Request(request) => f.debug_tuple("Request").field(request).finish(),
56            Self::RequestOperation(metadata) => f
57                .debug_struct("RequestOperation")
58                .field("metadata_entries", &metadata.len())
59                .finish(),
60        }
61    }
62}
63
64impl TaskSource {
65    /// Counts the owned variable-size input once for the shared payload budget.
66    pub(crate) fn payload_bytes(&self) -> Result<usize> {
67        match self {
68            Self::RequestOperation(metadata) => {
69                metadata.iter().try_fold(0usize, |bytes, (key, value)| {
70                    bytes
71                        .checked_add(key.len())
72                        .and_then(|size| size.checked_add(value.len()))
73                        .ok_or_else(|| NetError::from(ErrorKind::ItemTooLarge))
74                })
75            }
76            Self::Message(message) => Ok(message.len()),
77            Self::Request(request) => {
78                let mut bytes = request
79                    .message()
80                    .len()
81                    .checked_add(request.id().as_str().len())
82                    .ok_or_else(|| NetError::from(ErrorKind::ItemTooLarge))?;
83                for (key, value) in request.metadata() {
84                    bytes = bytes
85                        .checked_add(key.len())
86                        .and_then(|size| size.checked_add(value.len()))
87                        .ok_or_else(|| NetError::from(ErrorKind::ItemTooLarge))?;
88                }
89                Ok(bytes)
90            }
91        }
92    }
93}
94
95/// Reason why a message or request reached its terminal state.
96#[non_exhaustive]
97#[derive(Clone, Copy, Debug, Eq, PartialEq)]
98pub enum TaskEndCause {
99    /// Local write completed, or a matching final response was received.
100    Completed,
101    /// Explicit cancellation, cancellation-group cancellation, or owner drop.
102    Cancelled,
103    /// The operation deadline or processing timeout elapsed.
104    Expired,
105    /// The connection ended before the operation could continue.
106    Disconnected,
107    /// Client or engine shutdown terminated the operation.
108    Shutdown,
109    /// Another processing error caused failure.
110    Failed,
111}
112
113/// Owning subscription receiver for terminal task events.
114pub type TaskEvents = crate::subscription::EventReceiver<TaskEvent>;