hyprstream_vfs/lib.rs
1//! Plan9-inspired VFS namespace multiplexer.
2//!
3//! The VFS is a client-side mount table that routes 9P operations by path prefix.
4//! Services are auto-mounted under `/srv/{name}` from discovery. Commands live
5//! at `/bin/` (Plan9 convention). Local mounts (`/config/`, `/private/`, `/bin/`,
6//! `/env/`) are reserved for Mount only.
7//!
8//! ```text
9//! /bin/cat → filesystem command (CtlFile)
10//! /env/temperature → session variable (DynamicDir)
11//! /srv/model/qwen3:main/status → ModelService (via ZMQ or IPC)
12//! /srv/mcp/summarize/schema → McpService
13//! /config/temperature → in-process (Mount)
14//! /net/peer-a/srv/model/... → federated peer
15//! ```
16//!
17//! All types are WASM-compatible. Transport is abstracted via traits.
18
19pub mod devfile;
20mod fsmount;
21/// MAC PEP for the direct Namespace API (#1272): the contract `Namespace`
22/// invokes per op, plus fail-closed defaults. The audited production impl lives
23/// in `hyprstream::mac::pep`.
24pub mod mac_pep;
25mod mount;
26mod namespace;
27#[cfg(not(target_arch = "wasm32"))]
28pub mod proxy;
29
30// Native injected mounts (FS-D, #365): the `Send + Sync` ports of the wasm-only
31// `/stream` / synthetic injected mounts, suitable for serving to a CH guest.
32#[cfg(not(target_arch = "wasm32"))]
33pub mod injected;
34
35// Native-only: the `FileSystem → FsMount` up-adapter and the OverlayFs-backed
36// v1 overlay engine. Both wrap `fuse_backend_rs`, whose overlay/passthrough
37// backends are Linux-only.
38#[cfg(not(target_arch = "wasm32"))]
39mod fuse_adapter;
40#[cfg(not(target_arch = "wasm32"))]
41pub mod overlay;
42// Shim that makes a handleless `Layer` (e.g. RAFS) usable as an OverlayFs lower.
43#[cfg(not(target_arch = "wasm32"))]
44mod zero_open;
45
46pub use devfile::{ControlFile, DevFileState, DevFuture, DynamicDir, FieldFile, NoSetter};
47pub use fsmount::{FsMount, SetAttr};
48pub use hyprstream_rpc::Subject;
49pub use mac_pep::NamespaceAction;
50#[cfg(not(target_arch = "wasm32"))]
51pub use mac_pep::{
52 DenyAllNamespace, DenyAllSubjects, DenyUnlabeledResolver, NamespaceAccessDecider, NamespacePep,
53 SubjectContextResolver,
54};
55pub use mount::{
56 DirEntry, Fid, Mount, MountError, Stat, DMDIR, ORCLOSE, ORDWR, OREAD, OTRUNC, OWRITE,
57};
58pub use namespace::{BindFlag, MountTarget, Namespace, NamespaceError, ReadMountTarget};
59
60#[cfg(not(target_arch = "wasm32"))]
61pub use fuse_adapter::FuseFileSystemMount;
62
63#[cfg(not(target_arch = "wasm32"))]
64pub use injected::{StreamMount, StreamRegistry, SyntheticMount, SyntheticNode};
65
66// Overlay composition surface (FS-C v1 engine). Re-exported so downstream crates
67// (FS-B) can build a RAFS lower as a `BoxedLayer` via [`overlay::layer_from_fs`]
68// and compose it with [`overlay::rootfs_overlay`] without depending on
69// `fuse-backend-rs`'s overlay internals directly.
70#[cfg(not(target_arch = "wasm32"))]
71pub use fuse_backend_rs::overlayfs::BoxedLayer;
72#[cfg(not(target_arch = "wasm32"))]
73pub use zero_open::ZeroOpenLayer;
74
75// ─────────────────────────────────────────────────────────────────────────────
76// Standard namespace paths
77// ─────────────────────────────────────────────────────────────────────────────
78
79/// Canonical mount paths every hyprstream namespace exposes, regardless of
80/// transport (native TUI vs WASM browser).
81///
82/// This is the convergence contract from #389 + #391 (Option 1: shared content
83/// model). Both the native namespace builder
84/// (`hyprstream::cli::shell_handlers`) and the browser namespace builder
85/// (`hyprstream_rpc_std::vfs_mount::build_browser_namespace`) mount these
86/// content trees backed at the hyprstream spine — so `/srv/registry/foo/main`
87/// resolves to the same repo/worktree content in either context.
88///
89/// The transport leaf (DMA/SAB ring buffers for the browser, ZMQ for native)
90/// is correctly-scoped glue and is NOT part of this contract — only the
91/// backing content trees are converged.
92///
93/// # Paths
94///
95/// | Path | Backing |
96/// |------------------|----------------------------------------------------|
97/// | `/srv/model` | Model service: synthetic tree (status, load, ...) |
98/// | `/srv/registry` | Registry service: worktree FS (real qids) |
99/// | `/worktree` | Alias of `/srv/registry` (short ergonomic path) |
100///
101/// Per-target paths (NOT part of the convergence contract):
102/// - `/bin`, `/env`, `/lang/tcl` — native-only local synthetic mounts
103/// - `/stream`, `/srv/{service}/doc` — browser-only GenericServiceMount extras
104pub const STANDARD_NAMESPACE_PATHS: &[&str] = &["/srv/model", "/srv/registry", "/worktree"];