Skip to main content

hyprstream_vfs_server/
lib.rs

1//! `hyprstream-vfs-server` — serve a hyprstream VFS [`Namespace`] to a Cloud
2//! Hypervisor guest over vhost-user-fs.
3//!
4//! This crate is the **down** half of the bidirectional `FileSystem ↔ Mount`
5//! bridge from the converged FS/VFS design (FS-A, #362). FS-C built the *up*
6//! adapter ([`hyprstream_vfs::FuseFileSystemMount`]) that exposes a
7//! `fuse_backend_rs` `FileSystem` (RAFS / OverlayFs / Passthrough) as a VFS
8//! [`Mount`](hyprstream_vfs::Mount). This crate builds the *down* adapter
9//! ([`VfsFileSystem`]) that exposes a whole VFS [`Namespace`](hyprstream_vfs::Namespace)
10//! as a `fuse_backend_rs` `FileSystem`, and wires `fuse_backend_rs`'s FUSE
11//! protocol engine to a vhost-user-fs server ([`serve`]) so Cloud Hypervisor can
12//! mount it as a virtio-fs share.
13//!
14//! ```text
15//! Cloud Hypervisor  (virtio-fs / vhost-user-fs device)
16//!   → vhost-user-backend       (Unix-socket transport + vring loop) — server.rs
17//!     → fuse_backend_rs::Server (FUSE protocol engine)
18//!       → VfsFileSystem         (Namespace → FileSystem down-adapter) — filesystem.rs
19//!         → Namespace mounts    (Mount read/write + FsMount writes, Subject-per-call)
20//! ```
21//!
22//! [`serve_local`] is the non-VM counterpart (#653): the same [`VfsFileSystem`]
23//! down-adapter, mounted at a host directory via `fuse_backend_rs`'s `fusedev`
24//! transport (kernel `/dev/fuse`) instead of vhost-user-fs. This is what lets
25//! non-VM sandbox backends — `podman run --rootfs <dir>` (#617), `systemd-nspawn
26//! --directory=<dir>` — consume the same composed per-sandbox namespace
27//! (`SandboxFs::compose`/`into_filesystem`, #641/#365) the kata/CH path uses,
28//! rather than side-channeling their own image provisioning:
29//!
30//! ```text
31//! podman / systemd-nspawn  (plain POSIX directory)
32//!   → kernel /dev/fuse         (fusedev transport) — server.rs::serve_local
33//!     → fuse_backend_rs::Server (same FUSE protocol engine)
34//!       → VfsFileSystem         (same down-adapter, unmodified)
35//!         → Namespace mounts
36//! ```
37//!
38//! The crate is **native-only** (Linux): vhost-user-fs and `fuse_backend_rs`'s
39//! virtio transport are not available on wasm, and the whole point is serving a
40//! VMM (or, for `serve_local`, a real kernel FUSE mount). It is genuinely
41//! `Send + Sync` — no wasm `unsafe impl Send`.
42
43#![cfg(not(target_arch = "wasm32"))]
44
45mod filesystem;
46mod inode;
47mod server;
48
49#[cfg(test)]
50mod tests;
51
52pub use filesystem::VfsFileSystem;
53pub use server::{serve, serve_local, VfsBackend};