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}