Skip to main content

byob_exec/env/
container.rs

1//! Containers: a workspace can run its commands inside one long-lived Docker or Podman
2//! container instead of on this machine (opt-in per workspace; asked once when the
3//! workspace has a devcontainer.json).
4//!
5//! - **One container per workspace**, named `byob-<folder>-<hash of the path>` and
6//!   labelled `byob.managed=1`, `byob.workspace=<path>`, `byob.config=<stamp>`. It's
7//!   created on first use, reused across commands and byob restarts, and recreated when
8//!   devcontainer.json (or the image setting) changes. It idles in a `sleep` loop under
9//!   `--init`.
10//! - **The workspace is mounted at the same path** (`-v /ws:/ws`), so paths in output,
11//!   scripts and changed-file reports mean the same inside and out. byob's per-run temp
12//!   folders live under `<data>/envs/<ws>/ctmp`, mounted the same way.
13//! - **Commands run as the host user** (`exec -u uid:gid`; Podman adds
14//!   `--userns=keep-id`), so files they write aren't owned by root. `install_packages`
15//!   runs as root (apt-get / apk / dnf, and pip for Python libraries).
16//! - **Network follows the call**: the container is disconnected from its network after
17//!   creation and connected only while a call with `network: true` (or an install) runs.
18//! - **Stop and timeouts reach inside**: each run records its process group (the
19//!   `docker exec` process leads one), which is killed in the container when the run is
20//!   stopped or times out — killing the CLI alone would leave it running.
21//! - byob's own sandbox (Landlock, Seatbelt) doesn't apply inside: the container is the
22//!   isolation. A container can only reach the workspace and byob's temp folder.
23
24use std::collections::BTreeMap;
25use std::ffi::OsString;
26use std::path::{Path, PathBuf};
27use std::process::Command;
28use std::sync::{Mutex, PoisonError};
29use std::time::Duration;
30
31use byob_sandbox::{Outcome, RunOptions};
32
33use super::devcontainer::{Cmd, Image, Spec};
34use super::{Installed, STOPPED, fnv64};
35
36/// The image for workspaces without a devcontainer.json: small, Debian (apt), Python 3.
37pub const DEFAULT_IMAGE: &str = "python:3-slim";
38/// `docker` or `podman`: overrides the settings and the automatic choice.
39pub const RUNTIME_ENV: &str = "BYOB_CONTAINER_RUNTIME";
40
41const QUICK: Duration = Duration::from_secs(60);
42const SLOW: Duration = Duration::from_secs(1800);
43const MAX_CLI_OUTPUT: usize = 64 * 1024;
44/// Keeps the container alive doing nothing until it's stopped.
45const IDLE: &str = "trap 'exit 0' TERM INT; while sleep 1000; do :; done";
46/// Records the run's process group, sets up the user's home, runs the command.
47const WRAPPER: &str = r#"echo $$ > "$BYOB_PID"; mkdir -p "$HOME" 2>/dev/null; export PATH="$HOME/.local/bin:$PATH"; exec "$@""#;
48const HOME: &str = "/tmp/byob-home";
49
50#[derive(Debug, Clone, Copy, PartialEq, Eq)]
51pub enum RuntimeKind {
52    Docker,
53    Podman,
54}
55
56/// The container CLI.
57#[derive(Debug, Clone, PartialEq, Eq)]
58pub struct Runtime {
59    pub kind: RuntimeKind,
60    pub program: PathBuf,
61}
62
63impl Runtime {
64    /// `pref` ("docker", "podman"; [`RUNTIME_ENV`] wins over it) or, by default, Podman
65    /// if it's installed (rootless: a container escape is only the user), else Docker.
66    /// Not on Windows yet (workspace paths can't be mounted at the same path).
67    pub fn detect(pref: Option<&str>) -> Option<Self> {
68        if cfg!(windows) {
69            return None;
70        }
71        let find = |kind: RuntimeKind| {
72            let name = if kind == RuntimeKind::Docker { "docker" } else { "podman" };
73            byob_sandbox::which(name.as_ref()).map(|program| Self { kind, program })
74        };
75        let env = std::env::var(RUNTIME_ENV).ok();
76        match env.as_deref().or(pref).map(|p| p.trim().to_ascii_lowercase()).as_deref() {
77            Some("docker") => find(RuntimeKind::Docker),
78            Some("podman") => find(RuntimeKind::Podman),
79            _ => find(RuntimeKind::Podman).or_else(|| find(RuntimeKind::Docker)),
80        }
81    }
82
83    pub fn name(&self) -> &'static str {
84        match self.kind {
85            RuntimeKind::Docker => "docker",
86            RuntimeKind::Podman => "podman",
87        }
88    }
89
90    /// The network a container joins for network access.
91    fn network(&self) -> &'static str {
92        match self.kind {
93            RuntimeKind::Docker => "bridge",
94            RuntimeKind::Podman => "podman",
95        }
96    }
97
98    /// Run the CLI (outside byob's sandbox: it talks to the daemon, or is Podman itself).
99    fn call<S: AsRef<std::ffi::OsStr>>(&self, args: &[S], timeout: Duration, cancelled: &dyn Fn() -> bool) -> Result<Outcome, String> {
100        let mut cmd = Command::new(&self.program);
101        cmd.args(args);
102        let opts = RunOptions { timeout, max_output: MAX_CLI_OUTPUT, ..Default::default() };
103        byob_sandbox::run(cmd, &opts, cancelled).map_err(|e| format!("can't run {}: {e}", self.name()))
104    }
105
106    /// Run the CLI and require success; returns stdout, trimmed.
107    fn ok<S: AsRef<std::ffi::OsStr>>(&self, args: &[S], timeout: Duration, cancelled: &dyn Fn() -> bool) -> Result<String, String> {
108        let out = self.call(args, timeout, cancelled)?;
109        if out.cancelled {
110            return Err(STOPPED.into());
111        }
112        if out.timed_out {
113            return Err(format!("`{} {}` took too long", self.name(), first_args(args)));
114        }
115        if !out.success() {
116            return Err(format!("`{} {}` failed: {}", self.name(), first_args(args), out.stderr.text().trim()));
117        }
118        Ok(out.stdout.text().trim().to_owned())
119    }
120
121    /// Whether the daemon (or Podman) answers; the error says what to do.
122    pub fn check(&self) -> Result<(), String> {
123        let never = || false;
124        match self.call(&["info", "--format", "{{.ServerVersion}}"], QUICK, &never) {
125            Ok(out) if out.success() => Ok(()),
126            Ok(out) => Err(unreachable_message(self, out.stderr.text().trim())),
127            Err(e) => Err(unreachable_message(self, &e)),
128        }
129    }
130}
131
132fn first_args<S: AsRef<std::ffi::OsStr>>(args: &[S]) -> String {
133    args.iter().take(2).map(|a| a.as_ref().to_string_lossy().into_owned()).collect::<Vec<_>>().join(" ")
134}
135
136fn unreachable_message(rt: &Runtime, detail: &str) -> String {
137    let what = if rt.kind == RuntimeKind::Docker { "Docker isn't running or can't be reached" } else { "Podman doesn't work here" };
138    let detail: String = detail.lines().take(3).collect::<Vec<_>>().join(" ");
139    format!(
140        "{what} (`{} info`: {detail}). Nothing ran. Start it, or choose another environment in the workspace's settings \
141         (its menu in the chat list).",
142        rt.name()
143    )
144}
145
146/// A container ready to run commands in.
147#[derive(Debug, Clone)]
148pub struct Ready {
149    pub name: String,
150    /// For messages: the image, or what it was built from.
151    pub image: String,
152    pub remote_env: Vec<(String, String)>,
153    /// Per-run temp folders go here (mounted at the same path).
154    pub tmp_base: PathBuf,
155    /// Created (or recreated) just now.
156    pub fresh: bool,
157    /// Problems worth telling the model (a failed postCreateCommand, …).
158    pub notes: Vec<String>,
159}
160
161/// The containers of all workspaces, through one runtime.
162#[derive(Debug)]
163pub struct Containers {
164    pub runtime: Runtime,
165    pub default_image: String,
166    /// One creation at a time.
167    creating: Mutex<()>,
168    /// Runs using the network, per container.
169    online: Mutex<BTreeMap<String, usize>>,
170}
171
172/// `byob-<folder>-<hash>`: stable per workspace path, valid as a container name.
173pub fn container_name(ws: &Path) -> String {
174    let folder: String = ws
175        .file_name()
176        .map(|n| n.to_string_lossy().chars().filter(|c| c.is_ascii_alphanumeric() || "-_".contains(*c)).take(24).collect::<String>().to_ascii_lowercase())
177        .unwrap_or_default();
178    let hash = fnv64(ws.as_os_str().as_encoded_bytes());
179    format!("byob-{}-{:012x}", if folder.is_empty() { "ws" } else { &folder }, hash & 0xffff_ffff_ffff)
180}
181
182/// What the container was made from, as a label: recreate when it changes.
183fn stamp(spec: &Spec, rt: &Runtime) -> String {
184    let mut s = format!("v1\0{:?}\0{:?}\0{:?}\0", rt.kind, spec.env, spec.on_create);
185    match &spec.image {
186        Image::Pull(i) => s.push_str(i),
187        Image::Build { dockerfile, context, args } => {
188            s.push_str(&format!("{}\0{}\0{args:?}\0", dockerfile.display(), context.display()));
189            s.push_str(&String::from_utf8_lossy(&std::fs::read(dockerfile).unwrap_or_default()));
190        }
191    }
192    format!("{:016x}", fnv64(s.as_bytes()))
193}
194
195/// `uid:gid` of whoever owns `p` (a folder byob just made: this process's user).
196#[cfg(unix)]
197fn user_of(p: &Path) -> Option<String> {
198    use std::os::unix::fs::MetadataExt;
199    let m = std::fs::metadata(p).ok()?;
200    Some(format!("{}:{}", m.uid(), m.gid()))
201}
202
203#[cfg(not(unix))]
204fn user_of(_p: &Path) -> Option<String> {
205    None
206}
207
208/// The variables every run gets (like the sandbox's clean environment).
209fn run_env(tmp: &Path) -> Vec<(String, String)> {
210    let t = tmp.to_string_lossy().into_owned();
211    let mut v: Vec<(String, String)> = [
212        ("HOME", HOME),
213        ("LANG", "C.UTF-8"),
214        ("MPLBACKEND", "Agg"),
215        ("PYTHONIOENCODING", "utf-8"),
216        ("PYTHONUNBUFFERED", "1"),
217        ("PYTHONDONTWRITEBYTECODE", "1"),
218        ("PIP_DISABLE_PIP_VERSION_CHECK", "1"),
219        ("TERM", "dumb"),
220        ("NO_COLOR", "1"),
221        ("PAGER", "cat"),
222        ("GIT_PAGER", "cat"),
223    ]
224    .into_iter()
225    .map(|(k, v)| (k.to_owned(), v.to_owned()))
226    .collect();
227    for k in ["TMPDIR", "TMP", "TEMP"] {
228        v.push((k.to_owned(), t.clone()));
229    }
230    v.push(("MPLCONFIGDIR".into(), format!("{t}/.matplotlib")));
231    v
232}
233
234/// One command to run in a container.
235#[derive(Debug)]
236pub struct Exec {
237    pub argv: Vec<OsString>,
238    pub env: Vec<(String, OsString)>,
239    pub network: bool,
240    pub timeout: Duration,
241}
242
243impl Containers {
244    pub fn new(runtime: Runtime, default_image: Option<String>) -> Self {
245        let default_image = default_image.filter(|i| super::devcontainer::valid_image(i)).unwrap_or_else(|| DEFAULT_IMAGE.to_owned());
246        Self { runtime, default_image, creating: Mutex::new(()), online: Mutex::new(BTreeMap::new()) }
247    }
248
249    /// The container's state ("running", "exited", …), `None` if there is none (or the
250    /// daemon doesn't answer).
251    pub fn state(&self, ws: &Path) -> Option<String> {
252        let never = || false;
253        self.runtime.ok(&["container", "inspect", "--format", "{{.State.Status}}", &container_name(ws)], QUICK, &never).ok().filter(|s| !s.is_empty())
254    }
255
256    pub fn stop(&self, ws: &Path) -> Result<String, String> {
257        let never = || false;
258        let name = container_name(ws);
259        self.runtime.ok(&["stop", "-t", "3", &name], QUICK, &never)?;
260        Ok(format!("Stopped {name}; it starts again on the next command."))
261    }
262
263    pub fn remove(&self, ws: &Path) -> Result<String, String> {
264        let never = || false;
265        let name = container_name(ws);
266        self.runtime.ok(&["rm", "-f", &name], QUICK, &never)?;
267        Ok(format!("Removed {name}; the next command creates a new one."))
268    }
269
270    /// The workspace's container, created or started as needed. `tmp_base` is the folder
271    /// for per-run temp folders (in byob's data folder).
272    pub fn ensure(&self, ws: &Path, spec: &Spec, tmp_base: &Path, cancelled: &dyn Fn() -> bool) -> Result<Ready, String> {
273        let _one = self.creating.lock().unwrap_or_else(PoisonError::into_inner);
274        let rt = &self.runtime;
275        let name = container_name(ws);
276        let want = stamp(spec, rt);
277        std::fs::create_dir_all(tmp_base).map_err(|e| format!("can't create {}: {e}", tmp_base.display()))?;
278        let tmp_base = tmp_base.canonicalize().map_err(|e| format!("{}: {e}", tmp_base.display()))?;
279        let mut ready = Ready {
280            name: name.clone(),
281            image: spec.describe(ws),
282            remote_env: spec.remote_env.clone(),
283            tmp_base: tmp_base.clone(),
284            fresh: false,
285            notes: Vec::new(),
286        };
287        let inspect = rt.call(&["container", "inspect", "--format", "{{.State.Status}}|{{index .Config.Labels \"byob.config\"}}", &name], QUICK, cancelled)?;
288        if inspect.success() {
289            let text = inspect.stdout.text();
290            let (status, label) = text.trim().split_once('|').unwrap_or((text.trim(), ""));
291            if label == want {
292                if status != "running" {
293                    rt.ok(&["start", &name], QUICK, cancelled)?;
294                }
295                return Ok(ready);
296            }
297            rt.ok(&["rm", "-f", &name], QUICK, cancelled)?;
298            ready.notes.push("The workspace's container was recreated because its configuration changed; packages installed in the old one are gone.".into());
299        } else {
300            let err = inspect.stderr.text();
301            if !err.to_ascii_lowercase().contains("no such") {
302                rt.check()?;
303                return Err(format!("`{} container inspect` failed: {}", rt.name(), err.trim()));
304            }
305        }
306        let image = self.image(ws, spec, cancelled)?;
307        let mut args: Vec<String> = vec!["run".into(), "-d".into(), "--init".into(), "--name".into(), name.clone()];
308        for (k, v) in [("byob.managed", "1".to_owned()), ("byob.workspace", ws.display().to_string()), ("byob.config", want)] {
309            args.extend(["--label".into(), format!("{k}={v}")]);
310        }
311        for dir in [ws, tmp_base.as_path()] {
312            args.extend(["-v".into(), format!("{0}:{0}", dir.display())]);
313        }
314        args.extend(["-w".into(), ws.display().to_string(), "--network".into(), rt.network().into()]);
315        if rt.kind == RuntimeKind::Podman {
316            args.push("--userns=keep-id".into());
317        }
318        for (k, v) in &spec.env {
319            args.extend(["-e".into(), format!("{k}={v}")]);
320        }
321        args.extend(["--entrypoint".into(), "/bin/sh".into(), image, "-c".into(), IDLE.into()]);
322        rt.ok(&args, SLOW, cancelled)?;
323        ready.fresh = true;
324        // Lifecycle commands, as root, with network (they usually install things).
325        for c in &spec.on_create {
326            let mut a: Vec<String> = vec!["exec".into(), "-u".into(), "0".into(), "-w".into(), ws.display().to_string(), name.clone()];
327            match c {
328                Cmd::Shell(s) => a.extend(["/bin/sh".into(), "-c".into(), s.clone()]),
329                Cmd::Args(v) => a.extend(v.iter().cloned()),
330            }
331            match rt.call(&a, SLOW, cancelled) {
332                Ok(o) if o.success() => {}
333                Ok(o) if o.cancelled => return Err(STOPPED.into()),
334                Ok(o) => ready.notes.push(format!("The devcontainer's setup command failed (exit {:?}): {}", o.exit_code, o.stderr.text().trim())),
335                Err(e) => ready.notes.push(format!("The devcontainer's setup command didn't run: {e}")),
336            }
337        }
338        // No network until a call asks for it.
339        if let Err(e) = rt.ok(&["network", "disconnect", rt.network(), &name], QUICK, cancelled) {
340            log::warn!("containers: {name} keeps its network: {e}");
341            ready.notes.push(format!("byob couldn't take the container's network away ({e}), so every command has internet access."));
342        }
343        Ok(ready)
344    }
345
346    /// The image to run: pulled if missing, or built.
347    fn image(&self, ws: &Path, spec: &Spec, cancelled: &dyn Fn() -> bool) -> Result<String, String> {
348        let rt = &self.runtime;
349        match &spec.image {
350            Image::Pull(i) => {
351                if !rt.call(&["image", "inspect", "--format", "{{.Id}}", i], QUICK, cancelled)?.success() {
352                    rt.ok(&["pull", i.as_str()], SLOW, cancelled).map_err(|e| format!("couldn't get the image {i}: {e}"))?;
353                }
354                Ok(i.clone())
355            }
356            Image::Build { dockerfile, context, args } => {
357                let tag = format!("{}:{}", container_name(ws).replacen("byob-", "byob-image-", 1), stamp(spec, rt));
358                let mut a: Vec<String> = vec!["build".into(), "-t".into(), tag.clone(), "-f".into(), dockerfile.display().to_string()];
359                for (k, v) in args {
360                    a.extend(["--build-arg".into(), format!("{k}={v}")]);
361                }
362                a.push(context.display().to_string());
363                rt.ok(&a, SLOW, cancelled).map_err(|e| format!("building the dev container image failed: {e}"))?;
364                Ok(tag)
365            }
366        }
367    }
368
369    /// Connect `name` to the network while `f` runs (counted, so overlapping runs share).
370    fn online<T>(&self, name: &str, on: bool, f: impl FnOnce() -> T) -> (T, Option<String>) {
371        if !on {
372            return (f(), None);
373        }
374        let never = || false;
375        let mut problem = None;
376        {
377            let mut users = self.online.lock().unwrap_or_else(PoisonError::into_inner);
378            let n = users.entry(name.to_owned()).or_insert(0);
379            if *n == 0
380                && let Err(e) = self.runtime.ok(&["network", "connect", self.runtime.network(), name], QUICK, &never)
381                && !e.contains("already exists")
382            {
383                problem = Some(format!("couldn't give the container network access: {e}"));
384            }
385            *n += 1;
386        }
387        let out = f();
388        let mut users = self.online.lock().unwrap_or_else(PoisonError::into_inner);
389        let n = users.entry(name.to_owned()).or_insert(1);
390        *n = n.saturating_sub(1);
391        if *n == 0 {
392            users.remove(name);
393            if let Err(e) = self.runtime.ok(&["network", "disconnect", self.runtime.network(), name], QUICK, &never) {
394                log::warn!("containers: {name}: {e}");
395            }
396        }
397        (out, problem)
398    }
399
400    /// Run `job` in the container as this user, with `cwd` (the workspace) and `tmp`
401    /// (under `ready.tmp_base`) as its temp folder.
402    pub fn exec(&self, ready: &Ready, job: Exec, cwd: &Path, tmp: &Path, cancelled: &dyn Fn() -> bool) -> Result<(Outcome, Option<String>), String> {
403        let pid_file = tmp.join(".byob-pid");
404        let mut args: Vec<OsString> = vec!["exec".into()];
405        if let Some(u) = user_of(tmp) {
406            args.extend(["-u".into(), u.into()]);
407        }
408        args.extend(["-w".into(), cwd.as_os_str().to_owned()]);
409        let mut env: Vec<(String, OsString)> = run_env(tmp).into_iter().map(|(k, v)| (k, v.into())).collect();
410        env.extend(ready.remote_env.iter().map(|(k, v)| (k.clone(), v.into())));
411        env.extend(job.env);
412        env.push(("BYOB_PID".into(), pid_file.clone().into_os_string()));
413        for (k, v) in env {
414            let mut kv = OsString::from(format!("{k}="));
415            kv.push(v);
416            args.extend(["-e".into(), kv]);
417        }
418        args.extend([ready.name.clone().into(), "/bin/sh".into(), "-c".into(), WRAPPER.into(), "sh".into()]);
419        args.extend(job.argv);
420        let (out, problem) = self.online(&ready.name, job.network, || self.runtime.call(&args, job.timeout, cancelled));
421        let out = out?;
422        if out.timed_out || out.cancelled {
423            self.kill(ready, &pid_file);
424        }
425        Ok((out, problem))
426    }
427
428    /// Kill the run whose process group is in `pid_file`, inside the container.
429    fn kill(&self, ready: &Ready, pid_file: &Path) {
430        let Some(pid) = std::fs::read_to_string(pid_file).ok().and_then(|s| s.trim().parse::<u32>().ok()).filter(|p| *p > 1) else { return };
431        let never = || false;
432        let script = format!("kill -9 -{pid} 2>/dev/null; kill -9 {pid} 2>/dev/null; true");
433        if let Err(e) = self.runtime.ok(&["exec", "-u", "0", &ready.name, "/bin/sh", "-c", &script], QUICK, &never) {
434            log::warn!("containers: couldn't stop a run in {}: {e}", ready.name);
435        }
436    }
437
438    /// Install `packages` in the container as root: the distribution's package manager for
439    /// programs, pip for Python libraries (and for names it doesn't know).
440    pub fn install(&self, ready: &Ready, ws: &Path, packages: &[String], cancelled: &dyn Fn() -> bool) -> Result<Installed, String> {
441        let names: Vec<String> = packages.iter().map(|p| install_name(p)).collect::<Result<_, _>>()?;
442        let mut args: Vec<String> = vec!["exec".into(), "-u".into(), "0".into(), "-w".into(), ws.display().to_string()];
443        for (k, v) in [
444            ("DEBIAN_FRONTEND", "noninteractive"),
445            ("PIP_BREAK_SYSTEM_PACKAGES", "1"),
446            ("PIP_ROOT_USER_ACTION", "ignore"),
447            ("PIP_DISABLE_PIP_VERSION_CHECK", "1"),
448        ] {
449            args.extend(["-e".into(), format!("{k}={v}")]);
450        }
451        args.extend([ready.name.clone(), "/bin/sh".into(), "-c".into(), INSTALL.into(), "sh".into()]);
452        args.extend(names);
453        let (out, problem) = self.online(&ready.name, true, || self.runtime.call(&args, SLOW, cancelled));
454        let out = out?;
455        if out.cancelled {
456            return Err(STOPPED.into());
457        }
458        let report = parse_install(&out.stdout.text());
459        if let Some(p) = problem {
460            return Err(format!("{p}\n{}", out.stderr.text().trim()));
461        }
462        if report.manager.is_empty() && report.pip.is_empty() && report.missing.is_empty() {
463            return Err(format!("installing failed: {}", out.stderr.text().trim()));
464        }
465        Ok(report.describe(&out.stderr.text()))
466    }
467}
468
469/// Shell script run as root in the container: `$@` are names, `py:` marks Python libraries.
470/// Prints `BYOB-PM <manager>`, `BYOB-OS <names>` / `BYOB-OSFAIL <names>`, `BYOB-PIP <name>`,
471/// `BYOB-MISSING <name>` on stdout; the managers' output goes to stderr.
472const INSTALL: &str = r#"
473pm=""
474for m in apt-get apk dnf microdnf yum; do command -v $m >/dev/null 2>&1 && { pm=$m; break; }; done
475echo "BYOB-PM $pm"
476case "$pm" in apt-get) apt-get update -qq >&2 ;; apk) apk update -q >&2 ;; esac
477os=""; py=""
478for n in "$@"; do
479  case "$n" in py:*) py="$py ${n#py:}"; continue ;; esac
480  case "$pm" in
481    apt-get) apt-cache show "$n" >/dev/null 2>&1 && os="$os $n" || py="$py $n" ;;
482    apk) apk search -qe "$n" 2>/dev/null | grep -qx "$n" && os="$os $n" || py="$py $n" ;;
483    dnf|microdnf|yum) $pm info "$n" >/dev/null 2>&1 && os="$os $n" || py="$py $n" ;;
484    *) py="$py $n" ;;
485  esac
486done
487if [ -n "$os" ]; then
488  case "$pm" in
489    apt-get) apt-get install -y -qq --no-install-recommends $os >&2 ;;
490    apk) apk add --no-cache $os >&2 ;;
491    *) $pm install -y $os >&2 ;;
492  esac && echo "BYOB-OS$os" || echo "BYOB-OSFAIL$os"
493fi
494if [ -n "$py" ]; then
495  if ! python3 -m pip --version >/dev/null 2>&1; then
496    case "$pm" in
497      apt-get) apt-get install -y -qq --no-install-recommends python3 python3-pip >&2 ;;
498      apk) apk add --no-cache python3 py3-pip >&2 ;;
499      dnf|microdnf|yum) $pm install -y python3 python3-pip >&2 ;;
500    esac
501  fi
502  for p in $py; do
503    if python3 -m pip install -q "$p" >&2; then echo "BYOB-PIP $p"; else echo "BYOB-MISSING $p"; fi
504  done
505fi
506"#;
507
508/// What [`INSTALL`] reported.
509#[derive(Debug, Default, PartialEq, Eq)]
510pub struct Report {
511    pub manager: String,
512    pub os: Vec<String>,
513    pub os_failed: Vec<String>,
514    pub pip: Vec<String>,
515    pub missing: Vec<String>,
516}
517
518pub fn parse_install(stdout: &str) -> Report {
519    let mut r = Report::default();
520    for line in stdout.lines() {
521        let words = |rest: &str| rest.split_whitespace().map(str::to_owned).collect::<Vec<_>>();
522        if let Some(rest) = line.strip_prefix("BYOB-PM") {
523            rest.trim().clone_into(&mut r.manager);
524        } else if let Some(rest) = line.strip_prefix("BYOB-OSFAIL") {
525            r.os_failed.extend(words(rest));
526        } else if let Some(rest) = line.strip_prefix("BYOB-OS") {
527            r.os.extend(words(rest));
528        } else if let Some(rest) = line.strip_prefix("BYOB-PIP") {
529            r.pip.extend(words(rest));
530        } else if let Some(rest) = line.strip_prefix("BYOB-MISSING") {
531            r.missing.extend(words(rest));
532        }
533    }
534    r
535}
536
537impl Report {
538    fn describe(&self, stderr: &str) -> Installed {
539        let mut text = Vec::new();
540        if !self.os.is_empty() {
541            text.push(format!("Installed in the container with {}: {}.", self.manager, self.os.join(", ")));
542        }
543        if !self.pip.is_empty() {
544            text.push(format!("Installed in the container with pip: {} (run_python's python3 has them).", self.pip.join(", ")));
545        }
546        if !self.os.is_empty() || !self.pip.is_empty() {
547            text.push("run_command and run_python can use them now; they stay in this workspace's container.".into());
548        }
549        if !self.os_failed.is_empty() {
550            let tail: String = stderr.lines().rev().take(8).collect::<Vec<_>>().into_iter().rev().collect::<Vec<_>>().join("\n");
551            text.push(format!("{} couldn't install {}:\n{tail}", self.manager, self.os_failed.join(", ")));
552        }
553        if !self.missing.is_empty() {
554            text.push(format!(
555                "Not found{}: {}. Call install_packages again with the exact package name.",
556                if self.manager.is_empty() { String::new() } else { format!(" with {} or pip", self.manager) },
557                self.missing.iter().map(|m| format!("{m:?}")).collect::<Vec<_>>().join(", ")
558            ));
559        }
560        let failed = !self.missing.is_empty() || !self.os_failed.is_empty();
561        Installed { text: text.join("\n"), failed, missing: self.missing.clone() }
562    }
563}
564
565/// Python libraries models commonly ask for: installed with pip, not as system packages.
566const PIP_NAMES: &[&str] = &[
567    "numpy",
568    "pandas",
569    "matplotlib",
570    "scipy",
571    "seaborn",
572    "plotly",
573    "requests",
574    "httpx",
575    "openpyxl",
576    "xlrd",
577    "pyyaml",
578    "beautifulsoup4",
579    "lxml",
580    "sympy",
581    "statsmodels",
582    "pillow",
583    "scikit-learn",
584    "networkx",
585    "tabulate",
586    "polars",
587    "pyarrow",
588    "jinja2",
589    "pytest",
590    "flask",
591    "fastapi",
592    "torch",
593    "tqdm",
594    "rich",
595    "click",
596    "pydantic",
597    "python-dateutil",
598    "pytz",
599    "markdown",
600    "pypdf",
601    "reportlab",
602    "python-docx",
603];
604
605/// The name to pass to [`INSTALL`]: `py:<name>` for Python libraries, a Debian-style name
606/// otherwise; refuses anything that isn't a plain package name.
607pub fn install_name(raw: &str) -> Result<String, String> {
608    let p = raw.trim();
609    let (py, p) = match p.strip_prefix("python3Packages.").or_else(|| p.strip_prefix("python3.pkgs.")) {
610        Some(rest) => (true, rest),
611        None => (false, p),
612    };
613    let ok = !p.is_empty() && p.len() <= 100 && !p.starts_with(['-', '.']) && p.chars().all(|c| c.is_ascii_alphanumeric() || "-_.+=<>!~,".contains(c));
614    if !ok {
615        return Err(format!("{raw:?} is not a package name (like \"jq\" or \"pandas\")"));
616    }
617    let lower = p.to_ascii_lowercase();
618    let base = lower.split(['=', '<', '>', '!', '~']).next().unwrap_or(&lower);
619    let pip = py || PIP_NAMES.contains(&base) || super::nix::PYTHON_IMPORTS.iter().any(|(_, pkg)| *pkg == base);
620    if pip {
621        return Ok(format!("py:{p}"));
622    }
623    let os = match base {
624        "poppler_utils" | "poppler" => "poppler-utils",
625        "gnumake" => "make",
626        "python" => "python3",
627        "fd" => "fd-find",
628        "nodejs_22" | "nodejs_20" | "node" => "nodejs",
629        _ => base,
630    };
631    Ok(os.to_owned())
632}
633
634/// A per-run temp folder under the container's temp base, removed when dropped.
635#[derive(Debug)]
636pub struct RunTmp(PathBuf);
637
638impl RunTmp {
639    pub fn new(base: &Path) -> Result<Self, String> {
640        for attempt in 0..16u32 {
641            let nanos = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(|d| d.subsec_nanos()).unwrap_or(0);
642            let p = base.join(format!("run-{}-{nanos:x}-{attempt}", std::process::id()));
643            match std::fs::create_dir(&p) {
644                Ok(()) => return Ok(Self(p)),
645                Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
646                Err(e) => return Err(format!("can't create a temp folder in {}: {e}", base.display())),
647            }
648        }
649        Err("can't create a temp folder".into())
650    }
651
652    pub fn path(&self) -> &Path {
653        &self.0
654    }
655}
656
657impl Drop for RunTmp {
658    fn drop(&mut self) {
659        let _ = std::fs::remove_dir_all(&self.0);
660    }
661}
662
663#[cfg(test)]
664mod tests {
665    use super::*;
666
667    #[test]
668    fn names_are_stable_and_valid() {
669        let a = container_name(Path::new("/home/me/My Project"));
670        assert_eq!(a, container_name(Path::new("/home/me/My Project")));
671        assert_ne!(a, container_name(Path::new("/home/you/My Project")));
672        assert!(a.starts_with("byob-myproject-") && a.chars().all(|c| c.is_ascii_alphanumeric() || c == '-'), "{a}");
673        assert!(container_name(Path::new("/")).starts_with("byob-ws-"));
674    }
675
676    #[test]
677    fn install_names() {
678        assert_eq!(install_name("jq").unwrap(), "jq");
679        assert_eq!(install_name("pandas").unwrap(), "py:pandas");
680        assert_eq!(install_name("scikit-learn").unwrap(), "py:scikit-learn");
681        assert_eq!(install_name("python3Packages.six").unwrap(), "py:six");
682        assert_eq!(install_name("numpy>=2").unwrap(), "py:numpy>=2");
683        assert_eq!(install_name("poppler_utils").unwrap(), "poppler-utils");
684        for bad in ["", "-y", "a b", "x;rm -rf /", "$(id)"] {
685            assert!(install_name(bad).is_err(), "{bad}");
686        }
687    }
688
689    #[test]
690    fn install_reports() {
691        let r = parse_install("BYOB-PM apt-get\nBYOB-OS jq ripgrep\nBYOB-PIP pandas\nBYOB-MISSING nosuch\n");
692        assert_eq!(
693            r,
694            Report {
695                manager: "apt-get".into(),
696                os: vec!["jq".into(), "ripgrep".into()],
697                os_failed: vec![],
698                pip: vec!["pandas".into()],
699                missing: vec!["nosuch".into()]
700            }
701        );
702        let i = r.describe("");
703        assert!(i.failed && i.missing == vec!["nosuch".to_owned()]);
704        assert!(
705            i.text.contains("with apt-get: jq, ripgrep") && i.text.contains("pip: pandas") && i.text.contains("Not found with apt-get or pip: \"nosuch\""),
706            "{}",
707            i.text
708        );
709        let ok = parse_install("BYOB-PM apk\nBYOB-OS jq\n").describe("");
710        assert!(!ok.failed && ok.text.contains("with apk: jq"));
711    }
712
713    #[test]
714    fn stamps_change_with_the_config() {
715        let rt = Runtime { kind: RuntimeKind::Docker, program: "docker".into() };
716        let a = Spec::default_image("python:3-slim");
717        let b = Spec::default_image("debian:stable-slim");
718        assert_eq!(stamp(&a, &rt), stamp(&a.clone(), &rt));
719        assert_ne!(stamp(&a, &rt), stamp(&b, &rt));
720        let podman = Runtime { kind: RuntimeKind::Podman, program: "podman".into() };
721        assert_ne!(stamp(&a, &rt), stamp(&a, &podman));
722        assert_eq!(Containers::new(rt.clone(), Some("--bad".into())).default_image, DEFAULT_IMAGE);
723        assert_eq!(Containers::new(rt, Some("alpine:3".into())).default_image, "alpine:3");
724    }
725
726    #[test]
727    fn the_daemon_being_down_says_what_to_do() {
728        let rt = Runtime { kind: RuntimeKind::Docker, program: "docker".into() };
729        let m = unreachable_message(&rt, "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?");
730        assert!(m.contains("Docker isn't running") && m.contains("Cannot connect") && m.contains("workspace's settings"), "{m}");
731    }
732}