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, Debug)]
35pub enum TaskSource {
36    /// A message send that has no response tracking.
37    Message(
38        /// Original message shared by the task and observers.
39        Arc<Message>,
40    ),
41    /// A request whose business response is tracked.
42    Request(
43        /// Original request and metadata shared by the task and observers.
44        Arc<Request>,
45    ),
46}
47
48impl TaskSource {
49    /// Counts the owned variable-size input once for the shared payload budget.
50    pub(crate) fn payload_bytes(&self) -> Result<usize> {
51        match self {
52            Self::Message(message) => Ok(message.len()),
53            Self::Request(request) => {
54                let mut bytes = request
55                    .message()
56                    .len()
57                    .checked_add(request.id().as_str().len())
58                    .ok_or_else(|| NetError::from(ErrorKind::ItemTooLarge))?;
59                for (key, value) in request.metadata() {
60                    bytes = bytes
61                        .checked_add(key.len())
62                        .and_then(|size| size.checked_add(value.len()))
63                        .ok_or_else(|| NetError::from(ErrorKind::ItemTooLarge))?;
64                }
65                Ok(bytes)
66            }
67        }
68    }
69}
70
71/// Reason why a message or request reached its terminal state.
72#[non_exhaustive]
73#[derive(Clone, Copy, Debug, Eq, PartialEq)]
74pub enum TaskEndCause {
75    /// Local write completed, or a matching final response was received.
76    Completed,
77    /// Explicit cancellation, cancellation-group cancellation, or owner drop.
78    Cancelled,
79    /// The operation deadline or processing timeout elapsed.
80    Expired,
81    /// The connection ended before the operation could continue.
82    Disconnected,
83    /// Client or engine shutdown terminated the operation.
84    Shutdown,
85    /// Another processing error caused failure.
86    Failed,
87}
88
89/// Owning subscription receiver for terminal task events.
90pub type TaskEvents = crate::subscription::EventReceiver<TaskEvent>;