1use std::{fs, path::PathBuf};
29
30use nautilus_common::enums::Environment;
31use nautilus_model::data::NautilusDataType;
32use strum::IntoEnumIterator;
33
34use crate::catalog::types::{CatalogDataType, catalog_data_type_from_path};
35
36pub trait CatalogPathPrefix {
38 fn path_prefix() -> &'static str;
40}
41
42#[must_use]
48pub fn normalize_path_separators(path: &str) -> String {
49 path.replace('\\', "/")
50}
51
52#[must_use]
54pub fn extract_path_components(path_str: &str) -> Vec<String> {
55 normalize_path_separators(path_str)
56 .split('/')
57 .filter(|s| !s.is_empty())
58 .map(ToString::to_string)
59 .collect()
60}
61
62#[must_use]
64pub fn local_to_object_store_path(local_path: &std::path::Path) -> String {
65 normalize_path_separators(&local_path.to_string_lossy())
66}
67
68#[must_use]
72pub fn make_object_store_path<I, S>(base_path: &str, components: I) -> String
73where
74 I: IntoIterator<Item = S>,
75 S: AsRef<str>,
76{
77 let mut parts = Vec::new();
78 let normalized_base = normalize_path_separators(base_path)
79 .trim_end_matches('/')
80 .to_string();
81
82 if !normalized_base.is_empty() {
83 parts.push(normalized_base);
84 }
85
86 for component in components {
87 let normalized_component = normalize_path_separators(component.as_ref())
88 .trim_start_matches('/')
89 .trim_end_matches('/')
90 .to_string();
91
92 if !normalized_component.is_empty() {
93 parts.push(normalized_component);
94 }
95 }
96
97 parts.join("/")
98}
99
100#[must_use]
104pub fn urisafe_instrument_id(instrument_id: &str) -> String {
105 instrument_id.replace('/', "").replace('^', "_")
106}
107
108#[must_use]
113pub fn safe_directory_identifier(identifier: &str) -> String {
114 let normalized = normalize_path_separators(identifier).replace("//", "/");
115 let segments: Vec<&str> = normalized
116 .split('/')
117 .filter(|s| !s.is_empty() && *s != "..")
118 .collect();
119 segments.join("/")
120}
121
122#[must_use]
127pub fn extract_identifier_from_path(file_path: &str) -> Option<&str> {
128 let parent = file_path.rfind(['/', '\\']).map(|idx| &file_path[..idx])?;
129 let identifier = parent
130 .rfind(['/', '\\'])
131 .map_or(parent, |idx| &parent[idx + 1..]);
132 (!identifier.is_empty()).then_some(identifier)
133}
134
135#[must_use]
139pub fn make_sql_safe_identifier(identifier: &str) -> String {
140 urisafe_instrument_id(identifier)
141 .chars()
142 .map(|c| {
143 if c.is_ascii_alphanumeric() {
144 c.to_ascii_lowercase()
145 } else {
146 '_'
147 }
148 })
149 .collect()
150}
151
152pub fn normalize_path_to_uri(path: &str) -> anyhow::Result<String> {
176 if path.contains("://") {
177 Ok(path.to_string())
179 } else if is_absolute_path(path) {
180 Ok(path_to_file_uri(path))
181 } else {
182 let current_dir = std::env::current_dir().map_err(|e| {
184 anyhow::anyhow!("Failed to resolve current directory for relative path '{path}': {e}")
185 })?;
186
187 let absolute_path = current_dir.join(path);
188 Ok(path_to_file_uri(&absolute_path.to_string_lossy()))
189 }
190}
191
192pub(crate) fn local_writer_directory(path: &str) -> anyhow::Result<PathBuf> {
201 let uri = normalize_path_to_uri(path)?;
202 anyhow::ensure!(
203 uri.starts_with("file://"),
204 "Streaming writers append to local files, writer path must be local, was {path}"
205 );
206 Ok(PathBuf::from(file_uri_to_native_path(&uri)))
207}
208
209pub fn create_local_directory(path: &str) -> anyhow::Result<()> {
218 let uri = normalize_path_to_uri(path)?;
219
220 if uri.starts_with("file://") {
221 fs::create_dir_all(file_uri_to_native_path(&uri))?;
222 }
223
224 Ok(())
225}
226
227#[must_use]
229pub const fn environment_directory(environment: Environment) -> &'static str {
230 match environment {
231 Environment::Backtest => "backtest",
232 Environment::Sandbox => "sandbox",
233 Environment::Live => "live",
234 }
235}
236
237#[must_use]
239pub fn environment_from_directory(directory: &str) -> Option<Environment> {
240 Environment::iter().find(|environment| environment_directory(*environment) == directory)
241}
242
243#[must_use]
245fn is_absolute_path(path: &str) -> bool {
246 path.starts_with('/') || path.starts_with("\\\\") || is_windows_drive_path(path)
247}
248
249#[must_use]
251fn is_windows_drive_path(path: &str) -> bool {
252 path.len() >= 3
253 && path.chars().nth(1) == Some(':')
254 && matches!(path.chars().nth(2), Some('\\' | '/'))
255}
256
257#[must_use]
266pub(crate) fn file_protocol_uri(path: &str) -> String {
267 if is_windows_drive_path(path) {
268 path_to_file_uri(path)
269 } else if path.is_empty() || is_absolute_path(path) {
270 format!("file://{path}")
271 } else {
272 path.to_string()
273 }
274}
275
276#[must_use]
278pub(crate) fn path_to_file_uri(path: &str) -> String {
279 if path.starts_with('/') {
280 format!("file://{path}")
282 } else if path.len() >= 3 && path.chars().nth(1) == Some(':') {
283 let normalized = normalize_path_separators(path);
285 format!("file:///{normalized}")
286 } else if let Some(without_prefix) = path.strip_prefix("\\\\") {
287 let normalized = normalize_path_separators(without_prefix);
289 format!("file://{normalized}")
290 } else {
291 format!("file://{path}")
293 }
294}
295
296#[cfg(windows)]
299pub(crate) fn file_uri_to_native_path(uri: &str) -> String {
300 let without_scheme = uri
301 .strip_prefix("file://")
302 .or_else(|| uri.strip_prefix("file:"))
303 .unwrap_or(uri);
304 let without_leading = without_scheme.trim_start_matches('/');
306 without_leading.replace('/', "\\")
307}
308
309#[cfg(not(windows))]
311pub(crate) fn file_uri_to_native_path(uri: &str) -> String {
312 uri.strip_prefix("file://").unwrap_or(uri).to_string()
313}
314
315#[must_use]
319pub(crate) fn escape_local_file_uri(uri: &str) -> String {
320 uri.replace('%', "%25")
321 .replace('#', "%23")
322 .replace('?', "%3F")
323}
324
325pub(crate) fn catalog_data_type_from_session_feather_path(
336 path: &str,
337 environment: Environment,
338 instance_id: &str,
339) -> anyhow::Result<CatalogDataType> {
340 let components = extract_path_components(path);
341 let type_index = session_type_index(&components, environment, instance_id, path)?;
342 if has_custom_data_prefix(&components, type_index) {
343 let type_name = components.get(type_index + 2).ok_or_else(|| {
344 anyhow::anyhow!(
345 "Cannot infer custom data type from Feather session path '{path}' for {}/{instance_id}",
346 environment_directory(environment)
347 )
348 })?;
349
350 return Ok(CatalogDataType::from(NautilusDataType::Custom {
351 type_name: type_name.clone(),
352 }));
353 }
354
355 let type_segment = components[type_index].as_str();
356 let file_name = components.last().map_or(type_segment, String::as_str);
357
358 let type_name = if type_segment.ends_with(".feather") {
359 file_name
360 .strip_suffix(".feather")
361 .and_then(|stem| stem.rsplit_once('_').map(|(type_name, _)| type_name))
362 .unwrap_or(type_segment)
363 } else {
364 type_segment
365 };
366
367 catalog_data_type_from_path(type_name)
368}
369
370pub(crate) fn identifier_from_session_feather_path(
374 path: &str,
375 environment: Environment,
376 instance_id: &str,
377) -> Option<String> {
378 let components = extract_path_components(path);
379 let type_index = session_type_index(&components, environment, instance_id, path).ok()?;
380 if has_custom_data_prefix(&components, type_index) {
381 let identifier_start = type_index + 3;
382 let file_index = components.len().checked_sub(1)?;
383 if identifier_start >= file_index {
384 return None;
385 }
386
387 return Some(components[identifier_start].clone());
388 }
389
390 if components[type_index] == "instruments" {
392 return None;
393 }
394
395 let identifier = components.get(type_index + 1)?;
396 let file_name = components.last()?;
397
398 if identifier.ends_with(".feather") {
399 return None;
400 }
401
402 (identifier != file_name).then(|| identifier.clone())
403}
404
405fn session_type_index(
406 components: &[String],
407 environment: Environment,
408 instance_id: &str,
409 path: &str,
410) -> anyhow::Result<usize> {
411 let directory = environment_directory(environment);
412 components
413 .windows(2)
414 .position(|window| window[0] == directory && window[1] == instance_id)
415 .and_then(|environment_index| environment_index.checked_add(2))
416 .filter(|type_index| *type_index < components.len())
417 .ok_or_else(|| {
418 anyhow::anyhow!(
419 "Cannot infer data type from Feather session path '{path}' for {directory}/{instance_id}"
420 )
421 })
422}
423
424fn has_custom_data_prefix(components: &[String], type_index: usize) -> bool {
425 components.get(type_index).is_some_and(|c| c == "data")
426 && components
427 .get(type_index + 1)
428 .is_some_and(|c| c == "custom")
429}
430
431#[cfg(test)]
432mod tests {
433 use nautilus_core::UUID4;
434 use rstest::rstest;
435 use tempfile::TempDir;
436
437 use super::*;
438
439 #[rstest]
440 fn create_local_directory_creates_local_path_and_skips_remote_uri() {
441 let directory = TempDir::new().unwrap();
442 let local = directory.path().join("catalog").join("nested");
443 let bucket = format!("nautilus-{}", UUID4::new());
444
445 create_local_directory(&local.to_string_lossy()).unwrap();
446 create_local_directory(&format!("s3://{bucket}/catalog")).unwrap();
447
448 assert!(local.is_dir());
449 assert!(!PathBuf::from("s3:").join(&bucket).exists());
451 }
452
453 #[rstest]
454 fn normalize_path_separators_converts_backslashes() {
455 assert_eq!(
456 normalize_path_separators(r"C:\catalog\backtest\run-1"),
457 "C:/catalog/backtest/run-1",
458 );
459 assert_eq!(
460 normalize_path_separators("C:/catalog/backtest/run-1"),
461 "C:/catalog/backtest/run-1",
462 );
463 assert_eq!(
464 normalize_path_separators(r"\\server\share\live\run-2"),
465 "//server/share/live/run-2",
466 );
467 }
468
469 #[rstest]
470 fn extract_path_components_handles_platform_separators() {
471 assert_eq!(
472 extract_path_components(r"C:\catalog\backtest\run-1"),
473 vec!["C:", "catalog", "backtest", "run-1"],
474 );
475 assert_eq!(
476 extract_path_components("/catalog/backtest/run-1/"),
477 vec!["catalog", "backtest", "run-1"],
478 );
479 assert!(extract_path_components("").is_empty());
480 }
481
482 #[rstest]
483 fn extract_identifier_from_path_handles_platform_separators() {
484 assert_eq!(
485 extract_identifier_from_path("data/quotes/EURUSD/file.parquet"),
486 Some("EURUSD"),
487 );
488 assert_eq!(
489 extract_identifier_from_path(r"data\quotes\EURUSD\file.parquet"),
490 Some("EURUSD"),
491 );
492 assert_eq!(
493 extract_identifier_from_path(r"C:\data\quotes\EURUSD\file.parquet"),
494 Some("EURUSD"),
495 );
496 assert_eq!(extract_identifier_from_path("file.parquet"), None);
497 assert_eq!(extract_identifier_from_path(""), None);
498 }
499
500 #[rstest]
501 fn safe_directory_identifier_blocks_windows_traversal() {
502 assert_eq!(safe_directory_identifier(r"..\\..\\etc"), "etc");
503 assert_eq!(safe_directory_identifier("../../etc"), "etc");
504 assert_eq!(safe_directory_identifier("run-1"), "run-1");
505 }
506
507 #[rstest]
508 fn test_normalize_path_to_uri() {
509 assert_eq!(
511 normalize_path_to_uri("/tmp/test").unwrap(),
512 "file:///tmp/test"
513 );
514
515 assert_eq!(
517 normalize_path_to_uri("C:\\tmp\\test").unwrap(),
518 "file:///C:/tmp/test"
519 );
520 assert_eq!(
521 normalize_path_to_uri("C:/tmp/test").unwrap(),
522 "file:///C:/tmp/test"
523 );
524 assert_eq!(
525 normalize_path_to_uri("D:\\data\\file.txt").unwrap(),
526 "file:///D:/data/file.txt"
527 );
528
529 assert_eq!(
531 normalize_path_to_uri("\\\\server\\share\\file").unwrap(),
532 "file://server/share/file"
533 );
534
535 assert_eq!(
537 normalize_path_to_uri("s3://bucket/path").unwrap(),
538 "s3://bucket/path"
539 );
540 assert_eq!(
541 normalize_path_to_uri("file:///tmp/test").unwrap(),
542 "file:///tmp/test"
543 );
544 assert_eq!(
545 normalize_path_to_uri("https://example.com/path").unwrap(),
546 "https://example.com/path"
547 );
548 }
549
550 #[rstest]
551 fn test_is_absolute_path() {
552 assert!(is_absolute_path("/tmp/test"));
554 assert!(is_absolute_path("/"));
555
556 assert!(is_absolute_path("C:\\tmp\\test"));
558 assert!(is_absolute_path("C:/tmp/test"));
559 assert!(is_absolute_path("D:\\"));
560 assert!(is_absolute_path("Z:/"));
561
562 assert!(is_absolute_path("\\\\server\\share"));
564 assert!(is_absolute_path("\\\\localhost\\c$"));
565
566 assert!(!is_absolute_path("tmp/test"));
568 assert!(!is_absolute_path("./test"));
569 assert!(!is_absolute_path("../test"));
570 assert!(!is_absolute_path("test.txt"));
571
572 assert!(!is_absolute_path(""));
574 assert!(!is_absolute_path("C"));
575 assert!(!is_absolute_path("C:"));
576 assert!(!is_absolute_path("\\"));
577 }
578
579 #[rstest]
580 fn file_protocol_uri_normalizes_windows_drive_path() {
581 assert_eq!(
582 file_protocol_uri(r"C:\data\catalog"),
583 "file:///C:/data/catalog",
584 );
585 assert_eq!(
586 file_protocol_uri("C:/data/catalog"),
587 "file:///C:/data/catalog"
588 );
589 assert_eq!(file_protocol_uri("/tmp/cat"), "file:///tmp/cat");
590 assert_eq!(
591 file_protocol_uri(r"\\server\share\catalog"),
592 r"file://\\server\share\catalog",
593 );
594 }
595
596 #[rstest]
597 fn test_path_to_file_uri() {
598 assert_eq!(path_to_file_uri("/tmp/test"), "file:///tmp/test");
600 assert_eq!(path_to_file_uri("/"), "file:///");
601
602 assert_eq!(path_to_file_uri("C:\\tmp\\test"), "file:///C:/tmp/test");
604 assert_eq!(path_to_file_uri("C:/tmp/test"), "file:///C:/tmp/test");
605 assert_eq!(path_to_file_uri("D:\\"), "file:///D:/");
606
607 assert_eq!(
609 path_to_file_uri("\\\\server\\share\\file"),
610 "file://server/share/file"
611 );
612 assert_eq!(
613 path_to_file_uri("\\\\localhost\\c$\\test"),
614 "file://localhost/c$/test"
615 );
616 }
617
618 #[rstest]
619 #[case(Environment::Backtest, "backtest")]
620 #[case(Environment::Sandbox, "sandbox")]
621 #[case(Environment::Live, "live")]
622 fn environment_directory_round_trips(
623 #[case] environment: Environment,
624 #[case] directory: &str,
625 ) {
626 assert_eq!(environment_directory(environment), directory);
627 assert_eq!(environment_from_directory(directory), Some(environment));
628 }
629
630 #[rstest]
631 #[case("BACKTEST")]
632 #[case("data")]
633 #[case("")]
634 fn environment_from_directory_rejects_other_folders(#[case] directory: &str) {
635 assert_eq!(environment_from_directory(directory), None);
636 }
637
638 #[rstest]
639 fn session_feather_paths_recover_type_and_identifier() {
640 let path = "backtest/run-1/quotes/EURUSD.SIM/0001.feather";
644 assert_eq!(
645 catalog_data_type_from_session_feather_path(path, Environment::Backtest, "run-1")
646 .unwrap(),
647 CatalogDataType::from(NautilusDataType::QuoteTick),
648 );
649 assert_eq!(
650 identifier_from_session_feather_path(path, Environment::Backtest, "run-1").as_deref(),
651 Some("EURUSD.SIM"),
652 );
653 assert_eq!(
654 catalog_data_type_from_session_feather_path(
655 "backtest/run-1/quotes_1000-1.feather",
656 Environment::Backtest,
657 "run-1",
658 )
659 .unwrap(),
660 CatalogDataType::from(NautilusDataType::QuoteTick),
661 );
662
663 let custom = "backtest/run-1/data/custom/MyType/inst/0001.feather";
664 assert_eq!(
665 catalog_data_type_from_session_feather_path(custom, Environment::Backtest, "run-1")
666 .unwrap(),
667 CatalogDataType::from(NautilusDataType::Custom {
668 type_name: "MyType".to_string(),
669 }),
670 );
671 assert_eq!(
672 identifier_from_session_feather_path(custom, Environment::Backtest, "run-1").as_deref(),
673 Some("inst"),
674 );
675 }
676
677 #[rstest]
678 #[case::prefixed_custom(
679 "catalog/backtest/run-1/data/custom/MyType/inst/0001.feather",
680 "custom/MyType",
681 Some("inst")
682 )]
683 #[case::custom_without_identifier(
684 "backtest/run-1/data/custom/MyType/0001.feather",
685 "custom/MyType",
686 None
687 )]
688 #[case::identifier_named_custom(
689 "backtest/run-1/bars/custom/0001.feather",
690 "bars",
691 Some("custom")
692 )]
693 #[case::type_without_identifier("backtest/run-1/quotes/0001.feather", "quotes", None)]
694 #[case::instrument_class_folder(
695 "backtest/run-1/instruments/currency_pair/instruments_1.feather",
696 "instruments",
697 None
698 )]
699 fn session_feather_paths_recover_type_and_identifier_from_layouts(
700 #[case] path: &str,
701 #[case] expected_type: &str,
702 #[case] expected_identifier: Option<&str>,
703 ) {
704 assert_eq!(
705 catalog_data_type_from_session_feather_path(path, Environment::Backtest, "run-1")
706 .unwrap(),
707 catalog_data_type_from_path(expected_type).unwrap(),
708 );
709 assert_eq!(
710 identifier_from_session_feather_path(path, Environment::Backtest, "run-1").as_deref(),
711 expected_identifier,
712 );
713 }
714
715 #[rstest]
716 #[case::missing_type_segment(
717 "backtest/run-1",
718 "Cannot infer data type from Feather session path 'backtest/run-1' for backtest/run-1"
719 )]
720 #[case::other_instance(
721 "backtest/run-2/quotes/0001.feather",
722 "Cannot infer data type from Feather session path 'backtest/run-2/quotes/0001.feather' for backtest/run-1"
723 )]
724 #[case::missing_custom_type(
725 "backtest/run-1/data/custom",
726 "Cannot infer custom data type from Feather session path 'backtest/run-1/data/custom' for backtest/run-1"
727 )]
728 fn session_feather_paths_reject_unrecognized_layouts(
729 #[case] path: &str,
730 #[case] expected: &str,
731 ) {
732 let error =
733 catalog_data_type_from_session_feather_path(path, Environment::Backtest, "run-1")
734 .unwrap_err();
735
736 assert_eq!(error.to_string(), expected);
737 assert_eq!(
738 identifier_from_session_feather_path(path, Environment::Backtest, "run-1"),
739 None
740 );
741 }
742
743 #[rstest]
744 fn session_feather_paths_recover_type_and_identifier_with_backslashes() {
745 let path = r"backtest\run-1\quotes\EURUSD.SIM\0001.feather";
746 assert_eq!(
747 catalog_data_type_from_session_feather_path(path, Environment::Backtest, "run-1")
748 .unwrap(),
749 CatalogDataType::from(NautilusDataType::QuoteTick),
750 );
751 assert_eq!(
752 identifier_from_session_feather_path(path, Environment::Backtest, "run-1").as_deref(),
753 Some("EURUSD.SIM"),
754 );
755 }
756}