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

zenoh_protocol/network/
request.rs
