Struct FsClient 

pub struct FsClient<F: FileSystem> { /* private fields */ }

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.

Implementations

impl<F: FileSystem> FsClient<F>

pub fn new(filesystem: F) -> Self

pub fn with_limits(self, limits: ResourceLimits) -> Self

Configure this client view and its future clones. Existing clones keep their policy; all views still share the same connection and ownership.

pub fn limits(&self) -> ResourceLimits

pub fn into_inner(self) -> Result<F, Self>

pub fn drain_cleanup(&self) -> VfResult<()>

Drain queued Drop cleanup and report the first failure. Failed targets remain owned for later cleanup. No new file operation is replayed.

impl<F: FileSystem> FsClient<F>

pub fn capabilities(&self) -> VfResult<Capabilities>

pub fn open(&self, path: impl AsRef<Path>) -> VfResult<FsFile<F>>

Open a path read-only.

pub fn open_with(&self, request: OpenRequest) -> VfResult<FsFile<F>>

pub fn open_options(&self) -> OpenOptions<'_, F>

pub fn create(&self, path: impl AsRef<Path>) -> VfResult<FsFile<F>>

pub fn read(&self, path: impl AsRef<Path>) -> VfResult<Vec<u8>>

pub fn read_with_limit( &self, path: impl AsRef<Path>, max_bytes: usize, ) -> VfResult<Vec<u8>>

Read one complete file while limiting the returned allocation.

Use FsFile::read_native or std::io::Read to stream files that should not be held in one allocation.

pub fn read_to_string(&self, path: impl AsRef<Path>) -> VfResult<String>

pub fn read_to_string_with_limit( &self, path: impl AsRef<Path>, max_bytes: usize, ) -> VfResult<String>

Read one complete UTF-8 file with a caller-selected allocation limit.

pub fn write(&self, path: impl AsRef<Path>, data: &[u8]) -> VfResult<()>

impl<F: FileSystem> FsClient<F>

pub fn read_stream( &self, path: impl AsRef<Path>, callback: impl FnMut(u64, &[u8]) -> VfResult<bool>, ) -> VfResult<StreamCompletion>

Stream one file from offset zero in bounded chunks.

The callback runs without holding the backend lock, so it may use this client or drop other files owned by it. Return Ok(false) to stop successfully. Callback errors are propagated. The file is closed on success, cancellation, callback error, or read error. At most one requested chunk is buffered at once.

pub fn read_stream_with_options( &self, path: impl AsRef<Path>, options: ReadStreamOptions, callback: impl FnMut(u64, &[u8]) -> VfResult<bool>, ) -> VfResult<StreamCompletion>

Stream one file using an explicit maximum chunk size.

impl<F: Backend> FsClient<F>

pub fn metadata(&self, path: impl AsRef<Path>) -> VfResult<Metadata>

pub fn symlink_metadata(&self, path: impl AsRef<Path>) -> VfResult<Metadata>

pub fn set_metadata(&self, path: impl AsRef<Path>) -> SetMetadata<'_, F>

impl<F: Backend> FsClient<F>

pub fn create_dir(&self, path: impl AsRef<Path>) -> VfResult<()>

pub fn create_dir_with_mode( &self, path: impl AsRef<Path>, mode: u32, ) -> VfResult<()>

pub fn read_dir(&self, path: impl AsRef<Path>) -> VfResult<Vec<DirEntry>>

pub fn read_dir_with_options( &self, path: impl AsRef<Path>, options: ReadDirOptions, ) -> VfResult<Vec<DirEntry>>

Read one directory with explicit entry and path-storage limits.

pub fn visit_dir( &self, path: impl AsRef<Path>, callback: impl FnMut(DirEntry) -> VfResult<ControlFlow<()>>, ) -> VfResult<TraversalCompletion>

Visit one directory one bounded page at a time. Continue(()) requests the next entry; Break(()) stops the entire visit successfully. The callback runs without the lock and may reenter or drop its files.

pub fn visit_dir_with_options( &self, path: impl AsRef<Path>, options: ReadDirOptions, callback: impl FnMut(DirEntry) -> VfResult<ControlFlow<()>>, ) -> VfResult<TraversalCompletion>

Visit entries with explicit entry and cumulative path-byte limits.

pub fn visit_dir_with_fields( &self, path: impl AsRef<Path>, fields: AttrMask, options: ReadDirOptions, callback: impl FnMut(DirEntry) -> VfResult<ControlFlow<()>>, ) -> VfResult<TraversalCompletion>

impl<F: Backend> FsClient<F>

pub fn create_dir_all(&self, path: impl AsRef<Path>) -> VfResult<()>

impl<F: Backend> FsClient<F>

pub fn remove_file(&self, path: impl AsRef<Path>) -> VfResult<()>

pub fn remove_dir(&self, path: impl AsRef<Path>) -> VfResult<()>

pub fn remove_dir_all(&self, path: impl AsRef<Path>) -> VfResult<()>

pub fn remove_dir_contents_impl(&self, path: impl AsRef<Path>) -> VfResult<()>

Remove the contents of a directory, keeping the directory itself.

pub fn rename( &self, from: impl AsRef<Path>, to: impl AsRef<Path>, ) -> VfResult<()>

impl<F: Backend> FsClient<F>

pub fn vrename<P: AsRef<Path>, Q: AsRef<Path>>( &self, pairs: &[(P, Q)], ) -> VfResult<()>

Rename independent source/destination pairs in one vector phase.

pub fn vrename_with_options<P: AsRef<Path>, Q: AsRef<Path>>( &self, pairs: &[(P, Q)], options: RenameOptions, ) -> VfResult<()>

Rename pairs using native atomic no-replace semantics where supported.

pub fn vmkdir_default<P: AsRef<Path>>(&self, paths: &[P]) -> VfResult<()>

Create directories in input order using vector MKDIR. Parents must already exist. This is not transactional: failure may leave a prefix.

pub fn vmkdir<P: AsRef<Path>>(&self, directories: &[(P, u32)]) -> VfResult<()>

Create directories with per-request Unix permission bits.

pub fn vsymlink<P: AsRef<Path>, Q: AsRef<Path>>( &self, pairs: &[(P, Q)], ) -> VfResult<()>

Create symbolic links in one native backend vector.

pub fn vreadlink<P: AsRef<Path>>(&self, paths: &[P]) -> VfResult<Vec<PathBuf>>

Read targets without converting Unix path bytes through UTF-8.

pub fn vhardlink<P: AsRef<Path>, Q: AsRef<Path>>( &self, pairs: &[(P, Q)], ) -> VfResult<()>

Create hard links in one native backend vector.

pub fn walk_events_with_options( &self, root: impl AsRef<Path>, fields: AttrMask, options: WalkOptions, sort_by_name: bool, callback: impl FnMut(&WalkEvent) -> VfResult<WalkControl>, ) -> VfResult<TraversalCompletion>

Lazy between directories, with selective no-follow metadata and pruning. Enter runs before any listing; Leave follows even a pruned directory. Sorting buffers one bounded directory, not the whole tree. The callback runs outside the backend lock. Limits include the starting object.

pub fn visit_walk( &self, root: impl AsRef<Path>, callback: impl FnMut(&DirEntry) -> VfResult<ControlFlow<()>>, ) -> VfResult<TraversalCompletion>

Visit a tree using bounded directory pages, never follows symlinks, and invokes the callback outside the backend lock. Unlike collecting walk, this trades multi-directory batching for bounded incremental delivery. A backend without native paging may retain one bounded listing; finish its pages before descending, so snapshots never accumulate across ancestor directories. ControlFlow::Break(()) stops the entire walk successfully, not merely the current subtree. Directory order is backend-defined.

pub fn visit_walk_with_options( &self, root: impl AsRef<Path>, options: WalkOptions, callback: impl FnMut(&DirEntry) -> VfResult<ControlFlow<()>>, ) -> VfResult<TraversalCompletion>

pub fn visit_walk_with_fields( &self, root: impl AsRef<Path>, fields: AttrMask, options: WalkOptions, callback: impl FnMut(&DirEntry) -> VfResult<ControlFlow<()>>, ) -> VfResult<TraversalCompletion>

pub fn directory_page_batch_size(&self) -> VfResult<usize>

Maximum safe cohort size for incremental directory paging.

pub fn read_dir_pages_with_fields( &self, paths: &[&Path], fields: AttrMask, cursors: Vec<Option<DirPageCursor>>, page_size: usize, max_entries: usize, ) -> VfResult<Vec<DirectoryPage>>

Fetch a bounded vector of directory pages, retaining backend cursors.

pub fn read_dirs<P: AsRef<Path>>( &self, paths: &[P], ) -> VfResult<Vec<DirectoryListing>>

List several directories with common stat attributes and finite allocation limits. Use read_dirs_with_options for richer fields.

impl<F: Backend> FsClient<F>

pub fn walk(&self, root: impl AsRef<Path>) -> VfResult<Vec<DirectoryListing>>

Recursively enumerate a bounded tree with common stat attributes. Use walk_with_options to select fields or change limits.

pub fn ensure_empty_dir(&self, path: impl AsRef<Path>) -> VfResult<()>

Create path if missing, otherwise empty it. Errors if it exists and is not a directory (a symlink to a directory is not a directory here).

pub fn remove_dir_all_with_options( &self, path: impl AsRef<Path>, options: RemoveOptions, ) -> VfResult<()>

Remove a directory tree with explicit error, batching, and retry policy.

pub fn remove_dir_contents_with_options( &self, path: impl AsRef<Path>, options: RemoveOptions, ) -> VfResult<()>

Empty a directory while keeping it, with explicit removal policy.

pub fn open_dir_handle(&self, path: impl AsRef<Path>) -> VfResult<FsDir<F>>

Open a genuine directory handle for race-resistant, handle-rooted removal. Backends that only return a path fail instead of silently losing the handle safety guarantee.

impl<F: Backend> FsClient<F>

pub fn symlink( &self, target: impl AsRef<Path>, link: impl AsRef<Path>, ) -> VfResult<()>

pub fn hard_link( &self, source: impl AsRef<Path>, link: impl AsRef<Path>, ) -> VfResult<()>

pub fn read_link(&self, path: impl AsRef<Path>) -> VfResult<PathBuf>

impl<F: Backend> FsClient<F>

pub fn copy( &self, source: impl AsRef<Path>, destination: impl AsRef<Path>, ) -> VfResult<()>

impl<F: Backend> FsClient<F>

pub fn symlink_metadata_with_fields( &self, path: impl AsRef<Path>, fields: AttrMask, ) -> VfResult<Metadata>

Fetch selected metadata for one path without following its final symlink. Unavailable fields remain None on Metadata.

pub fn read_dirs_with_options<P: AsRef<Path>>( &self, paths: &[P], fields: AttrMask, options: ReadDirOptions, ) -> VfResult<Vec<DirectoryListing>>

List multiple directories in a vector call. The limits apply to the aggregate returned entries and stored path bytes. Streaming backends apply these limits before collecting a full listing; a backend using the compatibility visit_dir fallback may buffer one directory first. An error discards the collected prefix; callers may retry individual directories if desired.

pub fn walk_with_options( &self, root: impl AsRef<Path>, fields: AttrMask, options: WalkOptions, ) -> VfResult<Vec<DirectoryListing>>

Recursively enumerate directories with selected entry attributes. The walk is bounded by options; sorting and presentation remain the application’s responsibility.

pub fn vcopy<P: AsRef<Path>, Q: AsRef<Path>>( &self, pairs: &[(P, Q)], ) -> VfResult<()>

Copy whole files in request order. A successful prefix may remain if a later request fails; this operation does not provide atomicity.

pub fn vremove_native<P: AsRef<Path>>( &self, paths: &[P], recursive: bool, ) -> VfResult<()>

Remove paths in request order, optionally recursing into directories. A successful prefix may remain if a later path fails.

pub fn vremove_with_options_native<P: AsRef<Path>>( &self, paths: &[P], recursive: bool, options: RemoveOptions, ) -> VfResult<()>

Remove paths with explicit error, batching, and retry policy.

pub fn vgetattrs_native<P: AsRef<Path>>( &self, paths: &[P], fields: AttrMask, follow: bool, ) -> VfResult<Vec<Metadata>>

Vector metadata query with explicit fields and final-symlink handling. Ancestor symlinks follow the backend’s normal namespace semantics.

pub fn vsymlink_metadata_native( &self, paths: &[&Path], ) -> VfResult<Vec<Metadata>>

Fetch no-follow metadata for many paths using the backend vector operation.

impl<F: Backend> FsClient<F>

pub fn vopen(&self, requests: &[OpenRequest]) -> VfResult<Vec<FsFile<F>>>

Open an ordered vector of files.

Success returns one RAII handle per request. Failure returns no handles; VFSI does not promise transactional rollback of other filesystem effects such as file creation.

pub fn vclose<'a>( &self, files: impl IntoIterator<Item = &'a mut FsFile<F>>, ) -> VfResult<()>

where F: 'a,

Try to close a group through one vector operation without consuming the handles. On failure, all handles remain armed: the backend may have closed a prefix, so callers must reconcile before retrying.

pub fn vclose_owned(&self, files: Vec<FsFile<F>>) -> VfResult<()>

Close a group of files through one vector operation.

On failure, the handles are dropped and the backend receives best-effort scalar cleanup attempts. Use vclose to retain the handles after an error.

pub fn vread_native( &self, requests: &[FsRead<'_, F>], ) -> VfResult<Vec<FsReadResult>>

Read an ordered vector with a 16 MiB aggregate request limit. Use vread_with_limit_native to tune the limit or vread_into_native to provide bounded caller-owned buffers.

pub fn vread_with_limit_native( &self, requests: &[FsRead<'_, F>], max_total_bytes: usize, ) -> VfResult<Vec<FsReadResult>>

Read an ordered vector with an explicit aggregate request limit.

pub fn vread_with_limit_projected_native<'b, T>( &self, requests: &[T], max_total_bytes: usize, project: impl for<'r> Fn(&'r T) -> &'r FsRead<'b, F>, ) -> VfResult<Vec<FsReadResult>>

where F: 'b,

Backend adapter for opaque application requests; projection does not allocate. The projection must return the same embedded request on every invocation.

pub fn vread_into_native( &self, requests: &mut [FsReadInto<'_, F>], ) -> VfResult<Vec<FsReadIntoResult>>

pub fn vread_into_with_limit_native( &self, requests: &mut [FsReadInto<'_, F>], max_bytes: usize, ) -> VfResult<Vec<FsReadIntoResult>>

Read into caller storage with an explicit aggregate buffer budget. This also bounds allocation in copying fallback implementations.

pub fn vread_into_with_limit_projected_native<'b, T>( &self, requests: &mut [T], max_bytes: usize, project: impl for<'r> Fn(&'r T) -> &'r FsReadInto<'b, F>, project_mut: impl for<'r> FnMut(&'r mut T) -> &'r mut FsReadInto<'b, F>, ) -> VfResult<Vec<FsReadIntoResult>>

where F: 'b,

Project borrowed buffers without an intermediate request allocation. Both projections must identify the same embedded request, and remain stable across preflight, dispatch, and result validation.

pub fn vwrite_native( &self, requests: &[FsWrite<'_, F>], ) -> VfResult<Vec<FsWriteResult>>

pub fn vwrite_projected_native<'b, T>( &self, requests: &[T], project: impl for<'r> Fn(&'r T) -> &'r FsWrite<'b, F>, ) -> VfResult<Vec<FsWriteResult>>

where F: 'b,

Backend adapter for opaque application requests, preserving borrowed payloads. The projection must return the same embedded request on every invocation.

pub fn vwrite_all_native( &self, requests: &[FsWrite<'_, F>], ) -> VfResult<Vec<FsWriteResult>>

Write every byte in each positional request, retrying short writes in vector waves. Like vwrite_native, this is not transactional: an error may follow a successfully written prefix. Overlapping requests through the same path complete in input order; different paths are presumed independent (including hard-link aliases).

pub fn vwrite_all_projected_native<'b, T>( &self, requests: &[T], project: impl for<'r> Fn(&'r T) -> &'r FsWrite<'b, F>, ) -> VfResult<Vec<FsWriteResult>>

where F: 'b,

Complete projected requests with the same preflight and dependency waves. The projection must return the same embedded request on every invocation.

impl<F: Backend> FsClient<F>

pub fn read_files<P: AsRef<Path>>(&self, paths: &[P]) -> VfResult<Vec<Vec<u8>>>

Read several complete files by path using vector READ operations.

The aggregate returned data is limited to 16 MiB by default. Use read_files_with_options to choose a different limit, or stream large files instead. This is not a snapshot or an atomic operation across files.

pub fn read_files_with_options<P: AsRef<Path>>( &self, paths: &[P], options: ReadAllOptions, ) -> VfResult<Vec<Vec<u8>>>

Read several complete files with an explicit aggregate allocation limit.

pub fn write_files<P: AsRef<Path>, B: AsRef<[u8]>>( &self, entries: &[(P, B)], ) -> VfResult<()>

Replace several files from borrowed buffers using vector OPEN, WRITE, and CLOSE phases. Identical path spellings are rejected before opening anything; aliases such as hard links are still the caller’s responsibility. The batch is not transactional: an error may follow files already created or written. Large inputs should be chunked by the caller rather than held in memory solely for this convenience method.

impl<F: FileSystem> FsClient<F>

pub fn vstatfs<P: MetadataOperand<FsFile<F>>>( &self, targets: &[P], ) -> VfResult<Vec<FilesystemStats>>

Query filesystems using one native vector of paths and retained handles.

pub fn vsetattrs<P: MetadataOperand<FsFile<F>>>( &self, updates: &[(P, MetadataUpdate)], follow_symlinks: bool, ) -> VfResult<()>

Update paths and open objects with one native attribute vector.

Trait Implementations

impl<F: FileSystem> Clone for FsClient<F>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<F: FileSystem> Debug for FsClient<F>

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<F: Backend + 'static> Vfsi for FsClient<F>

type File = FsFile<F>

Owned handle; vectors must contain handles belonging to this client.

fn vrename<P: AsRef<Path>, Q: AsRef<Path>>( &self, pairs: &[(P, Q)], ) -> Result<()>

Rename independent pairs in input order. Failures may leave a completed prefix. Source and destination belong to this filesystem’s namespace.

fn vlistdirs<P: AsRef<Path>>( &self, paths: &[P], options: VisitOptions, callback: impl FnMut(usize, DirectoryListing) -> Result<ControlFlow<()>>, ) -> Result<Vec<TraversalCompletion>>

Visit shallow directories (default) or recursive trees using bounded pages. Entry/path-byte limits are shared across roots; recursive visits also charge retained directory path bytes. Root index accompanies every owned directory page, including empty directories. Callbacks run outside backend locks and may reenter. Entries for one directory may span several pages. Break stops the whole vector. The returned prefix covers every root whose pages reached the callback; unfinished roots are Stopped. Pages may interleave between roots.

fn vstream<P: AsRef<Path>>( &self, paths: &[P], options: ReadStreamOptions, callback: impl FnMut(usize, u64, &[u8]) -> Result<bool>, ) -> Result<Vec<StreamCompletion>>

Stream files through bounded chunks without collecting whole contents. The callback receives the input index, byte offset, and borrowed chunk. False stops the whole vector; results contain its completed/stopped prefix. Backends may process streams sequentially; this is not a parallelism promise.

fn capabilities(&self) -> Result<Capabilities>

Capabilities supported by this client. Routed clients report capabilities common to their routes; support does not imply authorization for a path.

fn vsymlink<P: AsRef<Path>, Q: AsRef<Path>>( &self, pairs: &[(P, Q)], ) -> Result<()>

Create symbolic links from (target text, link path) pairs. Targets are stored verbatim, including relative or dangling targets. Parents must exist. Errors may follow partial creation; no rollback.

fn vreadlink<P: AsRef<Path>>(&self, paths: &[P]) -> Result<Vec<PathBuf>>

Read symbolic link targets in input order without following final links. Returns their original path bytes, including non-UTF-8 names on Unix. An error identifies the input when known and discards collected results.

fn vhardlink<P: AsRef<Path>, Q: AsRef<Path>>( &self, pairs: &[(P, Q)], ) -> Result<()>

Create hard links from (existing source, new link path) pairs. Sources are not followed when the final component is a symlink. Cross-filesystem links can fail. Errors may follow partial creation.

fn vstatfs<P: MetadataOperand<Self::File>>( &self, targets: &[P], ) -> Result<Vec<FilesystemStats>>

Query filesystems for paths (following symlinks) and retained open handles. Results preserve input order. Unsupported fields are None.

fn vsetattrs<P: MetadataOperand<Self::File>>( &self, updates: &[(P, MetadataUpdate)], follow_symlinks: bool, ) -> Result<()>

Update selected attributes for paths or open handles using native batching. Every handle is validated before dispatch, including ownership and closure. Unspecified fields are unchanged. follow_symlinks controls the final component of path targets; it does not change open-handle identity. Ancestor symlinks retain ordinary backend resolution. Failure can follow partial mutations, including within one request; an error index identifies an input, not a committed-prefix count. Empty vectors succeed without I/O. Do not replay ambiguous failures.

fn vgetattrs<P: AsRef<Path>>( &self, paths: &[P], options: MetadataOptions, ) -> Result<Vec<Metadata>>

Query metadata in input order with selected fields and final-symlink behavior. Backend execution must preserve vector batching. Ancestor symlinks use ordinary namespace resolution; this is not a snapshot or confinement API.

fn limits(&self) -> ResourceLimits

Collection/batch defaults, not a process memory cap or file-reader cap.

fn vopen(&self, requests: &[OpenRequest]) -> Result<Vec<Self::File>>

Strict ordered OPEN results. Failure releases returned handles but cannot undo files created/truncated earlier; index() is not a progress count.

fn vread<'a>( &self, ops: impl IntoIterator<Item = ReadOp<'a, Self::File>>, options: ReadOptions, ) -> Result<Vec<ReadResult>>

Consume a read batch with an explicit aggregate logical-byte budget. Large files should usually be streamed instead of increasing the budget. Explicit options override client defaults.

fn vwrite<'a>( &self, requests: &[WriteOp<'a, Self::File>], options: WriteOptions, ) -> Result<Vec<WriteResult>>

Write positional ranges with explicit short-write policy. With default options, report accepted byte counts without completing short writes. With write_all(true), finish short writes after whole-batch local preflight. Backend failures can still follow mutations; aliasing paths are the caller’s responsibility and do not imply transactional ordering.

fn vclose(&self, files: &mut [Self::File]) -> Result<()>

Retain handles for failed cleanup; completed groups can already be closed. A lost reply leaves remote state ambiguous, not safely open.

fn vmkdir<P: AsRef<Path>>(&self, paths: &[(P, u32)]) -> Result<()>

Strict vector directory creation. Parents must already exist; errors can follow completed mutations, and do not imply rollback.

fn vcopy<P: AsRef<Path>, Q: AsRef<Path>>(&self, pairs: &[(P, Q)]) -> Result<()>

Strict file-copy batches; a failed call can have copied earlier files.

fn vremove<P: AsRef<Path>>( &self, paths: &[P], mode: RemoveMode, options: RemoveOptions, ) -> Result<()>

Remove entries, recursive trees, or directory contents with explicit policy.

fn vrename_with_options<P, Q>( &self, pairs: &[(P, Q)], options: RenameOptions, ) -> Result<(), VfError>

where P: AsRef<Path>, Q: AsRef<Path>,

Rename pairs with explicit atomic destination behavior. Each NoReplace pair is atomic, but a vector is not a transaction and a prefix may complete before a later pair fails. Backends without a native guarantee return Unsupported; they must never emulate it with check-then-rename.