Struct Client 

pub struct Client { /* private fields */ }

One ZeroFS session, one identity. Share via Arc; every method takes &self and is safe to call concurrently. The underlying connection reconnects transparently, blocking calls through outages; bound waits with your async runtime’s timeout facilities (every future is cancel-safe).

Paths are bytes, as on POSIX and the 9P wire: every path parameter is impl AsRef<Path>, so &str, PathBuf, and OsStr::from_bytes(..) for non-UTF-8 names all work.

Implementations

impl Client

pub async fn connect(target: &str) -> Result<Arc<Client>, ZeroFsError>

Connect with defaults. Targets: "unix:/sock", "tcp://host:port", "host:port", "host" (port 5564), or a bare filesystem path (unix socket).

pub async fn connect_with( target: &str, opts: ConnectOptions, ) -> Result<Arc<Client>, ZeroFsError>

Connect with explicit identity, timeout, and tuning.

pub fn capabilities(&self) -> Capabilities

Snapshot of currently negotiated session properties (may change across transparent reconnects).

pub async fn close(&self)

Mark the client closed (later calls return Closed), then hand the root fid to the janitor for a background clunk + recycle. Always succeeds, idempotent, and never blocks (no await), so a cancelled close still reclaims the root fid. Outstanding File/Dir handles keep working until individually closed.

pub async fn read(&self, path: impl AsRef<Path>) -> Result<Bytes, ZeroFsError>

Read the entire file into memory. Returns Bytes: a whole file that fits in one round trip comes back with no copy.

pub async fn read_range( &self, path: impl AsRef<Path>, offset: u64, len: u32, ) -> Result<Bytes, ZeroFsError>

Read up to len bytes at offset; a shorter result means EOF.

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

Create-or-truncate path (mode 0o644) and write all of data (composed client-side: open/create + truncate + write).

pub async fn append( &self, path: impl AsRef<Path>, data: &[u8], ) -> Result<u64, ZeroFsError>

Append data at end-of-file (open-or-create + fstat + positioned write, composed client-side); returns the offset where the data landed. Last-writer-wins under concurrent appenders.

pub async fn stat( &self, path: impl AsRef<Path>, ) -> Result<Metadata, ZeroFsError>

Report the entry at path without following symlinks; anywhere: a path THROUGH a symlinked directory fails NotADirectory (9P walks are literal; this applies to every path-taking method). Self::metadata and Self::canonicalize are the only resolvers.

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

Like Self::stat but resolves symlinks (final AND intermediate components) client-side (readlink + re-walk), capped at 40 hops.

pub async fn canonicalize( &self, path: impl AsRef<Path>, ) -> Result<PathBuf, ZeroFsError>

Resolve every symlink in path (40-hop cap) and return the canonical path, for use with any other method. Lossless: paths are bytes, so a non-UTF-8 component survives the round trip.

pub async fn exists(&self, path: impl AsRef<Path>) -> Result<bool, ZeroFsError>

True if the path exists (any file type, no symlink following); NotFound becomes false.

pub async fn set_attr( &self, path: impl AsRef<Path>, attrs: SetAttrs, ) -> Result<Metadata, ZeroFsError>

Apply any combination of metadata changes; returns post-change metadata.

pub async fn chmod( &self, path: impl AsRef<Path>, mode: u32, ) -> Result<Metadata, ZeroFsError>

Change permission bits.

pub async fn chown( &self, path: impl AsRef<Path>, uid: Option<u32>, gid: Option<u32>, ) -> Result<Metadata, ZeroFsError>

Change owner and/or group (None leaves a field untouched).

pub async fn truncate( &self, path: impl AsRef<Path>, size: u64, ) -> Result<Metadata, ZeroFsError>

Truncate or extend a file to size bytes.

pub async fn set_times( &self, path: impl AsRef<Path>, atime: Option<SetTime>, mtime: Option<SetTime>, ) -> Result<Metadata, ZeroFsError>

Set access/modification times (utimens; None leaves a field untouched).

pub async fn statfs(&self) -> Result<StatFs, ZeroFsError>

Filesystem-wide usage and limits.

pub async fn sync(&self) -> Result<(), ZeroFsError>

Flush to durable (S3-backed) storage. On ZeroFS the server-side flush is filesystem-global, so this is the durability endpoint for write→rename sequences.

pub async fn create_dir( &self, path: impl AsRef<Path>, mode: u32, ) -> Result<Metadata, ZeroFsError>

Create a directory; the parent must exist.

pub async fn create_dir_all( &self, path: impl AsRef<Path>, mode: u32, ) -> Result<(), ZeroFsError>

Create a directory and any missing ancestors.

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

Remove a file, symlink, or device node.

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

Remove an empty directory.

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

Remove a directory and all its contents, recursively (client-side walk, not atomic).

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

Atomically rename/move within the filesystem; replaces an existing target.

pub async fn hard_link( &self, original: impl AsRef<Path>, link: impl AsRef<Path>, ) -> Result<Metadata, ZeroFsError>

Create a hard link at link pointing to the inode of original.

pub async fn symlink( &self, target: impl AsRef<Path>, link_path: impl AsRef<Path>, ) -> Result<Metadata, ZeroFsError>

Create a symlink at link_path containing target (stored verbatim, bytes included).

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

Read a symlink target. Lossless: the target is returned byte-for-byte.

pub async fn mknod( &self, path: impl AsRef<Path>, kind: NodeKind, mode: u32, ) -> Result<Metadata, ZeroFsError>

Create a fifo, socket, or device node; mode carries permission bits only; the type (and device numbers) come from kind.

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

List a whole directory (./.. excluded); metadata inline when the server supports readdirplus.

pub async fn open_dir( &self, path: impl AsRef<Path>, ) -> Result<Arc<Dir>, ZeroFsError>

Open a directory for incremental listing and byte-exact child operations.

pub async fn open( &self, path: impl AsRef<Path>, opts: OpenOptions, ) -> Result<Arc<File>, ZeroFsError>

Open (and optionally create) a file for positioned I/O.

pub async fn create( &self, path: impl AsRef<Path>, ) -> Result<Arc<File>, ZeroFsError>

Shorthand: open read-write with create+truncate, mode 0o644.

Trait Implementations

impl Debug for Client

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

Formats the value using the given formatter.