qubit_fs/traits/
file_system.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2026 Haixing Hu.
4 *
5 *    SPDX-License-Identifier: Apache-2.0
6 *
7 *    Licensed under the Apache License, Version 2.0.
8 *
9 ******************************************************************************/
10//! Core filesystem trait.
11
12use std::fmt::Debug;
13
14use crate::{
15    CopyOptions,
16    CopyOutcome,
17    CreateDirOptions,
18    DeleteOptions,
19    DirectoryStream,
20    FileMetadata,
21    FileReader,
22    FileSystemCapabilities,
23    FileSystemMetadata,
24    FileWriter,
25    FsPath,
26    FsResult,
27    ListOptions,
28    ManagedTempResourceFactory,
29    ReadOptions,
30    RenameOptions,
31    TempResourceFactory,
32    WriteOptions,
33};
34
35/// Provider-neutral filesystem interface.
36pub trait FileSystem: Debug + Send + Sync {
37    /// Gets metadata describing this filesystem instance.
38    ///
39    /// # Returns
40    /// Filesystem metadata.
41    fn metadata(&self) -> FileSystemMetadata;
42
43    /// Gets capability hints for this filesystem.
44    ///
45    /// # Returns
46    /// Static capability hints.
47    #[inline]
48    fn capabilities(&self) -> FileSystemCapabilities {
49        self.metadata().capabilities
50    }
51
52    /// Gets the temporary resource factory for this filesystem instance.
53    ///
54    /// If the specified filesystem does not provide its specific implementation,
55    /// a default `ManagedTempResourceFactory` will be returned.
56    ///
57    /// # Returns
58    /// Factory used to create temporary files and directories owned by this
59    /// filesystem instance.
60    #[inline]
61    fn temp_resource_factory(&self) -> &dyn TempResourceFactory {
62        ManagedTempResourceFactory::shared()
63    }
64
65    /// Reads metadata for a path.
66    ///
67    /// # Parameters
68    /// - `path`: Resource path.
69    ///
70    /// # Returns
71    /// Resource metadata.
72    ///
73    /// # Errors
74    /// Returns [`crate::FsError`] when metadata cannot be read.
75    fn path_metadata(&self, path: &FsPath) -> FsResult<FileMetadata>;
76
77    /// Checks whether a path exists.
78    ///
79    /// # Parameters
80    /// - `path`: Resource path.
81    ///
82    /// # Returns
83    /// `true` when the resource exists.
84    ///
85    /// # Errors
86    /// Returns [`crate::FsError`] for errors other than confirmed absence.
87    fn exists(&self, path: &FsPath) -> FsResult<bool>;
88
89    /// Lists a directory, prefix, or collection.
90    ///
91    /// # Parameters
92    /// - `path`: Container path.
93    /// - `options`: Listing options.
94    ///
95    /// # Returns
96    /// Directory stream.
97    ///
98    /// # Errors
99    /// Returns [`crate::FsError`] when listing cannot be started.
100    fn list(&self, path: &FsPath, options: &ListOptions) -> FsResult<Box<dyn DirectoryStream>>;
101
102    /// Opens a readable resource.
103    ///
104    /// # Parameters
105    /// - `path`: Resource path.
106    /// - `options`: Read options.
107    ///
108    /// # Returns
109    /// Reader handle.
110    ///
111    /// # Errors
112    /// Returns [`crate::FsError`] when the reader cannot be opened.
113    fn open_reader(&self, path: &FsPath, options: &ReadOptions) -> FsResult<Box<dyn FileReader>>;
114
115    /// Opens a writable resource.
116    ///
117    /// # Parameters
118    /// - `path`: Resource path.
119    /// - `options`: Write options.
120    ///
121    /// # Returns
122    /// Writer handle.
123    ///
124    /// # Errors
125    /// Returns [`crate::FsError`] when the writer cannot be opened.
126    fn open_writer(&self, path: &FsPath, options: &WriteOptions) -> FsResult<Box<dyn FileWriter>>;
127
128    /// Creates a directory, collection, or equivalent container.
129    ///
130    /// # Parameters
131    /// - `path`: Container path.
132    /// - `options`: Creation options.
133    ///
134    /// # Errors
135    /// Returns [`crate::FsError`] when the container cannot be created.
136    fn create_dir(&self, path: &FsPath, options: &CreateDirOptions) -> FsResult<()>;
137
138    /// Deletes a resource.
139    ///
140    /// # Parameters
141    /// - `path`: Resource path.
142    /// - `options`: Delete options.
143    ///
144    /// # Errors
145    /// Returns [`crate::FsError`] when deletion fails.
146    fn delete(&self, path: &FsPath, options: &DeleteOptions) -> FsResult<()>;
147
148    /// Renames or moves a resource within this filesystem.
149    ///
150    /// # Parameters
151    /// - `from`: Source path.
152    /// - `to`: Destination path.
153    /// - `options`: Rename options.
154    ///
155    /// # Errors
156    /// Returns [`crate::FsError`] when rename fails.
157    fn rename(&self, from: &FsPath, to: &FsPath, options: &RenameOptions) -> FsResult<()>;
158
159    /// Copies a resource within this filesystem.
160    ///
161    /// # Parameters
162    /// - `from`: Source path.
163    /// - `to`: Destination path.
164    /// - `options`: Copy options.
165    ///
166    /// # Returns
167    /// Copy outcome.
168    ///
169    /// # Errors
170    /// Returns [`crate::FsError`] when copy fails.
171    fn copy(&self, from: &FsPath, to: &FsPath, options: &CopyOptions) -> FsResult<CopyOutcome>;
172}
qubit_fs/traits/file_system.rs

qubit_fs/traits/
file_system.rs
