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 MetadataFields, Capabilities, CopyOption, DirEntry, ErrorDomain, FilesystemStats,
14    Metadata, MetadataUpdate, OpenFlags, OpenRequest, Permissions, RemoveOptions, StatusCode,
15    TransportKind, VfType as FileType,
16};
17/// Atomic destination behavior requested by [`Vfsi::vrename_with_options`].
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}
26pub use std::io::ErrorKind;
27pub use std::ops::ControlFlow;
28mod traits;
29pub use traits::{FileHandle, Vfsi, VfsiExt};
30mod metadata;
31pub use metadata::MetadataOptions;
32mod read;
33pub use read::{ReadOp, ReadOptions, ReadResult};
34mod write;
35pub use write::{WriteOp, WriteOptions};
36mod visit;
37pub use visit::VisitOptions;
38mod support;
39pub use support::{
40    DEFAULT_DIRECTORY_MAX_ENTRIES, DEFAULT_DIRECTORY_MAX_PATH_BYTES,
41    DEFAULT_READ_ALLV_MAX_TOTAL_BYTES, DEFAULT_READ_MAX_BYTES, DEFAULT_READ_STREAM_CHUNK_BYTES,
42    DEFAULT_READV_MAX_TOTAL_BYTES, DEFAULT_WALK_MAX_DEPTH, DepthLimit, DirectoryListing,
43    ReadDirOptions, ReadStreamOptions, ResourceLimits, StreamCompletion, TraversalCompletion,
44    WalkOptions,
45};
46pub use support::{ReadIntoResult, WriteResult};
47mod traversal;
48#[doc(hidden)]
49pub use traversal::walk_events;
50pub use traversal::{WalkControl, WalkEvent, WalkEventKind};
51/// What each input to [`Vfsi::vremove`] removes.
52#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
53pub enum RemoveMode {
54    /// Remove a file, symlink, or empty directory; do not traverse directories.
55    #[default]
56    Entry,
57    /// Remove the entry and, for directories, its descendants.
58    Tree,
59    /// Remove descendants while retaining the directory root. Final symlinks
60    /// are not followed; execution uses the backend's anchored removal path.
61    Contents,
62}
63
64/// Unstable dispatch projections for workspace backend implementations.
65#[doc(hidden)]
66pub mod internal {
67    pub use super::read::{ReadRequest, consume_ops, read_batch};
68    pub use super::support::FsReadResult as OwnedReadResult;
69}
70
71/// Common imports for backend-independent application code.
72pub mod prelude {
73    pub use super::{
74        ControlFlow, CopyOption, FileHandle, MetadataFields, MetadataOperand, MetadataOptions,
75        MetadataTarget, MetadataUpdate, OpenFlags, OpenRequest, ReadOp, ReadOptions, ReadResult,
76        ReadStreamOptions, RemoveMode, RemoveOptions, RenameOptions, ResourceLimits, Vfsi, VfsiExt,
77        VisitOptions, WriteOp, WriteOptions,
78    };
79}
80
81/// A path or an opened object for an attribute update. Handle targets retain
82/// object identity across rename/unlink; `follow_symlinks` applies only to paths.
83pub enum MetadataTarget<'a, F> {
84    Path(&'a std::path::Path),
85    File(&'a F),
86}
87impl<F> MetadataTarget<'_, F> {
88    pub fn path(path: &impl AsRef<std::path::Path>) -> MetadataTarget<'_, F> {
89        MetadataTarget::Path(path.as_ref())
90    }
91    pub fn file(file: &F) -> MetadataTarget<'_, F> {
92        MetadataTarget::File(file)
93    }
94}
95/// Inputs accepted by [`Vfsi::vsetattrs`]. Paths can be passed directly;
96/// use [`MetadataTarget`] to submit handles or mixed path/handle vectors.
97pub trait MetadataOperand<F> {
98    fn metadata_target(&self) -> MetadataTarget<'_, F>;
99}
100impl<F, P: AsRef<std::path::Path>> MetadataOperand<F> for P {
101    fn metadata_target(&self) -> MetadataTarget<'_, F> {
102        MetadataTarget::Path(self.as_ref())
103    }
104}
105impl<F> MetadataOperand<F> for MetadataTarget<'_, F> {
106    fn metadata_target(&self) -> MetadataTarget<'_, F> {
107        match self {
108            Self::Path(path) => MetadataTarget::Path(path),
109            Self::File(file) => MetadataTarget::File(file),
110        }
111    }
112}
vfsi_core/api/mod.rs

vfsi_core/api/
mod.rs
