Skip to main content

nautilus_serialization/sbe/
market.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Hand-written SBE codecs for Nautilus market data types.
17
18mod bars;
19mod book;
20mod common;
21mod data_any;
22mod ticks;
23
24use nautilus_model::{
25    data::{
26        Bar, FundingRateUpdate, IndexPriceUpdate, InstrumentClose, InstrumentStatus,
27        MarkPriceUpdate, OptionGreeks, OrderBookDelta, OrderBookDeltas, OrderBookDepth, QuoteTick,
28        TradeTick,
29    },
30    types::fixed::FIXED_PRECISION,
31};
32
33use self::common::{HEADER_LENGTH, MessageHeader, decode_header, encode_header, validate_header};
34use super::{SbeCursor, SbeDecodeError, SbeEncodeError, SbeWriter};
35
36pub const MARKET_SCHEMA_ID: u16 = 1;
37/// Wire version identifying the model raw scale: 9 for standard precision, 16 for high precision.
38///
39/// Version 0 has no scale discriminator and is rejected in both precision modes.
40pub const MARKET_SCHEMA_VERSION: u16 = FIXED_PRECISION as u16;
41
42pub(super) mod data_any_variant {
43    pub(crate) const ORDER_BOOK_DELTA: u16 = 0;
44    pub(crate) const ORDER_BOOK_DELTAS: u16 = 1;
45    pub(crate) const ORDER_BOOK_DEPTH: u16 = 2;
46    pub(crate) const QUOTE: u16 = 3;
47    pub(crate) const TRADE: u16 = 4;
48    pub(crate) const BAR: u16 = 5;
49    pub(crate) const MARK_PRICE: u16 = 6;
50    pub(crate) const INDEX_PRICE: u16 = 7;
51    pub(crate) const FUNDING_RATE: u16 = 8;
52    pub(crate) const OPTION_GREEKS: u16 = 9;
53    pub(crate) const INSTRUMENT_STATUS: u16 = 10;
54    pub(crate) const INSTRUMENT_CLOSE: u16 = 11;
55    pub(crate) const ORDER_BOOK_DEPTH_FULL: u16 = 12;
56}
57
58pub(super) mod template_id {
59    pub(crate) const BOOK_ORDER: u16 = 30_001;
60    pub(crate) const ORDER_BOOK_DELTA: u16 = 30_002;
61    pub(crate) const ORDER_BOOK_DELTAS: u16 = 30_003;
62    pub(crate) const ORDER_BOOK_DEPTH: u16 = 30_004;
63    pub(crate) const QUOTE_TICK: u16 = 30_005;
64    pub(crate) const TRADE_TICK: u16 = 30_006;
65    pub(crate) const BAR_TYPE: u16 = 30_007;
66    pub(crate) const BAR: u16 = 30_008;
67    pub(crate) const MARK_PRICE_UPDATE: u16 = 30_009;
68    pub(crate) const INDEX_PRICE_UPDATE: u16 = 30_010;
69    pub(crate) const FUNDING_RATE_UPDATE: u16 = 30_011;
70    pub(crate) const OPTION_GREEKS: u16 = 30_012;
71    pub(crate) const INSTRUMENT_STATUS: u16 = 30_013;
72    pub(crate) const INSTRUMENT_CLOSE: u16 = 30_014;
73    pub(crate) const DATA_ANY: u16 = 30_015;
74    pub(crate) const ORDER_BOOK_DEPTH_FULL: u16 = 30_016;
75}
76
77#[expect(clippy::large_enum_variant)]
78#[derive(Debug, Clone, PartialEq)]
79pub enum DataAny {
80    BookDelta(OrderBookDelta),
81    BookDeltas(OrderBookDeltas),
82    BookDepth(OrderBookDepth),
83    Quote(QuoteTick),
84    Trade(TradeTick),
85    Bar(Bar),
86    MarkPrice(MarkPriceUpdate),
87    IndexPrice(IndexPriceUpdate),
88    FundingRate(FundingRateUpdate),
89    OptionGreeks(OptionGreeks),
90    InstrumentStatus(InstrumentStatus),
91    InstrumentClose(InstrumentClose),
92}
93
94pub trait ToSbe {
95    /// Encodes the value into an SBE message buffer.
96    ///
97    /// # Errors
98    ///
99    /// Returns an error if any field cannot be encoded into the target SBE wire format.
100    fn to_sbe(&self) -> Result<Vec<u8>, SbeEncodeError>;
101
102    /// Encodes the value into the provided SBE message buffer.
103    ///
104    /// This method clears any existing bytes in `buf` before encoding.
105    ///
106    /// # Errors
107    ///
108    /// Returns an error if any field cannot be encoded into the target SBE wire format.
109    fn to_sbe_into(&self, buf: &mut Vec<u8>) -> Result<(), SbeEncodeError> {
110        let bytes = self.to_sbe()?;
111        buf.clear();
112        buf.extend_from_slice(&bytes);
113        Ok(())
114    }
115}
116
117pub trait FromSbe: Sized {
118    /// Decodes the value from an SBE message buffer.
119    ///
120    /// # Errors
121    ///
122    /// Returns an error if the header is invalid or the payload is malformed.
123    fn from_sbe(bytes: &[u8]) -> Result<Self, SbeDecodeError>;
124}
125
126/// Extension of [`FromSbe`] that reuses allocations between decodes.
127///
128/// Scalar messages decode without heap allocation, so they do not need this trait. Types with
129/// growable internal buffers (for example [`OrderBookDeltas`] with its `Vec<OrderBookDelta>`)
130/// implement it to let callers supply a pre-allocated scratch buffer and avoid per-message
131/// allocation in hot paths.
132pub trait FromSbeReuse: FromSbe {
133    /// Scratch buffer whose allocation is reused across decodes.
134    type Scratch;
135
136    /// Decodes a value from an SBE message buffer, reusing `scratch`'s allocation.
137    ///
138    /// On success, ownership of the allocation moves from `scratch` into the returned value and
139    /// `scratch` is left in its empty state. To continue reusing the allocation, move the buffer
140    /// back from the returned value (for example `scratch = std::mem::take(&mut result.deltas)`).
141    ///
142    /// # Errors
143    ///
144    /// Returns an error if the header is invalid or the payload is malformed.
145    fn from_sbe_reuse(bytes: &[u8], scratch: &mut Self::Scratch) -> Result<Self, SbeDecodeError>;
146}
147
148pub(super) trait MarketSbeMessage: Sized {
149    const TEMPLATE_ID: u16;
150    const BLOCK_LENGTH: u16;
151
152    fn template_id(&self) -> u16 {
153        Self::TEMPLATE_ID
154    }
155
156    fn block_length(&self) -> u16 {
157        Self::BLOCK_LENGTH
158    }
159
160    fn decode_with_header(
161        header: MessageHeader,
162        cursor: &mut SbeCursor<'_>,
163    ) -> Result<Self, SbeDecodeError> {
164        validate_header(header, Self::TEMPLATE_ID, Self::BLOCK_LENGTH)?;
165        Self::decode_body(cursor)
166    }
167
168    fn encode_body(&self, writer: &mut SbeWriter<'_>) -> Result<(), SbeEncodeError>;
169
170    fn decode_body(cursor: &mut SbeCursor<'_>) -> Result<Self, SbeDecodeError>;
171
172    fn encoded_body_size(&self) -> usize {
173        usize::from(Self::BLOCK_LENGTH)
174    }
175}
176
177impl<T> ToSbe for T
178where
179    T: MarketSbeMessage,
180{
181    #[inline]
182    fn to_sbe(&self) -> Result<Vec<u8>, SbeEncodeError> {
183        let encoded_size = HEADER_LENGTH + self.encoded_body_size();
184        let mut buf = Vec::with_capacity(encoded_size);
185        encode_into_uninit(self, &mut buf, encoded_size)?;
186        Ok(buf)
187    }
188
189    #[inline]
190    fn to_sbe_into(&self, buf: &mut Vec<u8>) -> Result<(), SbeEncodeError> {
191        let encoded_size = HEADER_LENGTH + self.encoded_body_size();
192        buf.clear();
193        buf.reserve(encoded_size);
194        encode_into_uninit(self, buf, encoded_size)
195    }
196}
197
198impl<T> FromSbe for T
199where
200    T: MarketSbeMessage,
201{
202    #[inline]
203    fn from_sbe(bytes: &[u8]) -> Result<Self, SbeDecodeError> {
204        let mut cursor = SbeCursor::new(bytes);
205        let header = decode_header(&mut cursor)?;
206        T::decode_with_header(header, &mut cursor)
207    }
208}
209
210// Writes an SBE message into the spare capacity of `buf` without zero
211// initialization, then commits the length on success. Caller must ensure
212// `buf.len() == 0` and `buf.capacity() >= encoded_size`.
213#[inline]
214#[allow(
215    unsafe_code,
216    reason = "set_len commits writes the SbeWriter has already made into spare capacity"
217)]
218#[allow(
219    clippy::panic_in_result_fn,
220    reason = "load-bearing safety check for the unsafe set_len; panic is the right outcome"
221)]
222fn encode_into_uninit<T>(
223    value: &T,
224    buf: &mut Vec<u8>,
225    encoded_size: usize,
226) -> Result<(), SbeEncodeError>
227where
228    T: MarketSbeMessage,
229{
230    debug_assert_eq!(buf.len(), 0);
231    debug_assert!(buf.capacity() >= encoded_size);
232
233    let spare = &mut buf.spare_capacity_mut()[..encoded_size];
234    let mut writer = SbeWriter::new_uninit(spare);
235    encode_header(
236        &mut writer,
237        value.block_length(),
238        value.template_id(),
239        MARKET_SCHEMA_ID,
240        MARKET_SCHEMA_VERSION,
241    );
242    value.encode_body(&mut writer)?;
243
244    // Load-bearing for the unsafe `set_len` below: this is the invariant that
245    // converts the writer's per-byte initialization into Vec-level safety. Run
246    // in release builds too so a future size mismatch panics rather than
247    // commits uninit bytes.
248    assert_eq!(
249        writer.pos(),
250        encoded_size,
251        "SBE encode_body wrote {} bytes but encoded_body_size reported {}",
252        writer.pos(),
253        encoded_size,
254    );
255
256    // SAFETY: the writer panics if it attempts to write past `encoded_size`,
257    // the assert above confirms it wrote exactly `encoded_size` bytes, and
258    // errors propagate before `set_len` runs. Reaching this line means the
259    // first `encoded_size` bytes of `buf` hold initialized u8 values.
260    unsafe {
261        buf.set_len(encoded_size);
262    }
263    Ok(())
264}