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/// [`crate::network::NetworkMessage`]. I.e., the total length of the
28/// serialized [`crate::network::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/// [`crate::network::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    pub fn rand() -> Self {
89        use rand::Rng;
90
91        let mut rng = rand::thread_rng();
92
93        let reliability = Reliability::rand();
94        let sn: TransportSn = rng.gen();
95        let ext_qos = ext::QoSType::rand();
96        let mut payload = vec![];
97        for _ in 0..rng.gen_range(1..4) {
98            let mut m = NetworkMessage::rand();
99            m.reliability = reliability;
100            payload.push(m);
101        }
102
103        Frame {
104            reliability,
105            sn,
106            ext_qos,
107            payload,
108        }
109    }
110}
111
112// FrameHeader
113#[derive(Debug, Copy, Clone, PartialEq, Eq)]
114pub struct FrameHeader {
115    pub reliability: Reliability,
116    pub sn: TransportSn,
117    pub ext_qos: ext::QoSType,
118}
119
120impl FrameHeader {
121    #[cfg(feature = "test")]
122    pub fn rand() -> Self {
123        use rand::Rng;
124
125        let mut rng = rand::thread_rng();
126
127        let reliability = Reliability::rand();
128        let sn: TransportSn = rng.gen();
129        let ext_qos = ext::QoSType::rand();
130
131        FrameHeader {
132            reliability,
133            sn,
134            ext_qos,
135        }
136    }
137}
zenoh_protocol/transport/frame.rs

zenoh_protocol/transport/
frame.rs
