io-m2dir 0.2.0

M2dir client library for Rust
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
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

//! # Generator-shape coroutine contract
//!
//! Mirrors the shape of `core::ops::Coroutine`: a `Yield` associated type for
//! intermediate progress, a `Return` associated type for terminal output, and a
//! two-variant [`M2dirCoroutineState`] (`Yielded` / `Complete`).
//!
//! io-m2dir is filesystem-flavoured, so every coroutine in the crate picks the
//! standard [`M2dirYield`] directly: it gathers every filesystem (and
//! environmental) primitive the crate emits, namely directory create / remove /
//! read, file create / read / exists / remove, path rename, and the process id
//! / random bytes inputs needed to mint m2dir entry identifiers.
//!
//! [`M2dirClient::run`] runs any standard-Yield coroutine to completion
//! against the local filesystem.
//!
//! [`M2dirClient::run`]: crate::client::M2dirClient::run

use alloc::{
    collections::{BTreeMap, BTreeSet},
    vec::Vec,
};

use crate::path::M2dirPath;

/// State yielded by an [`M2dirCoroutine::resume`] step.
///
/// Two-variant by design (matches std's `core::ops::CoroutineState`): any
/// further variation lives inside the per-coroutine `Yield` type.
#[derive(Debug)]
pub enum M2dirCoroutineState<Y, R> {
    /// Intermediate yield. The caller reacts to `Y` (do filesystem I/O, supply
    /// pid / random bytes…) and resumes the coroutine again.
    Yielded(Y),
    /// Terminal yield. By convention `R = Result<Output, Error>`.
    Complete(R),
}

/// Standard-shape m2dir coroutine.
///
/// Implementors own their internal state machine and declare their per-step
/// `Yield` plus a terminal `Return`. The caller reacts to each `Yield` variant
/// and resumes until `Complete`.
pub trait M2dirCoroutine {
    /// Intermediate value handed back on every step. Per-coroutine: each
    /// implementor picks exactly the variants it needs. In io-m2dir every
    /// coroutine picks [`M2dirYield`].
    type Yield;
    /// Terminal value. By convention `Result<Output, Error>`; the "ok" arm
    /// carries the operation's final output, the "error" arm carries the cause.
    type Return;

    /// Advances the coroutine one step.
    ///
    /// Pass [`None`] on the initial call. Pass `Some(arg)` carrying the value
    /// matching the previous `Yielded` variant.
    fn resume(&mut self, arg: Option<M2dirArg>) -> M2dirCoroutineState<Self::Yield, Self::Return>;
}

/// Standard filesystem-only Yield. Every io-m2dir coroutine picks `type Yield =
/// M2dirYield`.
///
/// Each variant is paired with the matching [`M2dirArg`] variant the caller
/// feeds back on the next `resume`.
#[derive(Debug)]
pub enum M2dirYield {
    /// Caller must supply the current process id and feed back
    /// [`M2dirArg::Pid`].
    WantsPid,
    /// Caller must supply `len` random bytes and feed back
    /// [`M2dirArg::Random`].
    WantsRandom { len: usize },
    /// Caller must check each path for existence as a regular file and feed
    /// back [`M2dirArg::FileExists`].
    WantsFileExists(BTreeSet<M2dirPath>),
    /// Caller must list each directory's entries and feed back
    /// [`M2dirArg::DirRead`].
    WantsDirRead(BTreeSet<M2dirPath>),
    /// Caller must create each directory (with parents) and feed back
    /// [`M2dirArg::DirCreate`].
    WantsDirCreate(BTreeSet<M2dirPath>),
    /// Caller must recursively remove each directory and feed back
    /// [`M2dirArg::DirRemove`].
    WantsDirRemove(BTreeSet<M2dirPath>),
    /// Caller must read each file's bytes and feed back [`M2dirArg::FileRead`].
    WantsFileRead(BTreeSet<M2dirPath>),
    /// Caller must write each `(path, bytes)` pair and feed back
    /// [`M2dirArg::FileCreate`].
    WantsFileCreate(BTreeMap<M2dirPath, Vec<u8>>),
    /// Caller must remove each file and feed back [`M2dirArg::FileRemove`].
    WantsFileRemove(BTreeSet<M2dirPath>),
    /// Caller must rename each `(from, to)` pair and feed back
    /// [`M2dirArg::Rename`].
    WantsRename(Vec<(M2dirPath, M2dirPath)>),
}

/// Reply fed back into [`M2dirCoroutine::resume`] by the caller.
///
/// Each variant matches the corresponding [`M2dirYield`] request and carries
/// the value the caller gathered while servicing it.
#[derive(Clone, Debug)]
pub enum M2dirArg {
    /// Reply to [`M2dirYield::WantsPid`].
    Pid(u32),
    /// Reply to [`M2dirYield::WantsRandom`].
    Random(Vec<u8>),
    /// Reply to [`M2dirYield::WantsFileExists`]: probed path to whether it
    /// exists as a regular file.
    FileExists(BTreeMap<M2dirPath, bool>),
    /// Reply to [`M2dirYield::WantsDirRead`]: probed directory to the set of
    /// paths found inside.
    DirRead(BTreeMap<M2dirPath, BTreeSet<M2dirPath>>),
    /// Reply to [`M2dirYield::WantsDirCreate`].
    DirCreate,
    /// Reply to [`M2dirYield::WantsDirRemove`].
    DirRemove,
    /// Reply to [`M2dirYield::WantsFileRead`]: probed file to its bytes (or an
    /// empty buffer when the file is missing).
    FileRead(BTreeMap<M2dirPath, Vec<u8>>),
    /// Reply to [`M2dirYield::WantsFileCreate`].
    FileCreate,
    /// Reply to [`M2dirYield::WantsFileRemove`].
    FileRemove,
    /// Reply to [`M2dirYield::WantsRename`].
    Rename,
}