ailloli_ui_fs/
source.rs

1//! Worker-owned source contract used by the persistent file-tree coordinator.
2
3use crate::{FileEntry, FileError, FileIdentity, FileUri, WatchEvent};
4
5/// Synchronous provider instance owned exclusively by a filesystem worker.
6/// It may wrap an internally synchronous or asynchronous backend, but no UI
7/// handle or callback crosses this boundary.
8///
9/// # Examples
10///
11/// ```
12/// use ailloli_ui_fs::{FileError, FileTreeSource, FileUri};
13/// fn list(source: &mut dyn FileTreeSource, uri: &FileUri) -> Result<usize, FileError> {
14///     Ok(source.read_dir(uri)?.len())
15/// }
16/// # let _ = list;
17/// ```
18pub trait FileTreeSource: Send + 'static {
19    /// Returns a complete directory listing in provider-defined order.
20    ///
21    /// The mutable receiver permits worker-local clients and caches. No
22    /// pagination or sorting is imposed.
23    ///
24    /// # Errors
25    ///
26    /// Returns a provider [`FileError`] when the directory cannot be listed.
27    ///
28    /// # Examples
29    ///
30    /// ```
31    /// use ailloli_ui_fs::{FileEntry, FileError, FileTreeSource, FileUri};
32    /// fn read(source: &mut dyn FileTreeSource, uri: &FileUri) -> Result<Vec<FileEntry>, FileError> { source.read_dir(uri) }
33    /// # let _ = read;
34    /// ```
35    fn read_dir(&mut self, uri: &FileUri) -> Result<Vec<FileEntry>, FileError>;
36
37    /// Returns a stable provider identity for an entry when available.
38    ///
39    /// The default returns `Ok(None)`. Equal identities can represent hard
40    /// links, so tree stores do not assume global one-to-one identity.
41    ///
42    /// # Errors
43    ///
44    /// Implementations may return a provider [`FileError`] if lookup fails.
45    ///
46    /// # Examples
47    ///
48    /// ```
49    /// use ailloli_ui_fs::{FileError, FileIdentity, FileTreeSource, FileUri};
50    /// fn identity(source: &mut dyn FileTreeSource, uri: &FileUri) -> Result<Option<FileIdentity>, FileError> { source.identity(uri) }
51    /// # let _ = identity;
52    /// ```
53    fn identity(&mut self, _uri: &FileUri) -> Result<Option<FileIdentity>, FileError> {
54        Ok(None)
55    }
56
57    /// Creates one directory at `uri`.
58    ///
59    /// # Errors
60    ///
61    /// The default always returns [`FileError::Unsupported`]. Implementations
62    /// return provider errors for failed creation.
63    ///
64    /// # Examples
65    ///
66    /// ```
67    /// use ailloli_ui_fs::{FileError, FileTreeSource, FileUri};
68    /// fn create(source: &mut dyn FileTreeSource, uri: &FileUri) -> Result<(), FileError> { source.create_directory(uri) }
69    /// # let _ = create;
70    /// ```
71    fn create_directory(&mut self, _uri: &FileUri) -> Result<(), FileError> {
72        Err(FileError::Unsupported(
73            "this filesystem source cannot create directories".into(),
74        ))
75    }
76
77    /// Creates one empty file at `uri`.
78    ///
79    /// Existing-file behavior is provider-defined.
80    ///
81    /// # Errors
82    ///
83    /// The default always returns [`FileError::Unsupported`]. Implementations
84    /// return provider errors for failed creation.
85    ///
86    /// # Examples
87    ///
88    /// ```
89    /// use ailloli_ui_fs::{FileError, FileTreeSource, FileUri};
90    /// fn create(source: &mut dyn FileTreeSource, uri: &FileUri) -> Result<(), FileError> { source.create_file(uri) }
91    /// # let _ = create;
92    /// ```
93    fn create_file(&mut self, _uri: &FileUri) -> Result<(), FileError> {
94        Err(FileError::Unsupported(
95            "this filesystem source cannot create files".into(),
96        ))
97    }
98
99    /// Moves or renames one entry.
100    ///
101    /// Cross-filesystem and destination-replacement behavior are provider-defined.
102    ///
103    /// # Errors
104    ///
105    /// The default always returns [`FileError::Unsupported`]. Implementations
106    /// return provider errors for failed moves.
107    ///
108    /// # Examples
109    ///
110    /// ```
111    /// use ailloli_ui_fs::{FileError, FileTreeSource, FileUri};
112    /// fn move_entry(source: &mut dyn FileTreeSource, from: &FileUri, to: &FileUri) -> Result<(), FileError> { source.move_entry(from, to) }
113    /// # let _ = move_entry;
114    /// ```
115    fn move_entry(&mut self, _from: &FileUri, _to: &FileUri) -> Result<(), FileError> {
116        Err(FileError::Unsupported(
117            "this filesystem source cannot move entries".into(),
118        ))
119    }
120
121    /// Removes one entry, optionally including descendants.
122    ///
123    /// # Errors
124    ///
125    /// The default always returns [`FileError::Unsupported`]. Implementations
126    /// return provider errors for failed removal.
127    ///
128    /// # Examples
129    ///
130    /// ```
131    /// use ailloli_ui_fs::{FileError, FileTreeSource, FileUri};
132    /// fn remove(source: &mut dyn FileTreeSource, uri: &FileUri) -> Result<(), FileError> { source.remove_entry(uri, true) }
133    /// # let _ = remove;
134    /// ```
135    fn remove_entry(&mut self, _uri: &FileUri, _recursive: bool) -> Result<(), FileError> {
136        Err(FileError::Unsupported(
137            "this filesystem source cannot remove entries".into(),
138        ))
139    }
140
141    /// Starts native watch delivery for one directory.
142    ///
143    /// # Errors
144    ///
145    /// The default always returns [`FileError::Unsupported`]. Implementations
146    /// return provider errors if registration fails.
147    ///
148    /// # Examples
149    ///
150    /// ```
151    /// use ailloli_ui_fs::{FileError, FileTreeSource, FileUri};
152    /// fn watch(source: &mut dyn FileTreeSource, uri: &FileUri) -> Result<(), FileError> { source.watch_directory(uri) }
153    /// # let _ = watch;
154    /// ```
155    fn watch_directory(&mut self, _uri: &FileUri) -> Result<(), FileError> {
156        Err(FileError::Unsupported(
157            "this filesystem source does not provide native watch events".into(),
158        ))
159    }
160
161    /// Stops native watch delivery for one directory.
162    ///
163    /// The default is a successful no-op, including for an unwatched URI.
164    ///
165    /// # Errors
166    ///
167    /// Implementations may return a provider [`FileError`] if unregistration fails.
168    ///
169    /// # Examples
170    ///
171    /// ```
172    /// use ailloli_ui_fs::{FileError, FileTreeSource, FileUri};
173    /// fn unwatch(source: &mut dyn FileTreeSource, uri: &FileUri) -> Result<(), FileError> { source.unwatch_directory(uri) }
174    /// # let _ = unwatch;
175    /// ```
176    fn unwatch_directory(&mut self, _uri: &FileUri) -> Result<(), FileError> {
177        Ok(())
178    }
179
180    /// Drains up to the requested number of queued watch events.
181    ///
182    /// The default ignores `limit` and returns an empty vector. Implementations
183    /// should treat zero as a request to return no events; event ordering and
184    /// overflow signaling follow their watch contract.
185    ///
186    /// # Errors
187    ///
188    /// Implementations may return a provider [`FileError`] when polling fails.
189    ///
190    /// # Examples
191    ///
192    /// ```
193    /// use ailloli_ui_fs::{FileError, FileTreeSource, WatchEvent};
194    /// fn poll(source: &mut dyn FileTreeSource) -> Result<Vec<WatchEvent>, FileError> { source.poll_watch(64) }
195    /// # let _ = poll;
196    /// ```
197    fn poll_watch(&mut self, _limit: usize) -> Result<Vec<WatchEvent>, FileError> {
198        Ok(Vec::new())
199    }
200
201    /// Reports whether watch registration/polling is implemented natively.
202    ///
203    /// The default is `false`; it is independent of whether callers choose to poll.
204    ///
205    /// # Examples
206    ///
207    /// ```
208    /// use ailloli_ui_fs::FileTreeSource;
209    /// fn has_watch(source: &dyn FileTreeSource) -> bool { source.supports_native_watch() }
210    /// # let _ = has_watch;
211    /// ```
212    fn supports_native_watch(&self) -> bool {
213        false
214    }
215}
216
217/// Thread-safe factory that creates one worker-owned source instance.
218///
219/// # Examples
220///
221/// ```
222/// use ailloli_ui_fs::{FileError, FileTreeSource, FileTreeSourceFactory};
223/// fn open(factory: &dyn FileTreeSourceFactory) -> Result<Box<dyn FileTreeSource>, FileError> { factory.create() }
224/// # let _ = open;
225/// ```
226pub trait FileTreeSourceFactory: Send + Sync + 'static {
227    /// Creates a fresh source instance for exclusive ownership by one worker.
228    ///
229    /// # Errors
230    ///
231    /// Returns a provider [`FileError`] when the source cannot be initialized.
232    ///
233    /// # Examples
234    ///
235    /// ```
236    /// use ailloli_ui_fs::{FileError, FileTreeSource, FileTreeSourceFactory};
237    /// fn create(factory: &dyn FileTreeSourceFactory) -> Result<Box<dyn FileTreeSource>, FileError> { factory.create() }
238    /// # let _ = create;
239    /// ```
240    fn create(&self) -> Result<Box<dyn FileTreeSource>, FileError>;
241}