Module api 

Portable application contracts, operations, options, and extension workflows. Portable synchronous vectorized filesystem API.

Implement Vfsi for native vector execution; VfsiExt is blanket implemented and composes scalar conveniences and workflows from those vectors. This module has no backend, native RPC, or runtime dependencies.

Application read/write operations live here rather than sharing the legacy backend operation types at the crate root.

Value-style options use with_<property>(value) to configure a copy and <property>() to inspect it. Neither performs I/O. Read-budget overrides remain optional: None inherits the client’s policy. Resolve inherited limits before interpreting them as effective execution budgets. Dedicated builders such as OpenOptions retain their standard builder-style verbs.

Modules

prelude

Common imports for backend-independent application code.

Structs

Attributes

A bitflags set of requested attributes.

Attrs

Idiomatic metadata returned by the Rust-native path API.

AttrsOptions

Select metadata fields and whether to follow the final symlink. Ancestor symlinks use ordinary backend path-resolution semantics.

Capabilities

Typed backend capabilities. Unlike the legacy integer constants, this rejects accidental mixing with unrelated bit fields.

CopyOptions

Options for whole-file copies through crate::api::Vfsi::vcopy. Source final symlinks are followed by default; ancestor symlinks use normal namespace resolution. This is not a snapshot. When preserving a source symlink, its link text is copied and an existing destination is not replaced. Destination symlinks for data copies retain normal following behavior.

DepthLimit

A checked finite traversal depth or an explicitly unlimited traversal. The root has depth zero. Unlimited depth retains entry and byte budgets. Finite depths 0 through 65,533 are representable; larger values are rejected. Both this type and Option<DepthLimit> occupy two bytes.

DirEntry

One native directory entry with its already-fetched metadata.

DirectoryListing

One directory and its entries, with attributes fetched during enumeration.

FilesystemStats

Filesystem capacity and limits for the filesystem containing a target. Values are observations, not reservations. None means unknown or unsupported. Byte counts use the filesystem allocation unit, not its preferred I/O size. Getters preserve zero and false as known values. Fluent with_* setters accept None to restore an unknown value.

FsObjId

Filesystem-scoped identifier for an underlying filesystem object.

ListDirOptions

Shared directory traversal policy for collection and paged visiting. Defaults to immediate children only. Collection retains native batching; visiting delivers owned directory pages incrementally through callbacks. Unspecified budgets inherit the client’s resource limits. Require no symlink components when false; metadata’s final-component option has a deliberately different name.

MkDirOp

One directory creation with explicit Unix permission bits. Construction performs no I/O and can borrow the path without allocating. Parents must exist; submit independent siblings together with super::Vfsi::vmkdir.

OpenFlags

Typed file-open behavior for the Rust-native API.

OpenOp

One complete open request. This replaces three error-prone parallel slices of paths, flags, and modes.

OpenOptions

std::fs::OpenOptions-style builder for any Vfsi client.

Permissions

Rust-native permission bits, independent of protocol wire attributes.

ReadIntoResult

Application result for one read into caller storage, in request order.

ReadOp

One consuming read operation. Construction performs no I/O or allocation. Caller buffers are borrowed only until Vfsi::vread returns, including on errors.

ReadOptions

Fluent configuration must be retained; discarding a changed copy is diagnosed.

ReadResult

Progress for one operation, with no borrowed references to caller storage.

RemoveOptions

Options controlling recursive removal.

ResourceLimits

Default resource policy for a client. Per-call options override it. Byte limits bound logical payload, not allocator capacity or RPC overhead.

SetAttrsOp

One attribute update for a path or opened object.

StreamOptions

Tuning options for bounded single-file streaming reads.

WalkEvent

Root is depth zero. Symlinks are Entry events and are never followed.

WalkOptions

Event-walk presentation policy, separate from native directory-page options. Sorting and lifecycle events buffer complete bounded directory listings.

WriteOp

A positional write borrowing its handle and payload without copying either. Construction performs no I/O or allocation. Does not change the file cursor. Uses the same storage definition as the native crate::WriteOp.

WriteOptions

Policy for positional vector writes. Defaults to reporting short writes. Completion is not atomicity, durability, or permission to replay failed RPCs.

WriteResult

Application result for one vector write, in request order. For completed append writes, offset + bytes_written is the last reported end; concurrent writers can interleave between short-write waves.

Enums

ControlFlow

Used to tell an operation whether it should exit early or go on as usual.

ErrorDomain

Namespace in which a status code is meaningful.

ErrorKind

A list specifying general categories of I/O error.

FileType

The NFSv4 object type, replacing the raw NF4* wire codes in VfAttrs::ftype.

RemoveMode

What each input to Vfsi::vremove removes.

RenameMode

Per-pair rename semantics requested by Vfsi::vrename.

StatusCode

Typed protocol/filesystem status. Transport failures have no status.

StreamCompletion

Completion of a streaming read. Stopping does not mean EOF.

SyncMode

Durability requested for every handle in a synchronization vector.

Target

Borrowed filesystem operand: a path to resolve or an already-open object. Used by attribute updates, filesystem statistics, and scalar conveniences. Handle targets retain object identity across rename/unlink; path symlink policies do not change that identity. A target never owns or closes a handle.

TransportKind

Transport provenance, not a guarantee that an operation is safe to retry. Unknown failures remain Other; messages are never parsed to classify them.

TraversalCompletion

Completion of a callback-based directory traversal.

WalkControl

Callback decision. Pruning never reads the directory’s contents.

WalkEventKind

Enter/Leave surround a directory, including a pruned directory.

Constants

DEFAULT_DIRECTORY_MAX_ENTRIES

Default maximum number of entries returned by allocating directory APIs.

DEFAULT_DIRECTORY_MAX_PATH_BYTES

Default combined path-storage budget for allocating directory APIs.

DEFAULT_READV_MAX_TOTAL_BYTES

Default aggregate payload limit for owned vector reads.

DEFAULT_READ_ALLV_MAX_TOTAL_BYTES

Default aggregate payload limit for complete-file vector reads.

DEFAULT_READ_MAX_BYTES

Default payload limit for APIs that allocate and return complete contents.

DEFAULT_READ_STREAM_CHUNK_BYTES

Default size of each chunk delivered by the bounded single-file stream API.

DEFAULT_WALK_MAX_DEPTH

Default recursion depth for recursive walks.

Traits

AsTarget

Borrow a target for metadata queries, attribute updates or filesystem statistics. Paths can be passed directly; use Target for handles or mixed vectors. Conversion performs no I/O. Clients convert each operand once at preflight and retain that target for routing, execution, and error context.

DirHandle

Owned directory retaining the opened object’s identity after rename or path replacement. Paths are diagnostic only; clients validate ownership and live state before handle-rooted operations. Failed try_close retains cleanup ownership.

FileHandle

Owned handle to one open file instance.

Vfsi

Vectorized filesystem operations for direct and routed application clients. Construction, builders and protocol-specific diagnostics stay concrete. Vectors are strict, ordered results on success, not transactions: errors can follow partially completed requests and never imply rollback. Generic vector and callback methods require static generic dispatch, not dyn Vfsi. It adds no boxing, data copies or serial-loop fallbacks.

VfsiExt

Scalar operations and convenience workflows alongside the Vfsi vectors.

Type Aliases

Error

Result