Skip to main content

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;