feat: add --fuse-fd flag for pre-opened /dev/fuse file descriptor (#85)

## Summary

- Add `--fuse-fd=N` CLI flag to hf-mount-fuse
- When set, uses `fuser::Session::from_fd()` instead of
`Session::new()`, skipping the kernel mount
- Enables the CSI sidecar injection pattern: privileged CSI driver does
the kernel mount, passes fd via SCM_RIGHTS to an unprivileged sidecar
running hf-mount

Companion PR: huggingface/hf-csi-driver#19

Author: XciD

src/bin/hf-mount-fuse.rs

@@ -18,6 +18,7 @@ fn main() {
         &s.runtime,
         daemon_guard.as_mut(),
         s.fuse_owner_only,
+        s.fuse_fd,
     ) {
         std::process::exit(1);
     }

src/fuse.rs

@@ -1,4 +1,5 @@
 use std::ffi::OsStr;
+use std::os::fd::FromRawFd;
 use std::path::Path;
 use std::sync::Arc;
 use std::time::{Duration, SystemTime};
@@ -510,6 +511,7 @@ pub fn mount_fuse(
     runtime: &tokio::runtime::Runtime,
     daemon_guard: Option<&mut DaemonGuard>,
     fuse_owner_only: bool,
+    fuse_fd: Option<i32>,
 ) -> bool {
     let adapter = FuseAdapter::new(
         runtime.handle().clone(),
@@ -557,19 +559,33 @@ pub fn mount_fuse(
         config.n_threads = Some(max_threads);
     }
 
-    let session = match fuser::Session::new(adapter, mount_point, &config) {
-        Ok(s) => s,
-        Err(e) => {
-            if e.kind() == std::io::ErrorKind::PermissionDenied {
-                error!(
-                    "Permission denied: mounting a FUSE filesystem requires root privileges. \
-                     Try running with: sudo {}",
-                    std::env::args().collect::<Vec<_>>().join(" ")
-                );
-            } else {
-                error!("FUSE session failed: {}", e);
+    let session = if let Some(raw_fd) = fuse_fd {
+        // Use a pre-opened /dev/fuse fd (sidecar mode). The kernel FUSE mount
+        // was already performed by the CSI driver; we just run the userspace daemon.
+        let owned_fd = unsafe { std::os::fd::OwnedFd::from_raw_fd(raw_fd) };
+        info!("Using pre-opened FUSE fd={}", raw_fd);
+        match fuser::Session::from_fd(adapter, owned_fd, config.acl, config) {
+            Ok(s) => s,
+            Err(e) => {
+                error!("FUSE session from fd={} failed: {}", raw_fd, e);
+                return false;
+            }
+        }
+    } else {
+        match fuser::Session::new(adapter, mount_point, &config) {
+            Ok(s) => s,
+            Err(e) => {
+                if e.kind() == std::io::ErrorKind::PermissionDenied {
+                    error!(
+                        "Permission denied: mounting a FUSE filesystem requires root privileges. \
+                         Try running with: sudo {}",
+                        std::env::args().collect::<Vec<_>>().join(" ")
+                    );
+                } else {
+                    error!("FUSE session failed: {}", e);
+                }
+                return false;
             }
-            return false;
         }
     };
     let notifier = session.notifier();

src/setup.rs

@@ -150,6 +150,14 @@ pub struct MountOptions {
     /// When not set, requires `user_allow_other` in /etc/fuse.conf on Linux.
     #[arg(long, default_value_t = false)]
     pub fuse_owner_only: bool,
+
+    /// Use a pre-opened /dev/fuse file descriptor instead of opening /dev/fuse
+    /// and performing the kernel mount. The kernel FUSE mount must already be
+    /// established on this fd by the caller (e.g. a CSI driver).
+    /// When set, the mount_point argument is ignored for mounting but still
+    /// used for logging.
+    #[arg(long)]
+    pub fuse_fd: Option<i32>,
 }
 
 /// CLI args for the foreground FUSE/NFS binaries.
@@ -175,6 +183,7 @@ pub struct MountSetup {
     pub max_threads: usize,
     pub metadata_ttl_ms: u64,
     pub fuse_owner_only: bool,
+    pub fuse_fd: Option<i32>,
 }
 
 // ── Tracing + env vars (no threads) ──────────────────────────────────
@@ -405,6 +414,7 @@ pub fn build(source: Source, options: MountOptions, is_nfs: bool) -> MountSetup
         max_threads: options.max_threads,
         metadata_ttl_ms: options.metadata_ttl_ms,
         fuse_owner_only: options.fuse_owner_only,
+        fuse_fd: options.fuse_fd,
     }
 }