Skip to main content

hyprstream_9p/
backend.rs

1//! Backend trait — the capnp-RPC-shaped seam the translator dispatches to.
2//!
3//! Each method mirrors a 9P2000.L filesystem operation as expressed in
4//! `nine.capnp` (NpWalk / NpOpen / NpRead / NpWrite / NpClunk / NpStatReq).
5//! The translator owns the server-side fid table and calls these methods
6//! after resolving the incoming 9P fid.
7//!
8//! `MemoryBackend` ([`crate::memory::MemoryBackend`]) provides an
9//! in-process implementation for standalone tests; the `hyprstream` binary
10//! crate ships a `ModelBackend` that wraps the generated `ModelClient` and
11//! turns each call into a capnp RPC against the model service's `fs` scope
12//! (the inverse of `RemoteModelMount`, which goes VFS → RPC).
13
14use async_trait::async_trait;
15
16use crate::mac_seam::VerifiedAttach;
17use crate::msg::Qid;
18
19/// Result of a walk: the qid of the resolved path and, for directories, the
20/// qids of each intermediate component. For a single-component walk (the
21/// common case for this translator) `qids` holds exactly the leaf qid.
22#[derive(Debug, Clone)]
23pub struct WalkResult {
24    /// Qids for each path component successfully walked (length matches the
25    /// number of components traversed; the client treats a short list as
26    /// "walk stopped early").
27    pub qids: Vec<Qid>,
28    /// Exact request-component prefix to which `newfid` is bound. For a
29    /// non-empty walk this has the same length as `qids`; a short prefix is a
30    /// 9P partial walk. Backends must report their actual binding here rather
31    /// than inferring it from the number of leaf qids they happen to return.
32    ///
33    /// The translator rejects a result that is not a prefix of its request or
34    /// whose QID count disagrees with this prefix, so a backend cannot bind a
35    /// deeper object while making the monitor cache a shallower name.
36    pub reached: Vec<String>,
37}
38
39/// Result of an open/lopen.
40#[derive(Debug, Clone)]
41pub struct OpenResult {
42    pub qid: Qid,
43    /// Maximum read/write unit the backend will accept in a single call.
44    pub iounit: u32,
45}
46
47/// Result of a stat/getattr.
48#[derive(Debug, Clone)]
49pub struct StatResult {
50    pub qid: Qid,
51    /// Unix mode bits (e.g. `0o040755` for a dir).
52    pub mode: u32,
53    pub size: u64,
54    pub mtime_sec: u64,
55}
56
57/// 9P filesystem backend.
58///
59/// All methods are async and `Send`-safe so the translator can drive them on
60/// a multi-threaded tokio runtime. Fid numbers are opaque to the backend —
61/// the translator allocates and tracks them; the backend sees a stable fid
62/// per walked path.
63#[async_trait]
64pub trait Backend: Send + Sync {
65    /// Establish the session at `Tattach`, given the `uname` the client
66    /// presented and the `aname` export selector it requested. The default is a
67    /// no-op: backends whose caller identity is fixed at construction
68    /// (the UDS/vsock listeners) ignore both.
69    ///
70    /// A backend that resolves its caller identity from the attach itself
71    /// (the H1b `/9p` WebTransport plane carries a mount ticket in
72    /// `Tattach.uname` — the browser `WebSocket` can't set headers and the
73    /// cert-pinned WT session has no URL query) validates it here and binds
74    /// the session `Subject`. `aname` is the requested export (the 9P attach
75    /// name); an authorizing backend validates it against the ticket's granted
76    /// namespace and **denies an unknown/forbidden/malformed selector** rather
77    /// than falling back to a default export (#877/#1071 fail-closed contract).
78    /// Returning `Err` fails the attach; the translator maps it to an `Rlerror`
79    /// errno (a `hyprstream_vfs::MountError` in the cause chain picks the errno
80    /// — e.g. `PermissionDenied → EACCES`).
81    async fn attach(
82        &self,
83        _uname: &str,
84        _aname: &str,
85        verified: Option<VerifiedAttach>,
86    ) -> anyhow::Result<Option<VerifiedAttach>> {
87        Ok(verified)
88    }
89
90    /// Walk `components` from `fid` (the previously-walked parent, or the
91    /// attach root). Allocates internal state for `newfid`.
92    async fn walk(
93        &self,
94        fid: u32,
95        newfid: u32,
96        components: &[String],
97    ) -> anyhow::Result<WalkResult>;
98
99    /// Open `fid` with Linux-style `flags` (Tlopen). Returns the leaf qid
100    /// and the negotiated iounit.
101    async fn open(&self, fid: u32, flags: u32) -> anyhow::Result<OpenResult>;
102
103    /// Read up to `count` bytes from `fid` at `offset`.
104    async fn read(&self, fid: u32, offset: u64, count: u32) -> anyhow::Result<Vec<u8>>;
105
106    /// Write `data` to `fid` at `offset`. Returns the number of bytes written.
107    async fn write(&self, fid: u32, offset: u64, data: &[u8]) -> anyhow::Result<u32>;
108
109    /// Stat `fid`.
110    async fn stat(&self, fid: u32) -> anyhow::Result<StatResult>;
111
112    /// List directory entries under `fid` (a directory). The returned bytes
113    /// are 9P readdir records; the translator passes them through verbatim.
114    async fn readdir(&self, fid: u32, offset: u64, count: u32) -> anyhow::Result<Vec<u8>>;
115
116    /// Release `fid`. Best-effort — errors are logged and ignored by the
117    /// translator (the fid is dropped from its table regardless).
118    async fn clunk(&self, fid: u32) -> anyhow::Result<()>;
119
120    /// Release connection-local handles after EOF or a framing/write error.
121    /// Backends without retained remote handles may keep the default no-op.
122    async fn close_connection(&self) {}
123}