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: MetadataFileSystem> 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: DirectoryFileSystem> 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: DirectoryFileSystem + MetadataFileSystem> FsClient<F>

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

impl<F: NamespaceFileSystem + MetadataFileSystem> 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(&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: VecFs> FsClient<F>

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

Rename independent source/destination pairs in one vector phase.

pub fn mkdirv<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 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: VecFs> 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: LinkFileSystem> 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: CopyFileSystem> FsClient<F>

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

impl<F: VecFs> 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 copyv<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 remove_paths<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 remove_paths_with_options<P: AsRef<Path>>( &self, paths: &[P], recursive: bool, options: RemoveOptions, ) -> VfResult<()>

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

pub fn metadata_many<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 symlink_metadatav(&self, paths: &[&Path]) -> VfResult<Vec<Metadata>>

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

impl<F: VectorFileSystem> FsClient<F>

pub fn openv(&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 try_closev<'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 closev(&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 try_closev to retain the handles after an error.

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

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

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

Read an ordered vector with an explicit aggregate request limit.

pub fn readv_with_limit_projected<'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 readv_into( &self, requests: &mut [FsReadInto<'_, F>], ) -> VfResult<Vec<FsReadIntoResult>>

pub fn readv_into_with_limit( &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 readv_into_with_limit_projected<'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 writev( &self, requests: &[FsWrite<'_, F>], ) -> VfResult<Vec<FsWriteResult>>

pub fn writev_projected<'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 write_allv( &self, requests: &[FsWrite<'_, F>], ) -> VfResult<Vec<FsWriteResult>>

Write every byte in each positional request, retrying short writes in vector waves. Like writev, 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 write_allv_projected<'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: VectorFileSystem + VecFs> 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.

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: NativeFileSystem + VectorFileSystem + VecFs + '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 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]) -> 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.