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}