Client Libraries

ZeroFS ships official client libraries for Python, TypeScript/Node, and Go. They are a programmatic alternative to mounting: your process speaks 9P2000.L straight to the server and gets path-based filesystem calls (read, write, stat, readdir, open) with no kernel mount in between.

All three wrap one Rust core (zerofs-client) compiled to a native library, so they share its behavior exactly: the same connection targets, the same fast-path extensions, the same reconnect and cancellation semantics. They connect to the same [servers.ninep] endpoint a 9P mount uses, with the same trusted-network model: a client asserts its uid at connect time and the server trusts it.

Installation

Python

pip install zerofs-client

The wheel bundles the native library (manylinux and musllinux on Linux, plus macOS), so the install is self-contained (no Rust toolchain, no build step). Import zerofs_client for the idiomatic facade; the low-level uniffi module is also importable as zerofs_ffi.

import zerofs_client

async with await zerofs_client.Client.connect("unix:/run/zerofs/9p.sock") as fs:
    await fs.create_dir_all("/demo", 0o755)
    await fs.write("/demo/notes.txt", b"hello from zerofs")

    data = await fs.read("/demo/notes.txt")
    meta = await fs.metadata("/demo/notes.txt")
    print(len(data), meta.size, meta.is_file())

    # A File handle for positioned I/O.
    async with await fs.open("/demo/data.bin", zerofs_client.OpenOptions(write=True, create=True)) as f:
        await f.write_at(0, b"\x00" * 4096)
        await f.sync_all()

    # Stream the directory entry by entry.
    async with await fs.open_dir("/demo") as d:
        async for entry in d:
            print(entry.name)

    await fs.rename("/demo/notes.txt", "/demo/notes.md")
    await fs.remove_file("/demo/notes.md")
    await fs.remove_dir_all("/demo")

TypeScript / Node

npm install zerofs-client

The matching @zerofs/ffi-<platform> native package installs as an optional dependency and is selected at load time. The bindings call the library through koffi rather than WASM, so sockets work.

import { Client, openOptions, isFile } from "zerofs-client";

await using fs = await Client.connect("unix:/run/zerofs/9p.sock");

await fs.createDirAll("/demo", 0o755);
await fs.write("/demo/notes.txt", new TextEncoder().encode("hello from zerofs"));

const data = await fs.read("/demo/notes.txt");
const meta = await fs.metadata("/demo/notes.txt");
console.log(data.length, meta.size, isFile(meta));

// A File handle for positioned I/O.
await using f = await fs.open("/demo/data.bin", openOptions({ write: true, create: true }));
await f.writeAt(0n, new Uint8Array(4096));
await f.syncAll();

// Stream the directory entry by entry.
await using dir = await fs.openDir("/demo");
for await (const entry of dir) console.log(entry.name);

await fs.rename("/demo/notes.txt", "/demo/notes.md");
await fs.removeFile("/demo/notes.md");
await fs.removeDirAll("/demo");

Go

go get github.com/Barre/ZeroFS/zerofs/zerofs-ffi/bindings/go

The module ships the generated cgo sources and a C header, but not the native library: Go has no package registry that carries binaries. You build the zerofs-ffi cdylib from the ZeroFS source and point cgo at it; the module README covers the CGO_CFLAGS/CGO_LDFLAGS setup. This path needs a Rust toolchain and a C toolchain.

import (
	"log"

	zerofs "github.com/Barre/ZeroFS/zerofs/zerofs-ffi/bindings/go"
)

fs, err := zerofs.ClientConnect("unix:/run/zerofs/9p.sock")
if err != nil {
	log.Fatal(err)
}
defer fs.Close()

must := func(err error) { if err != nil { log.Fatal(err) } }

must(fs.CreateDirAll("/demo", 0o755))
must(fs.Write("/demo/notes.txt", []byte("hello from zerofs")))

data, err := fs.Read("/demo/notes.txt")
must(err)
meta, err := fs.Metadata("/demo/notes.txt")
must(err)
log.Printf("%d bytes, size=%d, isFile=%v", len(data), meta.Size, meta.IsFile())

// Stream the directory with a range-over-func iterator.
dir, err := fs.OpenDir("/demo")
must(err)
defer dir.Close()
for entry, err := range dir.Entries() {
	must(err)
	log.Println(entry.Name)
}

Connecting

Client.connect(target) takes the same target forms as zerofs mount and the kernel client:

For an explicit identity (uid/gid/uname), an attach subtree (aname), a custom msize, or a connect timeout, connect with a ConnectOptions (connect_with in Python/Go, connectWith in Node). The server clamps msize to 10 MiB, so requesting more has no effect (the same ceiling a 9P mount hits).

API reference

The full surface is the zerofs-client core projected mechanically by uniffi, plus a thin per-language facade. The tables below are the canonical, language-neutral reference for every operation and type; the projection rules turn each into a concrete per-language signature.

Projection rules

Every operation maps to each language by the same rules, so a single canonical signature is unambiguous in all three.

Client operations

One identity, one session, safe to share across tasks. Path arguments are strings; returns are shown in canonical form (-> Type; no arrow means the call returns nothing).

File operations

An open file; all I/O is positioned (there is no implicit cursor), usable from many tasks at once.

Directory operations

A pull-based listing cursor plus openat-style child operations. Child names cross as bytes, not strings, so non-UTF-8 entries need no separate API: feed DirEntry.name_bytes back in verbatim.

Types

OpenOptions — read (false), write (false), create (false), create_new (false), truncate (false), mode (0o644). create_new is the atomic exclusive create: it fails unless this call creates the file. In TypeScript, build it with the openOptions(...) helper so the defaults apply.

ConnectOptions — uid (process euid), gid (process egid), uname ($USER, informational), aname ("", the default export), msize (1 MiB; the server clamps to 10 MiB), connect_timeout_ms (30000; null waits indefinitely).

SetAttrs — optional mode, uid, gid, size, atime, mtime. An all-empty SetAttrs is a no-op; atime/mtime are SetTime.

SetTime — Now (the server clock) or At { time } (an explicit timestamp).

NodeKind — Fifo, Socket, BlockDevice { major, minor }, or CharDevice { major, minor }.

FileType — File, Dir, Symlink, Fifo, Socket, CharDevice, BlockDevice, Unknown.

Metadata — ino, file_type, mode (full st_mode), nlink, uid, gid, size, block_size, blocks (512-byte units), rdev, and atime/mtime/ctime timestamps. btime and data_version are reserved (servers currently report 0).

DirEntry — name (UTF-8, lossy: invalid bytes become U+FFFD), name_bytes (exact on-wire bytes for the *_at methods), name_is_utf8, file_type, ino, and metadata (present only when readdirplus is negotiated; null otherwise).

StatFs — block_size, blocks, blocks_free, blocks_available, files, files_free, filesystem_id, max_name_len.

Capabilities — extensions_v1, extensions_v2, msize, max_read_chunk, max_write_chunk. A live snapshot that can change across reconnects.

Idiomatic additions

uniffi generates a faithful but mechanical surface (async methods, raw handle objects). Each library layers a hand-written facade on top with the conveniences uniffi cannot express:

Connection loss and cancellation

Reconnection. The underlying session reconnects forever with backoff and replays its state. While the server is unreachable, calls block rather than fail, the same behavior as zerofs mount. One caveat: an operation in flight at the instant the connection drops is resent, so a non-idempotent operation (create, rename, unlink) can apply twice across a reconnect.

Cancellation. The libraries do not cancel server-side work; uniffi does not propagate host-side cancellation into Rust. Bound your own wait with the host's facilities: asyncio.wait_for (Python), Promise.race (TypeScript), or the Call(ctx, fn)/Do(ctx, fn) context wrappers (Go). These abandon the wait: they return as soon as your timeout fires while the in-flight operation keeps running until the server answers, then discards its result and self-cleans. Pass a deadline to bound how long you wait, not how long the server works.

Closing. close() marks a handle closed immediately, is idempotent, and never hangs. The server-side fid is released and its number recycled when the handle is dropped (or right after close() for scope-bound use), so a long-running client never exhausts fids.

Errors

Every fallible call surfaces one flat, exhaustive ZeroFsError. Exhaustive is deliberate: a new server-side variant fails the binding's build rather than silently degrading to a catch-all. The variant-to-errno mapping is 1:1, and error_to_errno(err) returns the Linux errno for any error (the Io variant carries its own).

Each language matches it idiomatically:

• Python raises typed exceptions: except zerofs_client.ZeroFsError.NotFound.
• TypeScript throws subclasses: err instanceof ZeroFsErrorNotFound.
• Go exposes sentinels for errors.Is(err, zerofs_ffi.ErrZeroFsErrorNotFound).

Security

Next Steps