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>;