zenoh_protocol/transport/
frame.rs

1//
2// Copyright (c) 2023 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 alloc::vec::Vec;
15
16use crate::{core::Reliability, network::NetworkMessage, transport::TransportSn};
17
18pub mod flag {
19    pub const R: u8 = 1 << 5; // 0x20 Reliable      if R==1 then the frame is reliable
20                              // pub const X: u8 = 1 << 6; // 0x40       Reserved
21    pub const Z: u8 = 1 << 7; // 0x80 Extensions    if Z==1 then an extension will follow
22}
23
24/// # Frame message
25///
26/// The [`Frame`] message is used to transmit one ore more complete serialized
27/// [`NetworkMessage`]. I.e., the total length of the
28/// serialized [`NetworkMessage`] (s) MUST be smaller
29/// than the maximum batch size (i.e. 2^16-1) and the link MTU.
30/// The [`Frame`] message is used as means to aggregate multiple
31/// [`NetworkMessage`] in a single atomic message that
32/// goes on the wire. By doing so, many small messages can be batched together and
33/// share common information like the sequence number.
34///
35/// The [`Frame`] message flow is the following:
36///
37/// ```text
38///     A                   B
39///     |      FRAME        |
40///     |------------------>|
41///     |                   |
42/// ```
43///
44/// The [`Frame`] message structure is defined as follows:
45///
46/// ```text
47/// Flags:
48/// - R: Reliable       If R==1 it concerns the reliable channel, else the best-effort channel
49/// - X: Reserved
50/// - Z: Extensions     If Z==1 then zenoh extensions will follow.
51///
52///  7 6 5 4 3 2 1 0
53/// +-+-+-+-+-+-+-+-+
54/// |Z|X|R|  FRAME  |
55/// +-+-+-+---------+
56/// %    seq num    %
57/// +---------------+
58/// ~  [FrameExts]  ~ if Flag(Z)==1
59/// +---------------+
60/// ~  [NetworkMsg] ~
61/// +---------------+
62/// ```
63///
64/// NOTE: 16 bits (2 bytes) may be prepended to the serialized message indicating the total length
65///       in bytes of the message, resulting in the maximum length of a message being 65535 bytes.
66///       This is necessary in those stream-oriented transports (e.g., TCP) that do not preserve
67///       the boundary of the serialized messages. The length is encoded as little-endian.
68///       In any case, the length of a message must not exceed 65535 bytes.
69///
70#[derive(Debug, Clone, PartialEq, Eq)]
71pub struct Frame {
72    pub reliability: Reliability,
73    pub sn: TransportSn,
74    pub ext_qos: ext::QoSType,
75    pub payload: Vec<NetworkMessage>,
76}
77
78// Extensions
79pub mod ext {
80    use crate::{common::ZExtZ64, zextz64};
81
82    pub type QoS = zextz64!(0x1, true);
83    pub type QoSType = crate::transport::ext::QoSType<{ QoS::ID }>;
84}
85
86impl Frame {
87    #[cfg(feature = "test")]
88    #[doc(hidden)]
89    pub fn rand() -> Self {
90        use rand::Rng;
91
92        let mut rng = rand::thread_rng();
93
94        let reliability = Reliability::rand();
95        let sn: TransportSn = rng.gen();
96        let ext_qos = ext::QoSType::rand();
97        let mut payload = vec![];
98        for _ in 0..rng.gen_range(1..4) {
99            let mut m = NetworkMessage::rand();
100            m.reliability = reliability;
101            payload.push(m);
102        }
103
104        Frame {
105            reliability,
106            sn,
107            ext_qos,
108            payload,
109        }
110    }
111}
112
113// FrameHeader
114#[derive(Debug, Copy, Clone, PartialEq, Eq)]
115pub struct FrameHeader {
116    pub reliability: Reliability,
117    pub sn: TransportSn,
118    pub ext_qos: ext::QoSType,
119}
120
121impl FrameHeader {
122    #[cfg(feature = "test")]
123    #[doc(hidden)]
124    pub fn rand() -> Self {
125        use rand::Rng;
126
127        let mut rng = rand::thread_rng();
128
129        let reliability = Reliability::rand();
130        let sn: TransportSn = rng.gen();
131        let ext_qos = ext::QoSType::rand();
132
133        FrameHeader {
134            reliability,
135            sn,
136            ext_qos,
137        }
138    }
139}
zenoh_protocol/transport/frame.rs

zenoh_protocol/transport/
frame.rs
