Skip to main content

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}