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}