From 5376a5698f03364827fb8c49afabdf784ffc9c91 Mon Sep 17 00:00:00 2001 From: Aaron Ogle Date: Fri, 16 Oct 2026 15:50:52 -0500 Subject: [PATCH 1/2] feat(sandbox): materialize a view prefix over RPC MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit MaterializeRequest.path_prefix (add-only, field 5): stream only the entries at or under one path, plus the plain directories that lead there. The terminal skeleton's live rows follow the same filter, so a sandbox cache rebuilt from the summary is prefix-coherent with what was streamed. Server-side the prefix is validated like any materialized path — plain relative components only (no "..", no ".", no root, no reserved bookkeeping names), normalized to component form before use; an invalid prefix refuses the whole request rather than truncating it. The CLI gains the flag: `atomic sandbox materialize --prefix `. Unset or empty materializes the whole view, as before. Why: a monorepo-scale view is more than a sandbox needs. With an RPC layer serving the sandbox data ops, a remote working copy can check out just the folder it works on (one service in a services/* tree), edit, and SubmitChange back — without ever holding the rest of the tree or the repository database. --- atomic-cli/src/commands/sandbox.rs | 9 +- atomic-cli/src/remote_sandbox.rs | 4 +- .../services/sandbox/sandbox_messages.proto | 7 ++ libatomic/src/daemon/services_sandbox.rs | 51 ++++++++- libatomic/tests/sandbox_service_test.rs | 100 ++++++++++++++++++ 5 files changed, 167 insertions(+), 4 deletions(-) diff --git a/atomic-cli/src/commands/sandbox.rs b/atomic-cli/src/commands/sandbox.rs index a2981de0..bb997395 100644 --- a/atomic-cli/src/commands/sandbox.rs +++ b/atomic-cli/src/commands/sandbox.rs @@ -460,7 +460,12 @@ impl Command for Close { /// Inside a remote sandbox: write its view's tree and make its cache. #[derive(Parser, Debug)] -pub struct Materialize {} +pub struct Materialize { + /// Materialize only entries at or under this path (a monorepo folder), + /// plus the directories that lead to it. Default: the whole view. + #[arg(long, value_name = "PATH")] + pub prefix: Option, +} impl Command for Materialize { fn run(&self) -> CliResult<()> { @@ -472,7 +477,7 @@ impl Command for Materialize { .to_string(), }); }; - let (entries, view) = crate::remote_sandbox::materialize(&root)?; + let (entries, view) = crate::remote_sandbox::materialize(&root, self.prefix.as_deref())?; println!( "Materialized {entries} entries of view '{view}' into {}", root.display() diff --git a/atomic-cli/src/remote_sandbox.rs b/atomic-cli/src/remote_sandbox.rs index ddeb85d0..ca172993 100644 --- a/atomic-cli/src/remote_sandbox.rs +++ b/atomic-cli/src/remote_sandbox.rs @@ -339,7 +339,7 @@ pub fn install_link() { /// Every entry goes through the kernel's path-checked writer (no climbing /// out, no writing the pointer or the cache). A fresh cache also clears a /// sandbox that had fallen behind. -pub fn materialize(root: &Path) -> CliResult<(u64, String)> { +pub fn materialize(root: &Path, prefix: Option<&str>) -> CliResult<(u64, String)> { use tokio_stream::StreamExt; let internal = |e: String| CliError::Internal(anyhow::anyhow!(e)); @@ -350,6 +350,7 @@ pub fn materialize(root: &Path) -> CliResult<(u64, String)> { )) })?; let root_for_thread = root.to_path_buf(); + let prefix = prefix.map(|p| p.to_string()); let (entries, skeleton) = std::thread::spawn(move || { let rt = tokio::runtime::Builder::new_current_thread() .enable_all() @@ -362,6 +363,7 @@ pub fn materialize(root: &Path) -> CliResult<(u64, String)> { .materialize(pb::MaterializeRequest { repository: Some(repository), target: Some(target(&pointer)), + path_prefix: prefix, }) .await .map_err(refused)? diff --git a/libatomic/proto/atomic/services/sandbox/sandbox_messages.proto b/libatomic/proto/atomic/services/sandbox/sandbox_messages.proto index 5fb573ef..92b93b94 100644 --- a/libatomic/proto/atomic/services/sandbox/sandbox_messages.proto +++ b/libatomic/proto/atomic/services/sandbox/sandbox_messages.proto @@ -213,6 +213,13 @@ message MaterializeRequest { RepositoryRef repository = 1; reserved 2, 3; // credentials moved to middleware; mutable view names removed optional ViewRef target = 4; // sandbox: inferred from grant; others: required + // Partial materialization (a monorepo folder): stream only entries at or + // under this path, plus the ancestor directories that lead to them, and + // filter the terminal skeleton's live rows the same way so the sandbox + // cache is prefix-coherent. Plain relative components only — the same + // path-safety rules as TreeEntry.path (no "..", no ".", no root, no + // empty components); unset or empty materializes the whole view. + optional string path_prefix = 5; } message MaterializeFrame { oneof frame { diff --git a/libatomic/src/daemon/services_sandbox.rs b/libatomic/src/daemon/services_sandbox.rs index 6b517632..03375138 100644 --- a/libatomic/src/daemon/services_sandbox.rs +++ b/libatomic/src/daemon/services_sandbox.rs @@ -18,7 +18,7 @@ use std::sync::Arc; use crate::atomic::ErrorCode; use crate::atomic::*; use atomic_core::pristine::ViewTxnT; -use atomic_repository::{Repository, RepositoryError, SealOptions, StageOptions, SubmitRejection}; +use atomic_repository::{Repository, RepositoryError, SealOptions, StageOptions, SubmitRejection, ViewEntryKind}; use tonic::{Request, Response, Status}; use super::convert::{hash_proto, timestamp_proto}; @@ -54,6 +54,42 @@ fn joined(error: tokio::task::JoinError) -> Status { Status::internal(error.to_string()) } +/// Validate a Materialize path prefix: plain relative components only (the +/// same lexical rules as the entries it filters — no `..`, no `.`, no root, +/// no empty components, no reserved bookkeeping names), normalized to +/// `component/component` form. Empty or unset means the whole view. +fn materialize_prefix(path_prefix: Option) -> Result, Status> { + use std::path::{Component, Path}; + let Some(prefix) = path_prefix else { + return Ok(None); + }; + if prefix.is_empty() { + return Ok(None); + } + let refuse = |why: &str| invalid(format!("refusing materialize prefix {prefix:?}: {why}")); + let relative = Path::new(&prefix); + if !relative.is_relative() { + return Err(refuse("not a relative path")); + } + let mut parts = Vec::new(); + for part in relative.components() { + let Component::Normal(name) = part else { + return Err(refuse("not a plain relative path")); + }; + if name == ".atomic" + || name == ".atomic-sandbox" + || name == ".atomic-sandbox.d" + { + return Err(refuse("names the sandbox's own bookkeeping")); + } + parts.push(name.to_string_lossy().into_owned()); + } + if parts.is_empty() { + return Err(refuse("empty path")); + } + Ok(Some(parts.join("/"))) +} + fn invalid(message: impl Into) -> Status { domain_status(ErrorCode::InvalidArgument, message) } @@ -445,6 +481,7 @@ impl sandbox_service_server::SandboxService for SandboxImpl { request.target.as_ref(), "sandbox.read", )?; + let prefix = materialize_prefix(request.path_prefix)?; let gate_handle = handle.clone(); let _gate = gate_handle.exclusive().await; if let Some(caller) = &caller { @@ -461,6 +498,18 @@ impl sandbox_service_server::SandboxService for SandboxImpl { let mut frames = Vec::new(); let mut live = BTreeMap::new(); repo.materialize_view_entries::<()>(&view, |entry| { + // A prefix materializes only its subtree: the entries at or + // under it, plus the plain directories that lead there. The + // live map follows the same filter so the skeleton's rows + // are prefix-coherent with what was streamed. + if let Some(prefix) = &prefix { + let under = entry.path.starts_with(prefix.as_str()); + let ancestor = prefix.starts_with(&entry.path) + && entry.kind == ViewEntryKind::Directory; + if !under && !ancestor { + return Ok(()); + } + } live.insert(entry.inode, entry.path.clone()); frames.push(MaterializeFrame { frame: Some(materialize_frame::Frame::Entry(wire::tree_entry_proto( diff --git a/libatomic/tests/sandbox_service_test.rs b/libatomic/tests/sandbox_service_test.rs index eee8c28b..289f92eb 100644 --- a/libatomic/tests/sandbox_service_test.rs +++ b/libatomic/tests/sandbox_service_test.rs @@ -426,12 +426,24 @@ fn materialize(host: &Host, opened: &SandboxOpened) -> Vm { } fn materialize_into(host: &Host, token: &[u8], root: &Path) -> (u64, SandboxSkeleton) { + materialize_prefix_into(host, token, root, None) +} + +/// Materialize with an optional path prefix, as a sandbox does: every entry +/// through the kernel's path-checked writer, then the cache's skeleton. +fn materialize_prefix_into( + host: &Host, + token: &[u8], + root: &Path, + path_prefix: Option<&str>, +) -> (u64, SandboxSkeleton) { let frames: Vec = host.rt.block_on(async { host.service() .materialize(with_token( MaterializeRequest { repository: Some(host.repository.clone()), target: None, + path_prefix: path_prefix.map(str::to_string), }, token, )) @@ -443,6 +455,7 @@ fn materialize_into(host: &Host, token: &[u8], root: &Path) -> (u64, SandboxSkel .await }); let mut written = 0; + let mut paths = Vec::new(); for frame in frames { match frame.frame.unwrap() { materialize_frame::Frame::Entry(entry) => { @@ -455,6 +468,7 @@ fn materialize_into(host: &Host, token: &[u8], root: &Path) -> (u64, SandboxSkel ) .unwrap(); written += 1; + paths.push(entry.path); } materialize_frame::Frame::Done(done) => { assert_eq!(done.entries, written, "every entry arrived"); @@ -464,6 +478,17 @@ fn materialize_into(host: &Host, token: &[u8], root: &Path) -> (u64, SandboxSkel done.snapshot, "one coherent state" ); + if let Some(prefix) = path_prefix { + // A prefix streams only its subtree plus the directories + // that lead to it — and the skeleton's live rows follow + // the same filter. + for path in &paths { + assert!( + path.starts_with(prefix) || prefix.starts_with(path.as_str()), + "{path:?} escaped the {prefix:?} materialize" + ); + } + } return (written, wire::skeleton_from_proto(&skeleton).unwrap()); } } @@ -723,6 +748,7 @@ fn a_token_reaches_its_view_and_nothing_else() { MaterializeRequest { repository: Some(host.repository.clone()), target, + path_prefix: None, }, token, ))) @@ -755,6 +781,7 @@ fn a_token_reaches_its_view_and_nothing_else() { MaterializeRequest { repository: Some(workspace), target: None, + path_prefix: None, }, &opened.token, ))), @@ -832,6 +859,7 @@ fn a_token_reaches_its_view_and_nothing_else() { let mut request = Request::new(MaterializeRequest { repository: Some(host.repository.clone()), target: None, + path_prefix: None, }); request.extensions_mut().insert(SandboxGrant { repository_id: elsewhere.repository.repository_id.clone(), @@ -850,6 +878,7 @@ fn a_token_reaches_its_view_and_nothing_else() { let mut request = Request::new(MaterializeRequest { repository: Some(host.repository.clone()), target: None, + path_prefix: None, }); request.extensions_mut().insert(SandboxGrant { repository_id: host.repository.repository_id.clone(), @@ -878,6 +907,7 @@ fn renew_keeps_the_token_close_ends_it_and_reopening_replaces_it() { MaterializeRequest { repository: Some(host.repository.clone()), target: None, + path_prefix: None, }, token, ))) @@ -965,6 +995,7 @@ fn a_view_deleted_and_recreated_does_not_revive_its_grant() { MaterializeRequest { repository: Some(host.repository.clone()), target: None, + path_prefix: None, }, &opened.token, ))), @@ -1075,6 +1106,75 @@ fn a_sandbox_on_the_checked_out_view_lands_in_the_working_copy() { ); } +/// A prefix materializes only its subtree (plus the directories that lead to +/// it), the skeleton's live rows follow the same filter, and a traversal or +/// reserved prefix is refused outright. A monorepo folder in, a monorepo +/// folder out — the sandbox cache stays prefix-coherent. +#[test] +fn a_prefix_materializes_only_its_subtree_and_refuses_traversal() { + let host = host(); + let opened = host.open("dev", ALL); + + // The whole view: README.md and src/lib.rs. + let dir = TempDir::new().unwrap(); + let root = dir.path().join("full"); + std::fs::create_dir_all(&root).unwrap(); + let root = root.canonicalize().unwrap(); + let (full, _) = materialize_prefix_into(&host, &opened.token, &root, None); + assert!(root.join("README.md").is_file()); + assert!(root.join("src/lib.rs").is_file()); + + // Only src: the subtree plus its leading directory — no README. + let dir = TempDir::new().unwrap(); + let root = dir.path().join("src-only"); + std::fs::create_dir_all(&root).unwrap(); + let root = root.canonicalize().unwrap(); + let (src, _) = materialize_prefix_into(&host, &opened.token, &root, Some("src")); + assert!(src < full, "a prefix streams fewer entries than the view"); + assert!(root.join("src/lib.rs").is_file()); + assert!( + !root.join("README.md").exists(), + "a src materialize leaked README.md" + ); + + // A prefix that matches nothing streams only its leading directories. + let dir = TempDir::new().unwrap(); + let root = dir.path().join("empty"); + std::fs::create_dir_all(&root).unwrap(); + let root = root.canonicalize().unwrap(); + let (_, _) = materialize_prefix_into(&host, &opened.token, &root, Some("nowhere")); + + // A deep prefix streams the chain of directories that lead to it. + let dir = TempDir::new().unwrap(); + let root = dir.path().join("deep"); + std::fs::create_dir_all(&root).unwrap(); + let root = root.canonicalize().unwrap(); + materialize_prefix_into(&host, &opened.token, &root, Some("src/deep/nested")); + + // Traversal and reserved prefixes are refused, never truncated. + for bad in ["..", "../elsewhere", "/abs", ".atomic", "a/../b"] { + let dir = TempDir::new().unwrap(); + let root = dir.path().join("bad"); + std::fs::create_dir_all(&root).unwrap(); + let root = root.canonicalize().unwrap(); + let refused = host.rt.block_on( + host.service().materialize(with_token( + MaterializeRequest { + repository: Some(host.repository.clone()), + target: None, + path_prefix: Some(bad.to_string()), + }, + &opened.token, + )), + ); + let code = match refused { + Err(status) => status.code(), + Ok(_) => panic!("{bad:?} must be refused"), + }; + assert_eq!(code, tonic::Code::InvalidArgument, "{bad:?} must be refused"); + } +} + fn reserve( host: &Host, token: Option<&[u8]>, From a3cdefd0ba3f07d53621b2a9b2bdee61d421aebb Mon Sep 17 00:00:00 2001 From: Aaron Ogle Date: Fri, 16 Oct 2026 16:08:17 -0500 Subject: [PATCH 2/2] style: fmt + fix test warnings and wrong-way assertion cargo fmt across the touched files; the refusal loop's destination was unused (assert it stays empty instead); the deep-prefix assertion checked is_file() where it meant !is_file(). --- libatomic/src/daemon/services_sandbox.rs | 13 +++---- libatomic/tests/sandbox_service_test.rs | 48 +++++++++++++++++------- 2 files changed, 41 insertions(+), 20 deletions(-) diff --git a/libatomic/src/daemon/services_sandbox.rs b/libatomic/src/daemon/services_sandbox.rs index 03375138..4888616b 100644 --- a/libatomic/src/daemon/services_sandbox.rs +++ b/libatomic/src/daemon/services_sandbox.rs @@ -18,7 +18,9 @@ use std::sync::Arc; use crate::atomic::ErrorCode; use crate::atomic::*; use atomic_core::pristine::ViewTxnT; -use atomic_repository::{Repository, RepositoryError, SealOptions, StageOptions, SubmitRejection, ViewEntryKind}; +use atomic_repository::{ + Repository, RepositoryError, SealOptions, StageOptions, SubmitRejection, ViewEntryKind, +}; use tonic::{Request, Response, Status}; use super::convert::{hash_proto, timestamp_proto}; @@ -76,10 +78,7 @@ fn materialize_prefix(path_prefix: Option) -> Result, Sta let Component::Normal(name) = part else { return Err(refuse("not a plain relative path")); }; - if name == ".atomic" - || name == ".atomic-sandbox" - || name == ".atomic-sandbox.d" - { + if name == ".atomic" || name == ".atomic-sandbox" || name == ".atomic-sandbox.d" { return Err(refuse("names the sandbox's own bookkeeping")); } parts.push(name.to_string_lossy().into_owned()); @@ -504,8 +503,8 @@ impl sandbox_service_server::SandboxService for SandboxImpl { // are prefix-coherent with what was streamed. if let Some(prefix) = &prefix { let under = entry.path.starts_with(prefix.as_str()); - let ancestor = prefix.starts_with(&entry.path) - && entry.kind == ViewEntryKind::Directory; + let ancestor = + prefix.starts_with(&entry.path) && entry.kind == ViewEntryKind::Directory; if !under && !ancestor { return Ok(()); } diff --git a/libatomic/tests/sandbox_service_test.rs b/libatomic/tests/sandbox_service_test.rs index 289f92eb..18decade 100644 --- a/libatomic/tests/sandbox_service_test.rs +++ b/libatomic/tests/sandbox_service_test.rs @@ -1142,14 +1142,29 @@ fn a_prefix_materializes_only_its_subtree_and_refuses_traversal() { let root = dir.path().join("empty"); std::fs::create_dir_all(&root).unwrap(); let root = root.canonicalize().unwrap(); - let (_, _) = materialize_prefix_into(&host, &opened.token, &root, Some("nowhere")); + let (nowhere, _) = materialize_prefix_into(&host, &opened.token, &root, Some("nowhere")); + assert!( + nowhere < src, + "a matching-nothing prefix streams fewer entries than a matching one" + ); - // A deep prefix streams the chain of directories that lead to it. + // A deep prefix streams only the ancestor entries the VIEW has (the + // leading directories of the chain that exist), not a synthesized + // chain — its missing members cost nothing until a file lands under + // them (the client-side writer creates parents on write). let dir = TempDir::new().unwrap(); let root = dir.path().join("deep"); std::fs::create_dir_all(&root).unwrap(); let root = root.canonicalize().unwrap(); - materialize_prefix_into(&host, &opened.token, &root, Some("src/deep/nested")); + let (deep, _) = materialize_prefix_into(&host, &opened.token, &root, Some("src/deep/nested")); + assert_eq!( + deep, 1, + "a deep prefix streams exactly the view's own leading directories" + ); + assert!( + !root.join("src/lib.rs").is_file(), + "a src/deep/... prefix must stream nothing of src/" + ); // Traversal and reserved prefixes are refused, never truncated. for bad in ["..", "../elsewhere", "/abs", ".atomic", "a/../b"] { @@ -1157,21 +1172,28 @@ fn a_prefix_materializes_only_its_subtree_and_refuses_traversal() { let root = dir.path().join("bad"); std::fs::create_dir_all(&root).unwrap(); let root = root.canonicalize().unwrap(); - let refused = host.rt.block_on( - host.service().materialize(with_token( - MaterializeRequest { - repository: Some(host.repository.clone()), - target: None, - path_prefix: Some(bad.to_string()), - }, - &opened.token, - )), + let refused = host.rt.block_on(host.service().materialize(with_token( + MaterializeRequest { + repository: Some(host.repository.clone()), + target: None, + path_prefix: Some(bad.to_string()), + }, + &opened.token, + ))); + // A refusal writes nothing: the destination stays empty. + assert!( + std::fs::read_dir(&root).unwrap().count() == 0, + "{bad:?} wrote into the destination despite being refused" ); let code = match refused { Err(status) => status.code(), Ok(_) => panic!("{bad:?} must be refused"), }; - assert_eq!(code, tonic::Code::InvalidArgument, "{bad:?} must be refused"); + assert_eq!( + code, + tonic::Code::InvalidArgument, + "{bad:?} must be refused" + ); } }