zerofs_client/
lib.rs

1//! Async, path-based client for a ZeroFS server, speaking 9P2000.L (plus the
2//! ZeroFS fast-path extensions, used automatically when the server offers
3//! them) over TCP or a unix socket.
4//!
5//! The primary surface is one-shot path operations on a shared [`Client`] (
6//! read, write, stat, rename, mkdir), with [`File`] and [`Dir`] handles only
7//! where statefulness pays (chunked I/O, incremental listing, openat-style
8//! child operations). Paths are bytes, as on POSIX and the 9P wire: every
9//! path parameter is `impl AsRef<Path>`, so non-UTF-8 names need nothing
10//! special. The API otherwise stays FFI-friendly (owned buffers, a flat
11//! exhaustive error enum, `Arc` handles, explicit `close`, cancel-safe
12//! futures) for the `zerofs-ffi` bindings layer built on top.
13//!
14//! This is a trusted-network client: you assert your uid at connect time,
15//! NFS-style.
16//!
17//! ```no_run
18//! use zerofs_client::{Client, OpenOptions};
19//!
20//! # async fn demo() -> Result<(), zerofs_client::ZeroFsError> {
21//! let fs = Client::connect("unix:/tmp/zerofs.9p.sock").await?;
22//!
23//! fs.create_dir_all("/projects/demo", 0o755).await?;
24//! fs.write("/projects/demo/hello.txt", b"hello from zerofs").await?;
25//!
26//! let data = fs.read("/projects/demo/hello.txt").await?;
27//! assert_eq!(&data[..], b"hello from zerofs");
28//!
29//! for entry in fs.read_dir("/projects/demo").await? {
30//!     let size = entry.metadata.as_ref().map_or(0, |m| m.size);
31//!     println!("{size:>8}  {}", entry.name);
32//! }
33//!
34//! let file = fs
35//!     .open("/projects/demo/big.bin", OpenOptions::read_write().create(true))
36//!     .await?;
37//! file.write_at(0, &vec![0u8; 4 << 20]).await?;
38//! file.sync_all().await?;
39//! file.close().await;
40//! # Ok(())
41//! # }
42//! ```
43//!
44//! # Lifecycles
45//!
46//! **Close & drop.** `close()` marks the handle closed immediately (later calls
47//! return [`ZeroFsError::Closed`]); it always succeeds, is idempotent, and never
48//! hangs. A handle's server-side fid is released and its number recycled when
49//! the handle is dropped (for scope-bound use, right after `close()`); the
50//! janitor performs the clunk in the background. Dropping a handle you never
51//! closed does the same. Fid numbers are always reused, so a long-running client
52//! never exhausts them.
53//!
54//! **Cancellation.** Every public future is cancel-safe: dropping it at any
55//! await point leaks nothing (in-flight fids are reclaimed in the background).
56//! There is deliberately no per-operation timeout parameter; bound waits with
57//! `tokio::time::timeout`.
58//!
59//! **Connection loss.** The underlying session reconnects forever with backoff
60//! and replays its state; while the server is unreachable, calls block rather
61//! than fail. An operation in flight at the instant of a disconnect is resent,
62//! so a non-idempotent op (rename, create, unlink) can apply twice across a
63//! reconnect.
64
65// `libc::mode_t` constants are u32 on Linux but u16 on macOS; the `as u32`
66// casts clippy flags here are portability.
67#![allow(clippy::unnecessary_cast)]
68#![warn(missing_docs)]
69
70mod client;
71mod dir;
72mod error;
73mod file;
74#[cfg(feature = "tokio-io")]
75pub mod io;
76mod path;
77mod session;
78#[cfg(feature = "stream")]
79pub mod stream;
80mod types;
81
82pub use client::Client;
83pub use dir::Dir;
84pub use error::ZeroFsError;
85pub use file::File;
86#[cfg(feature = "stream")]
87pub use stream::DirStream;
88pub use types::{
89    Capabilities, ConnectOptions, DirEntry, FileType, Metadata, NodeKind, OpenOptions, SetAttrs,
90    SetTime, StatFs, Timestamp,
91};
92
93/// Re-exported so callers need not depend on `bytes` directly; it is the return
94/// type of every read (cheap to clone and slice, derefs to `&[u8]`).
95pub use bytes::Bytes;
zerofs_client/lib.rs

zerofs_client/
lib.rs
