rsrs_core/frame/
setup.rs

1use recode::bytes::{Bytes, BytesMut};
2use recode::codec::*;
3
4use super::validators::*;
5use crate::{frame, FrameFlags};
6
7frame! {
8    /// SETUP Frame (0x01)
9    ///
10    /// Setup frames MUST always use Stream ID 0 as they pertain to the
11    /// connection.
12    ///
13    /// The SETUP frame is sent by the client to inform the server of the
14    /// parameters under which it desires to operate. The usage and message
15    /// sequence used is shown in Connection Establishment.
16    ///
17    /// One of the important parameters for a connection is the format, layout,
18    /// and any schema of the data and metadata for frames. This is, for lack
19    /// of a better term, referred to here as "MIME Type". An implementation
20    /// MAY use typical MIME type values or MAY decide to use specific non-MIME
21    /// type values to indicate format, layout, and any schema for data and
22    /// metadata. The protocol implementation MUST NOT interpret the MIME type
23    /// itself. This is an application concern only.
24    ///
25    /// The encoding format for Data and Metadata are included separately in
26    /// the SETUP.
27    ///
28    /// # Frame Contents
29    ///
30    /// ```text
31    ///  0                   1                   2                   3
32    ///  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
33    /// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
34    /// |                         Stream ID = 0                         |
35    /// +-----------+-+-+-+-+-----------+-------------------------------+
36    /// |Frame Type |0|M|R|L|  Flags    |
37    /// +-----------+-+-+-+-+-----------+-------------------------------+
38    /// |         Major Version         |        Minor Version          |
39    /// +-------------------------------+-------------------------------+
40    /// |0|                 Time Between KEEPALIVE Frames               |
41    /// +---------------------------------------------------------------+
42    /// |0|                       Max Lifetime                          |
43    /// +---------------------------------------------------------------+
44    /// |         Token Length          | Resume Identification Token  ...
45    /// +---------------+-----------------------------------------------+
46    /// |  MIME Length  |   Metadata Encoding MIME Type                ...
47    /// +---------------+-----------------------------------------------+
48    /// |  MIME Length  |     Data Encoding MIME Type                  ...
49    /// +---------------+-----------------------------------------------+
50    ///                       Metadata & Setup Payload
51    /// ```
52    ///
53    /// # Note
54    /// A server that receives a [`Setup`] frame that has
55    /// [`FrameFlags::RESUME`] Enabled set, but does not support resuming
56    /// operation, MUST reject the SETUP with an
57    /// [`ErrorCode::RejectedSetup`](crate::frame::ErrorCode)
58    Setup [header] {
59        #mask = [METADATA | RESUME | LEASE];
60
61        // 32-bits of major and minor version numbers of the protocol.
62        pub version(required): super::version::Version;
63
64        /// Unsigned 31-bit integer of Time (in milliseconds) between KEEPALIVE
65        /// frames that the client will send. Value **MUST be > 0**.
66        ///
67        /// * For server-to-server connections, a reasonable time interval
68        ///   between client KEEPALIVE frames is 500ms.
69        /// * For mobile-to-server connections, the time interval between
70        ///   client KEEPALIVE frames is often > 30,000ms.
71        @validate(r#"|v, b| non_zero("Setup.keepalive", v, b)"#);
72        pub keepalive(required): u32;
73
74        /// Unsigned 31-bit integer of Time (in milliseconds) that a client
75        /// will allow a server to not respond to a KEEPALIVE before it is
76        /// assumed to be dead. **Value MUST be > 0**.
77        @validate(r#"|v, b| non_zero("Setup.max_lifetime", v, b)"#);
78        pub max_lifetime(required): u32;
79
80        /// Token used for client resume identification (Not present if
81        /// [`R`](crate::FrameFlags::Resume) flag is not set).
82        @skip_if("!header.has(FrameFlags::RESUME)");
83        @with("LengthPrefixed::<u16>");
84        pub resume_identification_token: Bytes => [ set(RESUME) ];
85
86        /// MIME Type for encoding of Metadata.
87        ///
88        /// This SHOULD be a US-ASCII string that includes the Internet media
89        /// type specified in RFC 2045. Many are registered with IANA such as
90        /// CBOR. Suffix rules MAY be used for handling layout.
91        ///
92        /// For example, application/x.netflix+cbor or
93        /// application/x.reactivesocket+cbor or application/x.netflix+json.
94        ///
95        /// The string MUST NOT be null terminated.
96        @with("LengthPrefixed::<u8>");
97        @validate(r#"|v, b| is_ascii("Setup.metadata_mime_type", v, b)"#);
98        pub metadata_mime_type(required): Bytes;
99
100        /// MIME Type for encoding of Data.
101        ///
102        /// This SHOULD be a US-ASCII string that includes the Internet media
103        /// type specified in RFC 2045. Many are registered with IANA such as
104        /// CBOR. Suffix rules MAY be used for handling layout.
105        ///
106        /// For example, application/x.netflix+cbor or
107        /// application/x.reactivesocket+cbor or application/x.netflix+json.
108        ///
109        /// The string MUST NOT be null terminated.
110        @with("LengthPrefixed::<u16>");
111        @validate(r#"|v, b| is_ascii("Setup.data_mime_type", v, b)"#);
112        pub data_mime_type(required): Bytes;
113
114        /// Setup Metadata
115        ///
116        /// Includes payload describing connection capabilities of the endpoint
117        /// sending the Setup header.
118        @skip_if("!header.has(FrameFlags::METADATA)");
119        @with("LengthPrefixed::<u24>");
120        pub metadata: BytesMut => [ set (METADATA if !metadata.is_empty()) ];
121
122        /// Setup Data
123        ///
124        /// Includes payload describing connection capabilities of the endpoint
125        /// sending the Setup header.
126        @with("Unprefixed");
127        pub data: BytesMut;
128    }
129}
rsrs_core/frame/setup.rs

rsrs_core/frame/
setup.rs
