open_net/api/ws/incoming.rs
1use super::{ClientId, ConnectionId, Message, PeerClose, SessionId};
2use bytes::Bytes;
3use std::fmt;
4use std::sync::Arc;
5use std::sync::Weak;
6use std::time::SystemTime;
7
8/// Received business message or protocol-control payload.
9///
10/// `Debug` reports payload summaries without exposing business bodies or control-frame contents.
11#[derive(Clone)]
12pub enum IncomingPayload {
13 /// Text or binary business message.
14 Message(
15 /// Owned business body.
16 Message,
17 ),
18 /// Ping control frame sent by the peer.
19 Ping(
20 /// Raw bytes carried by the Ping frame.
21 Bytes,
22 ),
23 /// Pong control frame sent by the peer.
24 Pong(
25 /// Raw bytes carried by the Pong frame.
26 Bytes,
27 ),
28 /// Close control frame sent by the peer.
29 Close(
30 /// Decoded close code and reason.
31 PeerClose,
32 ),
33}
34
35impl fmt::Debug for IncomingPayload {
36 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
37 match self {
38 Self::Message(message) => formatter.debug_tuple("Message").field(message).finish(),
39 Self::Ping(bytes) => formatter
40 .debug_struct("Ping")
41 .field("bytes", &bytes.len())
42 .finish(),
43 Self::Pong(bytes) => formatter
44 .debug_struct("Pong")
45 .field("bytes", &bytes.len())
46 .finish(),
47 Self::Close(close) => formatter.debug_tuple("Close").field(close).finish(),
48 }
49 }
50}
51
52/// Source identity assigned by the receiving connection; owns no session resources.
53#[derive(Clone, Copy, Debug, Eq, PartialEq)]
54pub(crate) struct IncomingOrigin {
55 /// Client identity that received the item.
56 client_id: ClientId,
57 /// Logical session identity that received the item.
58 session_id: SessionId,
59 /// Physical connection that received the item.
60 connection_id: ConnectionId,
61}
62
63impl IncomingOrigin {
64 pub(crate) fn new(
65 client_id: ClientId,
66 session_id: SessionId,
67 connection_id: ConnectionId,
68 ) -> Self {
69 Self {
70 client_id,
71 session_id,
72 connection_id,
73 }
74 }
75}
76
77/// Immutable inbound item; clones share one payload allocation.
78#[derive(Clone, Debug)]
79pub struct IncomingMessage {
80 #[cfg(feature = "quality-doctor")]
81 quality: Option<crate::api::quality::QualityReportRef>,
82 /// Client, session, and physical connection that produced the item.
83 origin: IncomingOrigin,
84 /// Business or control payload shared by all clones.
85 payload: Arc<IncomingPayload>,
86 /// System time recorded when the SDK received the item.
87 received_at: SystemTime,
88 /// Response-dispatch identity, or `None` before request dispatch binding.
89 dispatch: Option<IncomingDispatch>,
90}
91
92/// Response-dispatch identity attached to an inbound item for source and validity checks.
93#[derive(Clone, Debug)]
94pub(crate) struct IncomingDispatch {
95 /// Weak reference to the request table; does not extend table or session lifetime.
96 pub(crate) pending: Weak<crate::module::ws_client::native_pending::NativePending>,
97 /// Identifier allocated by that table for this inbound dispatch.
98 pub(crate) id: u64,
99}
100
101impl IncomingMessage {
102 pub(crate) fn new(
103 origin: IncomingOrigin,
104 payload: IncomingPayload,
105 received_at: SystemTime,
106 ) -> Self {
107 Self {
108 #[cfg(feature = "quality-doctor")]
109 quality: None,
110 origin,
111 payload: Arc::new(payload),
112 received_at,
113 dispatch: None,
114 }
115 }
116 /// Returns the `WsReceive` report reference attached during SDK message routing.
117 ///
118 /// Its observation begins after the transport has supplied a complete decoded
119 /// message, and measures SDK routing/publication boundaries. It does not
120 /// measure time spent waiting for socket bytes, frame assembly, or the peer's
121 /// send time. The `PayloadReceived` marker uses the collector's monotonic
122 /// clock; [`Self::received_at`] is a separate wall-clock timestamp.
123 ///
124 /// Only text/binary business messages currently receive this routing report;
125 /// Ping, Pong, and Close items carry no `WsReceive` reference. This observation
126 /// is distinct from the request report attached to a matching
127 /// [`super::Response`]. Cloning the incoming message preserves its reference.
128 /// `None` can also mean collection was inactive, WebSocket was excluded, or
129 /// diagnostic allocation was unavailable. Reading it neither starts collection nor
130 /// performs routing. Resolve it through the owning engine's
131 /// `QualityDoctor::lookup`; history can be incomplete or already evicted.
132 #[cfg(feature = "quality-doctor")]
133 pub fn quality_ref(&self) -> Option<crate::api::quality::QualityReportRef> {
134 self.quality
135 }
136 #[cfg(feature = "quality-doctor")]
137 pub(crate) fn bind_quality(&mut self, reference: crate::api::quality::QualityReportRef) {
138 self.quality = Some(reference);
139 }
140
141 pub(crate) fn bind_dispatch(
142 &mut self,
143 pending: Weak<crate::module::ws_client::native_pending::NativePending>,
144 id: u64,
145 ) {
146 self.dispatch = Some(IncomingDispatch { pending, id });
147 }
148
149 pub(crate) fn dispatch(&self) -> Option<&IncomingDispatch> {
150 self.dispatch.as_ref()
151 }
152
153 /// Borrows the complete inbound payload, including control frames.
154 pub fn payload(&self) -> &IncomingPayload {
155 self.payload.as_ref()
156 }
157
158 /// Returns the business message, or `None` for control frames.
159 pub fn message(&self) -> Option<&Message> {
160 match self.payload() {
161 IncomingPayload::Message(message) => Some(message),
162 IncomingPayload::Ping(_) | IncomingPayload::Pong(_) | IncomingPayload::Close(_) => None,
163 }
164 }
165
166 /// Returns the SDK receive timestamp.
167 pub fn received_at(&self) -> SystemTime {
168 self.received_at
169 }
170
171 /// Returns the originating client identity.
172 pub fn client_id(&self) -> ClientId {
173 self.origin.client_id
174 }
175
176 /// Returns the originating logical session identity.
177 pub fn session_id(&self) -> SessionId {
178 self.origin.session_id
179 }
180
181 /// Returns the originating physical connection identity.
182 pub fn connection_id(&self) -> ConnectionId {
183 self.origin.connection_id
184 }
185}
186
187#[cfg(test)]
188#[path = "incoming_tests.rs"]
189mod tests;