Skip to content

A treemap for finding and removing what fills your disk, for Omarchy. Rust + GPUI.

Rust

ssh: discover remote mount roots without starting a scan

Tobi Lutke1e17fcc86ba0
diff --git a/README.md b/README.md
index bfe21a9..02526bb 100644
--- a/README.md
+++ b/README.md
@@ -202,6 +202,12 @@ terminal, it can ask for a password or key passphrase there; GUI launches
need key/agent access or a working SSH askpass helper. Connect once with
`ssh dev` to verify access and accept its host key.
+The protocol also supports lightweight root discovery, separate from a scan:
+it reads the target's mount namespace without walking or probing the listed
+paths. Same-device mounts remain distinct choices; capacity is unknown
+until a root is explicitly selected. Discovery requests omit scan fields,
+so outdated helpers reject them instead of silently scanning their home.
+
The Linux/macOS helper streams a depth-first walk directly to stdout. It
never constructs a tree or retains a directory's children: memory scales
with open ancestors (at most 256), not file count. Only pending hardlink
diff --git a/crates/disktree-core/src/remote.rs b/crates/disktree-core/src/remote.rs
index ebe3d30..5608b77 100644
--- a/crates/disktree-core/src/remote.rs
+++ b/crates/disktree-core/src/remote.rs
@@ -42,12 +42,45 @@ pub struct Request {
// Old helpers ignore this extra field. Old clients may still half-close
// stdin; only clients opting in promise to keep it open during the scan.
-#[derive(Serialize, Deserialize)]
-struct SessionRequest {
+#[derive(Debug, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum Operation {
+ // No scan fields: legacy helpers reject discovery before any traversal,
+ // instead of silently ignoring an unfamiliar operation and scanning ~.
+ Discover { discover_version: u32 },
+ Scan(Request),
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct SessionRequest {
#[serde(flatten)]
- request: Request,
+ pub operation: Operation,
#[serde(default)]
- watch_disconnect: bool,
+ pub watch_disconnect: bool,
+}
+
+/// The target's root candidates, without walking or probing any of them.
+#[derive(Debug, Serialize, Deserialize)]
+pub struct Roots {
+ version: u32,
+ pub home: Option<PathBuf>,
+ pub platform: String,
+ pub identity: Option<crate::identity::HostIdentity>,
+ pub volumes: Vec<crate::space::Volume>,
+}
+
+pub fn read_roots(input: &mut impl BufRead) -> io::Result<Roots> {
+ let roots: Roots = receive(input)?;
+ if roots.version != VERSION
+ || roots
+ .volumes
+ .iter()
+ .any(|volume| !volume.point.is_absolute())
+ || roots.home.as_ref().is_some_and(|home| !home.is_absolute())
+ {
+ return Err(io::Error::other("incompatible remote root discovery"));
+ }
+ Ok(roots)
}
#[derive(Debug, Serialize, Deserialize)]
@@ -117,17 +150,42 @@ fn receive<T: serde::de::DeserializeOwned>(
serde_json::from_str(&line).map_err(json_error)
}
-/// The helper has exactly one operation: scan. It never removes files,
-/// installs software, invokes sudo, or executes a command from the client.
+/// Only read-only discovery and scans: no command execution or removal.
pub fn serve(input: &mut impl BufRead, out: &mut impl Write) -> io::Result<()> {
- let (request, _) = read_request(input)?;
- serve_request(request, out)
+ serve_session(read_request(input)?, out)
}
/// Read one bounded request, including the opt-in connection lifetime.
-pub fn read_request(input: &mut impl BufRead) -> io::Result<(Request, bool)> {
- let session: SessionRequest = receive(input)?;
- Ok((session.request, session.watch_disconnect))
+pub fn read_request(input: &mut impl BufRead) -> io::Result<SessionRequest> {
+ receive(input)
+}
+
+/// Dispatch without resolving any scan path until a scan was requested.
+pub fn serve_session(
+ session: SessionRequest,
+ out: &mut impl Write,
+) -> io::Result<()> {
+ match session.operation {
+ Operation::Scan(request) => serve_request(request, out),
+ Operation::Discover { discover_version } => {
+ if discover_version != VERSION {
+ return Err(io::Error::other(
+ "unsupported root discovery version",
+ ));
+ }
+ send(
+ out,
+ &Roots {
+ version: VERSION,
+ home: std::env::home_dir(),
+ platform: std::env::consts::OS.into(),
+ identity: crate::identity::HostIdentity::current(),
+ volumes: crate::space::volume_roots()?,
+ },
+ )?;
+ out.flush()
+ }
+ }
}
/// Scan a decoded request. The standalone helper supervises its lifetime.
@@ -322,34 +380,44 @@ fn ssh_error(host: &str, details: &str, fallback: &io::Error) -> io::Error {
/// The helper monitors stdin for EOF even before it has a tree to write;
/// keep the request pipe open until the entire snapshot has arrived.
#[derive(Debug)]
-pub struct RemoteScan {
+pub struct RemoteJob<T> {
child: Arc<Mutex<Child>>,
- result: mpsc::Receiver<io::Result<Snapshot>>,
+ result: mpsc::Receiver<io::Result<T>>,
+}
+
+pub type RemoteScan = RemoteJob<Snapshot>;
+pub type RemoteRoots = RemoteJob<Roots>;
+
+fn ssh_command(
+ host: &str,
+) -> io::Result<(Command, Option<crate::payload::Archive>)> {
+ validate_host(host)?;
+ let archive = crate::payload::Archive::current()?;
+ let remote = if archive.is_some() {
+ crate::deployment::COMMAND
+ } else {
+ REMOTE_COMMAND
+ };
+ let mut command = Command::new("ssh");
+ command.args([
+ "-T",
+ "-C",
+ "-o",
+ "ConnectTimeout=15",
+ "-o",
+ "ServerAliveInterval=15",
+ "-o",
+ "ServerAliveCountMax=2",
+ "--",
+ host,
+ remote,
+ ]);
+ Ok((command, archive))
}
impl RemoteScan {
pub fn spawn(host: &str, request: &Request) -> io::Result<Self> {
- validate_host(host)?;
- let archive = crate::payload::Archive::current()?;
- let remote = if archive.is_some() {
- crate::deployment::COMMAND
- } else {
- REMOTE_COMMAND
- };
- let mut command = Command::new("ssh");
- command.args([
- "-T",
- "-C",
- "-o",
- "ConnectTimeout=15",
- "-o",
- "ServerAliveInterval=15",
- "-o",
- "ServerAliveCountMax=2",
- "--",
- host,
- remote,
- ]);
+ let (command, archive) = ssh_command(host)?;
Self::spawn_with_archive(command, host, request, archive)
}
@@ -363,10 +431,54 @@ impl RemoteScan {
}
fn spawn_with_archive(
- mut command: Command,
+ command: Command,
host: &str,
request: &Request,
archive: Option<crate::payload::Archive>,
+ ) -> io::Result<Self> {
+ let metric = request.options.metric;
+ Self::start(
+ command,
+ host,
+ Operation::Scan(request.clone()),
+ archive,
+ move |input| {
+ let mut snapshot = read_snapshot(input)?;
+ if metric != crate::tree::Metric::Bytes {
+ aggregate(&mut snapshot.tree, metric);
+ }
+ Ok(snapshot)
+ },
+ )
+ }
+}
+
+impl RemoteRoots {
+ pub fn discover(host: &str) -> io::Result<Self> {
+ let (command, archive) = ssh_command(host)?;
+ Self::start(
+ command,
+ host,
+ Operation::Discover {
+ discover_version: VERSION,
+ },
+ archive,
+ read_roots,
+ )
+ }
+}
+
+impl<T: Send + 'static> RemoteJob<T> {
+ fn start(
+ mut command: Command,
+ host: &str,
+ operation: Operation,
+ archive: Option<crate::payload::Archive>,
+ decode: impl FnOnce(
+ &mut BufReader<std::process::ChildStdout>,
+ ) -> io::Result<T>
+ + Send
+ + 'static,
) -> io::Result<Self> {
let mut child = command
.stdin(Stdio::piped())
@@ -374,20 +486,17 @@ impl RemoteScan {
.stderr(Stdio::piped())
.spawn()?;
let stderr = child.stderr.take().expect("piped stderr");
- // Drain concurrently: a noisy login script must not fill SSH's stderr
- // pipe and deadlock a scan. Retain only a bounded tail for the window.
+ // Drain concurrently so noisy login scripts cannot block discovery.
let diagnostics = std::thread::spawn(move || read_diagnostics(stderr));
let mut stdin = child.stdin.take().expect("piped stdin");
- let request = request.clone();
let stdout = child.stdout.take().expect("piped stdout");
let child = Arc::new(Mutex::new(child));
let worker = child.clone();
- let metric = request.options.metric;
let host = host.to_owned();
let (tx, result) = mpsc::channel();
std::thread::spawn(move || {
let mut input = BufReader::new(stdout);
- let snapshot = (|| {
+ let response = (|| {
if let Some(archive) = archive {
crate::deployment::deploy(
&archive, &mut input, &mut stdin,
@@ -396,28 +505,31 @@ impl RemoteScan {
send(
&mut stdin,
&SessionRequest {
- request,
+ operation,
watch_disconnect: true,
},
)?;
- read_snapshot(&mut input)
- })()
- .map(|mut snapshot| {
- if metric != crate::tree::Metric::Bytes {
- aggregate(&mut snapshot.tree, metric);
- }
- snapshot
- });
+ decode(&mut input)
+ })();
drop(stdin);
- let mut process = worker.lock().expect("SSH process lock");
- if snapshot.is_err() {
- let _ = process.kill();
+ if response.is_err() {
+ let _ = worker.lock().expect("SSH process lock").kill();
}
- let status = process.wait();
- drop(process);
+ // Never hold the process lock across wait(): cancellation must
+ // be able to acquire it even after a response was read.
+ let status = loop {
+ let status =
+ worker.lock().expect("SSH process lock").try_wait();
+ match status {
+ Ok(Some(status)) => break Ok(status),
+ Ok(None) => {}
+ Err(error) => break Err(error),
+ }
+ std::thread::park_timeout(std::time::Duration::from_millis(10));
+ };
let details = diagnostics.join().unwrap_or_default();
- let outcome = match (snapshot, status) {
- (Ok(snapshot), Ok(status)) if status.success() => Ok(snapshot),
+ let outcome = match (response, status) {
+ (Ok(response), Ok(status)) if status.success() => Ok(response),
(Err(error), _) | (_, Err(error)) => {
Err(ssh_error(&host, &details, &error))
}
@@ -432,12 +544,12 @@ impl RemoteScan {
Ok(Self { child, result })
}
- pub fn poll(&self) -> Option<io::Result<Snapshot>> {
+ pub fn poll(&self) -> Option<io::Result<T>> {
self.result.try_recv().ok()
}
}
-impl Drop for RemoteScan {
+impl<T> Drop for RemoteJob<T> {
fn drop(&mut self) {
if let Ok(mut child) = self.child.lock() {
let _ = child.kill();
@@ -457,14 +569,14 @@ mod tests {
}
}
- fn wait(scan: &RemoteScan) -> io::Result<Snapshot> {
+ fn wait<T: Send + 'static>(scan: &RemoteJob<T>) -> io::Result<T> {
wait_for(scan, std::time::Duration::from_secs(10))
}
- fn wait_for(
- scan: &RemoteScan,
+ fn wait_for<T: Send + 'static>(
+ scan: &RemoteJob<T>,
timeout: std::time::Duration,
- ) -> io::Result<Snapshot> {
+ ) -> io::Result<T> {
let deadline = std::time::Instant::now() + timeout;
loop {
if let Some(result) = scan.poll() {
@@ -521,6 +633,55 @@ mod tests {
}
}
+ #[test]
+ fn discovery_is_not_a_legacy_scan_request() {
+ let session = SessionRequest {
+ operation: Operation::Discover {
+ discover_version: VERSION,
+ },
+ watch_disconnect: true,
+ };
+ let bytes = serde_json::to_vec(&session).unwrap();
+ assert!(serde_json::from_slice::<Request>(&bytes).is_err());
+ let mut input = bytes;
+ input.push(b'\n');
+ let mut output = Vec::new();
+ serve(&mut input.as_slice(), &mut output).unwrap();
+ let roots = read_roots(&mut output.as_slice()).unwrap();
+ assert!(roots.volumes.iter().all(|volume| volume.space.is_none()));
+ assert!(!roots.platform.is_empty());
+ assert!(roots.identity.is_some());
+ }
+
+ #[test]
+ fn discovery_never_resolves_a_scan_path_and_rejects_unknown_versions() {
+ let mut output = Vec::new();
+ // No scan fields: an old helper fails to decode this, rather than
+ // falling back to its default home-directory walk.
+ serve(&mut b"{\"discover_version\":1,\"root\":\"/does-not-exist-disktree-test\"}\n".as_slice(),
+ &mut output).unwrap();
+ assert!(read_roots(&mut output.as_slice()).is_ok());
+ assert!(
+ serve(
+ &mut b"{\"discover_version\":99}\n".as_slice(),
+ &mut Vec::new()
+ )
+ .is_err()
+ );
+ }
+
+ #[test]
+ fn invalid_discovery_records_are_not_accepted_as_roots() {
+ for value in [
+ serde_json::json!({"version":99,"home":null,"platform":"linux","identity":null,"volumes":[]}),
+ serde_json::json!({"version":1,"home":null,"platform":"linux","identity":null,"volumes":[{"point":"relative","device":null,"space":null}]}),
+ ] {
+ let mut data = serde_json::to_vec(&value).unwrap();
+ data.push(b'\n');
+ assert!(read_roots(&mut data.as_slice()).is_err());
+ }
+ }
+
#[test]
fn diagnostics_are_bounded_and_controls_are_stripped() {
let mut data = vec![b'x'; MAX_DIAGNOSTICS * 4];
@@ -662,6 +823,52 @@ mod tests {
assert!(!home.path().join(".local/bin/disktree-scan").exists());
}
+ #[cfg(unix)]
+ #[test]
+ #[ignore = "requires isolated sshd and DISKTREE_TEST_ARCHIVE"]
+ fn real_ssh_transport_discovers_roots_without_a_scan() {
+ let config = std::env::var("DISKTREE_TEST_SSH_CONFIG").unwrap();
+ let archive = crate::payload::Archive::open(
+ PathBuf::from(std::env::var("DISKTREE_TEST_ARCHIVE").unwrap())
+ .as_path(),
+ )
+ .unwrap()
+ .unwrap();
+ let home = tempfile::tempdir().unwrap();
+ let cache = home.path().join("cache");
+ let remote = format!(
+ "HOME={} XDG_CACHE_HOME={}; export HOME XDG_CACHE_HOME;\n{}",
+ crate::export::shell_quote(home.path().to_str().unwrap()),
+ crate::export::shell_quote(cache.to_str().unwrap()),
+ crate::deployment::COMMAND,
+ );
+ let mut command = Command::new("ssh");
+ command.args(["-F", &config, "-T", "fixture", &remote]);
+ let job = RemoteRoots::start(
+ command,
+ "fixture",
+ Operation::Discover {
+ discover_version: VERSION,
+ },
+ Some(archive),
+ read_roots,
+ )
+ .unwrap();
+ let roots = wait(&job).unwrap();
+ assert_eq!(roots.home.as_deref(), Some(home.path()));
+ assert!(roots.identity.is_some());
+ assert!(
+ roots
+ .volumes
+ .iter()
+ .all(|volume| volume.point.is_absolute()
+ && volume.space.is_none())
+ );
+ // Only the checked cache was installed, not a per-root scan log,
+ // helper in PATH, or a traversed home tree.
+ assert!(!home.path().join(".local").exists());
+ }
+
/// Explicit opt-in only: never contact a real machine in the test gate.
#[test]
#[ignore = "requires DISKTREE_TEST_SSH_HOST and DISKTREE_TEST_SSH_ROOT"]
diff --git a/crates/disktree-core/src/space.rs b/crates/disktree-core/src/space.rs
index e318d87..2434c6c 100644
--- a/crates/disktree-core/src/space.rs
+++ b/crates/disktree-core/src/space.rs
@@ -738,7 +738,7 @@ pub const fn foreign_mounts_for(_root: &Path) -> Option<Vec<PathBuf>> {
/// A mounted volume the picker can switch the scan to: where it is mounted
/// and how much room it has. Listed by [`volumes`].
-#[derive(Clone, Debug, PartialEq, Eq)]
+#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct Volume {
/// Where the volume is mounted: `C:\` on Windows, `/` or `/home` on
/// Linux, `/` on macOS.
@@ -765,8 +765,46 @@ pub fn volumes() -> Vec<Volume> {
volumes_in(&parse_mounts(&table))
}
-/// [`volumes`] over a given mount table, for testing.
-pub fn volumes_in(mounts: &[Mount]) -> Vec<Volume> {
+/// Read root candidates without opening them, measuring free space, or
+/// touching network mounts. Discovery is not permission to start scanning.
+pub fn volume_roots() -> io::Result<Vec<Volume>> {
+ #[cfg(not(any(target_os = "macos", windows)))]
+ {
+ let mounts = mount_table()
+ .ok_or_else(|| io::Error::other("cannot read mount table"))?;
+ Ok(volume_roots_in(&mounts))
+ }
+ #[cfg(target_os = "macos")]
+ {
+ let output = std::process::Command::new("mount").output()?;
+ if !output.status.success() {
+ return Err(io::Error::other("cannot list mounted volumes"));
+ }
+ Ok(parse_macos_mounts(&String::from_utf8_lossy(&output.stdout))
+ .into_iter()
+ .filter(|point| point.as_os_str() != MACOS_DATA_VOLUME)
+ .map(|point| Volume {
+ point,
+ device: None,
+ space: None,
+ })
+ .collect())
+ }
+ #[cfg(windows)]
+ {
+ Ok(crate::windows::mount_points()
+ .into_iter()
+ .map(|point| Volume {
+ point,
+ device: None,
+ space: None,
+ })
+ .collect())
+ }
+}
+
+/// Root candidates from a mount table; deliberately never calls statvfs.
+pub fn volume_roots_in(mounts: &[Mount]) -> Vec<Volume> {
let mut seen: Vec<&Mount> = Vec::new();
for mount in mounts {
if !is_volume_candidate(mount) {
@@ -784,11 +822,19 @@ pub fn volumes_in(mounts: &[Mount]) -> Vec<Volume> {
.map(|mount| Volume {
point: mount.point.clone(),
device: Some(mount.source.clone()),
- space: space_info(&mount.point).ok(),
+ space: None,
})
.collect();
- // The scarcest room is the most interesting to a cleanup tool, so the
- // fullest volume that still reads is first; unreadable ones sort last.
+ volumes.sort_by(|left, right| left.point.cmp(&right.point));
+ volumes
+}
+
+/// [`volumes`] over a given mount table, for testing.
+pub fn volumes_in(mounts: &[Mount]) -> Vec<Volume> {
+ let mut volumes = volume_roots_in(mounts);
+ for volume in &mut volumes {
+ volume.space = space_info(&volume.point).ok();
+ }
sort_by_free_space(&mut volumes);
volumes
}
@@ -1061,6 +1107,23 @@ portal /run/user/1000/doc fuse.portal rw 0 0
);
}
+ #[test]
+ fn discovery_candidates_do_not_probe_unavailable_mounts() {
+ let table = parse_mounts(
+ "/dev/root /not-present-disktree-root ext4 rw 0 0\n\
+ /dev/root /not-present-disktree-bind ext4 rw 0 0\n\
+ server:/share /unreachable-disktree-network nfs rw 0 0\n\
+ systemd-1 /untriggered-disktree-autofs autofs rw 0 0\n",
+ );
+ let volumes = volume_roots_in(&table);
+ assert_eq!(volumes.len(), 3);
+ assert!(volumes.iter().all(|volume| volume.space.is_none()));
+ assert!(
+ !volumes.iter().any(|volume| volume.point
+ == Path::new("/untriggered-disktree-autofs"))
+ );
+ }
+
#[test]
fn strict_scan_boundaries_include_same_device_and_bind_mounts() {
let mounts = parse_mounts(
diff --git a/crates/disktree-scan/src/main.rs b/crates/disktree-scan/src/main.rs
index 0d51f63..802b43e 100644
--- a/crates/disktree-scan/src/main.rs
+++ b/crates/disktree-scan/src/main.rs
@@ -18,9 +18,8 @@ fn main() -> io::Result<()> {
std::process::exit(1);
})?;
let mut input = BufReader::new(io::stdin());
- let (request, watch_disconnect) =
- disktree_core::remote::read_request(&mut input)?;
- if watch_disconnect {
+ let session = disktree_core::remote::read_request(&mut input)?;
+ if session.watch_disconnect {
std::thread::Builder::new()
.name("scan-connection".into())
.spawn(move || {
@@ -41,8 +40,8 @@ fn main() -> io::Result<()> {
}
})?;
}
- disktree_core::remote::serve_request(
- request,
+ disktree_core::remote::serve_session(
+ session,
&mut BufWriter::new(io::stdout().lock()),
)
} else if args.is_empty() || args == ["--help"] || args == ["-h"] {
diff --git a/crates/disktree-scan/tests/stdio.rs b/crates/disktree-scan/tests/stdio.rs
index a5bc79f..9782a9b 100644
--- a/crates/disktree-scan/tests/stdio.rs
+++ b/crates/disktree-scan/tests/stdio.rs
@@ -201,3 +201,17 @@ fn wide_stream_has_bounded_resident_memory() {
assert!(helper.0.wait().unwrap().success());
drop(input);
}
+
+#[test]
+fn executable_discovers_roots_without_scanning_a_path() {
+ let mut helper = supervised_helper();
+ let mut input = helper.0.stdin.take().unwrap();
+ input.write_all(b"{\"discover_version\":1,\"watch_disconnect\":true,\"root\":\"/missing-disktree-discovery-root\"}\n").unwrap();
+ let roots = disktree_core::remote::read_roots(&mut BufReader::new(
+ helper.0.stdout.take().unwrap(),
+ ))
+ .unwrap();
+ assert!(roots.volumes.iter().all(|volume| volume.space.is_none()));
+ assert!(helper.0.wait().unwrap().success());
+ drop(input);
+}