Skip to main content

hyprstream_core/services/
remote_registry_mount.rs

1//! Remote registry mount — bridges the VFS `Mount` trait to the registry
2//! service's worktree filesystem via the generated `WorktreeClient` RPC.
3//!
4//! `RemoteRegistryMount` is the registry analogue of `RemoteModelMount`:
5//! where `RemoteModelMount` proxies 9P operations to the model service's
6//! per-`modelRef` synthetic tree (1 path level: first component = modelRef),
7//! this mount proxies to the registry service's per-`worktree` real
8//! filesystem — 2 path levels: first = repo name, second = worktree name,
9//! the rest = in-worktree wnames. Repo names resolve to UUIDs via the
10//! registry's `get_by_name` RPC.
11//!
12//! ## Shared bridge
13//!
14//! The sync→async plumbing (embedded tokio runtime, fid allocator, fid map,
15//! `anyhow → MountError` mapping, the opaque fid key) is shared with
16//! `RemoteModelMount` via [`NinePBridge`] in [`crate::services::ninep_bridge`].
17//! Only the registry-specific pieces live here: the
18//! `RegistryClient`/`WorktreeClient` types, the 2-level scope extraction
19//! (repo → worktree, with async `get_by_name` UUID resolution), the `np_stat`
20//! (not `stat`) RPC method name, and the worktree-specific directory-entry
21//! byte format (`name_len+name+is_dir+size`), parsed by
22//! `parse_worktree_dir_entries` below.
23//!
24//! ## Real qids
25//!
26//! Now that #388 widened `vfs::Stat` with `version` + `path`, this mount
27//! threads the wire qid `{qtype, version=ctime, path=ino}` from the registry
28//! service's `RStat`/`RWalk` responses straight through — that is the whole
29//! point of the qid-soundness work. See the invariant on
30//! `hyprstream_vfs::Stat`: these are advisory hints, not yet a strong
31//! identity (content-CID qid lands in #387).
32//!
33//! ## Fid management
34//!
35//! The mount allocates local fid numbers and tracks them via the bridge's
36//! `DashMap`. Each local fid maps to a `RemoteFidState` that stores the
37//! resolved `WorktreeClient` (curried with `repo_id` + `worktree_name`), the
38//! remote fid number returned by walk, plus qtype for stat/readdir synthesis.
39//!
40//! ## Timeout / graceful degradation
41//!
42//! A dedicated single-threaded tokio runtime drives the async client. If the
43//! registry service is unreachable, `block_on` will hang until the ZMQ socket
44//! timeout fires (set on the underlying socket). Callers see
45//! `MountError::Io("service unreachable: ...")`.
46
47use async_trait::async_trait;
48use hyprstream_rpc::Subject;
49use hyprstream_vfs::{DirEntry, Fid, Mount, MountError, Stat};
50
51use crate::services::ninep_bridge::{fid_key, map_err, NinePBridge, RemoteFidKey};
52use crate::services::types::QTDIR;
53use hyprstream_rpc_std::policy_client::{PolicyCheck, PolicyClient};
54use hyprstream_rpc_std::registry_client::{
55    NpClunk, NpCreate, NpOpen, NpRead, NpStatReq, NpWalk, NpWrite, RegistryClient, WorktreeClient,
56};
57
58struct HolderGate {
59    subject: Subject,
60    bearer: String,
61    policy: PolicyClient,
62    repo_name: String,
63    repo_id: String,
64    worktree: String,
65}
66
67fn uses_holder_read_rpc(holder: bool, mode: u8) -> bool {
68    holder && mode == 0
69}
70
71fn requested_remote_fid(holder: bool, local_fid: u32) -> u32 {
72    if holder {
73        0
74    } else {
75        local_fid
76    }
77}
78
79// ─────────────────────────────────────────────────────────────────────────────
80// Remote fid state
81// ─────────────────────────────────────────────────────────────────────────────
82
83/// Per-fid state held locally.
84///
85/// `worktree` is the curried `WorktreeClient` (already scoped to a specific
86/// repo + worktree name) so subsequent open/read/write/stat/clunk calls hit
87/// the right worktree without re-resolving the scope on every operation.
88struct RemoteFidState {
89    /// Fid number on the remote side.
90    remote_fid: u32,
91    /// Worktree client scoped to the resolved repo + worktree.
92    worktree: WorktreeClient,
93    /// Qtype from the walk response (QTDIR or QTFILE).
94    qtype: u8,
95    /// Whether open() has been called.
96    opened: bool,
97}
98
99// ─────────────────────────────────────────────────────────────────────────────
100// RemoteRegistryMount
101// ─────────────────────────────────────────────────────────────────────────────
102
103/// A `Mount` implementation that proxies 9P operations to the registry
104/// service's worktree filesystem via the generated `WorktreeClient` RPC.
105///
106/// Path layout under the mount point:
107///   `/{repo_name}/{worktree_name}/<...rest...>`
108///
109/// `repo_name` is resolved to the registry UUID via `get_by_name` on the
110/// first walk; `worktree_name` selects the worktree. The remainder is
111/// forwarded to the worktree's 9P `walk` as `wnames`.
112pub struct RemoteRegistryMount {
113    client: RegistryClient,
114    bridge: NinePBridge<RemoteFidState>,
115    holder: Option<HolderGate>,
116}
117
118impl RemoteRegistryMount {
119    /// Create a new remote registry mount wrapping the given registry client.
120    pub fn new(client: RegistryClient) -> Self {
121        Self {
122            client,
123            bridge: NinePBridge::new("RemoteRegistryMount"),
124            holder: None,
125        }
126    }
127
128    /// Build the one-repository read-only export. The Registry client and
129    /// Policy checks both relay the verified mount ticket on every request.
130    pub fn for_holder(
131        client: RegistryClient,
132        policy: PolicyClient,
133        subject: Subject,
134        bearer: String,
135        export: &crate::config::NinepCanonicalReadConfig,
136    ) -> Self {
137        Self {
138            client: client.with_delegated_bearer(bearer.clone()),
139            bridge: NinePBridge::new("HolderRegistryMount"),
140            holder: Some(HolderGate {
141                subject,
142                bearer,
143                policy,
144                repo_name: export.repo_name.clone(),
145                repo_id: export.repo_id.clone(),
146                worktree: export.worktree.clone(),
147            }),
148        }
149    }
150
151    pub(crate) async fn authorize(&self, caller: &Subject) -> Result<(), MountError> {
152        let Some(gate) = &self.holder else {
153            return Ok(());
154        };
155        if caller != &gate.subject {
156            return Err(MountError::PermissionDenied("9P holder changed".into()));
157        }
158        for resource in [
159            format!("model:{}", gate.repo_name),
160            format!("registry:{}", gate.repo_id),
161        ] {
162            let check = PolicyCheck {
163                subject: caller.to_string(),
164                domain: String::new(),
165                resource,
166                operation: "query".to_owned(),
167            };
168            let allowed = crate::services::policy::check_with_verified_bearer(
169                &gate.policy,
170                &check,
171                Some(&gate.bearer),
172                caller,
173            )
174            .await
175            .map_err(|_| MountError::PermissionDenied("9P holder policy unavailable".into()))?;
176            if !allowed {
177                return Err(MountError::PermissionDenied(
178                    "9P holder has no repository query grant".into(),
179                ));
180            }
181        }
182        Ok(())
183    }
184
185    /// Resolve `repo_name` to a `WorktreeClient` scoped to `worktree_name`.
186    ///
187    /// Uses the registry's `get_by_name` to look up the repo UUID, then
188    /// curries `repo(id).worktree(name)` — exactly the chain the worktree
189    /// helpers (`worktree_helpers.rs`) and the CLI git handlers use.
190    async fn resolve_worktree(
191        &self,
192        repo_name: &str,
193        worktree_name: &str,
194    ) -> Result<WorktreeClient, MountError> {
195        // NB: `RegistryClient` has an inherent `clone(&self, &CloneRequest)`
196        // RPC method (it clones a git repo) that shadows `Clone::clone`.
197        // Fully-qualify so we get the cheap Rc clone, not a repo clone RPC.
198        let client = Clone::clone(&self.client);
199        let repo_name = repo_name.to_owned();
200        let worktree_name = worktree_name.to_owned();
201        let tracked = if let Some(gate) = &self.holder {
202            if repo_name != gate.repo_name || worktree_name != gate.worktree {
203                return Err(MountError::PermissionDenied(
204                    "9P repository binding mismatch".into(),
205                ));
206            }
207            // The generated Text-resource gate for Registry.get is
208            // `registry:<UUID>`, the exact holder grant. A name lookup would
209            // instead demand `registry:<name>` and add a second entitlement.
210            let tracked = client.get(&gate.repo_id).await.map_err(map_err)?;
211            if tracked.id != gate.repo_id || tracked.name != gate.repo_name {
212                return Err(MountError::PermissionDenied(
213                    "9P repository binding mismatch".into(),
214                ));
215            }
216            tracked
217        } else {
218            client.get_by_name(&repo_name).await.map_err(map_err)?
219        };
220        let repo = client.repo(&tracked.id);
221        Ok(repo.worktree(&worktree_name))
222    }
223}
224
225#[async_trait]
226impl Mount for RemoteRegistryMount {
227    async fn walk(&self, components: &[&str], caller: &Subject) -> Result<Fid, MountError> {
228        self.authorize(caller).await?;
229        // 2-level scope: first = repo name, second = worktree name, rest = wnames.
230        if components.len() < 2 {
231            return Err(MountError::InvalidArgument(format!(
232                "registry walk needs at least /{{repo}}/{{worktree}}; got {:?}",
233                components
234            )));
235        }
236
237        let repo_name = components[0];
238        let worktree_name = components[1];
239        let wnames: Vec<String> = components[2..]
240            .iter()
241            .map(std::string::ToString::to_string)
242            .collect();
243
244        let worktree = self.resolve_worktree(repo_name, worktree_name).await?;
245
246        let local_fid = self.bridge.alloc_fid();
247        let requested_remote_fid = requested_remote_fid(self.holder.is_some(), local_fid);
248        let walk_req = NpWalk {
249            fid: 0, // root of the worktree
250            // Holder sessions share the Registry process and need a globally
251            // allocated fid. Ordinary mounts keep their prior requested fid.
252            newfid: requested_remote_fid,
253            wnames,
254        };
255
256        let result = worktree.walk(&walk_req).await.map_err(map_err)?;
257        let remote_newfid = result.fid;
258        if remote_newfid == 0 {
259            return Err(MountError::InvalidArgument(
260                "registry returned reserved fid zero".into(),
261            ));
262        }
263
264        // qid.type from the walk response tells us dir vs file.
265        let qtype = result.qid.qtype;
266
267        let state = RemoteFidState {
268            remote_fid: remote_newfid,
269            worktree,
270            qtype,
271            opened: false,
272        };
273        self.bridge.insert(local_fid, state);
274
275        Ok(Fid::new(RemoteFidKey(local_fid)))
276    }
277
278    async fn open(&self, fid: &mut Fid, mode: u8, caller: &Subject) -> Result<(), MountError> {
279        self.authorize(caller).await?;
280        if self.holder.is_some() && mode != 0 {
281            return Err(MountError::PermissionDenied(
282                "9P export is read-only".into(),
283            ));
284        }
285        let local_id = fid_key(fid)?.0;
286
287        let state = self.bridge.get(local_id)?;
288        let remote_fid = state.remote_fid;
289        let worktree = Clone::clone(&state.worktree);
290        drop(state);
291
292        if uses_holder_read_rpc(self.holder.is_some(), mode) {
293            let request = NpStatReq { fid: remote_fid };
294            worktree.open_read(&request).await.map_err(map_err)?;
295        } else {
296            let request = NpOpen {
297                fid: remote_fid,
298                mode,
299            };
300            worktree.open(&request).await.map_err(map_err)?;
301        }
302        self.bridge.get_mut(local_id)?.opened = true;
303
304        Ok(())
305    }
306
307    async fn read(
308        &self,
309        fid: &Fid,
310        offset: u64,
311        count: u32,
312        caller: &Subject,
313    ) -> Result<Vec<u8>, MountError> {
314        self.authorize(caller).await?;
315        let local_id = fid_key(fid)?.0;
316
317        let state = self.bridge.get(local_id)?;
318        let remote_fid = state.remote_fid;
319        let worktree = Clone::clone(&state.worktree);
320        drop(state);
321
322        let read_req = NpRead {
323            fid: remote_fid,
324            offset,
325            count,
326        };
327
328        let result = worktree.read(&read_req).await.map_err(map_err)?;
329        Ok(result.data)
330    }
331
332    async fn write(
333        &self,
334        fid: &Fid,
335        offset: u64,
336        data: &[u8],
337        caller: &Subject,
338    ) -> Result<u32, MountError> {
339        self.authorize(caller).await?;
340        if self.holder.is_some() {
341            return Err(MountError::PermissionDenied(
342                "9P export is read-only".into(),
343            ));
344        }
345        let local_id = fid_key(fid)?.0;
346
347        let state = self.bridge.get(local_id)?;
348        let remote_fid = state.remote_fid;
349        let worktree = Clone::clone(&state.worktree);
350        drop(state);
351
352        let write_req = NpWrite {
353            fid: remote_fid,
354            offset,
355            data: data.to_vec(),
356        };
357
358        let result = worktree.write(&write_req).await.map_err(map_err)?;
359        Ok(result.count)
360    }
361
362    /// Create a file/dir under a walked *directory* fid, then open it.
363    ///
364    /// This is the writable-layer primitive that powers the union's copy-up
365    /// (#394). The registry service's `handle_create` consumes the directory
366    /// fid and replaces it with an opened fid on the new file, so on success we
367    /// flip `opened = true` locally and thread the new file's qid back as the
368    /// returned `Stat` (the union's copy-up caller uses it for logging only —
369    /// it does not key authz on it; see the qid-soundness invariant on
370    /// `hyprstream_vfs::Stat`).
371    async fn create(
372        &self,
373        fid: &mut Fid,
374        name: &str,
375        perm: u32,
376        mode: u8,
377        caller: &Subject,
378    ) -> Result<Stat, MountError> {
379        self.authorize(caller).await?;
380        if self.holder.is_some() {
381            return Err(MountError::PermissionDenied(
382                "9P export is read-only".into(),
383            ));
384        }
385        let local_id = fid_key(fid)?.0;
386
387        let state = self.bridge.get(local_id)?;
388        let remote_fid = state.remote_fid;
389        let worktree = Clone::clone(&state.worktree);
390        drop(state);
391
392        let create_req = NpCreate {
393            fid: remote_fid,
394            name: name.to_owned(),
395            perm,
396            mode,
397        };
398
399        let result = worktree.create(&create_req).await.map_err(map_err)?;
400
401        // The directory fid has been replaced on the server with the opened new
402        // file. Mirror that transition locally so subsequent read/write/stat hit
403        // the new file rather than a stale directory handle.
404        let mut state = self.bridge.get_mut(local_id)?;
405        state.qtype = result.qid.qtype;
406        state.opened = true;
407
408        Ok(Stat {
409            qtype: result.qid.qtype,
410            // Advisory identity hint only — see the qid-soundness invariant on
411            // `hyprstream_vfs::Stat`. Content-CID qid lands in #387.
412            version: result.qid.version,
413            path: result.qid.path,
414            size: 0,
415            name: name.to_owned(),
416            mtime: 0,
417        })
418    }
419
420    async fn readdir(&self, fid: &Fid, caller: &Subject) -> Result<Vec<DirEntry>, MountError> {
421        self.authorize(caller).await?;
422        // The registry worktree service encodes directory listings in its
423        // read() response using the per-entry format documented in
424        // `WorktreeRequest.read`:
425        //   name_len(u32) + name(utf8) + is_dir(u8) + size(u64)
426        // (See `WorktreeClient::list_dir_path` in worktree_helpers.rs.)
427        let local_id = fid_key(fid)?.0;
428
429        let state = self.bridge.get(local_id)?;
430        let remote_fid = state.remote_fid;
431        let worktree = Clone::clone(&state.worktree);
432        let qtype = state.qtype;
433        drop(state);
434
435        if qtype != QTDIR {
436            return Err(MountError::NotDirectory(format!(
437                "fid {} is not a directory",
438                local_id
439            )));
440        }
441
442        // Read directory data from the worktree service.
443        let read_req = NpRead {
444            fid: remote_fid,
445            offset: 0,
446            count: 65536, // Large enough for most directory listings.
447        };
448
449        let result = worktree.read(&read_req).await.map_err(map_err)?;
450
451        Ok(parse_worktree_dir_entries(&result.data))
452    }
453
454    async fn stat(&self, fid: &Fid, caller: &Subject) -> Result<Stat, MountError> {
455        self.authorize(caller).await?;
456        let local_id = fid_key(fid)?.0;
457
458        let state = self.bridge.get(local_id)?;
459        let remote_fid = state.remote_fid;
460        let worktree = Clone::clone(&state.worktree);
461        drop(state);
462
463        let stat_req = NpStatReq { fid: remote_fid };
464
465        let result = worktree.np_stat(&stat_req).await.map_err(map_err)?;
466
467        // Convert the RPC RStat → VFS Stat, threading the wire qid
468        // version/path through. The registry service populates these from
469        // filesystem metadata (qid_from_metadata: version=ctime, path=ino),
470        // so this is a real qid, not a flattened one.
471        let np_stat = &result.stat;
472
473        Ok(Stat {
474            qtype: np_stat.qid.qtype,
475            // Thread the wire qid version/path through instead of discarding
476            // them — that's the whole point of #388's widening. These are
477            // advisory identity hints only; see the qid-soundness invariant
478            // on `hyprstream_vfs::Stat`. Content-CID qid lands in #387.
479            version: np_stat.qid.version,
480            path: np_stat.qid.path,
481            size: np_stat.length,
482            name: np_stat.name.clone(),
483            mtime: np_stat.mtime as u64,
484        })
485    }
486
487    async fn clunk(&self, fid: Fid, _caller: &Subject) {
488        let local_id = match fid_key(&fid) {
489            Ok(k) => k.0,
490            Err(_) => return,
491        };
492
493        if let Some(state) = self.bridge.remove(local_id) {
494            let clunk_req = NpClunk {
495                fid: state.remote_fid,
496            };
497
498            // Best-effort clunk — ignore errors.
499            let _ = state.worktree.clunk(&clunk_req).await;
500        }
501    }
502}
503
504// ─────────────────────────────────────────────────────────────────────────────
505// Directory entry parsing
506// ─────────────────────────────────────────────────────────────────────────────
507
508/// Parse directory entries from a registry worktree `read()` response.
509///
510/// The worktree service encodes directory entries in the documented per-entry
511/// format (see `WorktreeRequest.read` annotation in `registry.capnp`):
512///   `name_len(u32 LE) + name(utf8) + is_dir(u8) + size(u64 LE)`
513///
514/// This mirrors the parse loop in `WorktreeClient::list_dir_path`.
515///
516/// (The model service uses a different format — packed 9P stats — which is
517/// shared in [`crate::services::ninep_bridge::parse_dir_stats`].)
518fn parse_worktree_dir_entries(data: &[u8]) -> Vec<DirEntry> {
519    let mut entries = Vec::new();
520    let mut cursor = 0;
521
522    while cursor + 4 <= data.len() {
523        let name_len =
524            u32::from_le_bytes(data[cursor..cursor + 4].try_into().unwrap_or([0; 4])) as usize;
525        cursor += 4;
526        if cursor + name_len > data.len() {
527            break;
528        }
529        let name = String::from_utf8_lossy(&data[cursor..cursor + name_len]).to_string();
530        cursor += name_len;
531        if cursor + 9 > data.len() {
532            break;
533        }
534        let is_dir = data[cursor] != 0;
535        cursor += 1;
536        let size = u64::from_le_bytes(data[cursor..cursor + 8].try_into().unwrap_or([0; 8]));
537        cursor += 8;
538
539        entries.push(DirEntry {
540            name: name.clone(),
541            is_dir,
542            size,
543            // Qid is unknown for dir entries read in bulk — the worktree
544            // service's per-entry format carries only name/is_dir/size.
545            // Callers needing a real qid can stat the child explicitly.
546            stat: None,
547        });
548    }
549
550    entries
551}
552
553#[cfg(test)]
554mod tests {
555    use super::*;
556
557    #[test]
558    fn ordinary_read_open_keeps_legacy_write_scoped_leaf() {
559        assert!(!uses_holder_read_rpc(false, 0));
560        assert!(!uses_holder_read_rpc(false, 1));
561        assert!(uses_holder_read_rpc(true, 0));
562        assert!(!uses_holder_read_rpc(true, 1));
563    }
564
565    #[test]
566    fn ordinary_walk_keeps_its_requested_remote_fid() {
567        assert_eq!(requested_remote_fid(false, 7), 7);
568        assert_eq!(requested_remote_fid(true, 7), 0);
569    }
570
571    #[test]
572    fn parse_empty_worktree_dir() {
573        assert!(parse_worktree_dir_entries(&[]).is_empty());
574    }
575
576    #[test]
577    fn parse_truncated_worktree_dir() {
578        // name_len says 100 bytes but only 2 available — must not panic.
579        let data = [100, 0, 0, 0, 0, 0];
580        assert!(parse_worktree_dir_entries(&data).is_empty());
581    }
582
583    /// Build one worktree-format dir entry (name_len + name + is_dir + size)
584    /// and verify it decodes. This is the format produced by
585    /// `WorktreeClient::list_dir_path` per the registry.capnp annotation.
586    #[test]
587    fn parse_worktree_dir_decodes_entry() {
588        let name = b"README.md";
589        let is_dir: u8 = 0;
590        let size: u64 = 1234;
591
592        let mut data = Vec::new();
593        data.extend_from_slice(&(name.len() as u32).to_le_bytes());
594        data.extend_from_slice(name);
595        data.push(is_dir);
596        data.extend_from_slice(&size.to_le_bytes());
597
598        let entries = parse_worktree_dir_entries(&data);
599        assert_eq!(entries.len(), 1);
600        assert_eq!(entries[0].name, "README.md");
601        assert!(!entries[0].is_dir);
602        assert_eq!(entries[0].size, size);
603        assert!(entries[0].stat.is_none());
604    }
605
606    #[test]
607    fn parse_worktree_dir_decodes_directory_entry() {
608        let name = b"src";
609        let is_dir: u8 = 1;
610        let size: u64 = 0;
611
612        let mut data = Vec::new();
613        data.extend_from_slice(&(name.len() as u32).to_le_bytes());
614        data.extend_from_slice(name);
615        data.push(is_dir);
616        data.extend_from_slice(&size.to_le_bytes());
617
618        let entries = parse_worktree_dir_entries(&data);
619        assert_eq!(entries.len(), 1);
620        assert_eq!(entries[0].name, "src");
621        assert!(entries[0].is_dir);
622    }
623
624    #[test]
625    fn parse_worktree_dir_decodes_multiple_entries() {
626        let mut data = Vec::new();
627
628        // Entry 1: "src" directory.
629        data.extend_from_slice(&(3u32).to_le_bytes());
630        data.extend_from_slice(b"src");
631        data.push(1);
632        data.extend_from_slice(&0u64.to_le_bytes());
633
634        // Entry 2: "README.md" file.
635        data.extend_from_slice(&(9u32).to_le_bytes());
636        data.extend_from_slice(b"README.md");
637        data.push(0);
638        data.extend_from_slice(&4096u64.to_le_bytes());
639
640        let entries = parse_worktree_dir_entries(&data);
641        assert_eq!(entries.len(), 2);
642        assert_eq!(entries[0].name, "src");
643        assert!(entries[0].is_dir);
644        assert_eq!(entries[1].name, "README.md");
645        assert!(!entries[1].is_dir);
646        assert_eq!(entries[1].size, 4096);
647    }
648}