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