Skip to main content

hyprstream_workers_python/
mount.rs

1//! `/lang/python/` VFS mount backed by the wasm-sandboxed python guest.
2//!
3//! Exposes a `/lang/python` layout driven by a [`PythonShell`](crate::PythonShell)
4//! over the wasm guest, so the interpreter is the sandboxed guest rather than a native
5//! one.
6//!
7//! Layout:
8//! - `/lang/python/eval`    — ctl: write a Python EXPRESSION, read `repr(result)`
9//!   (with `\n---\n<stdout>` appended if it printed)
10//! - `/lang/python/stdout`  — ctl: write Python STATEMENTS, read captured stdout
11//! - `/lang/python/vars/`   — dynamic dir: non-dunder globals as readable files
12//! - `/lang/python/defs/`   — dynamic dir: callable globals (functions/classes)
13//!
14//! ## Why a command channel
15//!
16//! A [`PythonShell`](crate::PythonShell) owns a long-lived wasmtime `Store`. When the
17//! sandbox holds a VFS capability, its `vfs_*` host fns `blocking_send` on the proxy —
18//! so the shell MUST be driven from a NON-async thread, never a tokio worker. The
19//! async [`Mount`] methods therefore cannot call the shell directly: [`PythonMount`]
20//! holds a `tokio::sync::mpsc::Sender<PyCommand>` and forwards each request to the
21//! thread that owns the shell, which replies over a oneshot.
22//!
23//! [`PythonMount::spawn`] wires this end-to-end: it opens the shell, spawns the
24//! driver thread, and keeps the command channel internal. The driver exits when
25//! the mount is dropped. Mount the result at `/lang/python`; the namespace is the
26//! only interface (epic #508, issue #634).
27//!
28//! Built on `hyprstream-vfs`'s `devfile` primitives (`ControlFile` for
29//! `eval`/`stdout`, `DynamicDir` for `vars`/`defs`) rather than hand-rolling
30//! the write→latch→read state machine — see `hyprstream_vfs::devfile` (#609).
31
32use async_trait::async_trait;
33use hyprstream_vfs::devfile::{ControlFile, DevFileState, DevFuture, DynamicDir};
34use hyprstream_vfs::{DirEntry, Fid, Mount, MountError, Stat, Subject};
35
36use crate::{PyResult, PythonShell};
37
38// ─────────────────────────────────────────────────────────────────────────────
39// Commands sent from async Mount methods to the shell-owning thread.
40// ─────────────────────────────────────────────────────────────────────────────
41
42/// A request from [`PythonMount`] to the thread owning the [`PythonShell`](crate::PythonShell).
43pub enum PyCommand {
44    /// Evaluate a Python expression. Response: the rendered [`PyResult`].
45    Eval {
46        code: String,
47        resp: tokio::sync::oneshot::Sender<PyResult>,
48    },
49    /// Execute Python statements. Response: captured stdout as a [`PyResult`].
50    Exec {
51        code: String,
52        resp: tokio::sync::oneshot::Sender<PyResult>,
53    },
54    /// List non-dunder global variable names.
55    ListVars {
56        resp: tokio::sync::oneshot::Sender<Vec<String>>,
57    },
58    /// `repr` of one global variable (or `None` if absent).
59    GetVar {
60        name: String,
61        resp: tokio::sync::oneshot::Sender<PyResult>,
62    },
63    /// List callable global names.
64    ListDefs {
65        resp: tokio::sync::oneshot::Sender<Vec<String>>,
66    },
67    /// `repr` of one callable global (or `None` if absent/not callable).
68    GetDef {
69        name: String,
70        resp: tokio::sync::oneshot::Sender<PyResult>,
71    },
72}
73
74// ─────────────────────────────────────────────────────────────────────────────
75// Fid types.
76// ─────────────────────────────────────────────────────────────────────────────
77
78#[derive(Clone, Debug)]
79enum PyFidKind {
80    Root,
81    Eval,
82    Stdout,
83    VarsDir,
84    Var(String),
85    DefsDir,
86    Def(String),
87}
88
89/// Fid state. `ctl_state` buffers the response from a write to `eval`/`stdout`
90/// so a later read returns it (the Plan9 ctl pattern, via
91/// `devfile::ControlFile`). Unused for non-ctl fid kinds.
92struct PyFid {
93    kind: PyFidKind,
94    ctl_state: DevFileState,
95}
96
97// ─────────────────────────────────────────────────────────────────────────────
98// devfile callback type aliases
99// ─────────────────────────────────────────────────────────────────────────────
100
101type PyCtl = ControlFile<
102    Box<dyn Fn(Vec<u8>) -> DevFuture<'static, Result<Vec<u8>, MountError>> + Send + Sync>,
103>;
104type ListFn = Box<dyn Fn() -> DevFuture<'static, Vec<String>> + Send + Sync>;
105type GetFn =
106    Box<dyn Fn(String) -> DevFuture<'static, Result<Option<Vec<u8>>, MountError>> + Send + Sync>;
107type FieldDir = DynamicDir<ListFn, GetFn>;
108
109// ─────────────────────────────────────────────────────────────────────────────
110// PythonMount
111// ─────────────────────────────────────────────────────────────────────────────
112
113/// VFS mount that proxies `/lang/python` requests to a
114/// [`PythonShell`](crate::PythonShell) owned by the mount itself.
115///
116/// Construct with [`PythonMount::spawn`], which spins up a dedicated driver
117/// thread hosting the [`PythonShell`](crate::PythonShell) and drains the
118/// internal command channel. The driver exits cleanly when the mount is dropped
119/// (all command-channel senders live inside the mount). Callers never hold the
120/// shell, the channel sender, or the receiver — the namespace is the only
121/// interface (epic #508, issue #634).
122pub struct PythonMount {
123    eval: PyCtl,
124    stdout: PyCtl,
125    vars: FieldDir,
126    defs: FieldDir,
127    /// Sender clone kept for the mount's lifetime; the driver exits when every
128    /// clone (including the ones inside the devfile closures) drops with the
129    /// mount.
130    _driver_tx: tokio::sync::mpsc::Sender<PyCommand>,
131}
132
133impl PythonMount {
134    /// Spawn a self-contained `PythonMount` whose driver thread owns a fresh
135    /// [`PythonShell`](crate::PythonShell) over `sandbox` with `per_call_fuel`.
136    ///
137    /// The driver runs on a plain OS thread (the wasmtime `Store` the shell
138    /// holds may `blocking_send` on a VFS capability, so it MUST NOT run on a
139    /// tokio worker). Mount methods forward each request over an internal
140    /// channel and await the reply; the driver pumps the shell between
141    /// requests via [`PythonShell::process_command`](crate::PythonShell::process_command).
142    #[allow(clippy::expect_used)] // Thread creation failure is unrecoverable
143    pub fn spawn(
144        sandbox: hyprstream_workers_wasmtime::Sandbox,
145        per_call_fuel: u64,
146    ) -> wasmtime::Result<Self> {
147        let (tx, rx) = tokio::sync::mpsc::channel::<PyCommand>(16);
148        std::thread::Builder::new()
149            .name("python-mount-driver".into())
150            .spawn(move || {
151                let Ok(mut shell) = PythonShell::open(&sandbox, per_call_fuel) else {
152                    return;
153                };
154                let mut rx = rx;
155                while let Some(cmd) = rx.blocking_recv() {
156                    shell.process_command(cmd);
157                }
158            })
159            .expect("spawn python-mount-driver");
160        // `tx` is moved into `build`, which stores it as `_driver_tx`; the
161        // devfile closures hold their own clones. Every clone drops with the
162        // mount, which is what signals the driver to exit.
163        Ok(Self::build(tx))
164    }
165
166    /// Build a `PythonMount` over an existing command-channel sender.
167    ///
168    /// Internal helper used by tests that drive the shell via a fake owner
169    /// loop instead of `PythonShell::open`.
170    #[cfg(test)]
171    fn new(tx: tokio::sync::mpsc::Sender<PyCommand>) -> Self {
172        Self::build(tx)
173    }
174
175    fn build(tx: tokio::sync::mpsc::Sender<PyCommand>) -> Self {
176        let eval_tx = tx.clone();
177        let eval_handler = move |data: Vec<u8>| -> DevFuture<'static, Result<Vec<u8>, MountError>> {
178            let tx = eval_tx.clone();
179            let code = String::from_utf8_lossy(&data).into_owned();
180            Box::pin(async move {
181                let r = request(&tx, |resp| PyCommand::Eval { code, resp }).await?;
182                Ok(render(r))
183            })
184        };
185        let eval = ControlFile::new(Box::new(eval_handler) as _);
186
187        let stdout_tx = tx.clone();
188        let stdout_handler =
189            move |data: Vec<u8>| -> DevFuture<'static, Result<Vec<u8>, MountError>> {
190                let tx = stdout_tx.clone();
191                let code = String::from_utf8_lossy(&data).into_owned();
192                Box::pin(async move {
193                    let r = request(&tx, |resp| PyCommand::Exec { code, resp }).await?;
194                    Ok(render(r))
195                })
196            };
197        let stdout = ControlFile::new(Box::new(stdout_handler) as _);
198
199        let vars_list_tx = tx.clone();
200        let vars_get_tx = tx.clone();
201        let vars = DynamicDir::new(
202            Box::new(move || {
203                let tx = vars_list_tx.clone();
204                Box::pin(async move {
205                    request(&tx, |resp| PyCommand::ListVars { resp })
206                        .await
207                        .unwrap_or_default()
208                }) as DevFuture<'static, _>
209            }) as ListFn,
210            Box::new(move |name: String| {
211                let tx = vars_get_tx.clone();
212                Box::pin(async move {
213                    let r = request(&tx, |resp| PyCommand::GetVar { name, resp }).await?;
214                    Ok(match r {
215                        PyResult::None => None,
216                        other => Some(render(other)),
217                    })
218                }) as DevFuture<'static, _>
219            }) as GetFn,
220        );
221
222        let defs_list_tx = tx.clone();
223        let defs_get_tx = tx.clone();
224        let defs = DynamicDir::new(
225            Box::new(move || {
226                let tx = defs_list_tx.clone();
227                Box::pin(async move {
228                    request(&tx, |resp| PyCommand::ListDefs { resp })
229                        .await
230                        .unwrap_or_default()
231                }) as DevFuture<'static, _>
232            }) as ListFn,
233            Box::new(move |name: String| {
234                let tx = defs_get_tx.clone();
235                Box::pin(async move {
236                    let r = request(&tx, |resp| PyCommand::GetDef { name, resp }).await?;
237                    Ok(match r {
238                        PyResult::None => None,
239                        other => Some(render(other)),
240                    })
241                }) as DevFuture<'static, _>
242            }) as GetFn,
243        );
244
245        Self {
246            eval,
247            stdout,
248            vars,
249            defs,
250            _driver_tx: tx,
251        }
252    }
253}
254
255/// Send a command and await the shell response.
256async fn request<T>(
257    tx: &tokio::sync::mpsc::Sender<PyCommand>,
258    build: impl FnOnce(tokio::sync::oneshot::Sender<T>) -> PyCommand,
259) -> Result<T, MountError> {
260    let (resp_tx, resp_rx) = tokio::sync::oneshot::channel();
261    tx.send(build(resp_tx))
262        .await
263        .map_err(|_| MountError::Io("python interpreter gone".into()))?;
264    resp_rx
265        .await
266        .map_err(|_| MountError::Io("python interpreter did not respond".into()))
267}
268
269/// Render a [`PyResult`] for the `eval`/`stdout` ctl read.
270fn render(r: PyResult) -> Vec<u8> {
271    match r {
272        PyResult::Ok(s) => s.into_bytes(),
273        PyResult::None => Vec::new(),
274        PyResult::Err(e) => format!("error: {e}").into_bytes(),
275    }
276}
277
278#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
279#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
280impl Mount for PythonMount {
281    async fn walk(&self, components: &[&str], _caller: &Subject) -> Result<Fid, MountError> {
282        let kind = match components {
283            [] => PyFidKind::Root,
284            ["eval"] => PyFidKind::Eval,
285            ["stdout"] => PyFidKind::Stdout,
286            ["vars"] => PyFidKind::VarsDir,
287            ["vars", name] => PyFidKind::Var((*name).to_owned()),
288            ["defs"] => PyFidKind::DefsDir,
289            ["defs", name] => PyFidKind::Def((*name).to_owned()),
290            _ => return Err(MountError::NotFound(components.join("/"))),
291        };
292        Ok(Fid::new(PyFid {
293            kind,
294            ctl_state: DevFileState::new(),
295        }))
296    }
297
298    async fn open(&self, _fid: &mut Fid, _mode: u8, _caller: &Subject) -> Result<(), MountError> {
299        Ok(())
300    }
301
302    async fn read(
303        &self,
304        fid: &Fid,
305        offset: u64,
306        _count: u32,
307        _caller: &Subject,
308    ) -> Result<Vec<u8>, MountError> {
309        let inner = fid
310            .downcast_ref::<PyFid>()
311            .ok_or_else(|| MountError::InvalidArgument("bad fid".into()))?;
312        match &inner.kind {
313            PyFidKind::Eval => Ok(self.eval.handle_read(&inner.ctl_state, offset)),
314            PyFidKind::Stdout => Ok(self.stdout.handle_read(&inner.ctl_state, offset)),
315            PyFidKind::Var(name) => self.vars.read(name, offset).await,
316            PyFidKind::Def(name) => self.defs.read(name, offset).await,
317            PyFidKind::Root | PyFidKind::VarsDir | PyFidKind::DefsDir => {
318                Err(MountError::IsDirectory("use readdir".into()))
319            }
320        }
321    }
322
323    async fn write(
324        &self,
325        fid: &Fid,
326        _offset: u64,
327        data: &[u8],
328        _caller: &Subject,
329    ) -> Result<u32, MountError> {
330        let inner = fid
331            .downcast_ref::<PyFid>()
332            .ok_or_else(|| MountError::InvalidArgument("bad fid".into()))?;
333        match &inner.kind {
334            PyFidKind::Eval => self.eval.handle_write(&inner.ctl_state, data).await,
335            PyFidKind::Stdout => self.stdout.handle_write(&inner.ctl_state, data).await,
336            _ => Err(MountError::NotSupported("read-only".into())),
337        }
338    }
339
340    async fn readdir(&self, fid: &Fid, _caller: &Subject) -> Result<Vec<DirEntry>, MountError> {
341        let inner = fid
342            .downcast_ref::<PyFid>()
343            .ok_or_else(|| MountError::InvalidArgument("bad fid".into()))?;
344        let mk = |name: String, is_dir: bool| DirEntry {
345            name,
346            is_dir,
347            size: 0,
348            stat: None,
349        };
350        match &inner.kind {
351            PyFidKind::Root => Ok(vec![
352                mk("eval".into(), false),
353                mk("stdout".into(), false),
354                mk("vars".into(), true),
355                mk("defs".into(), true),
356            ]),
357            PyFidKind::VarsDir => Ok(self.vars.readdir().await),
358            PyFidKind::DefsDir => Ok(self.defs.readdir().await),
359            _ => Err(MountError::NotDirectory(format!("{:?}", inner.kind))),
360        }
361    }
362
363    async fn stat(&self, fid: &Fid, _caller: &Subject) -> Result<Stat, MountError> {
364        let inner = fid
365            .downcast_ref::<PyFid>()
366            .ok_or_else(|| MountError::InvalidArgument("bad fid".into()))?;
367        let (name, qtype) = match &inner.kind {
368            PyFidKind::Root => ("python".to_owned(), 0x80u8),
369            PyFidKind::Eval => ("eval".to_owned(), 0u8),
370            PyFidKind::Stdout => ("stdout".to_owned(), 0u8),
371            PyFidKind::VarsDir => ("vars".to_owned(), 0x80u8),
372            PyFidKind::Var(n) => (n.clone(), 0u8),
373            PyFidKind::DefsDir => ("defs".to_owned(), 0x80u8),
374            PyFidKind::Def(n) => (n.clone(), 0u8),
375        };
376        Ok(Stat {
377            qtype,
378            version: 0,
379            path: 0,
380            size: 0,
381            name,
382            mtime: 0,
383        })
384    }
385
386    async fn clunk(&self, _fid: Fid, _caller: &Subject) {}
387}
388
389#[cfg(test)]
390fn create_mount_channel() -> (
391    tokio::sync::mpsc::Sender<PyCommand>,
392    tokio::sync::mpsc::Receiver<PyCommand>,
393) {
394    tokio::sync::mpsc::channel(16)
395}
396
397#[cfg(test)]
398mod tests {
399    use super::*;
400    use crate::PythonShell;
401    use hyprstream_workers_wasmtime::Sandbox;
402    use std::path::PathBuf;
403
404    fn guest_wasm() -> Option<Vec<u8>> {
405        if let Ok(p) = std::env::var("HYPRSTREAM_PYGUEST_WASM") {
406            return std::fs::read(&p).ok();
407        }
408        let manifest = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
409        let guest_dir = manifest
410            .parent()
411            .map(|p| p.join("hyprstream-workers-python-guest"))?;
412        for profile in ["release", "debug"] {
413            let c = guest_dir
414                .join("target/wasm32-unknown-unknown")
415                .join(profile)
416                .join("hyprstream_workers_python_guest.wasm");
417            if c.exists() {
418                if let Ok(b) = std::fs::read(&c) {
419                    return Some(b);
420                }
421            }
422        }
423        None
424    }
425
426    /// CI guard: under CI a missing pyguest artifact is a hard failure (the mount
427    /// guarantees must be exercised); locally it still skips.
428    fn guest_wasm_or_ci_fail() -> Option<Vec<u8>> {
429        match guest_wasm() {
430            Some(wasm) => Some(wasm),
431            None => {
432                assert!(
433                    std::env::var("CI").is_err(),
434                    "mount test: pyguest wasm not built but running under CI — build the \
435                     pyguest and set HYPRSTREAM_PYGUEST_WASM"
436                );
437                eprintln!(
438                    "SKIP mount test: guest wasm not built (set CI=1 to make this a failure)"
439                );
440                None
441            }
442        }
443    }
444
445    /// End-to-end mount test against an in-memory VFS: write an expr to `eval`, read
446    /// the result; exec sets a var, read it back under `vars/`; `readdir` lists the
447    /// layout, driven by the wasm guest. The shell runs on a dedicated thread that
448    /// drains the mount channel (mirroring the daemon owner loop).
449    #[test]
450    fn mount_eval_vars_defs_over_guest() {
451        let Some(wasm) = guest_wasm_or_ci_fail() else {
452            return;
453        };
454        let rt = tokio::runtime::Builder::new_multi_thread()
455            .worker_threads(2)
456            .enable_all()
457            .build()
458            .unwrap();
459
460        let subject = Subject::new("alice");
461        let (tx, mut rx) = create_mount_channel();
462
463        // Shell owner thread: open the shell on a plain thread (vfs_* may
464        // blocking_send) and drain the mount channel.
465        let owner_wasm = wasm.clone();
466        let owner_subject = subject.clone();
467        let owner = std::thread::Builder::new()
468            .name("test-pyshell-owner".into())
469            .spawn(move || {
470                let sandbox = Sandbox::from_bytes_for(&owner_wasm, owner_subject).expect("load");
471                let mut shell = PythonShell::open(&sandbox, 50_000_000_000).expect("open shell");
472                while let Some(cmd) = rx.blocking_recv() {
473                    shell.process_command(cmd);
474                }
475            })
476            .expect("spawn owner");
477
478        let mount = PythonMount::new(tx);
479
480        rt.block_on(async {
481            // readdir root -> eval/stdout/vars/defs.
482            let root = mount.walk(&[], &subject).await.unwrap();
483            let entries = mount.readdir(&root, &subject).await.unwrap();
484            let names: Vec<&str> = entries.iter().map(|e| e.name.as_str()).collect();
485            assert!(names.contains(&"eval"));
486            assert!(names.contains(&"vars"));
487            assert!(names.contains(&"defs"));
488
489            // Write an expression to `eval`, read the repr back.
490            let eval = mount.walk(&["eval"], &subject).await.unwrap();
491            mount.write(&eval, 0, b"2 + 3", &subject).await.unwrap();
492            let out = mount.read(&eval, 0, 4096, &subject).await.unwrap();
493            assert_eq!(out, b"5", "eval should return repr 5");
494
495            // exec sets a var via `stdout`, then read it under `vars/x`.
496            let stdout = mount.walk(&["stdout"], &subject).await.unwrap();
497            mount.write(&stdout, 0, b"x = 42", &subject).await.unwrap();
498
499            let var_x = mount.walk(&["vars", "x"], &subject).await.unwrap();
500            let out = mount.read(&var_x, 0, 4096, &subject).await.unwrap();
501            assert_eq!(out, b"42", "vars/x should be the persisted value");
502
503            // vars/ readdir includes x.
504            let vars_dir = mount.walk(&["vars"], &subject).await.unwrap();
505            let entries = mount.readdir(&vars_dir, &subject).await.unwrap();
506            assert!(entries.iter().any(|e| e.name == "x"));
507
508            // Define a function; defs/ lists it.
509            let stdout2 = mount.walk(&["stdout"], &subject).await.unwrap();
510            mount
511                .write(&stdout2, 0, b"def f():\n    return 1\n", &subject)
512                .await
513                .unwrap();
514            let defs_dir = mount.walk(&["defs"], &subject).await.unwrap();
515            let defs = mount.readdir(&defs_dir, &subject).await.unwrap();
516            assert!(defs.iter().any(|e| e.name == "f"), "defs/ should list f");
517
518            eprintln!("mount: eval/vars/defs over guest all green");
519        });
520
521        // Close the channel so the owner thread exits, then join.
522        drop(mount);
523        owner.join().unwrap();
524    }
525}