nautilus_serialization/arrow/
report.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
16use std::collections::HashMap;
17
18use arrow::{datatypes::Schema, error::ArrowError, record_batch::RecordBatch};
19use nautilus_model::reports::{
20    ExecutionMassStatus, FillReport, OrderStatusReport, PositionStatusReport,
21};
22
23use super::{
24    ArrowSchemaProvider, DecodeTypedFromRecordBatch, EncodeToRecordBatch, EncodingError,
25    KEY_INSTRUMENT_ID,
26    json::{JsonFieldSpec, decode_batch, encode_batch, metadata_for_type, schema_for_type},
27};
28
29const ORDER_STATUS_REPORT_FIELDS: &[JsonFieldSpec] = &[
30    JsonFieldSpec::utf8("account_id", false),
31    JsonFieldSpec::utf8("instrument_id", false),
32    JsonFieldSpec::utf8("client_order_id", true),
33    JsonFieldSpec::utf8("venue_order_id", false),
34    JsonFieldSpec::utf8("order_side", false),
35    JsonFieldSpec::utf8("order_type", false),
36    JsonFieldSpec::utf8("time_in_force", false),
37    JsonFieldSpec::utf8("order_status", false),
38    JsonFieldSpec::utf8("quantity", false),
39    JsonFieldSpec::utf8("filled_qty", false),
40    JsonFieldSpec::utf8("report_id", false),
41    JsonFieldSpec::timestamp("ts_accepted", false),
42    JsonFieldSpec::timestamp("ts_last", false),
43    JsonFieldSpec::timestamp("ts_init", false),
44    JsonFieldSpec::utf8("order_list_id", true),
45    JsonFieldSpec::utf8("venue_position_id", true),
46    JsonFieldSpec::utf8_json("linked_order_ids", true),
47    JsonFieldSpec::utf8("parent_order_id", true),
48    JsonFieldSpec::utf8("contingency_type", false),
49    JsonFieldSpec::timestamp("expire_time", true),
50    JsonFieldSpec::utf8("price", true),
51    JsonFieldSpec::utf8("activation_price", true),
52    JsonFieldSpec::utf8("trigger_price", true),
53    JsonFieldSpec::utf8("trigger_type", true),
54    JsonFieldSpec::utf8("limit_offset", true),
55    JsonFieldSpec::utf8("trailing_offset", true),
56    JsonFieldSpec::utf8("trailing_offset_type", false),
57    JsonFieldSpec::utf8("avg_px", true),
58    JsonFieldSpec::utf8("display_qty", true),
59    JsonFieldSpec::boolean("post_only", false),
60    JsonFieldSpec::boolean("reduce_only", false),
61    JsonFieldSpec::utf8("cancel_reason", true),
62    JsonFieldSpec::timestamp("ts_triggered", true),
63];
64
65const FILL_REPORT_FIELDS: &[JsonFieldSpec] = &[
66    JsonFieldSpec::utf8("account_id", false),
67    JsonFieldSpec::utf8("instrument_id", false),
68    JsonFieldSpec::utf8("venue_order_id", false),
69    JsonFieldSpec::utf8("trade_id", false),
70    JsonFieldSpec::utf8("order_side", false),
71    JsonFieldSpec::utf8("last_qty", false),
72    JsonFieldSpec::utf8("last_px", false),
73    JsonFieldSpec::utf8("commission", false),
74    JsonFieldSpec::utf8("liquidity_side", false),
75    JsonFieldSpec::utf8("report_id", false),
76    JsonFieldSpec::timestamp("ts_event", false),
77    JsonFieldSpec::timestamp("ts_init", false),
78    JsonFieldSpec::utf8("client_order_id", true),
79    JsonFieldSpec::utf8("venue_position_id", true),
80];
81
82const POSITION_STATUS_REPORT_FIELDS: &[JsonFieldSpec] = &[
83    JsonFieldSpec::utf8("account_id", false),
84    JsonFieldSpec::utf8("instrument_id", false),
85    JsonFieldSpec::utf8("position_side", false),
86    JsonFieldSpec::utf8("quantity", false),
87    JsonFieldSpec::utf8("signed_decimal_qty", false),
88    JsonFieldSpec::utf8("report_id", false),
89    JsonFieldSpec::timestamp("ts_last", false),
90    JsonFieldSpec::timestamp("ts_init", false),
91    JsonFieldSpec::utf8("venue_position_id", true),
92    JsonFieldSpec::utf8("avg_px_open", true),
93    JsonFieldSpec::utf8("avg_px_open_reconciliation", true),
94    JsonFieldSpec::u64("avg_px_open_precision", true),
95    JsonFieldSpec::utf8("liquidation_price", true),
96];
97
98const EXECUTION_MASS_STATUS_FIELDS: &[JsonFieldSpec] = &[
99    JsonFieldSpec::utf8("client_id", false),
100    JsonFieldSpec::utf8("account_id", false),
101    JsonFieldSpec::utf8("venue", false),
102    JsonFieldSpec::utf8("report_id", false),
103    JsonFieldSpec::timestamp("ts_init", false),
104    JsonFieldSpec::utf8_json("order_reports", false),
105    JsonFieldSpec::utf8_json("fill_reports", false),
106    JsonFieldSpec::utf8_json("position_reports", false),
107];
108
109fn instrument_metadata(type_name: &'static str, instrument_id: &str) -> HashMap<String, String> {
110    let mut metadata = metadata_for_type(type_name);
111    metadata.insert(KEY_INSTRUMENT_ID.to_string(), instrument_id.to_string());
112    metadata
113}
114
115macro_rules! impl_report_arrow {
116    ($type:ty, $type_name:expr, $fields:expr) => {
117        impl_report_arrow!($type, $type_name, $fields, |_: &RecordBatch| $fields);
118    };
119    ($type:ty, $type_name:expr, $fields:expr, $decode_fields:expr) => {
120        impl ArrowSchemaProvider for $type {
121            fn get_schema(metadata: Option<HashMap<String, String>>) -> Schema {
122                schema_for_type($type_name, metadata, $fields)
123            }
124        }
125
126        impl EncodeToRecordBatch for $type {
127            fn encode_batch<T>(
128                metadata: &HashMap<String, String>,
129                data: &[T],
130            ) -> Result<RecordBatch, ArrowError>
131            where
132                T: std::borrow::Borrow<Self>,
133            {
134                encode_batch(
135                    $type_name,
136                    metadata,
137                    data.iter().map(std::borrow::Borrow::borrow),
138                    $fields,
139                )
140            }
141
142            fn metadata(&self) -> HashMap<String, String> {
143                instrument_metadata($type_name, &self.instrument_id.to_string())
144            }
145        }
146
147        impl DecodeTypedFromRecordBatch for $type {
148            fn decode_typed_batch(
149                metadata: &HashMap<String, String>,
150                record_batch: RecordBatch,
151            ) -> Result<Vec<Self>, EncodingError> {
152                let fields = ($decode_fields)(&record_batch);
153                decode_batch(metadata, &record_batch, fields, Some($type_name))
154            }
155        }
156    };
157}
158
159impl_report_arrow!(
160    OrderStatusReport,
161    "OrderStatusReport",
162    ORDER_STATUS_REPORT_FIELDS
163);
164impl_report_arrow!(FillReport, "FillReport", FILL_REPORT_FIELDS);
165impl_report_arrow!(
166    PositionStatusReport,
167    "PositionStatusReport",
168    POSITION_STATUS_REPORT_FIELDS,
169    position_status_report_decode_fields
170);
171
172// Older files omit liquidation price and, before that, average reconciliation metadata
173fn position_status_report_decode_fields(record_batch: &RecordBatch) -> &'static [JsonFieldSpec] {
174    let schema = record_batch.schema();
175
176    if schema.index_of("liquidation_price").is_ok() {
177        POSITION_STATUS_REPORT_FIELDS
178    } else if schema.index_of("avg_px_open_reconciliation").is_ok() {
179        &POSITION_STATUS_REPORT_FIELDS[..POSITION_STATUS_REPORT_FIELDS.len() - 1]
180    } else {
181        &POSITION_STATUS_REPORT_FIELDS[..POSITION_STATUS_REPORT_FIELDS.len() - 3]
182    }
183}
184
185impl ArrowSchemaProvider for ExecutionMassStatus {
186    fn get_schema(metadata: Option<HashMap<String, String>>) -> Schema {
187        schema_for_type(
188            "ExecutionMassStatus",
189            metadata,
190            EXECUTION_MASS_STATUS_FIELDS,
191        )
192    }
193}
194
195impl EncodeToRecordBatch for ExecutionMassStatus {
196    fn encode_batch<T>(
197        metadata: &HashMap<String, String>,
198        data: &[T],
199    ) -> Result<RecordBatch, ArrowError>
200    where
201        T: std::borrow::Borrow<Self>,
202    {
203        encode_batch(
204            "ExecutionMassStatus",
205            metadata,
206            data.iter().map(std::borrow::Borrow::borrow),
207            EXECUTION_MASS_STATUS_FIELDS,
208        )
209    }
210
211    fn metadata(&self) -> HashMap<String, String> {
212        metadata_for_type("ExecutionMassStatus")
213    }
214}
215
216impl DecodeTypedFromRecordBatch for ExecutionMassStatus {
217    fn decode_typed_batch(
218        metadata: &HashMap<String, String>,
219        record_batch: RecordBatch,
220    ) -> Result<Vec<Self>, EncodingError> {
221        decode_batch(
222            metadata,
223            &record_batch,
224            EXECUTION_MASS_STATUS_FIELDS,
225            Some("ExecutionMassStatus"),
226        )
227    }
228}
229
230#[cfg(test)]
231mod tests {
232    use std::str::FromStr;
233
234    use nautilus_core::{UUID4, UnixNanos};
235    use nautilus_model::{
236        enums::{
237            AvgPxReconciliation, OrderSide, OrderStatus, OrderType, PositionSide, TimeInForce,
238        },
239        identifiers::{AccountId, ClientOrderId, InstrumentId, PositionId, VenueOrderId},
240        reports::{OrderStatusReport, PositionStatusReport},
241        types::{Price, Quantity},
242    };
243    use rstest::rstest;
244    use rust_decimal::Decimal;
245
246    use super::*;
247
248    #[rstest]
249    fn test_order_status_report_round_trip() {
250        let report = OrderStatusReport::new(
251            AccountId::from("SIM-001"),
252            InstrumentId::from("AUDUSD.SIM"),
253            Some(ClientOrderId::from("O-19700101-000000-001-001-1")),
254            VenueOrderId::from("1"),
255            OrderSide::Buy.into(),
256            OrderType::Limit,
257            TimeInForce::Gtc,
258            OrderStatus::Accepted,
259            Quantity::from("100"),
260            Quantity::from("25"),
261            UnixNanos::from(1_000_000_000),
262            UnixNanos::from(2_000_000_000),
263            UnixNanos::from(3_000_000_000),
264            None,
265        )
266        .with_linked_order_ids([ClientOrderId::from("O-19700101-000000-001-001-2")]);
267        let report = OrderStatusReport {
268            activation_price: Some(Price::from("1.05000")),
269            limit_offset: Some(Decimal::from_str("0.123456789123456789").unwrap()),
270            trailing_offset: Some(Decimal::from_str("0.987654321987654321").unwrap()),
271            avg_px: Some(Decimal::from_str("1.23456789123456789").unwrap()),
272            ..report
273        };
274
275        let metadata = report.metadata();
276        let batch =
277            OrderStatusReport::encode_batch(&metadata, std::slice::from_ref(&report)).unwrap();
278        let decoded =
279            OrderStatusReport::decode_typed_batch(batch.schema().metadata(), batch).unwrap();
280
281        assert_eq!(decoded, vec![report]);
282    }
283
284    #[rstest]
285    #[case::reported(Some(Decimal::from_str("0.87654321987654321").unwrap()))]
286    #[case::zero(Some(Decimal::ZERO))]
287    #[case::unavailable(None)]
288    fn test_position_status_report_round_trip_preserves_decimal_precision(
289        #[case] liquidation_price: Option<Decimal>,
290    ) {
291        let report = PositionStatusReport {
292            account_id: AccountId::from("SIM-001"),
293            instrument_id: InstrumentId::from("AUDUSD.SIM"),
294            position_side: PositionSide::Long,
295            quantity: Quantity::from("100.25"),
296            signed_decimal_qty: Decimal::from_str("100.250000000123456789").unwrap(),
297            report_id: UUID4::default(),
298            ts_last: UnixNanos::from(1_000_000_000),
299            ts_init: UnixNanos::from(2_000_000_000),
300            venue_position_id: Some(PositionId::from("P-001")),
301            avg_px_open: Some(Decimal::from_str("1.23456789123456789").unwrap()),
302            avg_px_open_reconciliation: AvgPxReconciliation::OpeningOnly,
303            avg_px_open_precision: Some(4),
304            liquidation_price,
305        };
306        let metadata = report.metadata();
307        let batch =
308            PositionStatusReport::encode_batch(&metadata, std::slice::from_ref(&report)).unwrap();
309        let decoded =
310            PositionStatusReport::decode_typed_batch(batch.schema().metadata(), batch).unwrap();
311
312        assert_eq!(decoded, vec![report]);
313    }
314
315    #[rstest]
316    #[case::before_liquidation_price(1)]
317    #[case::before_avg_metadata(3)]
318    #[case::null_values(0)]
319    fn test_position_status_report_decodes_without_optional_metadata(
320        #[case] missing_columns: usize,
321    ) {
322        let report = PositionStatusReport::new(
323            AccountId::from("SIM-001"),
324            InstrumentId::from("AUDUSD.SIM"),
325            PositionSide::Short,
326            Quantity::from("100.25"),
327            UnixNanos::from(1_000_000_000),
328            UnixNanos::from(2_000_000_000),
329            None,
330            None,
331            Some(Decimal::from_str("1.2345").unwrap()),
332        );
333
334        let report = if missing_columns == 1 {
335            report
336                .with_avg_px_open_reconciliation(AvgPxReconciliation::OpeningOnly)
337                .with_avg_px_open_precision(4)
338        } else {
339            report
340        };
341
342        let metadata = report.metadata();
343
344        let batch = if missing_columns != 0 {
345            encode_batch(
346                "PositionStatusReport",
347                &metadata,
348                [&report],
349                &POSITION_STATUS_REPORT_FIELDS
350                    [..POSITION_STATUS_REPORT_FIELDS.len() - missing_columns],
351            )
352            .unwrap()
353        } else {
354            let mut row = serde_json::to_value(&report).unwrap();
355            let object = row.as_object_mut().unwrap();
356            object.insert(
357                "avg_px_open_reconciliation".to_string(),
358                serde_json::Value::Null,
359            );
360            object.insert("avg_px_open_precision".to_string(), serde_json::Value::Null);
361            object.insert("liquidation_price".to_string(), serde_json::Value::Null);
362            encode_batch(
363                "PositionStatusReport",
364                &metadata,
365                [&row],
366                POSITION_STATUS_REPORT_FIELDS,
367            )
368            .unwrap()
369        };
370
371        let decoded =
372            PositionStatusReport::decode_typed_batch(batch.schema().metadata(), batch).unwrap();
373
374        assert_eq!(decoded, vec![report]);
375    }
376}
nautilus_serialization/arrow/report.rs

nautilus_serialization/arrow/
report.rs
