Skip to main content

hyprstream_vfs_server/
server.rs

1//! vhost-user-fs server: serves a [`VfsFileSystem`] over a Unix socket.
2//!
3//! `fuse_backend_rs` provides the FUSE protocol engine
4//! ([`Server`](fuse_backend_rs::api::server::Server) +
5//! [`Reader`](fuse_backend_rs::transport::Reader) /
6//! [`VirtioFsWriter`](fuse_backend_rs::transport::VirtioFsWriter)) but **not** a
7//! vhost-user transport — we host it with the `vhost-user-backend` crate, the
8//! same stacking production virtiofsd uses. Cloud Hypervisor connects to the
9//! socket; for each request descriptor chain we build a `Reader`/`Writer` over
10//! guest memory and call [`Server::handle_message`], which dispatches to our
11//! [`VfsFileSystem`] (the `Namespace → FileSystem` down-adapter).
12//!
13//! This is the inverse direction of FS-C's adapter and the host side of the CH
14//! ShareFs attach in `kata_backend.rs`.
15
16use std::io;
17use std::path::Path;
18use std::sync::Arc;
19// `vhost-user-backend` only implements `VhostUserBackend` for the std `Mutex`/
20// `RwLock` (backend.rs:335/415), so we must use the std type here despite the
21// project's parking_lot preference — there is no poison risk as the daemon owns
22// the lock and our backend methods never panic while holding it.
23#[allow(clippy::disallowed_types)]
24use std::sync::Mutex;
25
26use fuse_backend_rs::api::server::Server;
27use fuse_backend_rs::transport::{FuseChannel, FuseSession, Reader, VirtioFsWriter, Writer};
28use vhost::vhost_user::message::{VhostUserProtocolFeatures, VhostUserVirtioFeatures};
29use vhost::vhost_user::Listener;
30use vhost_user_backend::{VhostUserBackendMut, VhostUserDaemon, VringRwLock, VringT};
31use virtio_bindings::bindings::virtio_config::VIRTIO_F_VERSION_1;
32use virtio_bindings::bindings::virtio_ring::{
33    VIRTIO_RING_F_EVENT_IDX, VIRTIO_RING_F_INDIRECT_DESC,
34};
35use virtio_queue::QueueOwnedT;
36use vm_memory::{GuestAddressSpace, GuestMemoryAtomic, GuestMemoryMmap};
37use vmm_sys_util::epoll::EventSet;
38use vmm_sys_util::eventfd::EventFd;
39
40use crate::filesystem::VfsFileSystem;
41
42/// Map any backend error into an `io::Error` for the vring loop.
43fn into_io<E: std::fmt::Debug>(e: E) -> io::Error {
44    io::Error::other(format!("{e:?}"))
45}
46
47/// Guest memory type the daemon manages.
48type GuestMemory = GuestMemoryAtomic<GuestMemoryMmap>;
49
50/// virtio-fs queues: 1 hiprio + 1 request queue (the minimal, single-thread set).
51const NUM_QUEUES: usize = 2;
52/// Max descriptors per queue (matches the CH `queue_size` default of 1024).
53const QUEUE_SIZE: usize = 1024;
54
55/// The vhost-user backend hosting a [`VfsFileSystem`] [`Server`].
56pub struct VfsBackend {
57    server: Arc<Server<VfsFileSystem>>,
58    mem: Option<GuestMemory>,
59    event_idx: bool,
60    /// Exit eventfd so the daemon can be signalled to stop.
61    exit: EventFd,
62}
63
64impl VfsBackend {
65    fn new(fs: VfsFileSystem) -> io::Result<Self> {
66        Ok(Self {
67            server: Arc::new(Server::new(fs)),
68            mem: None,
69            event_idx: false,
70            exit: EventFd::new(libc::EFD_NONBLOCK)?,
71        })
72    }
73
74    /// Drain one request queue, dispatching each chain through the FUSE server.
75    ///
76    /// Iteration borrows the queue under the vring's write guard; `add_used`
77    /// re-locks the vring, so we stage `(head, len)` completions and apply them
78    /// after dropping the guard (holding both would self-deadlock the lock).
79    fn process_queue(&self, vring: &VringRwLock) -> io::Result<bool> {
80        let mem = self
81            .mem
82            .as_ref()
83            .ok_or_else(|| io::Error::from_raw_os_error(libc::EINVAL))?
84            .memory();
85        // `&*mem` is the guard's `Deref::Target` (`&GuestMemoryMmap`), which is
86        // what `from_descriptor_chain`/`VirtioFsWriter::new` want; the chain's
87        // own `M` is the cloned guard handed to `iter`.
88        let desc_mem: &GuestMemoryMmap = &mem;
89
90        let mut completed: Vec<(u16, u32)> = Vec::new();
91        {
92            let mut state = vring.get_mut();
93            let queue = state.get_queue_mut();
94            let avail = queue.iter(mem.clone()).map_err(into_io)?;
95            for chain in avail {
96                let head = chain.head_index();
97                let reader =
98                    Reader::from_descriptor_chain(desc_mem, chain.clone()).map_err(into_io)?;
99                let writer: Writer = VirtioFsWriter::new(desc_mem, chain.clone())
100                    .map_err(into_io)?
101                    .into();
102                let len = self
103                    .server
104                    .handle_message(reader, writer, None, None)
105                    .map_err(into_io)?;
106                completed.push((head, len as u32));
107            }
108        } // write guard dropped before add_used
109
110        let used = !completed.is_empty();
111        for (head, len) in completed {
112            vring.add_used(head, len).map_err(into_io)?;
113        }
114        Ok(used)
115    }
116}
117
118impl VhostUserBackendMut for VfsBackend {
119    type Bitmap = ();
120    type Vring = VringRwLock;
121
122    fn num_queues(&self) -> usize {
123        NUM_QUEUES
124    }
125
126    fn max_queue_size(&self) -> usize {
127        QUEUE_SIZE
128    }
129
130    fn features(&self) -> u64 {
131        (1 << VIRTIO_F_VERSION_1)
132            | (1 << VIRTIO_RING_F_INDIRECT_DESC)
133            | (1 << VIRTIO_RING_F_EVENT_IDX)
134            | VhostUserVirtioFeatures::PROTOCOL_FEATURES.bits()
135    }
136
137    fn protocol_features(&self) -> VhostUserProtocolFeatures {
138        VhostUserProtocolFeatures::MQ | VhostUserProtocolFeatures::REPLY_ACK
139    }
140
141    fn set_event_idx(&mut self, enabled: bool) {
142        self.event_idx = enabled;
143    }
144
145    fn update_memory(&mut self, mem: GuestMemory) -> io::Result<()> {
146        self.mem = Some(mem);
147        Ok(())
148    }
149
150    fn handle_event(
151        &mut self,
152        device_event: u16,
153        _evset: EventSet,
154        vrings: &[Self::Vring],
155        _thread_id: usize,
156    ) -> io::Result<()> {
157        let vring = vrings
158            .get(device_event as usize)
159            .ok_or_else(|| io::Error::from_raw_os_error(libc::EINVAL))?;
160
161        let mut used = false;
162        if self.event_idx {
163            // event_idx: disable notifications, drain, re-enable, retry if work
164            // arrived in the window. Standard virtiofsd loop.
165            loop {
166                vring.disable_notification().map_err(into_io)?;
167                used |= self.process_queue(vring)?;
168                if !vring.enable_notification().map_err(into_io)? {
169                    break;
170                }
171            }
172        } else {
173            used = self.process_queue(vring)?;
174        }
175        // Signal the guest that descriptors were consumed.
176        if used {
177            vring.signal_used_queue().map_err(into_io)?;
178        }
179        Ok(())
180    }
181
182    fn exit_event(&self, _thread_id: usize) -> Option<EventFd> {
183        self.exit.try_clone().ok()
184    }
185}
186
187/// Serve `fs` over the vhost-user-fs Unix socket at `socket_path`, blocking until
188/// the daemon exits (the VMM disconnects or [`exit_event`](VfsBackend::exit_event)
189/// is signalled).
190///
191/// The caller is responsible for the socket lifecycle and for attaching the same
192/// path to Cloud Hypervisor as a ShareFs device (see `kata_backend.rs`). Run this
193/// on a dedicated thread; it blocks.
194#[allow(clippy::disallowed_types)] // std Mutex required by vhost-user-backend's blanket impl
195pub fn serve(fs: VfsFileSystem, socket_path: &str) -> io::Result<()> {
196    let backend = Arc::new(Mutex::new(VfsBackend::new(fs)?));
197    let mem = GuestMemoryAtomic::new(GuestMemoryMmap::new());
198    let mut daemon = VhostUserDaemon::new("hyprstream-vfs-fs".to_owned(), backend, mem)
199        .map_err(|e| io::Error::other(format!("daemon init: {e}")))?;
200
201    let listener = Listener::new(socket_path, true)
202        .map_err(|e| io::Error::other(format!("listen {socket_path}: {e}")))?;
203    daemon
204        .start(listener)
205        .map_err(|e| io::Error::other(format!("daemon start: {e}")))?;
206    daemon
207        .wait()
208        .map_err(|e| io::Error::other(format!("daemon wait: {e}")))?;
209    Ok(())
210}
211
212/// Mount `fs` at `mountpoint` as a real host directory via the kernel `fusedev`
213/// transport (`/dev/fuse`), blocking until the mount is torn down (unmounted, or
214/// the kernel closes the FUSE device).
215///
216/// This is the non-VM counterpart to [`serve`]: the same transport-agnostic
217/// [`VfsFileSystem`] down-adapter (`SandboxFs::into_filesystem`), served as a
218/// plain POSIX directory instead of a vhost-user-fs virtio-fs share. It exists
219/// so backends that cannot attach a virtio-fs device — `podman run --rootfs
220/// <dir>` (#617) and `systemd-nspawn --directory=<dir>` — can consume the same
221/// composed per-sandbox namespace the kata/CH path uses, instead of
222/// side-channeling their own image provisioning (spine violation, epic #508).
223///
224/// `mountpoint` must already exist as a directory; this function does not
225/// create it. The mount is torn down when [`FuseSession`] is dropped (which
226/// happens when this function returns, on any exit path) or when the kernel
227/// unmounts it out from under us (e.g. `fusermount3 -u`, or the guest killing
228/// the process).
229///
230/// Open question (tracked by #653, resolution deferred to #617): rootless FUSE
231/// (unprivileged `/dev/fuse` access via `fusermount3`) combined with podman's
232/// `--userns=keep-id` has not been validated here — this function mounts via
233/// the same kernel `/dev/fuse` + `fusermount3` path `fuse-backend-rs` uses for
234/// any fusedev consumer, but whether that composition works unprivileged under
235/// `keep-id` user-namespace remapping is unresolved and out of scope for this
236/// change.
237///
238/// Run this on a dedicated thread; like [`serve`], it blocks until the session
239/// ends.
240pub fn serve_local(fs: VfsFileSystem, mountpoint: &Path) -> io::Result<()> {
241    let server = Arc::new(Server::new(fs));
242
243    let mut session = FuseSession::new(mountpoint, "hyprstream-vfs", "", false)
244        .map_err(|e| io::Error::other(format!("fuse session init {mountpoint:?}: {e}")))?;
245    // `fuse-backend-rs` defaults `allow_other` to true, which requires
246    // `user_allow_other` in `/etc/fuse.conf` (a host-wide opt-in most
247    // deployments won't have set). We only need this mount visible to the
248    // process serving it (and whatever shares its uid/gid — e.g. a podman
249    // `--userns=keep-id` child), so disable it and mount unprivileged.
250    session.set_allow_other(false);
251    session
252        .mount()
253        .map_err(|e| io::Error::other(format!("fuse mount {mountpoint:?}: {e}")))?;
254
255    let mut channel = session
256        .new_channel()
257        .map_err(|e| io::Error::other(format!("fuse channel {mountpoint:?}: {e}")))?;
258
259    let result = drive_channel(&server, &mut channel);
260
261    // Always attempt to tear down the mount, even if the request loop errored,
262    // so a failure mid-mount doesn't leave a dangling `/dev/fuse` connection.
263    if let Err(e) = session.umount() {
264        tracing::warn!(mountpoint = %mountpoint.display(), error = %e, "fuse umount failed");
265    }
266
267    result
268}
269
270/// Drain `channel`, dispatching each request through the FUSE server, until the
271/// kernel closes the session (`get_request` returns `Ok(None)`).
272fn drive_channel(server: &Arc<Server<VfsFileSystem>>, channel: &mut FuseChannel) -> io::Result<()> {
273    loop {
274        let request = match channel.get_request() {
275            Ok(r) => r,
276            Err(e) => {
277                // `FuseChannel::get_request` treats a clean `ENODEV` read as
278                // `Ok(None)` (see its `linux_session.rs` docs), but a
279                // concurrent unmount can also surface as an epoll-error event
280                // on the `/dev/fuse` fd, which it reports as `Err` rather than
281                // `Ok(None)`. Either shape means the same thing here: the
282                // kernel end of the session is gone. Treat any channel error
283                // as ordinary session teardown rather than a hard failure —
284                // there is nothing left to serve once `/dev/fuse` is torn
285                // down, and propagating it would turn a normal `fusermount -u`
286                // into a spurious error from `serve_local`.
287                tracing::debug!(error = %e, "fuse channel closed");
288                return Ok(());
289            }
290        };
291        let Some((reader, writer)) = request else {
292            // Session closed (unmounted or kernel dropped /dev/fuse).
293            return Ok(());
294        };
295        if let Err(e) = server.handle_message(reader, writer.into(), None, None) {
296            // Mirrors fuse-backend-rs's own fusedev example: an encode failure
297            // means the kernel end is gone, so stop; any other per-request
298            // error is logged and the loop continues serving later requests.
299            match e {
300                fuse_backend_rs::Error::EncodeMessage(_) => return Ok(()),
301                _ => tracing::error!(error = %e, "fuse request failed"),
302            }
303        }
304    }
305}