Skip to main content

qubit_fs/metadata/
file_system_capabilities.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//! Filesystem capability support.
9
10use std::fmt::Debug;
11use std::fmt::Formatter;
12use std::fmt::Result as FmtResult;
13
14use crate::metadata::FileSystemCapability;
15use crate::metadata::FileSystemCapabilitySupport;
16
17const CAPABILITY_DEPENDENCIES: &[(FileSystemCapability, FileSystemCapability)] = &[
18    (FileSystemCapability::RangeRead, FileSystemCapability::Read),
19    (FileSystemCapability::ConditionalRead, FileSystemCapability::Read),
20    (FileSystemCapability::ChecksumValidation, FileSystemCapability::Read),
21    (FileSystemCapability::Append, FileSystemCapability::Write),
22    (FileSystemCapability::ConditionalWrite, FileSystemCapability::Write),
23    (FileSystemCapability::AtomicReplace, FileSystemCapability::Write),
24    (FileSystemCapability::DurableWrite, FileSystemCapability::Write),
25    (FileSystemCapability::RecursiveDelete, FileSystemCapability::Delete),
26    (FileSystemCapability::ConditionalDelete, FileSystemCapability::Delete),
27    (FileSystemCapability::AtomicRename, FileSystemCapability::Rename),
28    (FileSystemCapability::ServerSideCopy, FileSystemCapability::Copy),
29    (FileSystemCapability::AtomicFileCopy, FileSystemCapability::Copy),
30    (FileSystemCapability::AtomicTreeCopy, FileSystemCapability::Copy),
31    (FileSystemCapability::DurableFileCopy, FileSystemCapability::Copy),
32    (FileSystemCapability::DurableTreeCopy, FileSystemCapability::Copy),
33    (FileSystemCapability::DurableRename, FileSystemCapability::Rename),
34];
35
36/// Stable typed capability support for one configured filesystem.
37///
38/// Capabilities have one of two support strengths: conditional capabilities
39/// may be attempted and can still be rejected for an individual request, while
40/// guaranteed capabilities are promised for every valid request in scope.
41/// Derived capabilities must not be stronger than their base capability.
42///
43/// # Examples
44///
45/// ```
46/// use qubit_fs::metadata::{FileSystemCapabilities, FileSystemCapability,
47///     FileSystemCapabilitySupport};
48///
49/// let capabilities = FileSystemCapabilities::new()
50///     .with_conditional(FileSystemCapability::Read)
51///     .with_conditional(FileSystemCapability::RangeRead);
52/// assert_eq!(capabilities.support(FileSystemCapability::RangeRead),
53///     FileSystemCapabilitySupport::Conditional);
54/// assert_eq!(capabilities.support(FileSystemCapability::Write),
55///     FileSystemCapabilitySupport::Unsupported);
56/// assert!(capabilities.missing_dependency().is_none());
57///
58/// let invalid = FileSystemCapabilities::new()
59///     .with_guaranteed(FileSystemCapability::RangeRead)
60///     .with_conditional(FileSystemCapability::Read);
61/// assert_eq!(invalid.missing_dependency(), Some((
62///     FileSystemCapability::RangeRead, FileSystemCapability::Read)));
63/// ```
64#[derive(Clone, Copy, Eq, PartialEq)]
65pub struct FileSystemCapabilities {
66    /// Capabilities that can be attempted conditionally.
67    conditional: u128,
68    /// Capabilities guaranteed for every valid request in this scope.
69    guaranteed: u128,
70}
71
72impl FileSystemCapabilities {
73    /// Creates an empty capability set.
74    #[inline]
75    #[must_use]
76    pub const fn new() -> Self {
77        Self {
78            conditional: 0,
79            guaranteed: 0,
80        }
81    }
82
83    /// Returns a copy with one additional conditional capability.
84    ///
85    /// # Parameters
86    /// - `capability`: Capability that may be attempted but is not guaranteed
87    ///   for every valid request.
88    #[inline]
89    #[must_use]
90    pub const fn with_conditional(self, capability: FileSystemCapability) -> Self {
91        self.set_support(capability, FileSystemCapabilitySupport::Conditional)
92    }
93
94    /// Returns a copy with one additional guaranteed capability.
95    ///
96    /// # Parameters
97    /// - `capability`: Capability promised for every valid request in scope.
98    #[inline]
99    #[must_use]
100    pub const fn with_guaranteed(self, capability: FileSystemCapability) -> Self {
101        self.set_support(capability, FileSystemCapabilitySupport::Guaranteed)
102    }
103
104    /// Replaces the support status of one capability.
105    ///
106    /// # Parameters
107    /// - `capability`: Capability whose current status is replaced.
108    /// - `support`: New support strength to record for that capability.
109    #[inline]
110    #[must_use]
111    pub const fn set_support(mut self, capability: FileSystemCapability, support: FileSystemCapabilitySupport) -> Self {
112        let bit = capability.bit();
113        self.conditional &= !bit;
114        self.guaranteed &= !bit;
115        match support {
116            FileSystemCapabilitySupport::Unsupported => {}
117            FileSystemCapabilitySupport::Conditional => {
118                self.conditional |= bit;
119            }
120            FileSystemCapabilitySupport::Guaranteed => {
121                self.guaranteed |= bit;
122            }
123        }
124        self
125    }
126
127    /// Returns the support status of `capability`.
128    ///
129    /// # Parameters
130    /// - `capability`: Capability whose advertised support is queried.
131    #[inline]
132    pub const fn support(&self, capability: FileSystemCapability) -> FileSystemCapabilitySupport {
133        let bit = capability.bit();
134        if self.guaranteed & bit != 0 {
135            FileSystemCapabilitySupport::Guaranteed
136        } else if self.conditional & bit != 0 {
137            FileSystemCapabilitySupport::Conditional
138        } else {
139            FileSystemCapabilitySupport::Unsupported
140        }
141    }
142
143    /// Returns whether the provider can attempt `capability`.
144    ///
145    /// # Parameters
146    /// - `capability`: Capability to test for conditional or guaranteed
147    ///   support.
148    #[inline]
149    #[must_use]
150    pub const fn supports(&self, capability: FileSystemCapability) -> bool {
151        !matches!(self.support(capability), FileSystemCapabilitySupport::Unsupported)
152    }
153
154    /// Returns whether `capability` is guaranteed in this filesystem scope.
155    ///
156    /// # Parameters
157    /// - `capability`: Capability to test for guaranteed support.
158    #[inline]
159    #[must_use]
160    pub const fn guarantees(&self, capability: FileSystemCapability) -> bool {
161        matches!(self.support(capability), FileSystemCapabilitySupport::Guaranteed)
162    }
163
164    /// Returns the number of advertised capabilities.
165    ///
166    /// # Returns
167    /// Number of set capability flags.
168    #[inline]
169    #[must_use]
170    pub const fn len(&self) -> usize {
171        (self.conditional | self.guaranteed).count_ones() as usize
172    }
173
174    /// Returns whether no capability is advertised.
175    ///
176    /// # Returns
177    /// `true` when the set contains no capability.
178    #[inline]
179    #[must_use]
180    pub const fn is_empty(&self) -> bool {
181        self.conditional == 0 && self.guaranteed == 0
182    }
183
184    /// Iterates advertised capabilities in stable discriminant order.
185    ///
186    /// # Returns
187    /// An iterator over every capability contained in this set.
188    #[inline]
189    pub fn iter(&self) -> impl Iterator<Item = FileSystemCapability> + '_ {
190        FileSystemCapability::ALL
191            .iter()
192            .copied()
193            .filter(|capability| self.supports(*capability))
194    }
195
196    /// Iterates advertised capabilities with their support status.
197    #[inline]
198    pub fn iter_with_support(&self) -> impl Iterator<Item = (FileSystemCapability, FileSystemCapabilitySupport)> + '_ {
199        self.iter().map(|capability| (capability, self.support(capability)))
200    }
201
202    /// Returns the first advertised capability whose required base capability
203    /// has insufficient support.
204    ///
205    /// A conditional derived capability requires its base capability to be
206    /// conditional or guaranteed. A guaranteed derived capability requires a
207    /// guaranteed base capability. Thus a base capability may be advertised
208    /// yet still be insufficient. The returned pair contains the derived
209    /// capability followed by the absent or insufficient base capability.
210    ///
211    /// # Returns
212    /// `Some` with the first derived capability and missing base capability,
213    /// or `None` when no advertised dependency is missing.
214    #[inline]
215    #[must_use]
216    pub fn missing_dependency(&self) -> Option<(FileSystemCapability, FileSystemCapability)> {
217        CAPABILITY_DEPENDENCIES
218            .iter()
219            .copied()
220            .find(|(capability, dependency)| {
221                let capability_support = self.support(*capability);
222                let dependency_support = self.support(*dependency);
223                (matches!(capability_support, FileSystemCapabilitySupport::Conditional)
224                    && matches!(dependency_support, FileSystemCapabilitySupport::Unsupported))
225                    || (matches!(capability_support, FileSystemCapabilitySupport::Guaranteed)
226                        && !matches!(dependency_support, FileSystemCapabilitySupport::Guaranteed))
227            })
228    }
229}
230
231impl Default for FileSystemCapabilities {
232    /// Creates an empty capability set.
233    #[inline]
234    fn default() -> Self {
235        Self::new()
236    }
237}
238
239impl Debug for FileSystemCapabilities {
240    /// Formats each advertised capability with its support strength.
241    ///
242    /// # Parameters
243    /// - `formatter`: Destination for the debug map.
244    #[inline]
245    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
246        formatter.debug_map().entries(self.iter_with_support()).finish()
247    }
248}