ailloli_ui_fs/
provider.rs

1//! Synchronous provider contract for complete filesystem operations.
2
3use crate::{FileCapabilities, FileEntry, FileError, FileKind, FileMetadata, FileUri};
4
5/// Synchronous, UI-independent filesystem backend.
6///
7/// Methods do not impose thread-safety bounds, ordering, atomicity, or timeout
8/// guarantees; concrete providers document those details. Callers should gate
9/// optional operations with [`Self::capabilities`] and still handle failures.
10///
11/// # Examples
12///
13/// ```
14/// use ailloli_ui_fs::{FileCapabilities, FileProvider};
15/// fn can_write(provider: &dyn FileProvider) -> bool { provider.capabilities().write }
16/// # let _ = can_write;
17/// ```
18pub trait FileProvider {
19    /// Returns the provider's advertised operation set.
20    ///
21    /// The snapshot is advisory and may not account for per-resource permissions.
22    ///
23    /// # Examples
24    ///
25    /// ```
26    /// use ailloli_ui_fs::{FileCapabilities, FileProvider};
27    /// fn capabilities(provider: &dyn FileProvider) -> FileCapabilities { provider.capabilities() }
28    /// # let _ = capabilities;
29    /// ```
30    fn capabilities(&self) -> FileCapabilities;
31
32    /// Returns a complete directory listing in provider-defined order.
33    ///
34    /// No pagination or sorting is supplied by this trait.
35    ///
36    /// # Errors
37    ///
38    /// Returns a provider [`FileError`] when the URI cannot be listed.
39    ///
40    /// # Examples
41    ///
42    /// ```
43    /// use ailloli_ui_fs::{FileEntry, FileError, FileProvider, FileUri};
44    /// fn list(provider: &dyn FileProvider, uri: &FileUri) -> Result<Vec<FileEntry>, FileError> { provider.read_dir(uri) }
45    /// # let _ = list;
46    /// ```
47    fn read_dir(&self, uri: &FileUri) -> Result<Vec<FileEntry>, FileError>;
48
49    /// Reads the complete file into memory.
50    ///
51    /// # Errors
52    ///
53    /// Returns a provider [`FileError`] when `uri` cannot be read as bytes.
54    ///
55    /// # Examples
56    ///
57    /// ```
58    /// use ailloli_ui_fs::{FileError, FileProvider, FileUri};
59    /// fn read(provider: &dyn FileProvider, uri: &FileUri) -> Result<Vec<u8>, FileError> { provider.read_file(uri) }
60    /// # let _ = read;
61    /// ```
62    fn read_file(&self, uri: &FileUri) -> Result<Vec<u8>, FileError>;
63
64    /// Writes the complete byte slice to a file.
65    ///
66    /// Creation, truncation, atomicity, and permission preservation are
67    /// provider-defined; an empty slice is a valid request.
68    ///
69    /// # Errors
70    ///
71    /// Returns a provider [`FileError`] when the bytes cannot be written.
72    ///
73    /// # Examples
74    ///
75    /// ```
76    /// use ailloli_ui_fs::{FileError, FileProvider, FileUri};
77    /// fn write(provider: &dyn FileProvider, uri: &FileUri) -> Result<(), FileError> { provider.write_file(uri, b"hello") }
78    /// # let _ = write;
79    /// ```
80    fn write_file(&self, uri: &FileUri, bytes: &[u8]) -> Result<(), FileError>;
81
82    /// Returns one metadata snapshot without prescribing symlink-following policy.
83    ///
84    /// # Errors
85    ///
86    /// Returns a provider [`FileError`] when metadata cannot be obtained.
87    ///
88    /// # Examples
89    ///
90    /// ```
91    /// use ailloli_ui_fs::{FileError, FileMetadata, FileProvider, FileUri};
92    /// fn metadata(provider: &dyn FileProvider, uri: &FileUri) -> Result<FileMetadata, FileError> { provider.metadata(uri) }
93    /// # let _ = metadata;
94    /// ```
95    fn metadata(&self, uri: &FileUri) -> Result<FileMetadata, FileError>;
96
97    /// Returns a canonical provider URI when one is known.
98    ///
99    /// The default returns `Ok(None)`, meaning canonicalization is unavailable;
100    /// that is distinct from returning the unchanged input URI.
101    ///
102    /// # Errors
103    ///
104    /// Implementations may return a provider [`FileError`] if canonicalization fails.
105    ///
106    /// # Examples
107    ///
108    /// ```
109    /// use ailloli_ui_fs::{FileError, FileProvider, FileUri};
110    /// fn canonical(provider: &dyn FileProvider, uri: &FileUri) -> Result<Option<FileUri>, FileError> { provider.canonical_uri(uri) }
111    /// # let _ = canonical;
112    /// ```
113    fn canonical_uri(&self, _uri: &FileUri) -> Result<Option<FileUri>, FileError> {
114        Ok(None)
115    }
116
117    /// Creates one directory.
118    ///
119    /// Parent creation and behavior for an existing directory are provider-defined.
120    ///
121    /// # Errors
122    ///
123    /// Returns a provider [`FileError`] when the directory cannot be created.
124    ///
125    /// # Examples
126    ///
127    /// ```
128    /// use ailloli_ui_fs::{FileError, FileProvider, FileUri};
129    /// fn create(provider: &dyn FileProvider, uri: &FileUri) -> Result<(), FileError> { provider.create_dir(uri) }
130    /// # let _ = create;
131    /// ```
132    fn create_dir(&self, uri: &FileUri) -> Result<(), FileError>;
133
134    /// Renames or relocates one entry according to provider semantics.
135    ///
136    /// Cross-filesystem support and destination replacement are not guaranteed.
137    ///
138    /// # Errors
139    ///
140    /// Returns a provider [`FileError`] when the rename cannot complete.
141    ///
142    /// # Examples
143    ///
144    /// ```
145    /// use ailloli_ui_fs::{FileError, FileProvider, FileUri};
146    /// fn rename(provider: &dyn FileProvider, from: &FileUri, to: &FileUri) -> Result<(), FileError> { provider.rename(from, to) }
147    /// # let _ = rename;
148    /// ```
149    fn rename(&self, from: &FileUri, to: &FileUri) -> Result<(), FileError>;
150
151    /// Removes one file-like entry or empty directory.
152    ///
153    /// Recursive behavior is not implied; use [`Self::remove_recursive`] when advertised.
154    ///
155    /// # Errors
156    ///
157    /// Returns a provider [`FileError`] when removal fails.
158    ///
159    /// # Examples
160    ///
161    /// ```
162    /// use ailloli_ui_fs::{FileError, FileProvider, FileUri};
163    /// fn remove(provider: &dyn FileProvider, uri: &FileUri) -> Result<(), FileError> { provider.remove(uri) }
164    /// # let _ = remove;
165    /// ```
166    fn remove(&self, uri: &FileUri) -> Result<(), FileError>;
167
168    /// Recursively copies an entry using the provider's primitive methods.
169    ///
170    /// The default rejects symlinks, creates a destination directory before its
171    /// children, traverses listings in provider order, and buffers each file
172    /// completely in memory. [`FileKind::Other`] is copied as bytes. The process
173    /// is synchronous and non-transactional, so a failure can leave a partial
174    /// destination. Deep trees consume call stack.
175    ///
176    /// # Errors
177    ///
178    /// Propagates metadata, listing, URI-join, creation, read, or write errors;
179    /// returns [`FileError::Unsupported`] for symlinks/unsupported kinds.
180    ///
181    /// # Examples
182    ///
183    /// ```
184    /// use ailloli_ui_fs::{FileError, FileProvider, FileUri};
185    /// fn copy(provider: &dyn FileProvider, from: &FileUri, to: &FileUri) -> Result<(), FileError> { provider.copy_entry(from, to) }
186    /// # let _ = copy;
187    /// ```
188    fn copy_entry(&self, from: &FileUri, to: &FileUri) -> Result<(), FileError> {
189        let metadata = self.metadata(from)?;
190        if metadata.kind == FileKind::Symlink {
191            return Err(FileError::Unsupported(
192                "copying symlinks is not supported by this provider".into(),
193            ));
194        }
195        if metadata.kind == FileKind::Directory {
196            self.create_dir(to)?;
197            for entry in self.read_dir(from)? {
198                let child_to = to.join_child(&entry.name)?;
199                self.copy_entry(&entry.uri, &child_to)?;
200            }
201            return Ok(());
202        }
203        if metadata.is_file_like() || metadata.kind == FileKind::Other {
204            let bytes = self.read_file(from)?;
205            return self.write_file(to, &bytes);
206        }
207        Err(FileError::Unsupported(format!(
208            "unsupported entry kind for copy: {:?}",
209            metadata.kind
210        )))
211    }
212
213    /// Moves an entry; the default delegates directly to [`Self::rename`].
214    ///
215    /// It does not fall back to copy-then-remove across filesystems.
216    ///
217    /// # Errors
218    ///
219    /// Propagates the provider's rename failure.
220    ///
221    /// # Examples
222    ///
223    /// ```
224    /// use ailloli_ui_fs::{FileError, FileProvider, FileUri};
225    /// fn move_entry(provider: &dyn FileProvider, from: &FileUri, to: &FileUri) -> Result<(), FileError> { provider.move_entry(from, to) }
226    /// # let _ = move_entry;
227    /// ```
228    fn move_entry(&self, from: &FileUri, to: &FileUri) -> Result<(), FileError> {
229        self.rename(from, to)
230    }
231
232    /// Removes an entry subtree depth-first using primitive provider methods.
233    ///
234    /// The default lists only entries whose primary kind is
235    /// [`FileKind::Directory`], so symlinks are removed without following them.
236    /// Children are processed in provider order, then the root is removed. The
237    /// operation is synchronous, recursive, and non-transactional.
238    ///
239    /// # Errors
240    ///
241    /// Propagates metadata, listing, descendant, or final removal failures; an
242    /// error can occur after earlier descendants were already removed.
243    ///
244    /// # Examples
245    ///
246    /// ```
247    /// use ailloli_ui_fs::{FileError, FileProvider, FileUri};
248    /// fn remove_tree(provider: &dyn FileProvider, uri: &FileUri) -> Result<(), FileError> { provider.remove_recursive(uri) }
249    /// # let _ = remove_tree;
250    /// ```
251    fn remove_recursive(&self, uri: &FileUri) -> Result<(), FileError> {
252        let metadata = self.metadata(uri)?;
253        if metadata.kind == FileKind::Directory {
254            for entry in self.read_dir(uri)? {
255                self.remove_recursive(&entry.uri)?;
256            }
257        }
258        self.remove(uri)
259    }
260}