hyprstream_vfs/overlay.rs
1//! Rootfs overlay — the **v1** overlay backend (native only).
2//!
3//! This is the v1 engine of the hyprstream overlay interface: it builds an
4//! [`FsMount`](crate::FsMount) backed by `fuse_backend_rs::OverlayFs(lower,
5//! upper)`, exposed through the [`FuseFileSystemMount`](crate::FuseFileSystemMount)
6//! up-adapter. Copy-up and whiteouts are performed **by `OverlayFs`** — Kata's
7//! production overlay — not by us. We deliberately do **not** hand-roll
8//! copy-on-write here; a native hyprstream CoW engine (per-tenant writable
9//! layers over shared RO model weights, delta/sandbox snapshots) is the backlog
10//! ticket #370 and will implement the same `FsMount` trait with zero consumer
11//! churn.
12//!
13//! Layers are parameterised as `BoxedLayer`s so FS-B can later pass a RAFS lower
14//! (via `nydus-rafs`) without touching this code. For unit testing — and as the
15//! shape FS-B0/FS-B will reuse — [`passthrough_layer`] wraps a host directory
16//! (`PassthroughFs`) as a layer.
17
18use std::io;
19use std::path::Path;
20use std::sync::Arc;
21use std::time::Duration;
22
23use fuse_backend_rs::api::filesystem::Layer;
24use fuse_backend_rs::overlayfs::{config::Config as OverlayConfig, BoxedLayer, OverlayFs};
25use fuse_backend_rs::passthrough::{Config as PassthroughConfig, PassthroughFs};
26
27use crate::fuse_adapter::FuseFileSystemMount;
28use crate::mount::MountError;
29
30fn map_io(err: io::Error, ctx: &str) -> MountError {
31 MountError::Io(format!("{ctx}: {err}"))
32}
33
34/// Wrap any `fuse_backend_rs` [`Layer`] (a `FileSystem` that also implements the
35/// overlay `Layer` trait) as a [`BoxedLayer`] usable by [`rootfs_overlay`].
36///
37/// This is the generic seam FS-B uses to plug an **in-process RAFS** lower
38/// (`nydus_rafs::fs::Rafs`, which implements `Layer`) into the overlay without
39/// this crate depending on `nydus-rafs`: the caller owns the RAFS type, we only
40/// require it be a `Layer<Inode = u64, Handle = u64>`. The layer must already be
41/// ready to serve (RAFS: `import`ed; PassthroughFs: `import`ed).
42pub fn layer_from_fs<L>(fs: L) -> Arc<BoxedLayer>
43where
44 L: Layer<Inode = u64, Handle = u64> + Send + Sync + 'static,
45{
46 let layer: Box<dyn Layer<Inode = u64, Handle = u64> + Send + Sync> = Box::new(fs);
47 Arc::new(layer)
48}
49
50/// Build a `BoxedLayer` from a host directory using `PassthroughFs`.
51///
52/// `read_only` controls only the cache policy hint; OverlayFs enforces the
53/// RO-lower / RW-upper distinction structurally by which slot a layer occupies.
54/// This is the test/bootstrap layer constructor; FS-B swaps the lower for RAFS.
55pub fn passthrough_layer(root: &Path) -> Result<Arc<BoxedLayer>, MountError> {
56 let cfg = PassthroughConfig {
57 root_dir: root.to_string_lossy().into_owned(),
58 // `do_import = false`: the layer is driven through OverlayFs, which
59 // performs the namespace validation itself.
60 do_import: false,
61 writeback: false,
62 xattr: true,
63 ..Default::default()
64 };
65 let fs = PassthroughFs::<()>::new(cfg).map_err(|e| map_io(e, "PassthroughFs::new"))?;
66 fs.import()
67 .map_err(|e| map_io(e, "PassthroughFs::import"))?;
68 Ok(layer_from_fs(fs))
69}
70
71/// Build the v1 rootfs overlay as an [`FsMount`].
72///
73/// `upper` is the single writable layer (copy-ups and whiteouts land here);
74/// `lowers` are the read-only layers, highest priority first. The returned
75/// [`FuseFileSystemMount`] presents the merged view with full overlay semantics
76/// (copy-on-write, whiteout-on-delete, opaque dirs) implemented by `OverlayFs`.
77///
78/// `work` is the overlay work directory (scratch space for atomic operations).
79pub fn rootfs_overlay(
80 upper: Arc<BoxedLayer>,
81 lowers: Vec<Arc<BoxedLayer>>,
82 work: &Path,
83) -> Result<FuseFileSystemMount<OverlayFs>, MountError> {
84 let cfg = OverlayConfig {
85 work: work.to_string_lossy().into_owned(),
86 mountpoint: "/".to_owned(),
87 // `do_import = true`: OverlayFs builds its inode tree from the layers up
88 // front (matches Kata's usage); required before serving.
89 do_import: true,
90 writeback: true,
91 attr_timeout: Duration::from_secs(1),
92 entry_timeout: Duration::from_secs(1),
93 ..Default::default()
94 };
95
96 let overlay =
97 OverlayFs::new(Some(upper), lowers, cfg).map_err(|e| map_io(e, "OverlayFs::new"))?;
98 overlay
99 .import()
100 .map_err(|e| map_io(e, "OverlayFs::import"))?;
101
102 // The up-adapter runs `init` for option negotiation; `import` is already done.
103 FuseFileSystemMount::new(overlay)
104}
105
106/// Convenience: build a passthrough-backed rootfs overlay from host directories.
107///
108/// Wraps `lower` (RO) and `upper` (RW) host dirs as `PassthroughFs` layers and
109/// composes them via [`rootfs_overlay`]. This is the unit-test / bootstrap
110/// shape; production rootfs (FS-B) substitutes a RAFS lower.
111pub fn passthrough_rootfs_overlay(
112 lower: &Path,
113 upper: &Path,
114 work: &Path,
115) -> Result<FuseFileSystemMount<OverlayFs>, MountError> {
116 let upper_layer = passthrough_layer(upper)?;
117 let lower_layer = passthrough_layer(lower)?;
118 rootfs_overlay(upper_layer, vec![lower_layer], work)
119}