Struct FsClient 

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

Cloneable owner of one synchronous backend connection.

Implementations

impl<F> FsClient<F>

pub fn new(filesystem: F) -> Self

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

impl<F: FileSystem> FsClient<F>

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<()>

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<()>

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<bool>, ) -> VfResult<()>

Visit one directory incrementally without retaining all entries in the application. The callback runs under the backend lock and must not call this client or drop other files owned by it.

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

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

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

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 open_dir(&self, path: impl AsRef<Path>) -> VfResult<VfDir>

Open a directory for handle-rooted removal. The returned handle cannot be swapped for a symlink between opening and removal; release it with close_dir.

pub fn remove_dir_contents_handle(&self, dir: &VfDir) -> VfResult<()>

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

pub fn close_dir(&self, dir: &VfDir) -> VfResult<()>

Release a handle from open_dir.

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

Fetch no-follow metadata for many paths using the backend’s vector operation. Useful for routing without one metadata RPC per path.

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(&self, files: &mut [FsFile<F>]) -> VfResult<()>

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

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

Read an ordered vector with an explicit aggregate request limit.

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

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

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

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

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> 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> Debug for FsClient<F>

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

Formats the value using the given formatter.