zenoh_protocol/network/
request.rs

1//
2// Copyright (c) 2022 ZettaScale Technology
3//
4// This program and the accompanying materials are made available under the
5// terms of the Eclipse Public License 2.0 which is available at
6// http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
7// which is available at https://www.apache.org/licenses/LICENSE-2.0.
8//
9// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
10//
11// Contributors:
12//   ZettaScale Zenoh Team, <zenoh@zettascale.tech>
13//
14use core::sync::atomic::AtomicU32;
15
16use zenoh_buffers::buffer::Buffer;
17
18use crate::{core::WireExpr, zenoh::RequestBody};
19
20/// The resolution of a RequestId
21pub type RequestId = u32;
22pub type AtomicRequestId = AtomicU32;
23
24pub mod flag {
25    pub const N: u8 = 1 << 5; // 0x20 Named         if N==1 then the key expr has name/suffix
26    pub const M: u8 = 1 << 6; // 0x40 Mapping       if M==1 then key expr mapping is the one declared by the sender, else it is the one declared by the receiver
27    pub const Z: u8 = 1 << 7; // 0x80 Extensions    if Z==1 then an extension will follow
28}
29
30/// # Request message
31///
32/// ```text
33/// Flags:
34/// - N: Named          if N==1 then the key expr has name/suffix
35/// - M: Mapping        if M==1 then key expr mapping is the one declared by the sender, else it is the one declared by the receiver
36/// - Z: Extension      if Z==1 then at least one extension is present
37///
38///  7 6 5 4 3 2 1 0
39/// +-+-+-+-+-+-+-+-+
40/// |Z|M|N| Request |
41/// +-+-+-+---------+
42/// ~ request_id:z32~  (*)
43/// +---------------+
44/// ~ key_scope:z16 ~
45/// +---------------+
46/// ~  key_suffix   ~  if N==1 -- <u8;z16>
47/// +---------------+
48/// ~   [req_exts]  ~  if Z==1
49/// +---------------+
50/// ~  RequestBody  ~  -- Payload
51/// +---------------+
52///
53/// (*) The resolution of the request id is negotiated during the session establishment.
54///     This implementation limits the resolution to 32bit.
55/// ```
56#[derive(Debug, Clone, PartialEq, Eq)]
57pub struct Request {
58    pub id: RequestId,
59    pub wire_expr: WireExpr<'static>,
60    pub ext_qos: ext::QoSType,
61    pub ext_tstamp: Option<ext::TimestampType>,
62    pub ext_nodeid: ext::NodeIdType,
63    pub ext_target: ext::QueryTarget,
64    pub ext_budget: Option<ext::BudgetType>,
65    pub ext_timeout: Option<ext::TimeoutType>,
66    pub payload: RequestBody,
67}
68
69pub mod ext {
70    use core::{num::NonZeroU32, time::Duration};
71
72    use serde::Deserialize;
73
74    use crate::{
75        common::{ZExtZ64, ZExtZBuf},
76        zextz64, zextzbuf,
77    };
78
79    pub type QoS = zextz64!(0x1, false);
80    pub type QoSType = crate::network::ext::QoSType<{ QoS::ID }>;
81
82    pub type Timestamp = zextzbuf!(0x2, false);
83    pub type TimestampType = crate::network::ext::TimestampType<{ Timestamp::ID }>;
84
85    pub type NodeId = zextz64!(0x3, true);
86    pub type NodeIdType = crate::network::ext::NodeIdType<{ NodeId::ID }>;
87
88    pub type Target = zextz64!(0x4, true);
89    // ```text
90    // - Target (0x03)
91    //  7 6 5 4 3 2 1 0
92    // +-+-+-+-+-+-+-+-+
93    // %     target    %
94    // +---------------+
95    // ```
96    // The `zenoh::queryable::Queryable`s that should be target of a `zenoh::Session::get()`.
97    #[repr(u8)]
98    #[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Deserialize)]
99    pub enum QueryTarget {
100        /// Let Zenoh find the BestMatching queryable capabale of serving the query.
101        #[default]
102        BestMatching,
103        /// Deliver the query to all queryables matching the query's key expression.
104        All,
105        /// Deliver the query to all queryables matching the query's key expression that are declared as complete.
106        AllComplete,
107    }
108
109    impl QueryTarget {
110        pub const DEFAULT: Self = Self::BestMatching;
111
112        #[cfg(feature = "test")]
113        #[doc(hidden)]
114        pub fn rand() -> Self {
115            use rand::prelude::*;
116            let mut rng = rand::thread_rng();
117
118            *[
119                QueryTarget::All,
120                QueryTarget::AllComplete,
121                QueryTarget::BestMatching,
122            ]
123            .choose(&mut rng)
124            .unwrap()
125        }
126    }
127
128    // The maximum number of responses
129    pub type Budget = zextz64!(0x5, false);
130    pub type BudgetType = NonZeroU32;
131
132    // The timeout of the request
133    pub type Timeout = zextz64!(0x6, false);
134    pub type TimeoutType = Duration;
135}
136
137impl Request {
138    pub fn payload_size(&self) -> usize {
139        match &self.payload {
140            RequestBody::Query(q) => {
141                q.ext_body.as_ref().map_or(0, |b| b.payload.len())
142                    + q.ext_attachment.as_ref().map_or(0, |a| a.buffer.len())
143            }
144        }
145    }
146
147    #[cfg(feature = "test")]
148    #[doc(hidden)]
149    pub fn rand() -> Self {
150        use core::num::NonZeroU32;
151
152        use rand::Rng;
153
154        let mut rng = rand::thread_rng();
155        let wire_expr = WireExpr::rand();
156        let id: RequestId = rng.gen();
157        let payload = RequestBody::rand();
158        let ext_qos = ext::QoSType::rand();
159        let ext_tstamp = rng.gen_bool(0.5).then(ext::TimestampType::rand);
160        let ext_nodeid = ext::NodeIdType::rand();
161        let ext_target = ext::QueryTarget::rand();
162        let ext_budget = if rng.gen_bool(0.5) {
163            NonZeroU32::new(rng.gen())
164        } else {
165            None
166        };
167        let ext_timeout = if rng.gen_bool(0.5) {
168            Some(ext::TimeoutType::from_millis(rng.gen()))
169        } else {
170            None
171        };
172
173        Self {
174            wire_expr,
175            id,
176            payload,
177            ext_qos,
178            ext_tstamp,
179            ext_nodeid,
180            ext_target,
181            ext_budget,
182            ext_timeout,
183        }
184    }
185}
zenoh_protocol/network/request.rs

zenoh_protocol/network/
request.rs
