Skip to main content

nautilus_core/ffi/
parsing.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//! Converts common C types (primarily UTF-8 encoded `char *` pointers) into
17//! the Rust data structures used throughout NautilusTrader.
18//!
19//! The conversions are opinionated:
20//!
21//! - JSON is used as the interchange format for complex structures.
22//! - `ustr::Ustr` is preferred over `String` where possible for its performance benefits.
23//!
24//! Unless otherwise noted, input pointers must reference valid, null-terminated C strings.
25
26use std::{
27    collections::HashMap,
28    ffi::{CStr, CString, c_char},
29};
30
31use serde::de::DeserializeOwned;
32use serde_json::Value;
33use ustr::Ustr;
34
35use crate::{
36    ffi::{abort_on_panic, string::cstr_as_str},
37    string::parsing::min_increment_precision_from_str,
38};
39
40/// Convert a C bytes pointer into an owned `Vec<String>`.
41///
42/// # Safety
43///
44/// Assumes `ptr` is a valid C string pointer.
45///
46/// # Errors
47///
48/// Returns an error if the string contains invalid UTF-8 or JSON, or is not an array of strings.
49///
50/// # Panics
51///
52/// Panics if `ptr` is null.
53#[expect(
54    clippy::panic_in_result_fn,
55    reason = "a null pointer violates the unsafe caller contract"
56)]
57pub unsafe fn bytes_to_string_vec(ptr: *const c_char) -> serde_json::Result<Vec<String>> {
58    assert!(!ptr.is_null(), "`ptr` was NULL");
59
60    // SAFETY: Caller guarantees ptr is valid per function contract
61    let c_str = unsafe { CStr::from_ptr(ptr) };
62    serde_json::from_slice(c_str.to_bytes())
63}
64
65/// Convert a slice of `String` into a C string pointer (JSON encoded).
66///
67/// # Panics
68///
69/// Panics if JSON serialization fails or if the generated string contains interior null bytes.
70#[must_use]
71pub fn string_vec_to_bytes(strings: &[String]) -> *const c_char {
72    let json_string = serde_json::to_string(strings).expect("Failed to serialize strings to JSON");
73    let c_string = CString::new(json_string).expect("JSON string contains interior null bytes");
74
75    c_string.into_raw()
76}
77
78/// Convert a C bytes pointer into an owned `Option<HashMap<String, Value>>`.
79///
80/// # Safety
81///
82/// A non-null `ptr` must reference a valid C string.
83///
84/// # Errors
85///
86/// Returns an error if a non-null string contains invalid UTF-8 or JSON, or is not an object.
87pub unsafe fn optional_bytes_to_json(
88    ptr: *const c_char,
89) -> serde_json::Result<Option<HashMap<String, Value>>> {
90    // SAFETY: A non-null pointer is valid under the caller's contract
91    unsafe { optional_json_from_cstr(ptr) }
92}
93
94/// Convert a C bytes pointer into an owned `Option<HashMap<Ustr, Ustr>>`.
95///
96/// # Safety
97///
98/// A non-null `ptr` must reference a valid C string.
99///
100/// # Errors
101///
102/// Returns an error if a non-null string contains invalid UTF-8 or JSON, or is not a
103/// string-valued object.
104pub unsafe fn optional_bytes_to_str_map(
105    ptr: *const c_char,
106) -> serde_json::Result<Option<HashMap<Ustr, Ustr>>> {
107    // SAFETY: A non-null pointer is valid under the caller's contract
108    unsafe { optional_json_from_cstr(ptr) }
109}
110
111/// Convert a C bytes pointer into an owned `Option<Vec<String>>`.
112///
113/// # Safety
114///
115/// A non-null `ptr` must reference a valid C string.
116///
117/// # Errors
118///
119/// Returns an error if a non-null string contains invalid UTF-8 or JSON, or is not an array of
120/// strings.
121pub unsafe fn optional_bytes_to_str_vec(
122    ptr: *const c_char,
123) -> serde_json::Result<Option<Vec<String>>> {
124    // SAFETY: A non-null pointer is valid under the caller's contract
125    unsafe { optional_json_from_cstr(ptr) }
126}
127
128/// # Safety
129///
130/// If `ptr` is non-null, it must reference a valid, null-terminated C string that remains
131/// unchanged for the duration of this call.
132unsafe fn optional_json_from_cstr<T>(ptr: *const c_char) -> serde_json::Result<Option<T>>
133where
134    T: DeserializeOwned,
135{
136    if ptr.is_null() {
137        return Ok(None);
138    }
139
140    // SAFETY: A non-null pointer is valid under the caller's contract
141    let json = unsafe { CStr::from_ptr(ptr) };
142    serde_json::from_slice(json.to_bytes()).map(Some)
143}
144
145/// Return the decimal precision inferred from the given C string.
146///
147/// # Safety
148///
149/// Assumes `ptr` is a valid C string pointer.
150///
151/// # Panics
152///
153/// Panics if `ptr` is null, contains invalid UTF-8, or has a missing or non-numeric `e-` exponent.
154#[unsafe(no_mangle)]
155pub unsafe extern "C" fn precision_from_cstr(ptr: *const c_char) -> u8 {
156    abort_on_panic(|| {
157        assert!(!ptr.is_null(), "`ptr` was NULL");
158        // SAFETY: Caller guarantees ptr is valid per function contract
159        let s = unsafe { cstr_as_str(ptr) };
160        precision_from_v1_str(s)
161    })
162}
163
164/// Return the minimum price increment decimal precision inferred from the given C string.
165///
166/// # Safety
167///
168/// Assumes `ptr` is a valid C string pointer.
169///
170/// # Panics
171///
172/// Panics if `ptr` is null or contains invalid UTF-8.
173#[unsafe(no_mangle)]
174pub unsafe extern "C" fn min_increment_precision_from_cstr(ptr: *const c_char) -> u8 {
175    abort_on_panic(|| {
176        assert!(!ptr.is_null(), "`ptr` was NULL");
177        // SAFETY: Caller guarantees ptr is valid per function contract
178        let s = unsafe { cstr_as_str(ptr) };
179        min_increment_precision_from_str(s)
180    })
181}
182
183// TODO: Remove this temporary parser when v1 drops its legacy source-text precision contract
184fn precision_from_v1_str(value: &str) -> u8 {
185    let value = value.trim().to_ascii_lowercase();
186
187    if value.contains("e-") {
188        let exponent = value
189            .split("e-")
190            .nth(1)
191            .expect("Invalid scientific notation format: missing exponent after 'e-'");
192
193        if let Ok(exponent) = exponent.parse::<u64>() {
194            return u8::try_from(exponent).unwrap_or(u8::MAX);
195        }
196
197        assert!(
198            !exponent.is_empty(),
199            "Invalid scientific notation format: missing exponent after 'e-'"
200        );
201
202        if exponent.chars().all(|c| c.is_ascii_digit()) {
203            return u8::MAX;
204        }
205
206        panic!("Invalid scientific notation exponent '{exponent}': must be a valid number");
207    }
208
209    value.split_once('.').map_or(0, |(_, decimal)| {
210        u8::try_from(decimal.len()).unwrap_or(u8::MAX)
211    })
212}
213
214/// Return a `bool` value from the given `u8`.
215#[must_use]
216pub const fn u8_as_bool(value: u8) -> bool {
217    value != 0
218}
219
220#[cfg(test)]
221mod tests {
222    use std::ffi::CString;
223
224    use rstest::rstest;
225
226    use super::*;
227
228    #[rstest]
229    fn test_optional_bytes_to_json_null() {
230        let ptr = std::ptr::null();
231        let result = unsafe { optional_bytes_to_json(ptr) }.unwrap();
232        assert_eq!(result, None);
233        assert_eq!(unsafe { optional_bytes_to_str_map(ptr) }.unwrap(), None);
234        assert_eq!(unsafe { optional_bytes_to_str_vec(ptr) }.unwrap(), None);
235    }
236
237    #[rstest]
238    fn test_optional_bytes_to_json_empty() {
239        let json_str = CString::new("{}").unwrap();
240        let ptr = json_str.as_ptr().cast::<c_char>();
241        let result = unsafe { optional_bytes_to_json(ptr) }.unwrap();
242        assert_eq!(result, Some(HashMap::new()));
243        assert_eq!(
244            unsafe { optional_bytes_to_str_map(ptr) }.unwrap(),
245            Some(HashMap::new())
246        );
247    }
248
249    #[rstest]
250    fn test_string_vec_to_bytes_valid() {
251        let strings = vec!["value1", "value2", "value3"]
252            .into_iter()
253            .map(String::from)
254            .collect::<Vec<String>>();
255
256        let ptr = string_vec_to_bytes(&strings);
257
258        let result = unsafe { bytes_to_string_vec(ptr) }.unwrap();
259        assert_eq!(result, strings);
260    }
261
262    #[rstest]
263    fn test_string_vec_to_bytes_empty() {
264        let strings = Vec::new();
265        let ptr = string_vec_to_bytes(&strings);
266
267        let result = unsafe { bytes_to_string_vec(ptr) }.unwrap();
268        assert_eq!(result, strings);
269        assert_eq!(
270            unsafe { optional_bytes_to_str_vec(ptr) }.unwrap(),
271            Some(Vec::new())
272        );
273    }
274
275    #[rstest]
276    fn test_bytes_to_string_vec_valid() {
277        let json_str = CString::new(r#"["value1", "value2", "value3"]"#).unwrap();
278        let ptr = json_str.as_ptr().cast::<c_char>();
279        let result = unsafe { bytes_to_string_vec(ptr) }.unwrap();
280
281        let expected_vec = vec!["value1", "value2", "value3"]
282            .into_iter()
283            .map(String::from)
284            .collect::<Vec<String>>();
285
286        assert_eq!(result, expected_vec);
287    }
288
289    #[rstest]
290    fn test_bytes_to_string_vec_invalid() {
291        let json_str = CString::new(r#"["value1", 42, "value3"]"#).unwrap();
292        let ptr = json_str.as_ptr().cast::<c_char>();
293        let error = unsafe { bytes_to_string_vec(ptr) }.unwrap_err();
294        assert_eq!(error.classify(), serde_json::error::Category::Data);
295    }
296
297    #[rstest]
298    #[case::empty(Vec::new(), serde_json::error::Category::Eof, 0)]
299    #[case::invalid_utf8(vec![0xff], serde_json::error::Category::Syntax, 1)]
300    fn test_json_decoders_reject_invalid_bytes(
301        #[case] bytes: Vec<u8>,
302        #[case] category: serde_json::error::Category,
303        #[case] column: usize,
304    ) {
305        let input = CString::new(bytes).unwrap();
306        let ptr = input.as_ptr();
307
308        let errors = [
309            // SAFETY: `ptr` references `input`, which remains alive and unchanged
310            unsafe { bytes_to_string_vec(ptr) }.unwrap_err(),
311            // SAFETY: `ptr` references `input`, which remains alive and unchanged
312            unsafe { optional_bytes_to_json(ptr) }.unwrap_err(),
313            // SAFETY: `ptr` references `input`, which remains alive and unchanged
314            unsafe { optional_bytes_to_str_map(ptr) }.unwrap_err(),
315            // SAFETY: `ptr` references `input`, which remains alive and unchanged
316            unsafe { optional_bytes_to_str_vec(ptr) }.unwrap_err(),
317        ];
318
319        for error in errors {
320            assert_eq!(error.classify(), category);
321            assert_eq!(error.line(), 1);
322            assert_eq!(error.column(), column);
323        }
324    }
325
326    #[rstest]
327    fn test_json_decoders_reject_invalid_utf8_strings() {
328        let array = CString::new([b'[', b'"', 0xff, b'"', b']']).unwrap();
329        let object = CString::new([b'{', b'"', b'k', b'"', b':', b'"', 0xff, b'"', b'}']).unwrap();
330
331        let errors = [
332            // SAFETY: `array` remains alive and unchanged during the call
333            (
334                unsafe { bytes_to_string_vec(array.as_ptr()) }.unwrap_err(),
335                3,
336            ),
337            // SAFETY: `array` remains alive and unchanged during the call
338            (
339                unsafe { optional_bytes_to_str_vec(array.as_ptr()) }.unwrap_err(),
340                3,
341            ),
342            // SAFETY: `object` remains alive and unchanged during the call
343            (
344                unsafe { optional_bytes_to_json(object.as_ptr()) }.unwrap_err(),
345                7,
346            ),
347            // SAFETY: `object` remains alive and unchanged during the call
348            (
349                unsafe { optional_bytes_to_str_map(object.as_ptr()) }.unwrap_err(),
350                7,
351            ),
352        ];
353
354        for (error, column) in errors {
355            assert_eq!(error.classify(), serde_json::error::Category::Syntax);
356            assert_eq!(error.line(), 1);
357            assert_eq!(error.column(), column);
358        }
359    }
360
361    #[rstest]
362    fn test_optional_bytes_to_json_valid() {
363        let json_str = CString::new(r#"{"key1": "value1", "key2": 2}"#).unwrap();
364        let ptr = json_str.as_ptr().cast::<c_char>();
365        let result = unsafe { optional_bytes_to_json(ptr) }.unwrap();
366        let mut expected_map = HashMap::new();
367        expected_map.insert("key1".to_owned(), Value::String("value1".to_owned()));
368        expected_map.insert(
369            "key2".to_owned(),
370            Value::Number(serde_json::Number::from(2)),
371        );
372        assert_eq!(result, Some(expected_map));
373    }
374
375    #[rstest]
376    fn test_optional_bytes_to_str_map_valid() {
377        let json_str = CString::new(r#"{"key1": "value1", "key2": "value2"}"#).unwrap();
378        let ptr = json_str.as_ptr().cast::<c_char>();
379        let result = unsafe { optional_bytes_to_str_map(ptr) }.unwrap();
380        let expected_map = HashMap::from([
381            (Ustr::from("key1"), Ustr::from("value1")),
382            (Ustr::from("key2"), Ustr::from("value2")),
383        ]);
384        assert_eq!(result, Some(expected_map));
385    }
386
387    #[rstest]
388    fn test_optional_bytes_to_str_vec_valid() {
389        let json_str = CString::new(r#"["value1", "value2", "value3"]"#).unwrap();
390        let ptr = json_str.as_ptr().cast::<c_char>();
391        let result = unsafe { optional_bytes_to_str_vec(ptr) }.unwrap();
392        let expected_vec = vec![
393            "value1".to_string(),
394            "value2".to_string(),
395            "value3".to_string(),
396        ];
397        assert_eq!(result, Some(expected_vec));
398    }
399
400    #[rstest]
401    fn test_optional_bytes_to_json_invalid() {
402        let json_str = CString::new(r#"{"key1": "value1", "key2": }"#).unwrap();
403        let ptr = json_str.as_ptr().cast::<c_char>();
404        let error = unsafe { optional_bytes_to_json(ptr) }.unwrap_err();
405        assert_eq!(error.classify(), serde_json::error::Category::Syntax);
406    }
407
408    #[rstest]
409    #[case("1e8", 0)]
410    #[case("123", 0)]
411    #[case("123.45", 2)]
412    #[case("123.456789", 6)]
413    #[case("2.5e4", 3)]
414    #[case("7.89E1", 4)]
415    #[case("1.23456789e-2", 2)]
416    #[case("1.23456789e-12", 12)]
417    fn test_precision_from_cstr(#[case] input: &str, #[case] expected: u8) {
418        let c_str = CString::new(input).unwrap();
419        assert_eq!(unsafe { precision_from_cstr(c_str.as_ptr()) }, expected);
420    }
421
422    #[rstest]
423    #[case("1.010", 2)]
424    #[case("1.5e-2", 3)]
425    #[case("0.0001000", 4)]
426    fn test_min_increment_precision_from_cstr(#[case] input: &str, #[case] expected: u8) {
427        let c_str = CString::new(input).unwrap();
428        assert_eq!(
429            unsafe { min_increment_precision_from_cstr(c_str.as_ptr()) },
430            expected
431        );
432    }
433
434    #[rstest]
435    #[case(0, false)]
436    #[case(1, true)]
437    #[case(u8::MAX, true)]
438    fn test_u8_as_bool(#[case] input: u8, #[case] expected: bool) {
439        assert_eq!(u8_as_bool(input), expected);
440    }
441}