fuser_ng/async/types.rs
1//! Asynchronous filesystem interface and its FUSE adapter.
2
3use std::ffi::OsString;
4use std::future::Future;
5use std::path::PathBuf;
6use std::pin::Pin;
7use std::task::{Context, Poll};
8use std::time::SystemTime;
9
10use futures_core::Stream;
11
12use crate::{
13 EntryName, EntryRef, KernelConfig, RequestInfo, ResolvedPath, ResultCreate, ResultData,
14 ResultEmpty, ResultEntry, ResultOpen, ResultReaddirBatch, ResultStatfs, ResultWrite,
15 ResultXattr,
16};
17
18#[cfg(feature = "legacy_readdir")]
19use crate::ResultLegacyReaddirBatch;
20
21#[cfg(target_os = "macos")]
22use crate::ResultXTimes;
23
24/// A stream that yields one value.
25struct Once<T>(Option<T>);
26
27impl<T: Unpin> Stream for Once<T> {
28 type Item = T;
29
30 fn poll_next(mut self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
31 Poll::Ready(self.0.take())
32 }
33}
34
35/// Returns an immediately ready unsupported-operation result.
36fn enosys_future<T>() -> std::future::Ready<std::io::Result<T>> {
37 std::future::ready(Err(std::io::Error::from_raw_os_error(libc::ENOSYS)))
38}
39
40/// Filesystem operations that may complete asynchronously.
41///
42/// Operation arguments are owned so their futures can outlive the FUSE request callback.
43#[allow(unused_variables)]
44pub trait AsyncFilesystem: Send + Sync + 'static {
45 /// Called when the filesystem is mounted, before any other operation.
46 ///
47 /// * req: information about the FUSE request.
48 /// * config: kernel configuration that may be adjusted before mounting.
49 fn init(&self, req: RequestInfo, config: &mut KernelConfig) -> ResultEmpty {
50 Ok(())
51 }
52
53 /// Called when the filesystem is unmounted.
54 fn destroy(&self) {}
55
56 /// Get the attributes of a filesystem entry.
57 ///
58 /// * req: information about the FUSE request.
59 /// * path: path to the entry.
60 /// * fh: a file handle if this is called on an open file.
61 fn getattr(
62 &self,
63 req: RequestInfo,
64 path: EntryRef,
65 fh: Option<u64>,
66 ) -> impl Future<Output = ResultEntry> + Send {
67 enosys_future()
68 }
69
70 /// Change the mode of a filesystem entry.
71 ///
72 /// * req: information about the FUSE request.
73 /// * path: path to the entry.
74 /// * fh: a file handle if this is called on an open file.
75 /// * mode: the mode to change the file to.
76 fn chmod(
77 &self,
78 req: RequestInfo,
79 path: ResolvedPath,
80 fh: Option<u64>,
81 mode: u32,
82 ) -> impl Future<Output = ResultEmpty> + Send {
83 enosys_future()
84 }
85
86 /// Change the owner UID and/or group GID of a filesystem entry.
87 ///
88 /// * req: information about the FUSE request.
89 /// * path: path to the entry.
90 /// * fh: a file handle if this is called on an open file.
91 /// * uid: new user ID for the file owner. If None, leave the UID unchanged.
92 /// * gid: new group ID for the file. If None, leave the GID unchanged.
93 fn chown(
94 &self,
95 req: RequestInfo,
96 path: ResolvedPath,
97 fh: Option<u64>,
98 uid: Option<u32>,
99 gid: Option<u32>,
100 ) -> impl Future<Output = ResultEmpty> + Send {
101 enosys_future()
102 }
103
104 /// Set the length of a file.
105 ///
106 /// * req: information about the FUSE request.
107 /// * path: path to the file.
108 /// * fh: a file handle if this is called on an open file.
109 /// * size: new file length in bytes.
110 fn truncate(
111 &self,
112 req: RequestInfo,
113 path: ResolvedPath,
114 fh: Option<u64>,
115 size: u64,
116 ) -> impl Future<Output = ResultEmpty> + Send {
117 enosys_future()
118 }
119
120 /// Set the timestamps of a filesystem entry.
121 ///
122 /// * req: information about the FUSE request.
123 /// * path: path to the entry.
124 /// * fh: a file handle if this is called on an open file.
125 /// * atime: new access time, or None to leave it unchanged.
126 /// * mtime: new modification time, or None to leave it unchanged.
127 fn utimens(
128 &self,
129 req: RequestInfo,
130 path: ResolvedPath,
131 fh: Option<u64>,
132 atime: Option<SystemTime>,
133 mtime: Option<SystemTime>,
134 ) -> impl Future<Output = ResultEmpty> + Send {
135 enosys_future()
136 }
137
138 /// Set the timestamps of a filesystem entry using the additional macOS options.
139 ///
140 /// * req: information about the FUSE request.
141 /// * path: path to the entry.
142 /// * fh: a file handle if this is called on an open file.
143 /// * crtime: new creation time, or None to leave it unchanged.
144 /// * chgtime: new metadata change time, or None to leave it unchanged.
145 /// * bkuptime: new backup time, or None to leave it unchanged.
146 /// * flags: new macOS file flags, or None to leave them unchanged.
147 #[allow(clippy::too_many_arguments)]
148 fn utimens_macos(
149 &self,
150 req: RequestInfo,
151 path: ResolvedPath,
152 fh: Option<u64>,
153 crtime: Option<SystemTime>,
154 chgtime: Option<SystemTime>,
155 bkuptime: Option<SystemTime>,
156 flags: Option<u32>,
157 ) -> impl Future<Output = ResultEmpty> + Send {
158 enosys_future()
159 }
160
161 /// Read a symbolic link.
162 ///
163 /// * req: information about the FUSE request.
164 /// * path: path to the symbolic link.
165 fn readlink(
166 &self,
167 req: RequestInfo,
168 path: ResolvedPath,
169 ) -> impl Future<Output = ResultData> + Send {
170 enosys_future()
171 }
172
173 /// Create a special file.
174 ///
175 /// * req: information about the FUSE request.
176 /// * entry: entry name resolved relative to its parent directory.
177 /// * mode: mode for the new entry.
178 /// * rdev: device number when mode contains S_IFCHR or S_IFBLK; ignored otherwise.
179 fn mknod(
180 &self,
181 req: RequestInfo,
182 entry: EntryName,
183 mode: u32,
184 rdev: u32,
185 ) -> impl Future<Output = ResultEntry> + Send {
186 enosys_future()
187 }
188
189 /// Create a directory.
190 ///
191 /// * req: information about the FUSE request.
192 /// * entry: directory name resolved relative to its parent directory.
193 /// * mode: permissions for the new directory.
194 fn mkdir(
195 &self,
196 req: RequestInfo,
197 entry: EntryName,
198 mode: u32,
199 ) -> impl Future<Output = ResultEntry> + Send {
200 enosys_future()
201 }
202
203 /// Remove a file.
204 ///
205 /// * req: information about the FUSE request.
206 /// * entry: file name resolved relative to its parent directory.
207 fn unlink(
208 &self,
209 req: RequestInfo,
210 entry: EntryName,
211 ) -> impl Future<Output = ResultEmpty> + Send {
212 enosys_future()
213 }
214
215 /// Remove a directory.
216 ///
217 /// * req: information about the FUSE request.
218 /// * entry: directory name resolved relative to its parent directory.
219 fn rmdir(
220 &self,
221 req: RequestInfo,
222 entry: EntryName,
223 ) -> impl Future<Output = ResultEmpty> + Send {
224 enosys_future()
225 }
226
227 /// Create a symbolic link.
228 ///
229 /// * req: information about the FUSE request.
230 /// * entry: symbolic link name resolved relative to its parent directory.
231 /// * target: path (may be relative or absolute) to the target of the link.
232 fn symlink(
233 &self,
234 req: RequestInfo,
235 entry: EntryName,
236 target: PathBuf,
237 ) -> impl Future<Output = ResultEntry> + Send {
238 enosys_future()
239 }
240
241 /// Rename a filesystem entry.
242 ///
243 /// * req: information about the FUSE request.
244 /// * entry: current entry name resolved relative to its parent directory.
245 /// * new_entry: new entry name resolved relative to its parent directory.
246 fn rename(
247 &self,
248 req: RequestInfo,
249 entry: EntryName,
250 new_entry: EntryName,
251 ) -> impl Future<Output = ResultEmpty> + Send {
252 enosys_future()
253 }
254
255 /// Create a hard link.
256 ///
257 /// * req: information about the FUSE request.
258 /// * path: path to an existing file.
259 /// * new_entry: new link name resolved relative to its parent directory.
260 fn link(
261 &self,
262 req: RequestInfo,
263 path: ResolvedPath,
264 new_entry: EntryName,
265 ) -> impl Future<Output = ResultEntry> + Send {
266 enosys_future()
267 }
268
269 /// Open a file.
270 ///
271 /// * req: information about the FUSE request.
272 /// * path: path to the file.
273 /// * flags: one of O_RDONLY, O_WRONLY, or O_RDWR, plus any additional flags.
274 ///
275 /// Return a tuple of (file handle, flags). The file handle will be passed to any subsequent
276 /// calls that operate on the file, and can be any value you choose, though it should allow
277 /// your filesystem to identify the open file even without path information.
278 fn open(
279 &self,
280 req: RequestInfo,
281 path: ResolvedPath,
282 flags: u32,
283 ) -> impl Future<Output = ResultOpen> + Send {
284 enosys_future()
285 }
286
287 /// Read from a file.
288 ///
289 /// Reading past the end of the file is not an error. Return only the available data up to the
290 /// end of the file, which may be fewer bytes than requested or even zero bytes. Do not extend
291 /// the file in this case.
292 ///
293 /// * req: information about the FUSE request.
294 /// * path: path to the file.
295 /// * fh: file handle returned from the open call.
296 /// * offset: offset into the file to start reading.
297 /// * size: number of bytes to read.
298 fn read(
299 &self,
300 req: RequestInfo,
301 path: ResolvedPath,
302 fh: u64,
303 offset: u64,
304 size: u32,
305 ) -> impl Future<Output = ResultData> + Send {
306 enosys_future()
307 }
308
309 /// Write to a file.
310 ///
311 /// * req: information about the FUSE request.
312 /// * path: path to the file.
313 /// * fh: file handle returned from the open call.
314 /// * offset: offset into the file to start writing.
315 /// * data: data to write.
316 /// * flags: file open flags.
317 ///
318 /// Return the number of bytes written.
319 fn write(
320 &self,
321 req: RequestInfo,
322 path: ResolvedPath,
323 fh: u64,
324 offset: u64,
325 data: Vec<u8>,
326 flags: u32,
327 ) -> impl Future<Output = ResultWrite> + Send {
328 enosys_future()
329 }
330
331 /// Called each time a program calls close on an open file.
332 ///
333 /// Note that because file descriptors can be duplicated (by dup, dup2, fork) this may be
334 /// called multiple times for a given file handle. The main use of this function is if the
335 /// filesystem would like to return an error to the close call. Note that most programs
336 /// ignore the return value of close, though.
337 ///
338 /// * req: information about the FUSE request.
339 /// * path: path to the file.
340 /// * fh: file handle returned from the open call.
341 /// * lock_owner: if the filesystem supports locking (setlk, getlk), remove all locks
342 /// belonging to this lock owner.
343 fn flush(
344 &self,
345 req: RequestInfo,
346 path: ResolvedPath,
347 fh: u64,
348 lock_owner: u64,
349 ) -> impl Future<Output = ResultEmpty> + Send {
350 enosys_future()
351 }
352
353 /// Called when an open file is closed.
354 ///
355 /// There will be one of these for each open call. After release, no more calls will be
356 /// made with the given file handle.
357 ///
358 /// * req: information about the FUSE request.
359 /// * path: path to the file.
360 /// * fh: file handle returned from the open call.
361 /// * flags: the flags passed when the file was opened.
362 /// * lock_owner: if the filesystem supports locking (setlk, getlk), remove all locks
363 /// belonging to this lock owner.
364 /// * flush: whether pending data must be flushed or not.
365 #[allow(clippy::too_many_arguments)]
366 fn release(
367 &self,
368 req: RequestInfo,
369 path: ResolvedPath,
370 fh: u64,
371 flags: u32,
372 lock_owner: u64,
373 flush: bool,
374 ) -> impl Future<Output = ResultEmpty> + Send {
375 enosys_future()
376 }
377
378 /// Write out any pending changes to a file.
379 ///
380 /// When this returns, data should be written to persistent storage.
381 ///
382 /// * req: information about the FUSE request.
383 /// * path: path to the file.
384 /// * fh: file handle returned from the open call.
385 /// * datasync: if false, also write metadata; otherwise, write only file data.
386 fn fsync(
387 &self,
388 req: RequestInfo,
389 path: ResolvedPath,
390 fh: u64,
391 datasync: bool,
392 ) -> impl Future<Output = ResultEmpty> + Send {
393 enosys_future()
394 }
395
396 /// Open a directory.
397 ///
398 /// Analogous to the opendir call.
399 ///
400 /// * req: information about the FUSE request.
401 /// * path: path to the directory.
402 /// * flags: file access flags. Will contain O_DIRECTORY at least.
403 ///
404 /// Return a tuple of (file handle, flags). The file handle will be passed to any subsequent
405 /// calls that operate on the directory, and can be any value you choose, though it should
406 /// allow your filesystem to identify the open directory even without path information.
407 fn opendir(
408 &self,
409 req: RequestInfo,
410 path: ResolvedPath,
411 flags: u32,
412 ) -> impl Future<Output = ResultOpen> + Send {
413 enosys_future()
414 }
415
416 /// Gets directory entries together with their attributes.
417 ///
418 /// * req: information about the FUSE request.
419 /// * path: path to the directory.
420 /// * fh: file handle returned from the opendir call.
421 ///
422 /// Batching allows initial results to be returned before directory enumeration completes.
423 /// FuserNG deliberately retains consumed entries until releasedir so earlier offsets can be
424 /// replayed without restarting enumeration or repeating backend requests. This history
425 /// trades memory for fast replay; batching is intended to reduce result delivery latency.
426 fn readdir(
427 &self,
428 req: RequestInfo,
429 path: ResolvedPath,
430 fh: u64,
431 ) -> impl Stream<Item = ResultReaddirBatch> + Send + 'static {
432 Once(Some(Err(std::io::Error::from_raw_os_error(libc::ENOSYS))))
433 }
434
435 /// Gets directory entries without attributes for the legacy FUSE readdir operation.
436 ///
437 /// * req: information about the FUSE request.
438 /// * path: path to the directory.
439 /// * fh: file handle returned from the opendir call.
440 ///
441 /// Batching allows initial results to be returned before directory enumeration completes.
442 /// FuserNG deliberately retains consumed entries until releasedir so earlier offsets can be
443 /// replayed without restarting enumeration or repeating backend requests. This history
444 /// trades memory for fast replay; batching is intended to reduce result delivery latency.
445 #[cfg(feature = "legacy_readdir")]
446 fn legacy_readdir(
447 &self,
448 req: RequestInfo,
449 path: ResolvedPath,
450 fh: u64,
451 ) -> impl Stream<Item = ResultLegacyReaddirBatch> + Send + 'static {
452 Once(Some(Err(std::io::Error::from_raw_os_error(libc::ENOSYS))))
453 }
454
455 /// Close an open directory.
456 ///
457 /// This will be called exactly once for each opendir call.
458 ///
459 /// * req: information about the FUSE request.
460 /// * path: path to the directory.
461 /// * fh: file handle returned from the opendir call.
462 /// * flags: the file access flags passed to the opendir call.
463 fn releasedir(
464 &self,
465 req: RequestInfo,
466 path: ResolvedPath,
467 fh: u64,
468 flags: u32,
469 ) -> impl Future<Output = ResultEmpty> + Send {
470 enosys_future()
471 }
472
473 /// Write out any pending changes to a directory.
474 ///
475 /// Analogous to the fsync call.
476 ///
477 /// * req: information about the FUSE request.
478 /// * path: path to the directory.
479 /// * fh: file handle returned from the opendir call.
480 /// * datasync: if false, also write metadata; otherwise, write only directory data.
481 fn fsyncdir(
482 &self,
483 req: RequestInfo,
484 path: ResolvedPath,
485 fh: u64,
486 datasync: bool,
487 ) -> impl Future<Output = ResultEmpty> + Send {
488 enosys_future()
489 }
490
491 /// Get filesystem statistics.
492 ///
493 /// * req: information about the FUSE request.
494 /// * path: path to a directory in the filesystem.
495 ///
496 /// See the Statfs struct for more details.
497 fn statfs(
498 &self,
499 req: RequestInfo,
500 path: ResolvedPath,
501 ) -> impl Future<Output = ResultStatfs> + Send {
502 enosys_future()
503 }
504
505 /// Set an extended attribute on a file.
506 ///
507 /// * req: information about the FUSE request.
508 /// * path: path to the file.
509 /// * name: attribute name.
510 /// * value: the data to set the value to.
511 /// * flags: can be either XATTR_CREATE or XATTR_REPLACE.
512 /// * position: offset into the attribute value to write data.
513 #[allow(clippy::too_many_arguments)]
514 fn setxattr(
515 &self,
516 req: RequestInfo,
517 path: ResolvedPath,
518 name: OsString,
519 value: Vec<u8>,
520 flags: u32,
521 position: u32,
522 ) -> impl Future<Output = ResultEmpty> + Send {
523 enosys_future()
524 }
525
526 /// Get an extended attribute from a file.
527 ///
528 /// * req: information about the FUSE request.
529 /// * path: path to the file.
530 /// * name: attribute name.
531 /// * size: the maximum number of bytes to read.
532 ///
533 /// If size is 0, return Xattr::Size(n) where n is the size of the attribute data.
534 /// Otherwise, return Xattr::Data(data) with the requested data.
535 fn getxattr(
536 &self,
537 req: RequestInfo,
538 path: ResolvedPath,
539 name: OsString,
540 size: u32,
541 ) -> impl Future<Output = ResultXattr> + Send {
542 enosys_future()
543 }
544
545 /// List extended attributes for a file.
546 ///
547 /// * req: information about the FUSE request.
548 /// * path: path to the file.
549 /// * size: maximum number of bytes to return.
550 ///
551 /// If size is 0, return Xattr::Size(n) where n is the size required for the list of attribute
552 /// names. Otherwise, return Xattr::Data(data) where data is all the null-terminated attribute
553 /// names.
554 fn listxattr(
555 &self,
556 req: RequestInfo,
557 path: ResolvedPath,
558 size: u32,
559 ) -> impl Future<Output = ResultXattr> + Send {
560 enosys_future()
561 }
562
563 /// Remove an extended attribute from a file.
564 ///
565 /// * req: information about the FUSE request.
566 /// * path: path to the file.
567 /// * name: name of the attribute to remove.
568 fn removexattr(
569 &self,
570 req: RequestInfo,
571 path: ResolvedPath,
572 name: OsString,
573 ) -> impl Future<Output = ResultEmpty> + Send {
574 enosys_future()
575 }
576
577 /// Check for access to a file.
578 ///
579 /// * req: information about the FUSE request.
580 /// * path: path to the file.
581 /// * mask: mode bits to check for access to.
582 ///
583 /// Return Ok(()) if all requested permissions are allowed, otherwise return Err(EACCES)
584 /// or another appropriate error code (e.g. ENOENT if the file doesn't exist).
585 fn access(
586 &self,
587 req: RequestInfo,
588 path: ResolvedPath,
589 mask: u32,
590 ) -> impl Future<Output = ResultEmpty> + Send {
591 enosys_future()
592 }
593
594 /// Create and open a new file.
595 ///
596 /// * req: information about the FUSE request.
597 /// * path: path to the new file.
598 /// * mode: the mode to set on the new file.
599 /// * flags: flags that would be passed to open.
600 ///
601 /// Return a CreatedEntry containing the new file's attributes and a file handle. See the
602 /// documentation for open for more information about file handles.
603 fn create(
604 &self,
605 req: RequestInfo,
606 path: ResolvedPath,
607 mode: u32,
608 flags: u32,
609 ) -> impl Future<Output = ResultCreate> + Send {
610 enosys_future()
611 }
612
613 /// macOS only: Rename the volume.
614 ///
615 /// * req: information about the FUSE request.
616 /// * name: new name for the volume.
617 #[cfg(target_os = "macos")]
618 fn setvolname(
619 &self,
620 req: RequestInfo,
621 name: OsString,
622 ) -> impl Future<Output = ResultEmpty> + Send {
623 enosys_future()
624 }
625
626 /// macOS only: Query extended times (bkuptime and crtime).
627 ///
628 /// * req: information about the FUSE request.
629 /// * path: path to the file to get the times for.
630 ///
631 /// Return an XTimes struct containing the times, or an appropriate error.
632 #[cfg(target_os = "macos")]
633 fn getxtimes(
634 &self,
635 req: RequestInfo,
636 path: ResolvedPath,
637 ) -> impl Future<Output = ResultXTimes> + Send {
638 enosys_future()
639 }
640}