hyprstream_inference/worktree_ext.rs
1//! 9P convenience helpers for WorktreeClient.
2//!
3//! Provides high-level file operations that implement the walk/open/read-loop/clunk
4//! pattern over the 9P protocol. These replace the old `read_file`/`write_file`/`mkdir`
5//! convenience methods that sent entire files in a single message.
6
7use anyhow::Result;
8use hyprstream_rpc_std::registry_client::WorktreeClient;
9use hyprstream_rpc_std::registry_client::{
10 NpClunk, NpCreate, NpOpen, NpRead, NpRemove, NpStatReq, NpWalk, NpWrite,
11};
12use std::path::Path;
13use std::sync::atomic::{AtomicU32, Ordering};
14
15// 9P open-mode flags (mirrors the daemon-side constants in `services::types`;
16// the wire encoding is fixed by 9P, so these are protocol constants, not
17// shared state).
18const OREAD: u8 = 0;
19const OWRITE: u8 = 1;
20const DMDIR: u32 = 0x80000000;
21
22/// COW-aware file copy (uses reflink when the filesystem supports it, falls
23/// back to a regular copy). Carved out of the main crate's `git::ops` with the
24/// training checkpoint path — its only caller.
25pub fn cow_copy(src: &Path, dst: &Path) -> Result<()> {
26 reflink_copy::reflink_or_copy(src, dst)
27 .map(|_| ())
28 .map_err(|e| anyhow::anyhow!("cow_copy failed: {}", e))
29}
30
31/// Atomic counter for allocating client-side fids.
32static NEXT_CLIENT_FID: AtomicU32 = AtomicU32::new(100);
33
34/// Allocate a client-side fid.
35fn next_fid() -> u32 {
36 NEXT_CLIENT_FID.fetch_add(1, Ordering::Relaxed)
37}
38
39/// Split a path string into 9P wname components.
40fn split_path(path: &str) -> Vec<String> {
41 path.split('/')
42 .filter(|s| !s.is_empty() && *s != ".")
43 .map(std::borrow::ToOwned::to_owned)
44 .collect()
45}
46
47/// Stat result for backward compatibility with callers using the old API.
48pub struct StatResult {
49 pub exists: bool,
50 pub is_dir: bool,
51 pub size: u64,
52 pub modified_at: i64,
53}
54
55/// Directory entry returned by [`WorktreeClientExt::list_dir_path`].
56pub struct DirEntryInfo {
57 pub name: String,
58 pub is_dir: bool,
59 pub size: u64,
60}
61
62/// High-level 9P helpers for the generated Registry worktree client.
63///
64/// The client itself is owned by `hyprstream-rpc-std`; keeping these
65/// implementation-specific convenience operations as an extension trait lets
66/// the AGPL daemon add ergonomics without defining an inherent impl for an
67/// external type. Public here so the main crate (which consumes this crate)
68/// can keep implementing/training flows against it.
69//
70// AFIT is intentional (same style as the generated `*Rpc` traits); the
71// auto-trait-bounds caveat is accepted because every caller drives this over
72// a known-Send client within one runtime.
73#[allow(async_fn_in_trait)]
74pub trait WorktreeClientExt: hyprstream_rpc_std::registry_client::WorktreeRpc {
75 /// Read at most `limit` bytes without transferring the rest of a file.
76 /// Used for checkpoint metadata preflight before tensor allocation.
77 async fn read_file_prefix(&self, path: &str, limit: usize) -> Result<Vec<u8>> {
78 let fid = next_fid();
79 self.walk(&NpWalk {
80 fid: 0,
81 newfid: fid,
82 wnames: split_path(path),
83 })
84 .await?;
85 let result: Result<Vec<u8>> = async {
86 let opened = self.open(&NpOpen { fid, mode: OREAD }).await?;
87 anyhow::ensure!(opened.iounit > 0, "file read returned zero iounit");
88 let mut bytes = Vec::new();
89 while bytes.len() < limit {
90 let count = (limit - bytes.len()).min(opened.iounit as usize) as u32;
91 let response = self
92 .read(&NpRead {
93 fid,
94 offset: bytes.len() as u64,
95 count,
96 })
97 .await?;
98 anyhow::ensure!(
99 response.data.len() <= count as usize,
100 "file read exceeded requested prefix"
101 );
102 if response.data.is_empty() {
103 break;
104 }
105 bytes.extend_from_slice(&response.data);
106 }
107 Ok(bytes)
108 }
109 .await;
110 // Release the walked fid even when open/read/metadata access fails.
111 let closed = self.clunk(&NpClunk { fid }).await;
112 let bytes = result?;
113 closed?;
114 Ok(bytes)
115 }
116
117 /// Read an entire file via walk/open/read-loop/clunk (bounded by iounit per message).
118 ///
119 /// This is the replacement for the old `read_file()` method. Instead of sending
120 /// the entire file in a single Cap'n Proto message (which fails for files >16MB),
121 /// this reads in iounit-sized chunks via the 9P protocol.
122 async fn read_file_chunked(&self, path: &str) -> Result<Vec<u8>> {
123 let fid = next_fid();
124 let wnames = split_path(path);
125
126 // Walk to the file
127 let _walk_resp = self
128 .walk(&NpWalk {
129 fid: 0,
130 newfid: fid,
131 wnames: wnames.clone(),
132 })
133 .await?;
134
135 // Stat to get file size (for pre-allocation)
136 let stat_resp = self.np_stat(&NpStatReq { fid }).await?;
137 let file_size = stat_resp.stat.length;
138
139 // Open for reading
140 let open_resp = self.open(&NpOpen { fid, mode: OREAD }).await?;
141 let iounit = open_resp.iounit;
142
143 // Read loop — bounded by iounit per message
144 let mut buf = Vec::with_capacity(file_size as usize);
145 let mut offset = 0u64;
146 loop {
147 let resp = self
148 .read(&NpRead {
149 fid,
150 offset,
151 count: iounit,
152 })
153 .await?;
154 if resp.data.is_empty() {
155 break; // EOF
156 }
157 offset += resp.data.len() as u64;
158 buf.extend_from_slice(&resp.data);
159 }
160
161 // Clunk the fid
162 self.clunk(&NpClunk { fid }).await?;
163
164 Ok(buf)
165 }
166
167 /// Write an entire file via walk-parent/create/write-loop/clunk.
168 ///
169 /// This is the replacement for the old `write_file()` method.
170 async fn write_file_chunked(&self, path: &str, data: &[u8]) -> Result<()> {
171 let components = split_path(path);
172 let (parent_components, file_name) = if components.len() > 1 {
173 (
174 &components[..components.len() - 1],
175 &components[components.len() - 1],
176 )
177 } else if components.len() == 1 {
178 // File is in the root directory
179 (&components[..0], &components[0])
180 } else {
181 anyhow::bail!("empty path");
182 };
183
184 let fid = next_fid();
185
186 // Walk to the parent directory
187 let parent_wnames: Vec<String> = parent_components.to_vec();
188 if parent_wnames.is_empty() {
189 // Root directory — walk with empty wnames
190 self.walk(&NpWalk {
191 fid: 0,
192 newfid: fid,
193 wnames: vec![],
194 })
195 .await?;
196 } else {
197 self.walk(&NpWalk {
198 fid: 0,
199 newfid: fid,
200 wnames: parent_wnames.clone(),
201 })
202 .await?;
203 }
204
205 // Create the file (opens it for writing)
206 let create_resp = self
207 .create(&NpCreate {
208 fid,
209 name: file_name.clone(),
210 perm: 0o644,
211 mode: OWRITE,
212 })
213 .await?;
214 let iounit = create_resp.iounit;
215
216 // Write in iounit-sized chunks
217 let mut offset = 0u64;
218 while offset < data.len() as u64 {
219 let end = std::cmp::min(offset + iounit as u64, data.len() as u64);
220 let chunk = &data[offset as usize..end as usize];
221 let write_resp = self
222 .write(&NpWrite {
223 fid,
224 offset,
225 data: chunk.to_vec(),
226 })
227 .await?;
228 offset += write_resp.count as u64;
229 }
230
231 // Clunk the fid
232 self.clunk(&NpClunk { fid }).await?;
233
234 Ok(())
235 }
236
237 /// Create a directory (and parents if needed), like `mkdir -p`.
238 ///
239 /// This replaces the old `mkdir(path, recursive)` method.
240 async fn mkdir_p(&self, path: &str) -> Result<()> {
241 let components = split_path(path);
242 if components.is_empty() {
243 return Ok(());
244 }
245
246 // Walk + create each component
247 let mut current_fid = next_fid();
248 // Start at root
249 self.walk(&NpWalk {
250 fid: 0,
251 newfid: current_fid,
252 wnames: vec![],
253 })
254 .await?;
255
256 for component in &components {
257 let child_fid = next_fid();
258 // Try to walk to the component first (it may already exist)
259 match self
260 .walk(&NpWalk {
261 fid: current_fid,
262 newfid: child_fid,
263 wnames: vec![component.clone()],
264 })
265 .await
266 {
267 Ok(_) => {
268 // Directory exists, clunk the old fid and continue
269 self.clunk(&NpClunk { fid: current_fid }).await?;
270 current_fid = child_fid;
271 }
272 Err(_) => {
273 // Directory doesn't exist — create it
274 self.create(&NpCreate {
275 fid: current_fid,
276 name: component.clone(),
277 perm: DMDIR | 0o755,
278 mode: OREAD,
279 })
280 .await?;
281 // After create, the fid now points to the new directory
282 // current_fid is mutated by the server (fid now = new dir)
283 }
284 }
285 }
286
287 self.clunk(&NpClunk { fid: current_fid }).await?;
288 Ok(())
289 }
290
291 /// Stat a file by path. Returns a StatResult for backward compatibility.
292 ///
293 /// This replaces the old `stat(path)` method.
294 async fn stat_path(&self, path: &str) -> Result<StatResult> {
295 let fid = next_fid();
296 let wnames = split_path(path);
297
298 // Try to walk to the path
299 match self
300 .walk(&NpWalk {
301 fid: 0,
302 newfid: fid,
303 wnames: wnames.clone(),
304 })
305 .await
306 {
307 Ok(_) => {
308 let stat_resp = self.np_stat(&NpStatReq { fid }).await?;
309 self.clunk(&NpClunk { fid }).await?;
310
311 let is_dir = (stat_resp.stat.qid.qtype & 0x80) != 0;
312 let modified_at = stat_resp.stat.mtime as i64;
313 Ok(StatResult {
314 exists: true,
315 is_dir,
316 size: stat_resp.stat.length,
317 modified_at,
318 })
319 }
320 Err(_) => {
321 // Path doesn't exist
322 Ok(StatResult {
323 exists: false,
324 is_dir: false,
325 size: 0,
326 modified_at: 0,
327 })
328 }
329 }
330 }
331
332 /// Remove a file by path via walk/remove.
333 ///
334 /// This replaces the old `remove(path)` method.
335 async fn remove_path(&self, path: &str) -> Result<()> {
336 let fid = next_fid();
337 let wnames = split_path(path);
338
339 self.walk(&NpWalk {
340 fid: 0,
341 newfid: fid,
342 wnames: wnames.clone(),
343 })
344 .await?;
345 self.remove(&NpRemove { fid }).await?;
346
347 Ok(())
348 }
349
350 /// Copy a file by path via read + write.
351 ///
352 /// This replaces the old `copy(src, dst)` method. Since 9P has no copy op,
353 /// this reads the source file and writes it to the destination.
354 async fn copy_path(&self, src: &str, dst: &str) -> Result<()> {
355 let data = self.read_file_chunked(src).await?;
356 self.write_file_chunked(dst, &data).await
357 }
358
359 /// List directory entries by path.
360 ///
361 /// This replaces the old `list_dir(path)` method. Returns directory entries
362 /// by walking to the directory, opening it, and reading the dir entries.
363 /// For now, implemented via walk + stat on the directory.
364 async fn list_dir_path(&self, path: &str) -> Result<Vec<DirEntryInfo>> {
365 // Walk to the directory and open it for reading
366 let fid = next_fid();
367 let wnames = split_path(path);
368
369 self.walk(&NpWalk {
370 fid: 0,
371 newfid: fid,
372 wnames: wnames.clone(),
373 })
374 .await?;
375 let open_resp = self.open(&NpOpen { fid, mode: OREAD }).await?;
376 let iounit = open_resp.iounit;
377
378 // Read directory entries (9P encodes them as serialized stat entries)
379 // For simplicity in this initial implementation, we read the raw data
380 // and parse it. The server encodes FsDirEntryInfo in the read response.
381 let mut entries = Vec::new();
382 let mut offset = 0u64;
383 loop {
384 let resp = self
385 .read(&NpRead {
386 fid,
387 offset,
388 count: iounit,
389 })
390 .await?;
391 if resp.data.is_empty() {
392 break;
393 }
394 // Parse directory entries from the response data
395 // Each entry is: name_len(u32) + name(utf8) + is_dir(u8) + size(u64)
396 let mut cursor = 0;
397 while cursor + 4 <= resp.data.len() {
398 let name_len =
399 u32::from_le_bytes(resp.data[cursor..cursor + 4].try_into().unwrap_or([0; 4]))
400 as usize;
401 cursor += 4;
402 if cursor + name_len > resp.data.len() {
403 break;
404 }
405 let name =
406 String::from_utf8_lossy(&resp.data[cursor..cursor + name_len]).to_string();
407 cursor += name_len;
408 if cursor + 9 > resp.data.len() {
409 break;
410 }
411 let is_dir = resp.data[cursor] != 0;
412 cursor += 1;
413 let size =
414 u64::from_le_bytes(resp.data[cursor..cursor + 8].try_into().unwrap_or([0; 8]));
415 cursor += 8;
416 entries.push(DirEntryInfo { name, is_dir, size });
417 }
418 offset += resp.data.len() as u64;
419 }
420
421 self.clunk(&NpClunk { fid }).await?;
422 Ok(entries)
423 }
424}
425
426impl WorktreeClientExt for WorktreeClient {}