Skip to main content

rig_tools/
remote.rs

1//! Workspaces on other machines: [`Remote`], one machine reached through a
2//! transport, and [`Hosts`], which sends each path written `HOST:PATH` to
3//! that host's `Remote` and every other path to the workspace it wraps.
4//!
5//! A transport is a command that runs its last argument, a shell line, on
6//! the other machine with the remote user's shell in their home, forwards
7//! its stdin, keeps its stdout and stderr apart, ends with its exit status,
8//! and ends with 255 when the transport itself failed: `ssh` does, and so
9//! does `koh exec`. Every file operation is one short `sh` script run that
10//! way, at most [`CALLS_PER_HOST`] at once, and every process a local
11//! transport process running the command there. That command is stopped
12//! there when the transport's stdin closes, which this side holds open
13//! until the process ends or is stopped, so a timeout, an interrupt or a
14//! lost connection leaves nothing running on the other machine.
15//!
16//! ```no_run
17//! use std::path::Path;
18//! use std::sync::Arc;
19//! use rig_tools::process::Launcher;
20//! use rig_tools::remote::{Hosts, Remote};
21//! use rig_tools::workspace::{Local, Workspace};
22//!
23//! let bench = ["koh", "exec", "bench", "--sh"];
24//! let dev = ["ssh", "-o", "BatchMode=yes", "dev@box"];
25//! let hosts = Hosts::new(
26//!     Arc::new(Local),
27//!     [
28//!         Remote::new("bench", bench, Launcher::default())?,
29//!         Remote::new("box", dev, Launcher::default())?,
30//!     ],
31//! );
32//! let text = hosts.read(Path::new("bench:~/strata/src/lib.rs"), 4096)?;
33//! # Ok::<(), std::io::Error>(())
34//! ```
35
36use std::collections::BTreeMap;
37use std::ffi::{OsStr, OsString};
38use std::fmt;
39use std::io::{self, ErrorKind, Write as _};
40use std::path::{Component, Path, PathBuf};
41use std::process::Stdio;
42use std::sync::{Arc, Condvar, Mutex, PoisonError};
43use std::thread;
44
45use ignore::overrides::OverrideBuilder;
46
47use rig_core::tool::{ContentHash, content_hash};
48
49use crate::process::{Launcher, Process, STOP_GRACE, Spawn};
50use crate::workspace::{
51    Contents, Excerpt, Listing, Stat, Workspace, excerpt_of, not_text, read_file, too_large,
52};
53use crate::{MAX_BYTES, MAX_FILE_BYTES, quote};
54
55/// The exit status with which a transport says it failed, as `ssh` does.
56pub const TRANSPORT_FAILED: i32 = 255;
57/// How many files one script of [`Remote::read_files`] reads.
58const FILES_PER_CALL: usize = 100;
59/// How many file operations run on one host at once; the rest wait for a
60/// turn. Each is a connection of its own, and a server may drop some of a
61/// burst of new connections from one client, as one that takes only two
62/// handshakes from a client at a time does.
63pub const CALLS_PER_HOST: usize = 2;
64
65/// The exit codes the scripts below say what went wrong with.
66const NOT_FOUND: i32 = 2;
67const NOT_A_FILE: i32 = 3;
68const READ_ONLY: i32 = 4;
69const A_DIRECTORY: i32 = 5;
70const ROOT_IS_A_FILE: i32 = 6;
71
72/// Another machine, reached through a transport (see the [module](self)
73/// docs). Its paths are that machine's: absolute, or under `~`, its user's
74/// home; a relative path is relative to that home, where the transport
75/// starts. Paths are folded without asking the machine
76/// ([`canonical`](Workspace::canonical)), so links there are not followed.
77#[derive(Clone)]
78pub struct Remote {
79    name: String,
80    transport: Vec<OsString>,
81    /// How the transport starts for a file operation: in no directory of
82    /// its own.
83    launcher: Launcher,
84    /// The file operations running there now, shared by its clones.
85    running: Arc<(Mutex<usize>, Condvar)>,
86}
87
88/// Whether a script may run again when its transport failed: one that only
89/// reads may, one that writes may not, as it may have done its work.
90#[derive(Clone, Copy, PartialEq, Eq)]
91enum Again {
92    Once,
93    Never,
94}
95
96/// A turn to run a file operation, given back when dropped.
97struct Turn<'a>(&'a (Mutex<usize>, Condvar));
98
99impl<'a> Turn<'a> {
100    /// Waits until fewer than [`CALLS_PER_HOST`] operations run.
101    fn take(running: &'a (Mutex<usize>, Condvar)) -> Self {
102        let (count, freed) = running;
103        let mut count = count.lock().unwrap_or_else(PoisonError::into_inner);
104        while *count >= CALLS_PER_HOST {
105            count = freed.wait(count).unwrap_or_else(PoisonError::into_inner);
106        }
107        *count += 1;
108        Self(running)
109    }
110}
111
112impl Drop for Turn<'_> {
113    fn drop(&mut self) {
114        let (count, freed) = self.0;
115        let mut count = count.lock().unwrap_or_else(PoisonError::into_inner);
116        *count = count.saturating_sub(1);
117        freed.notify_one();
118    }
119}
120
121/// What a remote script printed and how it ended.
122struct Ran {
123    code: Option<i32>,
124    /// The signal that ended the transport, when one did.
125    signal: Option<i32>,
126    out: Vec<u8>,
127    err: String,
128}
129
130impl Ran {
131    /// Whether the transport failed or was killed, so the script may not
132    /// have run there at all.
133    fn dropped(&self) -> bool {
134        self.code.is_none_or(|code| code == TRANSPORT_FAILED)
135    }
136}
137
138impl fmt::Debug for Remote {
139    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
140        f.debug_struct("Remote")
141            .field("name", &self.name)
142            .field("transport", &self.transport)
143            .finish()
144    }
145}
146
147impl Remote {
148    /// The machine `name`, such as `bench`, reached through `transport`,
149    /// such as `["ssh", "dev@box"]`, which file operations start under
150    /// `launcher`'s policy (its wrapper and variables; not its directory).
151    ///
152    /// # Errors
153    ///
154    /// An [`InvalidInput`](ErrorKind::InvalidInput) error when `name` is
155    /// empty or holds a `:`, `/` or space, or `transport` is empty.
156    pub fn new(
157        name: impl Into<String>,
158        transport: impl IntoIterator<Item = impl Into<OsString>>,
159        mut launcher: Launcher,
160    ) -> io::Result<Self> {
161        let name = name.into();
162        let transport: Vec<OsString> = transport.into_iter().map(Into::into).collect();
163        if name.is_empty() || name.contains([':', '/']) || name.contains(char::is_whitespace) {
164            return Err(io::Error::new(
165                ErrorKind::InvalidInput,
166                format!("`{name}` is no host name: it is empty or holds a `:`, `/` or space"),
167            ));
168        }
169        if transport.is_empty() {
170            return Err(io::Error::new(
171                ErrorKind::InvalidInput,
172                format!("the transport of {name} is empty"),
173            ));
174        }
175        launcher.cwd = None;
176        Ok(Self {
177            name,
178            transport,
179            launcher,
180            running: Arc::default(),
181        })
182    }
183
184    /// Its name.
185    pub fn name(&self) -> &str {
186        &self.name
187    }
188
189    /// The transport and `script` as its last argument, run with `sh`
190    /// there whatever the remote user's shell is.
191    fn command(&self, script: &str) -> io::Result<(OsString, Vec<OsString>)> {
192        let Some((program, args)) = self.transport.split_first() else {
193            return Err(io::Error::other(format!(
194                "the transport of {} is empty",
195                self.name
196            )));
197        };
198        let mut args = args.to_vec();
199        args.push(format!("sh -c {}", quote(script)).into());
200        Ok((program.clone(), args))
201    }
202
203    /// Runs `script` there once, with `stdin`, when its turn comes, and
204    /// says how it ended.
205    fn once(&self, script: &str, stdin: Option<&[u8]>) -> io::Result<Ran> {
206        let (program, args) = self.command(script)?;
207        let _turn = Turn::take(&self.running);
208        let mut command = self.launcher.command(&program);
209        command
210            .args(args)
211            .stdin(match stdin {
212                Some(_) => Stdio::piped(),
213                None => Stdio::null(),
214            })
215            .stdout(Stdio::piped())
216            .stderr(Stdio::piped());
217        let mut child = command
218            .spawn()
219            .map_err(|error| self.unstarted(&program, error))?;
220        let pipe = child.stdin.take();
221        let output = thread::scope(|scope| {
222            if let (Some(mut pipe), Some(bytes)) = (pipe, stdin) {
223                scope.spawn(move || pipe.write_all(bytes).ok());
224            }
225            child.wait_with_output()
226        })?;
227        #[cfg(unix)]
228        let signal = std::os::unix::process::ExitStatusExt::signal(&output.status);
229        #[cfg(not(unix))]
230        let signal = None;
231        Ok(Ran {
232            code: output.status.code(),
233            signal,
234            out: output.stdout,
235            err: String::from_utf8_lossy(&output.stderr).trim().to_owned(),
236        })
237    }
238
239    /// Runs `script` there, failing when the transport failed or was
240    /// killed, after trying again once when `again` allows.
241    fn run(&self, script: &str, stdin: Option<&[u8]>, again: Again) -> io::Result<Ran> {
242        let mut ran = self.once(script, stdin)?;
243        if ran.dropped() && again == Again::Once {
244            ran = self.once(script, stdin)?;
245        }
246        match ran.dropped() {
247            true => Err(self.failed(&ran, again)),
248            false => Ok(ran),
249        }
250    }
251
252    /// Runs `script` there: an exit code the script names becomes its
253    /// error, another an error with its stderr.
254    fn checked(&self, script: &str, stdin: Option<&[u8]>, again: Again) -> io::Result<Vec<u8>> {
255        let ran = self.run(script, stdin, again)?;
256        self.outcome(ran, again)
257    }
258
259    /// What `ran` comes to: its output on exit 0, the error an exit code
260    /// the scripts name stands for, or [`failed`](Self::failed).
261    fn outcome(&self, ran: Ran, again: Again) -> io::Result<Vec<u8>> {
262        match ran.code {
263            Some(0) => Ok(ran.out),
264            Some(NOT_FOUND) => Err(ErrorKind::NotFound.into()),
265            Some(NOT_A_FILE) => Err(io::Error::new(
266                ErrorKind::InvalidInput,
267                "not a regular file",
268            )),
269            Some(READ_ONLY) => Err(io::Error::new(
270                ErrorKind::PermissionDenied,
271                "the file is read-only; leave it unchanged or ask the user",
272            )),
273            Some(A_DIRECTORY) => Err(ErrorKind::IsADirectory.into()),
274            _ => Err(self.failed(&ran, again)),
275        }
276    }
277
278    /// What a call fails with when its script ended as `ran` did, with no
279    /// exit status the script names: how it ended, what it said, and, for
280    /// a script that writes, that it may have done its work. The transport
281    /// failed when it ended with [`TRANSPORT_FAILED`] or by a signal, after
282    /// the tries
283    /// `again` allowed.
284    fn failed(&self, ran: &Ran, again: Again) -> io::Error {
285        let (kind, ended) = self.ended(ran);
286        let after = match again {
287            Again::Once if ran.dropped() => " (tried twice)",
288            Again::Once => "",
289            Again::Never => {
290                "; the change may have been made or not, so read the file before trying again"
291            }
292        };
293        io::Error::new(kind, format!("{ended}{after}"))
294    }
295
296    /// How a script that ended as `ran` did ended, and what it said.
297    fn ended(&self, ran: &Ran) -> (ErrorKind, String) {
298        let name = &self.name;
299        let (kind, how) = match ran.code {
300            Some(TRANSPORT_FAILED) => (
301                ErrorKind::NotConnected,
302                format!("the transport to {name} failed (exit status {TRANSPORT_FAILED})"),
303            ),
304            Some(code) => (
305                ErrorKind::Other,
306                format!("the operation on {name} ended with exit status {code}"),
307            ),
308            None => (
309                ErrorKind::ConnectionAborted,
310                match ran.signal {
311                    #[cfg(unix)]
312                    Some(signal) => format!(
313                        "the transport to {name} was killed by {} (signal {signal}), which rig \
314                         did not send",
315                        crate::shell::sent(signal).0
316                    ),
317                    _ => format!("the transport to {name} was killed by a signal rig did not send"),
318                },
319            ),
320        };
321        let said = match ran.err.as_str() {
322            "" => " and said nothing".to_owned(),
323            err => format!(": {err}"),
324        };
325        (kind, format!("{how}{said}"))
326    }
327
328    /// Runs `script`, which writes `bytes` to the file `path`, once. When
329    /// it ends with no exit status it names, such as a transport that
330    /// dropped mid-write, the file is hashed there again (a read, so tried
331    /// twice) and the error says whether it holds `bytes`: whether the
332    /// write happened.
333    fn written(&self, path: &Path, script: &str, bytes: &[u8]) -> io::Result<Vec<u8>> {
334        let ran = self.once(script, Some(bytes))?;
335        if matches!(
336            ran.code,
337            Some(0 | NOT_FOUND | NOT_A_FILE | READ_ONLY | A_DIRECTORY)
338        ) {
339            return self.outcome(ran, Again::Never);
340        }
341        let (kind, ended) = self.ended(&ran);
342        let check = format!(
343            "p={}; [ -f \"$p\" ] || exit {NOT_FOUND}; \
344             h=$({{ sha256sum || shasum -a 256; }} < \"$p\" 2>/dev/null); echo \"${{h%% *}}\"",
345            quote_path(path)
346        );
347        let checked = self.checked(&check, None, Again::Once);
348        let sent = content_hash(bytes).0;
349        let found = match checked.as_deref().map(|out| String::from_utf8_lossy(out)) {
350            Ok(hash) if hash.trim() == sent => {
351                "it holds what this write sent, so the write happened".to_owned()
352            }
353            Ok(hash) if !hash.trim().is_empty() => "it does not hold what this write sent, so \
354                 the write did not happen; make the change again"
355                .to_owned(),
356            Err(error) if error.kind() == ErrorKind::NotFound => {
357                "it is not there, so the write did not happen; make the change again".to_owned()
358            }
359            Ok(_) => "it could not be hashed there, so the write may or may not have \
360                 happened; read the file before going on"
361                .to_owned(),
362            Err(error) => format!(
363                "that failed too ({error}), so the write may or may not have happened; read \
364                 the file before going on"
365            ),
366        };
367        Err(io::Error::new(
368            kind,
369            format!("the write failed: {ended}. The file was checked again: {found}"),
370        ))
371    }
372
373    /// What a call fails with when its transport could not start.
374    fn unstarted(&self, program: &OsStr, error: io::Error) -> io::Error {
375        io::Error::other(format!(
376            "could not start `{}`, the transport to {}: {error}",
377            program.to_string_lossy(),
378            self.name
379        ))
380    }
381}
382
383impl Workspace for Remote {
384    /// Its name.
385    fn host(&self) -> Option<&str> {
386        Some(&self.name)
387    }
388
389    fn stat(&self, path: &Path) -> io::Result<Stat> {
390        let script = format!(
391            "p={}; if [ -f \"$p\" ]; then wc -c < \"$p\" || exit 1; \
392             if [ -w \"$p\" ]; then echo w; else echo r; fi; \
393             elif [ -d \"$p\" ]; then echo d; elif [ -e \"$p\" ]; then echo o; else echo m; fi",
394            quote_path(path)
395        );
396        let out = String::from_utf8_lossy(&self.checked(&script, None, Again::Once)?).into_owned();
397        let mut words = out.split_whitespace();
398        Ok(match (words.next(), words.next()) {
399            (Some("d"), _) => Stat::Dir,
400            (Some("o"), _) => Stat::Other,
401            (Some("m"), _) => Stat::Missing,
402            (Some(size), Some(access)) => Stat::File {
403                size: size.parse().map_err(io::Error::other)?,
404                read_only: access == "r",
405                modified: None,
406            },
407            _ => return Err(io::Error::other(format!("stat said `{}`", out.trim()))),
408        })
409    }
410
411    fn read(&self, path: &Path, limit: u64) -> io::Result<Contents> {
412        let script = format!(
413            "p={}; [ -f \"$p\" ] || {{ [ -e \"$p\" ] && exit {NOT_A_FILE}; exit {NOT_FOUND}; }}; \
414             wc -c < \"$p\" && head -c {limit} -- \"$p\"",
415            quote_path(path)
416        );
417        let out = self.checked(&script, None, Again::Once)?;
418        let Some((size, bytes)) = split_line(&out) else {
419            return Err(io::Error::other("the remote read said nothing"));
420        };
421        Ok(Contents {
422            bytes: bytes.to_vec(),
423            size: size.trim().parse().map_err(io::Error::other)?,
424        })
425    }
426
427    /// One script that sends the file's size, its line count, its hash and
428    /// only the lines asked, or the whole file when it is at most
429    /// [`MAX_BYTES`], all of a copy made aside first, so they agree when
430    /// the file changes meanwhile. A machine with neither `sha256sum` nor
431    /// `shasum` sends a larger file whole in a second call, to hash it here.
432    fn excerpt(&self, path: &Path, first: usize, count: usize) -> io::Result<Excerpt> {
433        let first = first.max(1);
434        let last = first.saturating_add(count.max(1) - 1);
435        let script = format!(
436            "p={}; [ -f \"$p\" ] || {{ [ -e \"$p\" ] && exit {NOT_A_FILE}; exit {NOT_FOUND}; }}; \
437             s=$(wc -c < \"$p\") || exit 1; [ $s -le {MAX_FILE_BYTES} ] || {{ echo $s; exit 0; }}; \
438             t=$(mktemp) || exit 1; trap 'rm -f \"$t\"' EXIT; cat -- \"$p\" > \"$t\" || exit 1; \
439             s=$(wc -c < \"$t\") && echo $s && wc -l < \"$t\" && tail -c 1 \"$t\" | wc -l && \
440             {{ sha256sum || shasum -a 256 || echo -; }} < \"$t\" 2>/dev/null && \
441             if [ $s -le {MAX_BYTES} ]; then cat \"$t\"; else sed -n '{first},{last}p;{last}q' \"$t\"; fi",
442            quote_path(path)
443        );
444        let out = self.checked(&script, None, Again::Once)?;
445        let mut rest = out.as_slice();
446        let mut line = || {
447            let (line, after) = split_line(rest)?;
448            rest = after;
449            Some(line.trim().to_owned())
450        };
451        let size: u64 = line()
452            .and_then(|size| size.parse().ok())
453            .ok_or_else(|| io::Error::other("the remote read said no size"))?;
454        if size > MAX_FILE_BYTES {
455            return Err(too_large(size));
456        }
457        let (Some(newlines), Some(ends_in_newline), Some(hash)) = (line(), line(), line()) else {
458            return Err(io::Error::other("the remote read stopped short"));
459        };
460        let text = String::from_utf8(rest.to_vec()).map_err(|_| not_text());
461        if size <= MAX_BYTES as u64 {
462            return Ok(Excerpt::of(&text?, first, count));
463        }
464        let hash = hash.split_whitespace().next().unwrap_or_default();
465        if hash.len() != 64 {
466            return excerpt_of(self, path, first, count);
467        }
468        let newlines: usize = newlines.parse().map_err(io::Error::other)?;
469        let unended = size > 0 && ends_in_newline == "0";
470        Ok(Excerpt {
471            text: text?,
472            total: newlines + usize::from(unended),
473            hash: ContentHash(hash.to_ascii_lowercase()),
474            whole: None,
475        })
476    }
477
478    /// The files in scripts of 100 each, every file copied
479    /// aside before it is sent, so one that changes meanwhile is sent whole
480    /// as it was.
481    fn read_files(&self, paths: &[PathBuf], limit: u64) -> Vec<Option<Vec<u8>>> {
482        let mut read = Vec::with_capacity(paths.len());
483        for chunk in paths.chunks(FILES_PER_CALL) {
484            let quoted: Vec<String> = chunk.iter().map(|path| quote_path(path)).collect();
485            let script = format!(
486                "t=$(mktemp) || exit 1; trap 'rm -f \"$t\"' EXIT; for p in {}; do \
487                 if [ -f \"$p\" ] && n=$(wc -c < \"$p\") && [ $((n)) -le {limit} ] && \
488                 cat -- \"$p\" > \"$t\" 2>/dev/null; then wc -c < \"$t\"; cat \"$t\"; \
489                 else echo -; fi; done",
490                quoted.join(" ")
491            );
492            let out = match self.run(&script, None, Again::Once) {
493                Ok(ran) if ran.code == Some(0) => ran.out,
494                _ => Vec::new(),
495            };
496            let mut rest = out.as_slice();
497            for _ in chunk {
498                let file = split_line(rest).and_then(|(size, after)| {
499                    let size: usize = size.trim().parse().ok()?;
500                    let (bytes, after) = after.split_at_checked(size)?;
501                    Some((bytes, after))
502                });
503                match file {
504                    Some((bytes, after)) => {
505                        read.push(Some(bytes.to_vec()));
506                        rest = after;
507                    }
508                    None => {
509                        read.push(None);
510                        rest = split_line(rest).map_or(&[][..], |(_, after)| after);
511                    }
512                }
513            }
514        }
515        read
516    }
517
518    /// [`replace`](Workspace::replace)s it, sending back nothing of what
519    /// it held.
520    fn write(&self, path: &Path, bytes: &[u8]) -> io::Result<()> {
521        self.replace(path, bytes, 0).map(drop)
522    }
523
524    /// Writes a temporary file beside it and moves it over the file, so a
525    /// lost connection never leaves it half written, keeping an existing
526    /// file's permissions; the copy the temporary file starts as is what
527    /// is sent back, in the same call.
528    fn replace(&self, path: &Path, bytes: &[u8], limit: u64) -> io::Result<io::Result<Contents>> {
529        let script = format!(
530            "p={}; if [ -e \"$p\" ]; then [ -f \"$p\" ] || exit {NOT_A_FILE}; \
531             [ -w \"$p\" ] || exit {READ_ONLY}; fi; d=$(dirname -- \"$p\"); \
532             mkdir -p -- \"$d\" && t=$(mktemp \"$d/.rig-write.XXXXXX\") || exit 1; \
533             if [ -e \"$p\" ]; then cp -p -- \"$p\" \"$t\" && wc -c < \"$t\" && \
534             head -c {limit} -- \"$t\"; \
535             else chmod \"$(printf %o $((0666 & ~$(umask))))\" \"$t\"; fi && \
536             cat > \"$t\" && mv -f -- \"$t\" \"$p\" || {{ rm -f -- \"$t\"; exit 1; }}",
537            quote_path(path)
538        );
539        let out = self.written(path, &script, bytes)?;
540        Ok(match split_line(&out) {
541            None => Err(ErrorKind::NotFound.into()),
542            Some((size, bytes)) => size
543                .trim()
544                .parse()
545                .map(|size| Contents {
546                    bytes: bytes.to_vec(),
547                    size,
548                })
549                .map_err(io::Error::other),
550        })
551    }
552
553    /// One script: a copy of the file is made beside it and hashed there,
554    /// then filled with `bytes` and moved over the file when the hash is
555    /// `held`, or sent back when it is not. A machine with neither
556    /// `sha256sum` nor `shasum` always sends it back.
557    fn write_if(
558        &self,
559        path: &Path,
560        bytes: &[u8],
561        held: &ContentHash,
562    ) -> io::Result<Option<Contents>> {
563        let script = format!(
564            "p={}; [ -f \"$p\" ] || {{ [ -e \"$p\" ] && exit {NOT_A_FILE}; exit {NOT_FOUND}; }}; \
565             [ -w \"$p\" ] || exit {READ_ONLY}; \
566             t=$(mktemp \"$(dirname -- \"$p\")/.rig-write.XXXXXX\") || exit 1; \
567             cp -p -- \"$p\" \"$t\" || {{ rm -f -- \"$t\"; exit 1; }}; \
568             h=$({{ sha256sum || shasum -a 256; }} < \"$t\" 2>/dev/null); \
569             if [ \"${{h%% *}}\" = {} ]; then \
570             cat > \"$t\" && mv -f -- \"$t\" \"$p\" && echo = || {{ rm -f -- \"$t\"; exit 1; }}; \
571             else wc -c < \"$t\" && head -c {MAX_FILE_BYTES} -- \"$t\"; s=$?; rm -f -- \"$t\"; exit $s; fi",
572            quote_path(path),
573            quote(&held.0)
574        );
575        let out = self.written(path, &script, bytes)?;
576        let Some((first, rest)) = split_line(&out) else {
577            return Err(io::Error::other("the remote write said nothing"));
578        };
579        if first == "=" {
580            return Ok(None);
581        }
582        Ok(Some(Contents {
583            bytes: rest.to_vec(),
584            size: first.trim().parse().map_err(io::Error::other)?,
585        }))
586    }
587
588    fn remove(&self, path: &Path) -> io::Result<()> {
589        let script = format!(
590            "p={}; [ -d \"$p\" ] && exit {A_DIRECTORY}; \
591             [ -e \"$p\" ] || [ -L \"$p\" ] || exit {NOT_FOUND}; rm -f -- \"$p\"",
592            quote_path(path)
593        );
594        self.checked(&script, None, Again::Never).map(drop)
595    }
596
597    fn rename(&self, from: &Path, to: &Path) -> io::Result<()> {
598        let script = format!(
599            "f={}; t={}; [ -e \"$f\" ] || exit {NOT_FOUND}; \
600             mkdir -p -- \"$(dirname -- \"$t\")\" && mv -f -- \"$f\" \"$t\"",
601            quote_path(from),
602            quote_path(to)
603        );
604        self.checked(&script, None, Again::Never).map(drop)
605    }
606
607    /// A path starting with `~` stays whole: the remote `sh` reads it as
608    /// the home directory there.
609    fn join(&self, base: &Path, path: &Path) -> PathBuf {
610        match path.starts_with("~") {
611            true => path.to_path_buf(),
612            false => base.join(path),
613        }
614    }
615
616    /// Folds `.` and `..` without asking the machine, a relative path under
617    /// `~`; a `..` above `~` stays, as the remote `sh` reads it.
618    fn canonical(&self, path: &Path) -> PathBuf {
619        let joined = match path.is_absolute() || path.starts_with("~") {
620            true => path.to_path_buf(),
621            false => Path::new("~").join(path),
622        };
623        let mut out = PathBuf::new();
624        for component in joined.components() {
625            match component {
626                Component::CurDir => {}
627                Component::ParentDir => match out.components().next_back() {
628                    Some(Component::Normal(last)) if last != "~" => {
629                        out.pop();
630                    }
631                    Some(Component::RootDir) => {}
632                    _ => out.push(".."),
633                },
634                other => out.push(other),
635            }
636        }
637        out
638    }
639
640    /// As git lists them there in a git work tree (unless `listing` is
641    /// [`All`](Listing::All)), else as `find` does, then filtered by
642    /// [`Listing::keeps`] and `glob`.
643    fn files(&self, root: &Path, glob: Option<&str>, listing: Listing) -> io::Result<Vec<PathBuf>> {
644        let globs = glob
645            .map(|glob| {
646                OverrideBuilder::new(root)
647                    .add(glob)
648                    .and_then(|builder| builder.build())
649                    .map_err(|error| {
650                        io::Error::new(ErrorKind::InvalidInput, format!("bad glob: {error}"))
651                    })
652            })
653            .transpose()?;
654        let git = match listing {
655            Listing::All => "false",
656            Listing::Visible | Listing::Hidden => {
657                "git rev-parse --is-inside-work-tree >/dev/null 2>&1"
658            }
659        };
660        let script = format!(
661            "r={}; [ -f \"$r\" ] && exit {ROOT_IS_A_FILE}; cd \"$r\" || exit {NOT_FOUND}; \
662             if {git}; then git ls-files -z -co --exclude-standard; \
663             else find . -type f -print0; fi",
664            quote_path(root)
665        );
666        let ran = self.run(&script, None, Again::Once)?;
667        match ran.code {
668            Some(ROOT_IS_A_FILE) => return Ok(vec![root.to_path_buf()]),
669            Some(0) => {}
670            Some(NOT_FOUND) => return Err(ErrorKind::NotFound.into()),
671            _ => return Err(self.failed(&ran, Again::Once)),
672        }
673        let mut files: Vec<PathBuf> = String::from_utf8_lossy(&ran.out)
674            .split('\0')
675            .map(|name| Path::new(name.trim_start_matches("./")))
676            .filter(|name| !name.as_os_str().is_empty() && listing.keeps(name))
677            .map(|name| root.join(name))
678            .filter(|path| {
679                globs
680                    .as_ref()
681                    .is_none_or(|globs| globs.matched(path, false).is_whitelist())
682            })
683            .collect();
684        files.sort();
685        Ok(files)
686    }
687
688    /// Runs `program` there in `dir` (`None`: the remote home) with `sh -l`,
689    /// so the remote user's login environment holds, and the launcher's
690    /// variables, from a local transport started under the launcher's
691    /// wrapper (the launcher's directory is this machine's, so it is not
692    /// used). The process is marked [`through`](Process::through) this
693    /// host: stopping it stops the local transport (`SIGTERM`, then
694    /// `SIGKILL`), and whether that stops the command there is the
695    /// transport's to say.
696    fn spawn(
697        &self,
698        launcher: &Launcher,
699        dir: Option<&Path>,
700        program: &OsStr,
701        args: &[OsString],
702        how: Spawn,
703    ) -> io::Result<Process> {
704        let dir = dir.unwrap_or(Path::new("~"));
705        let mut run = String::from("env");
706        for (name, value) in &launcher.env {
707            let set = format!("{}={}", name.to_string_lossy(), value.to_string_lossy());
708            run.push_str(&format!(" {}", quote(&set)));
709        }
710        run.push_str(" sh -lc 'exec \"$0\" \"$@\"'");
711        for word in std::iter::once(program).chain(args.iter().map(OsString::as_os_str)) {
712            run.push_str(&format!(" {}", quote(&word.to_string_lossy())));
713        }
714        let cd = format!("cd {} || exit", quote_path(&self.canonical(dir)));
715        let hold = how.stdin.is_none();
716        let script = match hold {
717            true => format!("{cd}; {}", guarded(&run)),
718            false => format!("{cd}; exec {run}"),
719        };
720        let (transport, line) = self.command(&script)?;
721        let mut launcher = launcher.clone();
722        launcher.cwd = None;
723        launcher
724            .spawn_holding(&transport, line, how, hold)
725            .map(|process| process.through(&self.name))
726            .map_err(|error| self.unstarted(&transport, error))
727    }
728}
729
730/// A workspace (the inner one, such as [`Local`](crate::workspace::Local))
731/// whose paths written `HOST:PATH`, `HOST` the name of one of its
732/// [`Remote`]s, are that host's `PATH`, as `scp` reads them:
733/// `bench:~/strata/src/lib.rs`, `bench:/srv/app`. Every other path is the
734/// inner workspace's. Every path it gives back for a remote file
735/// ([`canonical`](Workspace::canonical), [`files`](Workspace::files)) keeps
736/// the `HOST:` form, so the facts and footprints the tools make of them can
737/// be passed back as they are; a relative path joined onto a `HOST:` base
738/// stays there.
739///
740/// Its [`host`](Workspace::host) is the inner workspace's, as its project
741/// is there; a call on a `HOST:` path waits for the transport.
742#[derive(Clone, Debug)]
743pub struct Hosts {
744    inner: Arc<dyn Workspace>,
745    hosts: BTreeMap<String, Remote>,
746}
747
748impl Hosts {
749    /// `inner`, and `remotes` by their names; a later remote replaces an
750    /// earlier one of the same name.
751    pub fn new(inner: Arc<dyn Workspace>, remotes: impl IntoIterator<Item = Remote>) -> Self {
752        let hosts = remotes
753            .into_iter()
754            .map(|remote| (remote.name.clone(), remote))
755            .collect();
756        Self { inner, hosts }
757    }
758
759    /// The remote `path` names and the path there: `~` for `HOST:` alone.
760    pub fn route(&self, path: &Path) -> Option<(&Remote, PathBuf)> {
761        let (host, rest) = path.to_str()?.split_once(':')?;
762        let remote = self.hosts.get(host)?;
763        Some((
764            remote,
765            PathBuf::from(if rest.is_empty() { "~" } else { rest }),
766        ))
767    }
768
769    /// `path` on `remote` as this workspace names it: `HOST:PATH`.
770    fn named(remote: &Remote, path: &Path) -> PathBuf {
771        let mut named = OsString::from(&remote.name);
772        named.push(":");
773        named.push(path);
774        PathBuf::from(named)
775    }
776}
777
778impl Workspace for Hosts {
779    fn host(&self) -> Option<&str> {
780        self.inner.host()
781    }
782
783    /// A `HOST:` path stays whole; a path starting with `~` joined onto a
784    /// `HOST:` base is in that host's home.
785    fn join(&self, base: &Path, path: &Path) -> PathBuf {
786        match (self.route(path), self.route(base)) {
787            (Some(_), _) => path.to_path_buf(),
788            (None, Some((remote, _))) if path.starts_with("~") => Self::named(remote, path),
789            (None, _) => self.inner.join(base, path),
790        }
791    }
792
793    fn stat(&self, path: &Path) -> io::Result<Stat> {
794        match self.route(path) {
795            Some((remote, path)) => remote.stat(&path),
796            None => self.inner.stat(path),
797        }
798    }
799
800    fn read(&self, path: &Path, limit: u64) -> io::Result<Contents> {
801        match self.route(path) {
802            Some((remote, path)) => remote.read(&path, limit),
803            None => self.inner.read(path, limit),
804        }
805    }
806
807    /// All in one go on their host when every path is on one, else one by
808    /// one.
809    fn read_files(&self, paths: &[PathBuf], limit: u64) -> Vec<Option<Vec<u8>>> {
810        let first = paths.first().and_then(|path| self.route(path));
811        let there = first.and_then(|(remote, _)| {
812            let there: Option<Vec<PathBuf>> = paths
813                .iter()
814                .map(|path| {
815                    let (other, there) = self.route(path)?;
816                    (other.name == remote.name).then_some(there)
817                })
818                .collect();
819            Some((remote, there?))
820        });
821        match there {
822            Some((remote, there)) => remote.read_files(&there, limit),
823            None => paths
824                .iter()
825                .map(|path| read_file(self, path, limit))
826                .collect(),
827        }
828    }
829
830    fn excerpt(&self, path: &Path, first: usize, count: usize) -> io::Result<Excerpt> {
831        match self.route(path) {
832            Some((remote, path)) => remote.excerpt(&path, first, count),
833            None => self.inner.excerpt(path, first, count),
834        }
835    }
836
837    fn write(&self, path: &Path, bytes: &[u8]) -> io::Result<()> {
838        match self.route(path) {
839            Some((remote, path)) => remote.write(&path, bytes),
840            None => self.inner.write(path, bytes),
841        }
842    }
843
844    fn replace(&self, path: &Path, bytes: &[u8], limit: u64) -> io::Result<io::Result<Contents>> {
845        match self.route(path) {
846            Some((remote, path)) => remote.replace(&path, bytes, limit),
847            None => self.inner.replace(path, bytes, limit),
848        }
849    }
850
851    fn write_if(
852        &self,
853        path: &Path,
854        bytes: &[u8],
855        held: &ContentHash,
856    ) -> io::Result<Option<Contents>> {
857        match self.route(path) {
858            Some((remote, path)) => remote.write_if(&path, bytes, held),
859            None => self.inner.write_if(path, bytes, held),
860        }
861    }
862
863    fn remove(&self, path: &Path) -> io::Result<()> {
864        match self.route(path) {
865            Some((remote, path)) => remote.remove(&path),
866            None => self.inner.remove(path),
867        }
868    }
869
870    /// Within one host, or within the inner workspace; a move between them
871    /// is refused.
872    fn rename(&self, from: &Path, to: &Path) -> io::Result<()> {
873        match (self.route(from), self.route(to)) {
874            (None, None) => self.inner.rename(from, to),
875            (Some((one, from)), Some((other, to))) if one.name == other.name => {
876                one.rename(&from, &to)
877            }
878            _ => Err(io::Error::new(
879                ErrorKind::Unsupported,
880                "a file is not moved between machines; read it and write it there instead",
881            )),
882        }
883    }
884
885    fn canonical(&self, path: &Path) -> PathBuf {
886        match self.route(path) {
887            Some((remote, path)) => Self::named(remote, &remote.canonical(&path)),
888            None => self.inner.canonical(path),
889        }
890    }
891
892    fn files(&self, root: &Path, glob: Option<&str>, listing: Listing) -> io::Result<Vec<PathBuf>> {
893        match self.route(root) {
894            Some((remote, root)) => Ok(remote
895                .files(&root, glob, listing)?
896                .iter()
897                .map(|path| Self::named(remote, path))
898                .collect()),
899            None => self.inner.files(root, glob, listing),
900        }
901    }
902
903    /// On the host `dir` names, else in the inner workspace.
904    fn spawn(
905        &self,
906        launcher: &Launcher,
907        dir: Option<&Path>,
908        program: &OsStr,
909        args: &[OsString],
910        how: Spawn,
911    ) -> io::Result<Process> {
912        match dir.and_then(|dir| self.route(dir)) {
913            Some((remote, dir)) => remote.spawn(launcher, Some(&dir), program, args, how),
914            None => self.inner.spawn(launcher, dir, program, args, how),
915        }
916    }
917
918    /// A remote root is looked at every second, as the default does.
919    fn watch(
920        self: Arc<Self>,
921        root: &Path,
922        recursive: bool,
923        listing: Listing,
924    ) -> io::Result<crate::watch::Watch> {
925        match self.route(root) {
926            Some(_) => crate::watch::poll(self, root, recursive, listing),
927            None => self.inner.clone().watch(root, recursive, listing),
928        }
929    }
930}
931
932/// `bytes` split at its first `\n`: the line before it, as text, and
933/// what follows.
934fn split_line(bytes: &[u8]) -> Option<(String, &[u8])> {
935    let newline = bytes.iter().position(|&byte| byte == b'\n')?;
936    let (line, rest) = bytes.split_at(newline);
937    Some((
938        String::from_utf8_lossy(line).into_owned(),
939        rest.get(1..).unwrap_or_default(),
940    ))
941}
942
943/// A script that runs the command line `run` there, with an empty stdin,
944/// in a session of its own where `setsid` is found, and stops it when the
945/// script's own stdin closes: the transport's, which this side holds open
946/// with nothing written, so it closes when the transport goes, as when a
947/// call times out, is interrupted or rig ends, or when the script is
948/// signalled to hang up or stop. The stop asks the command's group (its
949/// process alone without `setsid`) to end, and kills it [`STOP_GRACE`]
950/// later. The script ends as the command does.
951fn guarded(run: &str) -> String {
952    let grace = STOP_GRACE.as_secs().max(1);
953    format!(
954        "exec 3<&0 </dev/null; \
955         command -v setsid >/dev/null 2>&1 || setsid() {{ exec \"$@\"; }}; \
956         setsid {run} 3<&- & c=$!; \
957         stop() {{ kill -TERM -$c || kill -TERM $c; sleep {grace}; \
958         kill -KILL -$c || kill -KILL $c; }} 2>/dev/null; \
959         {{ read -r x <&3; stop; }} >/dev/null 2>&1 & w=$!; \
960         trap 'kill $w; stop; exit 143' HUP INT TERM; \
961         exec 3<&-; wait $c; s=$?; kill $w 2>/dev/null; exit $s"
962    )
963}
964
965/// A remote path quoted for `sh`, a leading `~` kept as the home
966/// directory.
967fn quote_path(path: &Path) -> String {
968    let path = path.to_string_lossy();
969    match path.strip_prefix("~/") {
970        Some(rest) => format!("\"$HOME\"/{}", quote(rest)),
971        None if path == "~" => "\"$HOME\"".to_owned(),
972        None => quote(&path),
973    }
974}
975
976#[cfg(test)]
977mod tests;