Crate vfsi_sync 

Synchronous filesystem contracts.

FileSystem supports owned handles. Backend adds vector engines and overridable workflows; shared helpers compose those engines.

Re-exports

pub use traits::ReadAllOptions;

Modules

api

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

sfsi

Scalar/singular view of the synchronous interface.

vfsi

Vectorized view of the synchronous interface.

Structs

Adb

An Application Data Block (ADB) pattern, mirroring struct tc_adb.

AttrMask

A bitflags set of requested attributes.

Attrs

Idiomatic metadata returned by the Rust-native path API.

Capabilities

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

CopyOption

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

Compact traversal depth: 0 through 200 are finite, larger inputs are unlimited. The root has depth zero. Unlimited depth does not disable entry/byte budgets. Both this type and Option<DepthLimit> occupy one byte.

DirEntry

One native directory entry with its already-fetched metadata.

DirectoryListing

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

ExtentPair

One extent to copy, mirroring struct tc_extent_pair.

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.

FsClient

Cloneable owner of one synchronous backend connection. Clones share a mutex and serialize backend calls; use separate connections for parallel RPCs. Explicitly close handles to observe cleanup failures. Handle Drop queues cleanup, drained before later operations or by drain_cleanup. Dropping the final backend owner performs synchronous teardown and may wait for pending closes and backend request timeouts.

FsDir

Owned, handle-rooted directory. Dropping it queues backend cleanup; close reports cleanup errors explicitly.

FsFile

Owned RAII file which does not borrow the client.

FsRead

Typed read request for FsClient::vread_native.

FsReadInto

Typed vector read into caller-provided storage.

FsReadIntoResult

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

FsReadResult

Application result for one positional vector read, in request order.

FsWrite

Typed borrowed write request for FsClient::vwrite_native.

FsWriteResult

Application result for one positional vector write, in request order.

HandleId

Opaque identifier for a backend-owned open file.

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.

MetadataQuery

Typed metadata lookup request. Returned fields are still represented by VfAttrs during the compatibility transition, but request and mutation masks are no longer conflated.

MetadataUpdate

Rust-native metadata changes used by Backend.

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 tied to an FsClient.

Permissions

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

ReadAllOptions

Resource limits for reading multiple complete files into memory.

ReadDirOptions

Resource limits for one allocating directory listing.

ReadIntoResult

Metadata for a read placed directly into caller-provided storage.

ReadOp

One element of a batched read, replacing the C tc_iovec (which mixed input and output fields in a single mutable struct).

ReadOptions

Aggregate logical byte budget, defaulting to the client’s policy (16 MiB). Range request lengths must fit even if EOF returns fewer bytes. Complete files share the remaining returned-data budget and fail rather than truncate.

ReadResult

The result of one ReadOp: the data and whether end-of-file was hit. file echoes the request’s file reference so results can be paired back to mixed fd/path inputs without reordering assumptions.

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.

RpcError

An error from the low-level client: either an NFS4ERR_* status reported by the server for a compound operation, or a transport/RPC-level failure.

SetAttributes

Valid-by-construction metadata mutation request.

SetMetadata

Builder for an atomic metadata update request.

StreamOptions

Tuning options for bounded single-file streaming reads.

VfAttrs

File attributes, mirroring struct tc_attrs. mode is the full st_mode (permission bits plus S_IFMT file-type bits); the mtime/atime/ctime fields hold seconds and nanoseconds.

VfFileHandle

RAII descriptor adapter implementing standard synchronous Rust I/O traits.

VfOpenOptions

Idiomatic Rust open options for a VFSI filesystem.

WalkEntry

A directory and its entries, as returned by a filesystem walk. path is the directory’s root-relative path; entries are its immediate children.

WalkEvent

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

WalkOptions

Resource limits for an allocating recursive directory walk.

WriteOp

One element of a batched write.

WriteOpRef

Borrowed write request for callers that should not have to allocate an owned Vec<u8> merely to submit a vector operation.

WriteResult

The result of one WriteOp. file echoes the request’s file reference.

Enums

ErrorDomain

Namespace in which a status code is meaningful.

MetadataTarget

A path or an opened object for an attribute update. Handle targets retain object identity across rename/unlink; follow_symlinks applies only to paths.

SeekFrom

How filesystem seek operations interpret their offset, mirroring SEEK_SET / SEEK_CUR / SEEK_END as an enum.

StatusCode

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

StreamCompletion

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

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.

VfDir

An opaque handle to an open directory.

VfError

The failure of one operation in a vectorized call.

VfFile

A reference to a file: an open descriptor, a path, or a special pseudo-file. This is the Rust-native form of the C tc_file tagged struct (type + fd + path), where the variant is the tag.

VfOffset

The offset of a read or write operation.

VfPathBase

The base a path is resolved against, replacing the C VF_FD_CWD / VF_FD_ABS sentinel descriptors.

VfType

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

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.

ERR_ACCES

ERR_EBADF

ERR_EXIST

ERR_INVAL

ERR_IO

ERR_ISDIR

ERR_NOENT

Generic errno-style error codes (they coincide with the NFS4ERR codes for the same conditions, which the NFS backend reports).

ERR_NOTDIR

NF4BLK

NF4CHR

NF4DIR

NF4FIFO

NF4LNK

NF4REG

NFSv4 wire type codes (NF4*), used to decode/encode VfType.

NF4SOCK

STATUS_TRANSPORT

NFS4 status used for transport-level failures (there is no NFS status).

VF_CAP_HARDLINKS

The backend can create hard links and report their shared identity.

VF_CAP_LSTAT

The backend implements no-follow metadata operations (lstat semantics).

VF_CAP_NON_UTF8_PATHS

The backend accepts paths containing arbitrary non-UTF-8 Unix bytes.

VF_CAP_POSIX_METADATA

The backend reports and honors Unix mode/ownership/link-count metadata.

VF_CAP_SERVER_COPY

Capability bit returned by a backend’s capability query when it will currently attempt a server-side copy operation (NFSv4.2 COPY or SMB FSCTL_SRV_COPYCHUNK).

VF_CAP_SYMLINKS

The backend can create, inspect, and copy symbolic links without following them.

VF_CAP_UNIX_SEMANTICS

Capabilities shared by the complete Unix-like NFS and dummy backends.

VF_ERR_RPC

Errors that have no filesystem status (transport / client side).

VF_ERR_UNSUPPORTED

Requested feature is not implemented by this backend.

Traits

Backend

Native vector engines and backend workflow overrides.

FileHandle

Owned application file. Borrowed requests preserve the file’s lifetime; clients validate connection ownership before dispatching a vector.

FileSystem

Minimum contract for owned handles and descriptor lifecycle. This includes handle-level metadata/statistics hooks, but does not require namespace operations, directory enumeration, or native vector I/O.

MetadataOperand

Inputs accepted by Vfsi::vsetattrs. Paths can be passed directly; use MetadataTarget to submit handles or mixed path/handle vectors.

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. This uses borrowed request GATs, so it is for 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.

Functions

error_from_rpc

Convert an RPC error using an explicitly chosen logical request index. None keeps the failure unattributed; it never invents index zero. Transport errors retain their transport category rather than becoming a filesystem status. The RPC’s wire-operation index is not used here.

error_from_rpc_indexed

Convert a semantic RPC failure using its wire-operation index. Transport failures have no trustworthy operation index and remain unattributed. Callers mapping compound operations to logical requests should instead use error_from_rpc with their mapped index.

file_type_from_nfs

file_type_to_nfs

The NFSv4 wire type code.

metadata_from_attrs

Backend attribute conversion; absent fields remain absent.

open_flags_to_libc

Translate the typed flags for compatibility backends.

Type Aliases

Fd

An open file descriptor (backend-assigned), the Rust spelling of the C int fd.

ReadStreamCallback

Callback used by vectorized streaming reads.

RpcResult

Convenience alias used throughout the low-level client.

VfRes

Result of a compound-style operation: () on success, or the index and error of the first failing operation.

VfResult