vfsi_core/api/
mod.rs

1//! Portable synchronous vectorized filesystem API.
2//!
3//! Implement [`Vfsi`] for native vector execution; [`VfsiExt`] is blanket
4//! implemented and composes scalar conveniences and workflows from those vectors.
5//! This module has no backend, native RPC, or runtime dependencies.
6//!
7//! Application read/write operations live here rather than sharing the legacy
8//! backend operation types at the crate root.
9
10pub type Result<T> = crate::VfResult<T>;
11pub type Error = crate::VfError;
12pub use crate::{
13    AttrMask as Attributes, Attrs, Capabilities, CopyOption, DirEntry, ErrorDomain,
14    FilesystemStats, MetadataUpdate, OpenFlags, OpenOp, Permissions, RemoveOptions, StatusCode,
15    TransportKind, VfType as FileType,
16};
17/// Per-pair rename semantics requested by [`Vfsi::vrename`].
18#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
19pub enum RenameOptions {
20    /// Replace a destination according to ordinary filesystem rename semantics.
21    #[default]
22    Replace,
23    /// Fail atomically if the destination already exists.
24    NoReplace,
25    /// Atomically exchange the source and destination names.
26    /// Both paths must exist. This is available only on backends that provide
27    /// native exchange semantics; it is never emulated as multiple operations.
28    Exchange,
29}
30pub use std::io::ErrorKind;
31pub use std::ops::ControlFlow;
32mod traits;
33pub use traits::{FileHandle, Vfsi, VfsiExt};
34mod metadata;
35pub use metadata::AttrsOptions;
36mod read;
37pub use read::{ReadOp, ReadOptions, ReadResult};
38mod write;
39pub use write::{WriteOp, WriteOptions};
40mod visit;
41pub use visit::ListDirOptions;
42mod support;
43pub use support::{
44    DEFAULT_DIRECTORY_MAX_ENTRIES, DEFAULT_DIRECTORY_MAX_PATH_BYTES,
45    DEFAULT_READ_ALLV_MAX_TOTAL_BYTES, DEFAULT_READ_MAX_BYTES, DEFAULT_READ_STREAM_CHUNK_BYTES,
46    DEFAULT_READV_MAX_TOTAL_BYTES, DEFAULT_WALK_MAX_DEPTH, DepthLimit, DirectoryListing,
47    ReadDirOptions, ResourceLimits, StreamCompletion, StreamOptions, TraversalCompletion,
48    WalkOptions,
49};
50pub use support::{ReadIntoResult, WriteResult};
51mod traversal;
52#[doc(hidden)]
53pub use traversal::walk_events;
54pub use traversal::{WalkControl, WalkEvent, WalkEventKind};
55/// What each input to [`Vfsi::vremove`] removes.
56#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
57pub enum RemoveMode {
58    /// Remove a file, symlink, or empty directory; do not traverse directories.
59    #[default]
60    Entry,
61    /// Remove the entry and, for directories, its descendants.
62    Tree,
63    /// Remove descendants while retaining the directory root. Final symlinks
64    /// are not followed; execution uses the backend's anchored removal path.
65    Contents,
66}
67
68/// Unstable dispatch projections for workspace backend implementations.
69#[doc(hidden)]
70pub mod internal {
71    pub use super::read::{ReadRequest, consume_ops, read_batch};
72    pub use super::support::FsReadResult as OwnedReadResult;
73}
74
75/// Common imports for backend-independent application code.
76pub mod prelude {
77    pub use super::{
78        Attributes, AttrsOptions, ControlFlow, CopyOption, FileHandle, ListDirOptions,
79        MetadataOperand, MetadataTarget, MetadataUpdate, OpenFlags, OpenOp, ReadOp, ReadOptions,
80        ReadResult, RemoveMode, RemoveOptions, RenameOptions, ResourceLimits, StreamOptions, Vfsi,
81        VfsiExt, WriteOp, WriteOptions,
82    };
83}
84
85/// A path or an opened object for an attribute update. Handle targets retain
86/// object identity across rename/unlink; `follow_symlinks` applies only to paths.
87pub enum MetadataTarget<'a, F> {
88    Path(&'a std::path::Path),
89    File(&'a F),
90}
91impl<F> MetadataTarget<'_, F> {
92    pub fn path(path: &impl AsRef<std::path::Path>) -> MetadataTarget<'_, F> {
93        MetadataTarget::Path(path.as_ref())
94    }
95    pub fn file(file: &F) -> MetadataTarget<'_, F> {
96        MetadataTarget::File(file)
97    }
98}
99/// Inputs accepted by [`Vfsi::vsetattrs`]. Paths can be passed directly;
100/// use [`MetadataTarget`] to submit handles or mixed path/handle vectors.
101pub trait MetadataOperand<F> {
102    fn metadata_target(&self) -> MetadataTarget<'_, F>;
103}
104impl<F, P: AsRef<std::path::Path>> MetadataOperand<F> for P {
105    fn metadata_target(&self) -> MetadataTarget<'_, F> {
106        MetadataTarget::Path(self.as_ref())
107    }
108}
109impl<F> MetadataOperand<F> for MetadataTarget<'_, F> {
110    fn metadata_target(&self) -> MetadataTarget<'_, F> {
111        match self {
112            Self::Path(path) => MetadataTarget::Path(path),
113            Self::File(file) => MetadataTarget::File(file),
114        }
115    }
116}
vfsi_core/api/mod.rs

vfsi_core/api/
mod.rs
