Skip to main content

hyprstream_vfs/
injected.rs

1//! Native **injected mounts** for a per-sandbox VFS namespace (FS-D, #365).
2//!
3//! FS-C built the injected mounts (`/stream`, models, deltas) as **wasm-only**
4//! `Mount` impls (e.g. `hyprstream-rpc-std`'s `stream_mount.rs`, gated
5//! `#![cfg(target_arch = "wasm32")]`). Those rely on `unsafe impl Send/Sync`
6//! over `RefCell` because the browser side is single-threaded. They cannot be
7//! served to a Cloud Hypervisor guest: FS-A's `hyprstream-vfs-server` runs the
8//! down-adapter on real OS threads and requires genuinely `Send + Sync` mounts.
9//!
10//! This module is the **native** port of those injected mounts:
11//!
12//! - [`SyntheticMount`] — a read-only synthetic file tree built from in-memory
13//!   directory/file nodes. The native counterpart of the wasm `SyntheticTree`,
14//!   used for the models / deltas listings injected into the sandbox (e.g.
15//!   `/models/<id>/info`, `/deltas/<id>/meta`). Read-only by construction: a
16//!   plain [`Mount`] (not an [`FsMount`](crate::FsMount)), so the down-adapter
17//!   treats writes as `EROFS` — fail-closed.
18//! - [`StreamMount`] — the native `/stream` pipe mount. Streams appear as
19//!   `/stream/{topic}/{data,info,ctl}`; `data` yields queued blocks (EOF on an
20//!   empty read), `info` is JSON metadata, `ctl` accepts `cancel`. The registry
21//!   ([`StreamRegistry`]) is `Mutex`-guarded — genuinely `Send + Sync`, no wasm
22//!   `unsafe impl`. The block source is decoupled behind [`StreamRegistry`]'s
23//!   `push`/`complete` API so the worker runtime can feed it from any transport.
24//!
25//! Every op threads the caller [`Subject`] — the same uniform Subject-per-call
26//! boundary the rest of the VFS enforces. A sandbox's injected mounts live in
27//! that sandbox's forked [`Namespace`](crate::Namespace) only, so tenant
28//! isolation is structural (#365): there is no shared registry across sandboxes
29//! unless the caller deliberately clones the `Arc`.
30
31#![cfg(not(target_arch = "wasm32"))]
32
33use std::collections::BTreeMap;
34use std::collections::VecDeque;
35use std::sync::Arc;
36
37use async_trait::async_trait;
38use parking_lot::Mutex;
39
40use crate::mount::{DirEntry, Fid, Mount, MountError, Stat};
41use hyprstream_rpc::Subject;
42
43// ─────────────────────────────────────────────────────────────────────────────
44// SyntheticMount — read-only in-memory tree (models / deltas injected listings)
45// ─────────────────────────────────────────────────────────────────────────────
46
47/// A node in a [`SyntheticMount`] tree: either a directory of named children or
48/// a file with fixed byte contents.
49#[derive(Clone, Debug)]
50pub enum SyntheticNode {
51    /// Directory: an ordered map of child name → node.
52    Dir(BTreeMap<String, SyntheticNode>),
53    /// File: fixed contents served on read.
54    File(Vec<u8>),
55}
56
57impl SyntheticNode {
58    /// Build an empty directory node.
59    pub fn dir() -> Self {
60        Self::Dir(BTreeMap::new())
61    }
62
63    /// Build a file node from bytes.
64    pub fn file(contents: impl Into<Vec<u8>>) -> Self {
65        Self::File(contents.into())
66    }
67
68    /// Insert a child into a directory node (chainable). No-op on a file node.
69    pub fn with_child(mut self, name: impl Into<String>, child: SyntheticNode) -> Self {
70        if let Self::Dir(children) = &mut self {
71            children.insert(name.into(), child);
72        }
73        self
74    }
75
76    /// Resolve `components` relative to this node.
77    fn resolve(&self, components: &[&str]) -> Option<&SyntheticNode> {
78        let mut cur = self;
79        for comp in components {
80            match cur {
81                Self::Dir(children) => cur = children.get(*comp)?,
82                Self::File(_) => return None,
83            }
84        }
85        Some(cur)
86    }
87}
88
89/// A read-only synthetic filesystem mount (native).
90///
91/// The native counterpart of the wasm `SyntheticTree`, used for the injected
92/// models / deltas listings. It is a plain [`Mount`] — not an
93/// [`FsMount`](crate::FsMount) — so the FS-A down-adapter serves it read-only
94/// (writes return `EROFS`).
95pub struct SyntheticMount {
96    root: SyntheticNode,
97}
98
99impl SyntheticMount {
100    /// Build a synthetic mount from a directory root node.
101    pub fn new(root: SyntheticNode) -> Self {
102        Self { root }
103    }
104}
105
106/// Fid state for a [`SyntheticMount`]: the resolved absolute components.
107struct SyntheticFid {
108    components: Vec<String>,
109}
110
111#[async_trait]
112impl Mount for SyntheticMount {
113    async fn walk(&self, components: &[&str], _caller: &Subject) -> Result<Fid, MountError> {
114        if self.root.resolve(components).is_none() {
115            return Err(MountError::NotFound(components.join("/")));
116        }
117        Ok(Fid::new(SyntheticFid {
118            components: components.iter().map(|s| s.to_string()).collect(),
119        }))
120    }
121
122    async fn open(&self, _fid: &mut Fid, mode: u8, _caller: &Subject) -> Result<(), MountError> {
123        // Read-only: reject any write/rdwr open.
124        if mode & 0x03 != 0 {
125            return Err(MountError::PermissionDenied(
126                "synthetic mount is read-only".into(),
127            ));
128        }
129        Ok(())
130    }
131
132    async fn read(
133        &self,
134        fid: &Fid,
135        offset: u64,
136        count: u32,
137        _caller: &Subject,
138    ) -> Result<Vec<u8>, MountError> {
139        let st = fid
140            .downcast_ref::<SyntheticFid>()
141            .ok_or_else(|| MountError::InvalidArgument("bad fid".into()))?;
142        let comps: Vec<&str> = st.components.iter().map(String::as_str).collect();
143        match self.root.resolve(&comps) {
144            Some(SyntheticNode::File(data)) => {
145                let start = (offset as usize).min(data.len());
146                let end = (start + count as usize).min(data.len());
147                Ok(data[start..end].to_vec())
148            }
149            Some(SyntheticNode::Dir(_)) => Err(MountError::IsDirectory(st.components.join("/"))),
150            None => Err(MountError::NotFound(st.components.join("/"))),
151        }
152    }
153
154    async fn write(
155        &self,
156        _fid: &Fid,
157        _offset: u64,
158        _data: &[u8],
159        _caller: &Subject,
160    ) -> Result<u32, MountError> {
161        Err(MountError::PermissionDenied(
162            "synthetic mount is read-only".into(),
163        ))
164    }
165
166    async fn readdir(&self, fid: &Fid, _caller: &Subject) -> Result<Vec<DirEntry>, MountError> {
167        let st = fid
168            .downcast_ref::<SyntheticFid>()
169            .ok_or_else(|| MountError::InvalidArgument("bad fid".into()))?;
170        let comps: Vec<&str> = st.components.iter().map(String::as_str).collect();
171        match self.root.resolve(&comps) {
172            Some(SyntheticNode::Dir(children)) => Ok(children
173                .iter()
174                .map(|(name, node)| DirEntry {
175                    name: name.clone(),
176                    is_dir: matches!(node, SyntheticNode::Dir(_)),
177                    size: match node {
178                        SyntheticNode::File(d) => d.len() as u64,
179                        SyntheticNode::Dir(_) => 0,
180                    },
181                    stat: None,
182                })
183                .collect()),
184            Some(SyntheticNode::File(_)) => Err(MountError::NotDirectory(st.components.join("/"))),
185            None => Err(MountError::NotFound(st.components.join("/"))),
186        }
187    }
188
189    async fn stat(&self, fid: &Fid, _caller: &Subject) -> Result<Stat, MountError> {
190        let st = fid
191            .downcast_ref::<SyntheticFid>()
192            .ok_or_else(|| MountError::InvalidArgument("bad fid".into()))?;
193        let comps: Vec<&str> = st.components.iter().map(String::as_str).collect();
194        match self.root.resolve(&comps) {
195            Some(node) => {
196                let (qtype, size) = match node {
197                    SyntheticNode::Dir(_) => (0x80, 0),
198                    SyntheticNode::File(d) => (0, d.len() as u64),
199                };
200                Ok(Stat {
201                    qtype,
202                    version: 0,
203                    path: 0,
204                    size,
205                    name: st.components.last().cloned().unwrap_or_default(),
206                    mtime: 0,
207                })
208            }
209            None => Err(MountError::NotFound(st.components.join("/"))),
210        }
211    }
212
213    async fn clunk(&self, _fid: Fid, _caller: &Subject) {}
214}
215
216// ─────────────────────────────────────────────────────────────────────────────
217// StreamMount — native /stream pipe mount
218// ─────────────────────────────────────────────────────────────────────────────
219
220/// State for one active stream topic.
221struct StreamEntry {
222    /// Owner identity (the Subject name that registered the topic).
223    owner: Option<String>,
224    /// Queued blocks awaiting a guest read (FIFO).
225    blocks: VecDeque<Vec<u8>>,
226    /// Whether the producer has signalled end-of-stream.
227    complete: bool,
228    /// Whether the stream was cancelled (ctl `cancel`).
229    cancelled: bool,
230    /// Bytes delivered to the guest so far.
231    bytes_read: u64,
232    /// Blocks delivered to the guest so far.
233    blocks_read: u64,
234}
235
236/// Registry of active streams for a single sandbox's `/stream` mount.
237///
238/// `Mutex`-guarded and genuinely `Send + Sync` — the native replacement for the
239/// wasm `SyncRefCell` registry. A sandbox owns one registry; the worker runtime
240/// feeds blocks via [`push`](Self::push) / [`complete`](Self::complete) from
241/// whatever transport produced them, and the guest drains them by reading
242/// `/stream/{topic}/data`.
243pub struct StreamRegistry {
244    streams: Mutex<BTreeMap<String, StreamEntry>>,
245}
246
247impl StreamRegistry {
248    /// Create an empty registry.
249    pub fn new() -> Self {
250        Self {
251            streams: Mutex::new(BTreeMap::new()),
252        }
253    }
254
255    /// Register (or reset) a stream topic owned by `owner`.
256    pub fn register(&self, topic: impl Into<String>, owner: Option<String>) {
257        self.streams.lock().insert(
258            topic.into(),
259            StreamEntry {
260                owner,
261                blocks: VecDeque::new(),
262                complete: false,
263                cancelled: false,
264                bytes_read: 0,
265                blocks_read: 0,
266            },
267        );
268    }
269
270    /// Append a data block to a topic. No-op if the topic is unknown or done.
271    pub fn push(&self, topic: &str, block: Vec<u8>) {
272        let mut s = self.streams.lock();
273        if let Some(entry) = s.get_mut(topic) {
274            if !entry.complete && !entry.cancelled {
275                entry.blocks.push_back(block);
276            }
277        }
278    }
279
280    /// Mark a topic complete: no more blocks; reads drain the queue then EOF.
281    pub fn complete(&self, topic: &str) {
282        if let Some(entry) = self.streams.lock().get_mut(topic) {
283            entry.complete = true;
284        }
285    }
286
287    /// Whether a topic exists.
288    pub fn exists(&self, topic: &str) -> bool {
289        self.streams.lock().contains_key(topic)
290    }
291
292    /// List topic names visible to `owner` (all if `owner` is `None`).
293    pub fn list_topics(&self, owner: Option<&str>) -> Vec<String> {
294        self.streams
295            .lock()
296            .iter()
297            .filter(|(_, e)| owner.is_none() || owner == e.owner.as_deref())
298            .map(|(k, _)| k.clone())
299            .collect()
300    }
301}
302
303impl Default for StreamRegistry {
304    fn default() -> Self {
305        Self::new()
306    }
307}
308
309/// Fid state for a `/stream` path.
310#[derive(Clone)]
311enum StreamFidState {
312    Root,
313    TopicDir { topic: String },
314    Data { topic: String },
315    Info { topic: String },
316    Ctl { topic: String },
317}
318
319/// Native `/stream` mount: streaming data pipes as a 9P-shaped tree.
320///
321/// Genuinely `Send + Sync` (the registry is `Mutex`-guarded), so it can be
322/// served to a CH guest by FS-A's down-adapter. Read-only file surface except
323/// `/stream/{topic}/ctl`, which accepts `cancel`.
324pub struct StreamMount {
325    registry: Arc<StreamRegistry>,
326}
327
328impl StreamMount {
329    /// Build a stream mount over `registry`.
330    pub fn new(registry: Arc<StreamRegistry>) -> Self {
331        Self { registry }
332    }
333
334    /// The backing registry (so the runtime can feed blocks).
335    pub fn registry(&self) -> &Arc<StreamRegistry> {
336        &self.registry
337    }
338}
339
340#[async_trait]
341impl Mount for StreamMount {
342    async fn walk(&self, components: &[&str], _caller: &Subject) -> Result<Fid, MountError> {
343        let state = match components {
344            [] => StreamFidState::Root,
345            [topic] => {
346                if !self.registry.exists(topic) {
347                    return Err(MountError::NotFound((*topic).to_string()));
348                }
349                StreamFidState::TopicDir {
350                    topic: (*topic).to_string(),
351                }
352            }
353            [topic, "data"] => StreamFidState::Data {
354                topic: (*topic).to_string(),
355            },
356            [topic, "info"] => StreamFidState::Info {
357                topic: (*topic).to_string(),
358            },
359            [topic, "ctl"] => StreamFidState::Ctl {
360                topic: (*topic).to_string(),
361            },
362            _ => return Err(MountError::NotFound(components.join("/"))),
363        };
364        Ok(Fid::new(state))
365    }
366
367    async fn open(&self, _fid: &mut Fid, _mode: u8, _caller: &Subject) -> Result<(), MountError> {
368        Ok(())
369    }
370
371    async fn read(
372        &self,
373        fid: &Fid,
374        offset: u64,
375        count: u32,
376        _caller: &Subject,
377    ) -> Result<Vec<u8>, MountError> {
378        let state = fid
379            .downcast_ref::<StreamFidState>()
380            .ok_or_else(|| MountError::InvalidArgument("bad fid".into()))?;
381        match state {
382            StreamFidState::Root => Err(MountError::IsDirectory("stream root".into())),
383            StreamFidState::TopicDir { .. } => Err(MountError::IsDirectory("stream topic".into())),
384            StreamFidState::Data { topic } => {
385                let mut s = self.registry.streams.lock();
386                let entry = s
387                    .get_mut(topic.as_str())
388                    .ok_or_else(|| MountError::NotFound(topic.clone()))?;
389                if entry.cancelled {
390                    return Err(MountError::Io("stream cancelled".into()));
391                }
392                match entry.blocks.pop_front() {
393                    Some(block) => {
394                        entry.bytes_read += block.len() as u64;
395                        entry.blocks_read += 1;
396                        Ok(block)
397                    }
398                    // No block queued: EOF only when the producer is done,
399                    // otherwise an empty (non-blocking) read — the guest retries.
400                    None => Ok(Vec::new()),
401                }
402            }
403            StreamFidState::Info { topic } => {
404                let s = self.registry.streams.lock();
405                let entry = s
406                    .get(topic.as_str())
407                    .ok_or_else(|| MountError::NotFound(topic.clone()))?;
408                let info = format!(
409                    "{{\"topic\":\"{}\",\"bytesRead\":{},\"blocksRead\":{},\"queued\":{},\"complete\":{},\"cancelled\":{}}}\n",
410                    topic, entry.bytes_read, entry.blocks_read, entry.blocks.len(), entry.complete, entry.cancelled
411                );
412                let bytes = info.into_bytes();
413                let start = (offset as usize).min(bytes.len());
414                let end = (start + count as usize).min(bytes.len());
415                Ok(bytes[start..end].to_vec())
416            }
417            StreamFidState::Ctl { .. } => Ok(Vec::new()),
418        }
419    }
420
421    async fn write(
422        &self,
423        fid: &Fid,
424        _offset: u64,
425        data: &[u8],
426        _caller: &Subject,
427    ) -> Result<u32, MountError> {
428        let state = fid
429            .downcast_ref::<StreamFidState>()
430            .ok_or_else(|| MountError::InvalidArgument("bad fid".into()))?;
431        match state {
432            StreamFidState::Ctl { topic } => {
433                let cmd = std::str::from_utf8(data).unwrap_or("").trim();
434                match cmd {
435                    "cancel" => {
436                        if let Some(entry) = self.registry.streams.lock().get_mut(topic.as_str()) {
437                            entry.cancelled = true;
438                            entry.complete = true;
439                            entry.blocks.clear();
440                        }
441                        Ok(cmd.len() as u32)
442                    }
443                    _ => Err(MountError::NotSupported(format!(
444                        "unknown stream command: {cmd}"
445                    ))),
446                }
447            }
448            _ => Err(MountError::NotSupported(
449                "stream files are read-only".into(),
450            )),
451        }
452    }
453
454    async fn readdir(&self, fid: &Fid, _caller: &Subject) -> Result<Vec<DirEntry>, MountError> {
455        let state = fid
456            .downcast_ref::<StreamFidState>()
457            .ok_or_else(|| MountError::InvalidArgument("bad fid".into()))?;
458        match state {
459            StreamFidState::Root => Ok(self
460                .registry
461                .list_topics(None)
462                .into_iter()
463                .map(|name| DirEntry {
464                    name,
465                    is_dir: true,
466                    size: 0,
467                    stat: None,
468                })
469                .collect()),
470            StreamFidState::TopicDir { .. } => Ok(["data", "info", "ctl"]
471                .iter()
472                .map(|name| DirEntry {
473                    name: (*name).to_string(),
474                    is_dir: false,
475                    size: 0,
476                    stat: None,
477                })
478                .collect()),
479            _ => Err(MountError::NotDirectory("not a directory".into())),
480        }
481    }
482
483    async fn stat(&self, fid: &Fid, _caller: &Subject) -> Result<Stat, MountError> {
484        let state = fid
485            .downcast_ref::<StreamFidState>()
486            .ok_or_else(|| MountError::InvalidArgument("bad fid".into()))?;
487        let (qtype, name) = match state {
488            StreamFidState::Root => (0x80, "stream".to_string()),
489            StreamFidState::TopicDir { topic } => (0x80, topic.clone()),
490            StreamFidState::Data { .. } => (0, "data".to_string()),
491            StreamFidState::Info { .. } => (0, "info".to_string()),
492            StreamFidState::Ctl { .. } => (0, "ctl".to_string()),
493        };
494        Ok(Stat {
495            qtype,
496            version: 0,
497            path: 0,
498            size: 0,
499            name,
500            mtime: 0,
501        })
502    }
503
504    async fn clunk(&self, _fid: Fid, _caller: &Subject) {}
505}
506
507#[cfg(test)]
508#[allow(clippy::unwrap_used)]
509mod tests {
510    use super::*;
511    use crate::mount::{OREAD, OWRITE};
512
513    fn subj() -> Subject {
514        Subject::new("tester")
515    }
516
517    #[tokio::test]
518    async fn synthetic_reads_files_and_lists_dirs() {
519        let root = SyntheticNode::dir().with_child(
520            "models",
521            SyntheticNode::dir().with_child(
522                "qwen3",
523                SyntheticNode::dir()
524                    .with_child("info", SyntheticNode::file(b"qwen3 model\n".to_vec())),
525            ),
526        );
527        let mount = SyntheticMount::new(root);
528        let s = subj();
529
530        // Read a leaf file.
531        let mut fid = mount.walk(&["models", "qwen3", "info"], &s).await.unwrap();
532        mount.open(&mut fid, OREAD, &s).await.unwrap();
533        let data = mount.read(&fid, 0, 4096, &s).await.unwrap();
534        assert_eq!(data, b"qwen3 model\n");
535        mount.clunk(fid, &s).await;
536
537        // List a directory.
538        let mut dfid = mount.walk(&["models"], &s).await.unwrap();
539        mount.open(&mut dfid, OREAD, &s).await.unwrap();
540        let entries = mount.readdir(&dfid, &s).await.unwrap();
541        assert_eq!(entries.len(), 1);
542        assert_eq!(entries[0].name, "qwen3");
543        assert!(entries[0].is_dir);
544    }
545
546    #[tokio::test]
547    async fn synthetic_is_read_only() {
548        let root = SyntheticNode::dir().with_child("f", SyntheticNode::file(b"x".to_vec()));
549        let mount = SyntheticMount::new(root);
550        let s = subj();
551        let mut fid = mount.walk(&["f"], &s).await.unwrap();
552        // Write open is rejected.
553        assert!(mount.open(&mut fid, OWRITE, &s).await.is_err());
554        // Plain mount, not an FsMount.
555        assert!(mount.as_fsmount().is_none());
556    }
557
558    #[tokio::test]
559    async fn synthetic_missing_path_not_found() {
560        let mount = SyntheticMount::new(SyntheticNode::dir());
561        assert!(mount.walk(&["nope"], &subj()).await.is_err());
562    }
563
564    #[tokio::test]
565    async fn stream_drains_blocks_then_eof() {
566        let reg = Arc::new(StreamRegistry::new());
567        reg.register("topic-a", Some("tester".to_string()));
568        reg.push("topic-a", b"hello".to_vec());
569        reg.push("topic-a", b"world".to_vec());
570        reg.complete("topic-a");
571
572        let mount = StreamMount::new(reg);
573        let s = subj();
574        let mut fid = mount.walk(&["topic-a", "data"], &s).await.unwrap();
575        mount.open(&mut fid, OREAD, &s).await.unwrap();
576        assert_eq!(mount.read(&fid, 0, 1024, &s).await.unwrap(), b"hello");
577        assert_eq!(mount.read(&fid, 0, 1024, &s).await.unwrap(), b"world");
578        // Drained: empty read = EOF.
579        assert!(mount.read(&fid, 0, 1024, &s).await.unwrap().is_empty());
580        mount.clunk(fid, &s).await;
581    }
582
583    #[tokio::test]
584    async fn stream_ctl_cancel() {
585        let reg = Arc::new(StreamRegistry::new());
586        reg.register("t", None);
587        reg.push("t", b"data".to_vec());
588        let mount = StreamMount::new(reg);
589        let s = subj();
590        let mut cfid = mount.walk(&["t", "ctl"], &s).await.unwrap();
591        mount.open(&mut cfid, OWRITE, &s).await.unwrap();
592        mount.write(&cfid, 0, b"cancel", &s).await.unwrap();
593        mount.clunk(cfid, &s).await;
594
595        // After cancel, reading data errors.
596        let mut dfid = mount.walk(&["t", "data"], &s).await.unwrap();
597        mount.open(&mut dfid, OREAD, &s).await.unwrap();
598        assert!(mount.read(&dfid, 0, 1024, &s).await.is_err());
599        mount.clunk(dfid, &s).await;
600    }
601
602    #[tokio::test]
603    async fn stream_root_lists_topics() {
604        let reg = Arc::new(StreamRegistry::new());
605        reg.register("a", None);
606        reg.register("b", None);
607        let mount = StreamMount::new(reg);
608        let s = subj();
609        let mut fid = mount.walk(&[], &s).await.unwrap();
610        mount.open(&mut fid, OREAD, &s).await.unwrap();
611        let entries = mount.readdir(&fid, &s).await.unwrap();
612        let names: Vec<&str> = entries.iter().map(|e| e.name.as_str()).collect();
613        assert!(names.contains(&"a"));
614        assert!(names.contains(&"b"));
615    }
616}