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}