Skip to main content

nautilus_core/serialization/
timestamps.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//! In-place timestamp rewriting for payload value trees.
17//!
18//! Field names determine conversion, including inside general metadata maps.
19
20use anyhow::Context;
21use jiff::Timestamp;
22use serde_json::Value;
23
24/// Converts `ts_*`, `expire_time`, and `expire_time_ns` fields to ISO 8601 or nanosecond strings.
25///
26/// Rewrites unsigned integers and decimal strings in nested objects and arrays.
27/// ISO output uses UTC with nine fractional digits and a `Z` suffix.
28/// Existing nonnumeric strings are preserved.
29/// Preserves `exec_algorithm_params` and the `info` maps in `OrderFilled` and `OrderFillVoided`.
30///
31/// # Errors
32///
33/// Returns an error if [`Timestamp`] rejects a value; its range includes all `u64` nanoseconds.
34pub fn serialize(value: &mut Value, iso8601: bool) -> anyhow::Result<()> {
35    match value {
36        Value::Object(map) => {
37            let string_info = has_string_info(map);
38            for (key, value) in map
39                .iter_mut()
40                .filter(|(key, _)| !is_opaque(key, string_info))
41            {
42                if is_timestamp(key)
43                    && let Some(nanos) = value
44                        .as_u64()
45                        .or_else(|| value.as_str().and_then(|s| s.parse::<u64>().ok()))
46                {
47                    let timestamp = if iso8601 {
48                        let timestamp = Timestamp::from_nanosecond(i128::from(nanos))?;
49                        format!("{timestamp:.9}")
50                    } else {
51                        nanos.to_string()
52                    };
53
54                    *value = Value::String(timestamp);
55                } else {
56                    serialize(value, iso8601)?;
57                }
58            }
59        }
60        Value::Array(values) => {
61            for value in values {
62                serialize(value, iso8601)?;
63            }
64        }
65        _ => {}
66    }
67
68    Ok(())
69}
70
71/// Converts RFC 3339 and nanosecond strings in timestamp fields to nanosecond integers.
72///
73/// Rewrites nested objects and arrays in place. Timestamp strings require `Z` or a numeric UTC offset.
74/// Preserves strings that do not parse as timestamps.
75/// Preserves `exec_algorithm_params` and the `info` maps in `OrderFilled` and `OrderFillVoided`.
76///
77/// # Errors
78///
79/// Returns an error if a parsed timestamp is outside the unsigned nanosecond range.
80pub fn deserialize(value: &mut Value) -> anyhow::Result<()> {
81    match value {
82        Value::Object(map) => {
83            let string_info = has_string_info(map);
84            for (key, value) in map
85                .iter_mut()
86                .filter(|(key, _)| !is_opaque(key, string_info))
87            {
88                if is_timestamp(key)
89                    && let Value::String(text) = value
90                {
91                    if let Ok(nanos) = text.parse::<u64>() {
92                        *value = Value::Number(nanos.into());
93                    } else if let Ok(timestamp) = text.parse::<Timestamp>() {
94                        let nanos = u64::try_from(timestamp.as_nanosecond())
95                            .context("timestamp is outside the unsigned nanosecond range")?;
96                        *value = Value::Number(nanos.into());
97                    }
98                } else {
99                    deserialize(value)?;
100                }
101            }
102        }
103        Value::Array(values) => {
104            for value in values {
105                deserialize(value)?;
106            }
107        }
108        _ => {}
109    }
110
111    Ok(())
112}
113
114fn is_timestamp(key: &str) -> bool {
115    key.starts_with("ts_") || matches!(key, "expire_time" | "expire_time_ns")
116}
117
118fn has_string_info(map: &serde_json::Map<String, Value>) -> bool {
119    matches!(
120        map.get("type").and_then(Value::as_str),
121        Some("OrderFilled" | "OrderFillVoided")
122    )
123}
124
125fn is_opaque(key: &str, string_info: bool) -> bool {
126    key == "exec_algorithm_params" || (string_info && key == "info")
127}
128
129#[cfg(test)]
130mod tests {
131    use rstest::rstest;
132    use serde::Serialize;
133
134    use super::*;
135
136    #[derive(Serialize)]
137    struct Payload {
138        ts_event: u64,
139        ts_init: u64,
140        expire_time_ns: Option<u64>,
141        expire_time: u64,
142        value: u64,
143        nested: Vec<Nested>,
144    }
145
146    #[derive(Serialize)]
147    struct Nested {
148        ts_event: u64,
149        text: &'static str,
150    }
151
152    #[rstest]
153    #[case("1969-12-31T23:59:59.999999999Z")]
154    #[case("3000-01-01T00:00:00Z")]
155    fn test_timestamp_outside_unsigned_range_is_rejected(#[case] timestamp: &str) {
156        let mut value = Value::Object(serde_json::Map::from_iter([(
157            "ts_event".into(),
158            Value::String(timestamp.into()),
159        )]));
160
161        let error = deserialize(&mut value).unwrap_err();
162
163        assert_eq!(
164            error.to_string(),
165            "timestamp is outside the unsigned nanosecond range"
166        );
167    }
168
169    #[rstest]
170    fn test_execution_parameters_preserve_timestamp_keys(#[values(false, true)] iso8601: bool) {
171        let mut value = serde_json::json!({
172            "ts_event": 123,
173            "nested": [{"exec_algorithm_params": {
174                "ts_start": "9007199254740993",
175                "ts_end": "1970-01-01T00:00:00.000000987Z"
176            }}]
177        });
178        let original = value.clone();
179
180        serialize(&mut value, iso8601).unwrap();
181
182        assert_eq!(value["nested"], original["nested"]);
183
184        deserialize(&mut value).unwrap();
185
186        assert_eq!(value, original);
187    }
188
189    #[rstest]
190    #[case(false, "123", "456", "789", "987", "9007199254740993")]
191    #[case(
192        true,
193        "1970-01-01T00:00:00.000000123Z",
194        "1970-01-01T00:00:00.000000456Z",
195        "1970-01-01T00:00:00.000000789Z",
196        "1970-01-01T00:00:00.000000987Z",
197        "1970-04-15T05:59:59.254740993Z"
198    )]
199    fn test_timestamp_fields_round_trip(
200        #[case] iso8601: bool,
201        #[case] ts_event: &str,
202        #[case] ts_init: &str,
203        #[case] expire_time_ns: &str,
204        #[case] expire_time: &str,
205        #[case] nested: &str,
206        #[values(false, true)] strings: bool,
207    ) {
208        let payload = Payload {
209            ts_event: 123,
210            ts_init: 456,
211            expire_time_ns: Some(789),
212            expire_time: 987,
213            value: 42,
214            nested: vec![Nested {
215                ts_event: 9_007_199_254_740_993,
216                text: "unchanged",
217            }],
218        };
219
220        let original = serde_json::to_value(payload).unwrap();
221        let mut value = original.clone();
222
223        if strings {
224            for field in ["ts_event", "ts_init", "expire_time_ns", "expire_time"] {
225                value[field] = Value::String(value[field].to_string());
226            }
227
228            value["nested"][0]["ts_event"] = Value::String("9007199254740993".into());
229        }
230
231        serialize(&mut value, iso8601).unwrap();
232
233        assert_eq!(value["ts_event"], ts_event);
234        assert_eq!(value["ts_init"], ts_init);
235        assert_eq!(value["expire_time_ns"], expire_time_ns);
236        assert_eq!(value["expire_time"], expire_time);
237        assert_eq!(value["value"], 42);
238        assert_eq!(value["nested"][0]["ts_event"], nested);
239        assert_eq!(value["nested"][0]["text"], "unchanged");
240
241        deserialize(&mut value).unwrap();
242
243        assert_eq!(value, original);
244    }
245}