Crate zerofs_client 

Async, path-based client for a ZeroFS server, speaking the private 9P2000.L.Z dialect over TCP or a unix socket natively, and over WebSocket in browser WASM builds.

The primary surface is one-shot path operations on a shared Client (read, write, stat, rename, mkdir), with File and Dir handles for chunked I/O, incremental listing, and openat-style child operations. Paths are byte-oriented. Native APIs accept non-UTF-8 paths; browser paths originate as UTF-8 JavaScript strings. The API uses owned data, an exhaustive error enum, Arc handles, explicit close, and cancellation cleanup for FFI compatibility.

The client asserts its uid at connect time and assumes a trusted network.

use zerofs_client::{Client, OpenOptions};

let fs = Client::connect("unix:/tmp/zerofs.9p.sock").await?;

fs.create_dir_all("/projects/demo", 0o755).await?;
fs.write("/projects/demo/hello.txt", b"hello from zerofs").await?;

let data = fs.read("/projects/demo/hello.txt").await?;
assert_eq!(&data[..], b"hello from zerofs");

for entry in fs.read_dir("/projects/demo").await? {
    let size = entry.metadata.size;
    println!("{size:>8}  {}", entry.name);
}

let file = fs
    .open("/projects/demo/big.bin", OpenOptions::read_write().create(true))
    .await?;
file.write_at(0, &vec![0u8; 4 << 20]).await?;
file.sync_all().await?;
file.close().await;

Lifecycles

Close and drop. close() marks the handle closed and is idempotent and non-blocking. Dropping the handle schedules its fid for release and recycling.

Cancellation. Dropping a Rust operation future releases any temporary fids it owns. If the future is dropped while a fid-state request is dispatched and unsettled, the connection that carried the request is retired. If it is still current, the session reconnects and replays before other operations resume. A dispatched mutation may still complete, leaving an ambiguous outcome. Callers supply per-operation timeouts when this ambiguity is acceptable. zerofs-ffi timeouts abandon a timed-out wait without cancelling the Rust future.

Connection loss. The session reconnects with backoff and restores state before accepting requests. In-flight mutations retain their op-id across resends. The retry horizon bounds automatic resends; expiry returns an ambiguous connection failure. An open-unlinked handle cannot be replayed and returns ESTALE after connection loss; other handles remain usable. The negotiated msize is fixed for the logical session; every reconnect target must accept that value.

Re-exports

pub use stream::DirStream;

Modules

io

tokio-io feature: a FileCursor adapter that turns the positioned File API into a stateful AsyncRead + AsyncWrite + AsyncSeek stream, so tokio::io::copy and friends work against a ZeroFS file. Rust-only; never crosses the FFI boundary.

stream

stream feature: a futures_core::Stream adapter over Dir listing, so a directory can be consumed with StreamExt (.next(), .collect(), try_for_each, …). Rust-only; never crosses the FFI boundary.

Structs

Bytes

Re-exported so callers need not depend on bytes directly; it is the return type of every read (cheap to clone and slice, derefs to &[u8]). A cheaply cloneable and sliceable chunk of contiguous memory.

Capabilities

Negotiated session properties, fixed for the logical session lifetime.

Client

One concurrent ZeroFS session and identity. Calls wait during reconnect. Cancelling an unsettled fid-state request retires the connection that carried it; the session reconnects and replays if that connection is still current. Cancelling a dispatched mutation leaves its outcome ambiguous.

ConnectOptions

Options for crate::Client::connect_with. Defaults are representable in UniFFI records. Rust resolves None identity fields during connect.

Dir

An open directory with a listing cursor and at-style child operations. Child names are one byte-exact component without / or NUL. Use DirEntry::name_bytes with the *_at methods for non-UTF-8 names.

DirEntry

One directory entry; the library filters out . and ...

File

An open file with concurrent positioned I/O.

Metadata

POSIX-shaped attributes; plain data record everywhere.

OpenOptions

FFI-compatible open options. Defaults are false and mode 420 (0o644). Append is exposed as crate::Client::append.

SetAttrs

Metadata changes; None fields are untouched. All-None is a no-op.

StatFs

Filesystem usage, from 9P statfs.

Timestamp

Nanosecond UNIX timestamp as explicit fields (predictable across all bindings).

TrafficStats

Cumulative wire traffic for this logical client across reconnects.

Enums

FileType

File type derived from the mode/dirent type.

NodeKind

Kind of special node for mknod; a tagged enum so callers never pack S_IF* bits or pass meaningless major/minor for fifos and sockets.

SetTime

A time to set: the server’s current clock, or an explicit instant.

ZeroFsError

Flat, exhaustive error type. New variants require matching updates in zerofs-ffi.