qubit_fs/metadata/file_system_info.rs
1// =============================================================================
2// Copyright (c) 2026 Haixing Hu.
3//
4// SPDX-License-Identifier: Apache-2.0
5//
6// Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Immutable configured filesystem information.
9
10use std::fmt::Display;
11
12use crate::error::FsError;
13use crate::error::FsErrorKind;
14use crate::error::FsOperation;
15use crate::error::FsResult;
16use crate::metadata::FileSystemId;
17use crate::metadata::NonSensitiveMetadata;
18use crate::metadata::UserMetadata;
19use crate::path::PathSemantics;
20use crate::path::Uri;
21
22/// Construction-time local snapshot describing one filesystem object.
23///
24/// # Examples
25///
26/// ```
27/// use qubit_fs::metadata::FileSystemId;
28/// use qubit_fs::metadata::FileSystemInfo;
29/// use qubit_fs::path::PathSemantics;
30///
31/// let info = FileSystemInfo::new(
32/// FileSystemId::new("local-instance")?,
33/// "local",
34/// PathSemantics::Hierarchical,
35/// );
36/// assert_eq!("local", info.provider_id());
37/// # Ok::<(), qubit_fs::FsError>(())
38/// ```
39#[derive(Clone, Debug, PartialEq)]
40pub struct FileSystemInfo {
41 /// Stable identity of the configured filesystem.
42 id: FileSystemId,
43 /// Stable identity of the provider implementation.
44 provider_id: Box<str>,
45 /// Validated URI schemes accepted by this filesystem.
46 schemes: Vec<String>,
47 /// Logical path model used by the provider.
48 path_semantics: PathSemantics,
49 /// Provider metadata safe for automatic structural formatting.
50 provider_metadata: NonSensitiveMetadata,
51}
52
53impl FileSystemInfo {
54 /// Creates a filesystem information snapshot without scheme aliases.
55 ///
56 /// # Parameters
57 /// - `id`: Stable identity for the configured filesystem.
58 /// - `provider_id`: Stable identifier of the provider implementation.
59 /// - `path_semantics`: Logical path model used by the provider.
60 #[inline]
61 #[must_use]
62 pub fn new(id: FileSystemId, provider_id: impl Display, path_semantics: PathSemantics) -> Self {
63 Self {
64 id,
65 provider_id: provider_id.to_string().into(),
66 schemes: Vec::new(),
67 path_semantics,
68 provider_metadata: NonSensitiveMetadata::new(),
69 }
70 }
71
72 /// Adds one validated supported URI scheme.
73 ///
74 /// # Errors
75 ///
76 /// Returns an invalid-URI error when `scheme` is not a valid URI scheme.
77 ///
78 /// # Parameters
79 /// - `scheme`: URI scheme alias to validate and add if not already present.
80 pub fn with_scheme(mut self, scheme: &str) -> FsResult<Self> {
81 let mut characters = scheme.bytes();
82 let valid = characters.next().is_some_and(|first| first.is_ascii_alphabetic())
83 && characters.all(|next| next.is_ascii_alphanumeric() || matches!(next, b'+' | b'-' | b'.'));
84 if !valid {
85 return Err(FsError::new(
86 FsErrorKind::InvalidUri,
87 FsOperation::ParseUri,
88 "invalid URI scheme",
89 ));
90 }
91 let scheme = Uri::parse(&format!("{scheme}:/"))?.scheme().to_owned();
92 if !self.schemes.contains(&scheme) {
93 self.schemes.push(scheme);
94 }
95 Ok(self)
96 }
97
98 /// Replaces the scrubbed provider metadata snapshot.
99 ///
100 /// `metadata` has already rejected credential-like keys. Providers must
101 /// expose secrets only through an external credential boundary, never
102 /// through this debug-visible local snapshot.
103 ///
104 /// # Parameters
105 /// - `metadata`: User metadata whose keys have passed credential-name
106 /// checks; values are retained as supplied.
107 #[inline]
108 #[must_use]
109 pub fn with_provider_metadata(mut self, metadata: UserMetadata) -> Self {
110 self.provider_metadata = NonSensitiveMetadata::from(metadata);
111 self
112 }
113
114 /// Returns the configured filesystem identity.
115 #[inline]
116 #[must_use]
117 pub const fn id(&self) -> &FileSystemId {
118 &self.id
119 }
120
121 /// Returns the provider identity that created this filesystem.
122 #[inline]
123 #[must_use]
124 pub const fn provider_id(&self) -> &str {
125 &self.provider_id
126 }
127
128 /// Returns supported URI schemes in provider-defined order.
129 #[inline]
130 #[must_use]
131 pub fn schemes(&self) -> &[String] {
132 &self.schemes
133 }
134
135 /// Returns the provider-local path semantics.
136 #[inline]
137 #[must_use]
138 pub const fn path_semantics(&self) -> PathSemantics {
139 self.path_semantics
140 }
141
142 /// Returns scrubbed provider-specific information.
143 #[inline]
144 #[must_use]
145 pub const fn provider_metadata(&self) -> &NonSensitiveMetadata {
146 &self.provider_metadata
147 }
148}