async-fs-io 0.2.0

Async-first filesystem primitives, bounded reads, streaming directory access, and temporary resources
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

//! Typed errors returned by the asynchronous filesystem boundary.

use std::path::Path;

/// The filesystem operation that failed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Operation {
    /// Reading file contents or metadata.
    Read,
    /// Writing, renaming, or removing file contents.
    Write,
    /// Creating, traversing, or removing directories.
    Directory,
    /// Acquiring or releasing a filesystem lock.
    Lock,
    /// Resolving a path before I/O begins.
    PathResolution,
}

impl Operation {
    /// Return the stable lower-case operation name.
    #[must_use]
    pub const fn name(self) -> &'static str {
        match self {
            Self::Read => "read",
            Self::Write => "write",
            Self::Directory => "directory",
            Self::Lock => "lock",
            Self::PathResolution => "path resolution",
        }
    }
}

/// Error from an asynchronous filesystem operation.
#[derive(Debug, thiserror::Error)]
pub enum FsError {
    /// A file read operation failed.
    #[error("file read error: {path}: {detail}")]
    Read {
        /// The path involved in the failed operation.
        path: String,
        /// Human-readable operating-system detail.
        detail: String,
    },
    /// A file write operation failed.
    #[error("file write error: {path}: {detail}")]
    Write {
        /// The path involved in the failed operation.
        path: String,
        /// Human-readable operating-system detail.
        detail: String,
    },
    /// A directory operation failed.
    #[error("directory error: {path}: {detail}")]
    Directory {
        /// The directory involved in the failed operation.
        path: String,
        /// Human-readable operating-system detail.
        detail: String,
    },
    /// A filesystem lock operation failed.
    #[error("lock error: {path}: {detail}")]
    Lock {
        /// The lock path involved in the failed operation.
        path: String,
        /// Human-readable operating-system detail.
        detail: String,
    },
    /// A path could not be resolved before filesystem I/O began.
    #[error("path resolution error: {0}")]
    PathResolution(String),
    /// A caller supplied an invalid bound or path relationship.
    #[error("invalid filesystem request: {0}")]
    InvalidRequest(String),
}

impl FsError {
    /// Construct an error with the appropriate operation and path context.
    #[must_use]
    pub fn io(operation: Operation, path: &Path, detail: impl std::fmt::Display) -> Self {
        let path = path.display().to_string();
        let detail = detail.to_string();
        match operation {
            Operation::Read => Self::Read { path, detail },
            Operation::Write => Self::Write { path, detail },
            Operation::Directory => Self::Directory { path, detail },
            Operation::Lock => Self::Lock { path, detail },
            Operation::PathResolution => Self::PathResolution(detail),
        }
    }
}