fuse: Expose FUSE serving via CLI and varlink RPC

Wire the composefs-fuse crate into cfsctl behind a new `fuse` cargo
feature (on by default) and expose it through both the command line and
the varlink RPC API, with an integration test exercising the FUSE mount
end to end.

CLI surface:
  - `cfsctl fuse-serve <image> <mountpoint>` serves an EROFS composefs
    image over FUSE from a file on disk.
  - `cfsctl oci mount --fuse[=<opts>]` FUSE-serves an OCI image's EROFS
    instead of doing a kernel composefs mount, so it works without
    fs-verity on the backing store. `--fuse=passthrough` opts into
    kernel-bypass reads (Linux 6.9+). Options are parsed via a small
    FuseOptions FromStr so the surface can grow without new flags.

Varlink surface:
  - `org.composefs.Repository.FuseServe` and `org.composefs.Oci.OciFuseMount`
    let a client drive FUSE mounts over the RPC socket. Both take a
    `wait` parameter: with `wait=true` the call blocks for the session;
    with `wait=false` the FUSE session is detached into a background task
    and the call returns once the mount is registered, so a caller can
    mount and then go on to use the filesystem.

The privileged_fuse_dumpfile_roundtrip integration test spawns
`cfsctl fuse-serve` as a subprocess, polls for mount readiness via st_dev
change, reads external files directly, and compares the dumpfile produced
by `cfsctl create-dumpfile` over the FUSE mount against the expected
output from write_dumpfile, asserting the FUSE implementation reports
every piece of metadata the dumpfile format captures. Uses
similar_asserts for readable diffs on mismatch.

Assisted-by: OpenCode (claude-sonnet-4-6)
Signed-off-by: Colin Walters <walters@verbum.org>

Author: cgwalters

crates/composefs-ctl/Cargo.toml

@@ -17,7 +17,8 @@ name = "cfsctl"
 path = "src/main.rs"
 
 [features]
-default = ['pre-6.15', 'oci', 'containers-storage']
+default = ['pre-6.15', 'oci', 'containers-storage', 'fuse']
+fuse = ['dep:composefs-fuse']
 http = ['composefs-http']
 oci = ['composefs-oci', 'composefs-oci/varlink']
 containers-storage = ['composefs-oci/containers-storage', 'cstorage']
@@ -31,6 +32,7 @@ clap = { version = "4.5.0", default-features = false, features = ["std", "help",
 comfy-table = { version = "7.1", default-features = false }
 composefs = { workspace = true, features = ["varlink"] }
 composefs-boot = { workspace = true }
+composefs-fuse = { path = "../composefs-fuse", optional = true }
 composefs-oci = { workspace = true, optional = true, features = ["boot"] }
 composefs-http = { workspace = true, optional = true }
 cstorage = { package = "composefs-storage", path = "../composefs-storage", version = "0.4.0", features = ["userns-helper"], optional = true }

crates/composefs-ctl/src/lib.rs

@@ -318,6 +318,33 @@ impl From<LocalFetchCli> for composefs_oci::LocalFetchOpt {
     }
 }
 
+/// Options accepted by `--fuse[=<opts>]` on `oci mount`.
+///
+/// Pass bare `--fuse` to FUSE-mount with defaults, or `--fuse=passthrough`
+/// to also enable kernel-bypass reads for external files.
+///
+/// Multiple options are comma-separated: `--fuse=passthrough,option2`
+/// (only `passthrough` is defined today).
+#[derive(Debug, Default, Clone)]
+struct FuseOptions {
+    passthrough: bool,
+}
+
+impl std::str::FromStr for FuseOptions {
+    type Err = anyhow::Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let mut opts = FuseOptions::default();
+        for token in s.split(',').map(str::trim).filter(|t| !t.is_empty()) {
+            match token {
+                "passthrough" => opts.passthrough = true,
+                other => anyhow::bail!("unknown fuse option: {other:?} (known: passthrough)"),
+            }
+        }
+        Ok(opts)
+    }
+}
+
 /// Common options for operations using OCI config manifest streams that may transform the image rootfs
 #[cfg(feature = "oci")]
 #[derive(Debug, Parser)]
@@ -447,6 +474,17 @@ enum OciCommand {
         /// Mount read-write (requires --upperdir)
         #[arg(long, requires = "upperdir")]
         read_write: bool,
+        /// Serve the EROFS image over FUSE instead of using a kernel composefs mount.
+        /// Requires /dev/fuse and blocks until the mount is detached or the process
+        /// is killed. Does not require fs-verity on the backing store.
+        ///
+        /// Accepts an optional comma-separated list of options:
+        ///   --fuse              basic FUSE mount
+        ///   --fuse=passthrough  also enable kernel-bypass reads (Linux 6.9+, root, non-tmpfs)
+        #[cfg_attr(not(feature = "fuse"), arg(hide = true))]
+        #[arg(long, num_args = 0..=1, require_equals = false, value_name = "OPTS",
+              default_missing_value = "")]
+        fuse: Option<FuseOptions>,
     },
     /// Compute the composefs image ID of a stored OCI image's rootfs
     ///
@@ -584,6 +622,23 @@ enum Command {
         #[arg(long, requires = "upperdir")]
         read_write: bool,
     },
+    /// Serve an EROFS composefs image over FUSE at the given mountpoint.
+    ///
+    /// Reads the EROFS image, opens /dev/fuse, mounts and attaches the
+    /// FUSE filesystem at `<mountpoint>`, then blocks serving requests
+    /// until killed or unmounted. External file objects are resolved
+    /// via the repository given by `--repo`.
+    #[cfg(feature = "fuse")]
+    FuseServe {
+        /// Path to the EROFS composefs image file.
+        image: PathBuf,
+        /// Directory to attach the FUSE mount at (must already exist).
+        mountpoint: PathBuf,
+        /// Enable FUSE passthrough for external files (Linux 6.9+;
+        /// requires root and a non-tmpfs backing filesystem).
+        #[clap(long)]
+        passthrough: bool,
+    },
     /// Read rootfs located at a path, add all files to the repo, then create the composefs image of the rootfs,
     /// commit it to the repo, and print its image object ID
     CreateImage {
@@ -1264,9 +1319,8 @@ where
                 ref upperdir,
                 ref workdir,
                 read_write,
+                fuse,
             } => {
-                let mount_options =
-                    get_mount_options(upperdir.as_deref(), workdir.as_deref(), read_write)?;
                 let img = if image.starts_with("sha256:") {
                     let digest: composefs_oci::OciDigest =
                         image.parse().context("Parsing manifest digest")?;
@@ -1289,7 +1343,50 @@ where
                         ),
                     }
                 };
-                repo.mount_at(&erofs_id.to_hex(), mountpoint.as_str(), &mount_options)?;
+                if let Some(fuse_opts) = fuse {
+                    #[cfg(feature = "fuse")]
+                    {
+                        use composefs_fuse::{FuseConfig, mount_fuse, open_fuse, serve_tree_fuse};
+
+                        // Read the EROFS image from the repository's images/ directory.
+                        let (image_fd, _verified) = repo.open_image(&erofs_id.to_hex())?;
+                        let erofs_bytes = {
+                            let mut buf = Vec::new();
+                            std::fs::File::from(image_fd).read_to_end(&mut buf)?;
+                            buf
+                        };
+                        let filesystem = erofs_to_filesystem::<ObjectID>(&erofs_bytes)
+                            .context("parsing EROFS image")?;
+
+                        let dev_fuse = open_fuse()?;
+                        let mnt_fd = mount_fuse(&dev_fuse)?;
+                        composefs::mount::mount_at(&mnt_fd, CWD, mountpoint.as_str())
+                            .with_context(|| format!("attaching FUSE mount at {mountpoint}"))?;
+
+                        // Hold mnt_fd alive for the session duration — it pins the FUSE
+                        // superblock so the connection stays alive while we serve.
+                        let _mnt_fd = mnt_fd;
+
+                        serve_tree_fuse(
+                            dev_fuse,
+                            Arc::new(filesystem),
+                            Arc::clone(&repo),
+                            FuseConfig {
+                                passthrough: fuse_opts.passthrough,
+                            },
+                        )
+                        .context("FUSE session error")?;
+                    }
+                    #[cfg(not(feature = "fuse"))]
+                    {
+                        let _ = fuse_opts;
+                        anyhow::bail!("cfsctl was built without FUSE support");
+                    }
+                } else {
+                    let mount_options =
+                        get_mount_options(upperdir.as_deref(), workdir.as_deref(), read_write)?;
+                    repo.mount_at(&erofs_id.to_hex(), mountpoint.as_str(), &mount_options)?;
+                }
             }
             OciCommand::ComputeId { config_opts } => {
                 let mut fs = load_filesystem_from_oci_image(&repo, config_opts)?;
@@ -1521,6 +1618,36 @@ where
                 get_mount_options(upperdir.as_deref(), workdir.as_deref(), read_write)?;
             repo.mount_at(&name, &mountpoint, &mount_options)?;
         }
+        #[cfg(feature = "fuse")]
+        Command::FuseServe {
+            ref image,
+            ref mountpoint,
+            passthrough,
+        } => {
+            use composefs_fuse::{FuseConfig, mount_fuse, open_fuse, serve_tree_fuse};
+
+            let erofs_bytes = std::fs::read(image)
+                .with_context(|| format!("reading EROFS image {}", image.display()))?;
+            let filesystem =
+                erofs_to_filesystem::<ObjectID>(&erofs_bytes).context("parsing EROFS image")?;
+
+            let dev_fuse = open_fuse()?;
+            let mnt_fd = mount_fuse(&dev_fuse)?;
+            composefs::mount::mount_at(&mnt_fd, CWD, mountpoint)
+                .with_context(|| format!("attaching FUSE mount at {}", mountpoint.display()))?;
+
+            // Hold mnt_fd alive for the session duration — it pins the FUSE
+            // superblock so the connection stays alive while we serve.
+            let _mnt_fd = mnt_fd;
+
+            serve_tree_fuse(
+                dev_fuse,
+                Arc::new(filesystem),
+                Arc::clone(&repo),
+                FuseConfig { passthrough },
+            )
+            .context("FUSE session error")?;
+        }
         Command::ImageObjects { name } => {
             let objects = repo.objects_for_image(&name)?;
             for object in objects {