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}