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 open_options(&self) -> OpenOptions<'_, F>

impl<F: Backend> FsClient<F>

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

impl<F: Backend> FsClient<F>

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 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.

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)], options: RenameOptions, ) -> Result<()>

Rename independent pairs in input order using the requested atomic destination behavior. Each pair is atomic where the backend supports the option; the vector is not a transaction, so failures may leave a completed prefix. Source and destination are resolved in this filesystem namespace. Unsupported guarantees return Unsupported rather than being emulated with check-then-rename.

fn vlistdirs<P: AsRef<Path>>( &self, paths: &[P], options: ListDirOptions, 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: StreamOptions, 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: AttrsOptions, ) -> Result<Vec<Attrs>>

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: &[OpenOp]) -> 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)], options: CopyOption, ) -> 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.