Skip to main content

runner_manager_platform/
runner_env.rs

1//! The environment a native runner starts with, beyond what the daemon has.
2//!
3//! A runner inherits the daemon's environment, and a service's environment is
4//! not a login shell's. On macOS launchd starts the agent with
5//! `PATH=/usr/bin:/bin:/usr/sbin:/sbin` and no `LANG`, so a job finds no
6//! Homebrew tool (`actions/cache` falls back from `zstd` to gzip and never
7//! hits), and nothing the operator put in a shell profile reaches it. A classic
8//! runner gets those from the `.env` and `.path` files its `config.sh` writes;
9//! a just-in-time runner never runs `config.sh`.
10//!
11//! Two things fill the gap, applied to every native runner in this order, each
12//! overriding the one before:
13//!
14//! 1. **Platform defaults** ([`platform_defaults`]): on macOS, Homebrew's
15//!    directories ahead of the inherited `PATH` and a UTF-8 `LANG`; on Windows,
16//!    a profile of the runner's own (`USERPROFILE`, `HOME`, `APPDATA`,
17//!    `LOCALAPPDATA`) inside the attempt, so concurrent jobs stop sharing the
18//!    service account's `~/.bun`, npm cache and pnpm store. Every platform
19//!    also gets `POWERSHELL_TELEMETRY_OPTOUT=1` unless the daemon sets it
20//!    ([`POWERSHELL_TELEMETRY_OPTOUT`]).
21//! 2. **The host's `runner.env`** ([`RunnerEnv`]): `KEY=VALUE` lines in the
22//!    configuration directory, edited with `runner-manager host env`. A name
23//!    set here replaces the platform default of the same name outright.
24//!
25//! The per-attempt temporary directory (`TMPDIR`, `TEMP`, `TMP`) is applied
26//! last and cannot be overridden, and neither can GitHub's
27//! `ACTIONS_RUNNER_INPUT_*` inputs, one of which carries the JIT
28//! configuration: [`RESERVED_NAMES`] and [`RESERVED_PREFIX`].
29//!
30//! # Not a secret store
31//!
32//! The file is plain text in the configuration directory and every runner's
33//! environment can read it back. Nothing here logs or prints a value except
34//! `host env show`, which exists to show them; errors name a line or a
35//! variable, never what it was set to.
36
37use std::ffi::{OsStr, OsString};
38use std::fs;
39use std::io::{self, Write as _};
40use std::path::{Path, PathBuf};
41
42/// The file's name inside the configuration directory.
43pub const RUNNER_ENV_FILE: &str = "runner.env";
44
45/// Names `runner.env` may not set, compared without regard to case: the
46/// temporary directory is per attempt, and cleanup and isolation rely on it.
47pub const RESERVED_NAMES: [&str; 3] = ["TMPDIR", "TEMP", "TMP"];
48
49/// The prefix of every name `runner.env` may not set: the listener reads each
50/// such variable as a command-line input, including the JIT configuration
51/// that registers it.
52pub const RESERVED_PREFIX: &str = "ACTIONS_RUNNER_INPUT_";
53
54/// macOS directories put ahead of the inherited `PATH`, when they exist and
55/// are not on it already: Apple Silicon Homebrew, then Intel Homebrew.
56pub const MACOS_TOOL_DIRECTORIES: [&str; 3] =
57    ["/opt/homebrew/bin", "/opt/homebrew/sbin", "/usr/local/bin"];
58
59/// The `PATH` launchd gives a service, kept behind Homebrew's directories when
60/// the daemon has no `PATH` of its own.
61pub const MACOS_SYSTEM_PATH: &str = "/usr/bin:/bin:/usr/sbin:/sbin";
62
63/// The `LANG` a macOS runner gets when the daemon has none. It is what
64/// `config.sh` would have recorded from a default macOS terminal, and without a
65/// UTF-8 locale Ruby, CocoaPods and Python mis-handle non-ASCII text.
66pub const MACOS_DEFAULT_LANG: &str = "en_US.UTF-8";
67
68/// The `runner.env` path for a configuration directory.
69#[must_use]
70pub fn path_in(config_dir: &Path) -> PathBuf {
71    config_dir.join(RUNNER_ENV_FILE)
72}
73
74/// Why a `runner.env` line or assignment was refused, or the file could not
75/// be read or written. No variant carries a value.
76#[derive(Debug, thiserror::Error)]
77pub enum RunnerEnvError {
78    #[error("{}is not KEY=VALUE", at(*.line))]
79    NotAnAssignment { line: Option<usize> },
80    #[error(
81        "{}the name before `=` is not a valid environment variable name; use letters, \
82         digits and `_`, not starting with a digit",
83        at(*.line)
84    )]
85    InvalidName { line: Option<usize> },
86    #[error(
87        "{}`{name}` is set by runner-manager for every runner and cannot be changed",
88        at(*.line)
89    )]
90    Reserved { line: Option<usize>, name: String },
91    #[error("line {line} sets `{name}` a second time")]
92    Duplicate { line: usize, name: String },
93    #[error(
94        "{}the value of `{name}` contains a line break or a NUL character, which runner.env \
95         cannot hold",
96        at(*.line)
97    )]
98    LineBreak { line: Option<usize>, name: String },
99    #[error("cannot {action} {}: {source}", path.display())]
100    Io {
101        action: &'static str,
102        path: PathBuf,
103        #[source]
104        source: io::Error,
105    },
106}
107
108fn at(line: Option<usize>) -> String {
109    line.map_or_else(String::new, |line| format!("line {line}: "))
110}
111
112/// One line of the file. Comments and blank lines are kept so that
113/// `host env set` and `unset` do not discard what an operator wrote by hand.
114#[derive(Debug, Clone, PartialEq, Eq)]
115enum Line {
116    Text(String),
117    Entry { name: String, value: String },
118}
119
120/// The parsed `runner.env`: ordered, one entry per name.
121#[derive(Debug, Clone, Default, PartialEq, Eq)]
122pub struct RunnerEnv {
123    lines: Vec<Line>,
124}
125
126impl RunnerEnv {
127    /// Parses the file's text. Blank lines and lines starting with `#` are
128    /// kept as text; every other line must be `NAME=VALUE`. The value is
129    /// everything after the first `=`, verbatim: no quoting, no expansion.
130    ///
131    /// # Errors
132    /// The first line that is not an assignment, has an invalid or reserved
133    /// name, or repeats a name.
134    pub fn parse(text: &str) -> Result<Self, RunnerEnvError> {
135        let mut env = Self::default();
136        for (index, raw) in text.lines().enumerate() {
137            let line = index + 1;
138            let raw = raw.strip_suffix('\r').unwrap_or(raw);
139            let trimmed = raw.trim_start();
140            if trimmed.is_empty() || trimmed.starts_with('#') {
141                env.lines.push(Line::Text(raw.to_owned()));
142                continue;
143            }
144            let (name, value) = trimmed
145                .split_once('=')
146                .ok_or(RunnerEnvError::NotAnAssignment { line: Some(line) })?;
147            let name = name.trim_end();
148            validate_name(name, Some(line))?;
149            // A NUL cannot reach a process environment: the launch would fail
150            // with nothing naming this file as the cause.
151            if value.contains('\0') {
152                return Err(RunnerEnvError::LineBreak {
153                    line: Some(line),
154                    name: name.to_owned(),
155                });
156            }
157            if env.get(name).is_some() {
158                return Err(RunnerEnvError::Duplicate {
159                    line,
160                    name: name.to_owned(),
161                });
162            }
163            env.lines.push(Line::Entry {
164                name: name.to_owned(),
165                value: value.to_owned(),
166            });
167        }
168        Ok(env)
169    }
170
171    /// Reads `path`; a file that does not exist is an empty environment.
172    ///
173    /// # Errors
174    /// [`RunnerEnvError::Io`] when the file exists and cannot be read, and the
175    /// [`Self::parse`] errors.
176    pub fn load(path: &Path) -> Result<Self, RunnerEnvError> {
177        match fs::read_to_string(path) {
178            Ok(text) => Self::parse(&text),
179            Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(Self::default()),
180            Err(source) => Err(RunnerEnvError::Io {
181                action: "read",
182                path: path.to_path_buf(),
183                source,
184            }),
185        }
186    }
187
188    /// Writes the file atomically: a reader sees the old file or the new one,
189    /// never a partial one. Created owner-only where the platform has modes,
190    /// since an operator may put something sensitive here regardless.
191    ///
192    /// On Unix the replacement keeps the existing file's owner and mode, and a
193    /// new file takes its directory's owner, best effort: the daemon may run as
194    /// another account than this command (a `sudo` edit of a user agent's
195    /// file), and a file it cannot read stops every native launch.
196    ///
197    /// # Errors
198    /// [`RunnerEnvError::Io`].
199    pub fn save(&self, path: &Path) -> Result<(), RunnerEnvError> {
200        let failed = |action, source| RunnerEnvError::Io {
201            action,
202            path: path.to_path_buf(),
203            source,
204        };
205        let parent = path.parent().unwrap_or_else(|| Path::new("."));
206        fs::create_dir_all(parent).map_err(|source| failed("create the directory of", source))?;
207        let mut temporary =
208            tempfile::NamedTempFile::new_in(parent).map_err(|source| failed("write", source))?;
209        temporary
210            .write_all(self.render().as_bytes())
211            .and_then(|()| temporary.as_file().sync_all())
212            .map_err(|source| failed("write", source))?;
213        #[cfg(unix)]
214        {
215            use std::os::unix::fs::{MetadataExt as _, PermissionsExt as _};
216            let existing = fs::metadata(path).ok();
217            if let Some(owner) = existing.clone().or_else(|| fs::metadata(parent).ok()) {
218                // Fails without privilege unless the owner is already this
219                // account, which is the case this exists for.
220                let _ = std::os::unix::fs::chown(
221                    temporary.path(),
222                    Some(owner.uid()),
223                    Some(owner.gid()),
224                );
225            }
226            if let Some(existing) = existing {
227                let mode = existing.permissions().mode() & 0o777;
228                temporary
229                    .as_file()
230                    .set_permissions(fs::Permissions::from_mode(mode))
231                    .map_err(|source| failed("write", source))?;
232            }
233        }
234        temporary
235            .persist(path)
236            .map(|_| ())
237            .map_err(|error| failed("replace", error.error))
238    }
239
240    /// The file's text.
241    fn render(&self) -> String {
242        let mut text = String::new();
243        for line in &self.lines {
244            match line {
245                Line::Text(raw) => text.push_str(raw),
246                Line::Entry { name, value } => {
247                    text.push_str(name);
248                    text.push('=');
249                    text.push_str(value);
250                }
251            }
252            text.push('\n');
253        }
254        text
255    }
256
257    /// Sets `name`, replacing its value in place if it is already set.
258    /// Returns whether it was already set.
259    ///
260    /// # Errors
261    /// An invalid or reserved name, or a value with a line break.
262    pub fn set(&mut self, name: &str, value: &str) -> Result<bool, RunnerEnvError> {
263        validate_name(name, None)?;
264        if value.contains(['\n', '\r', '\0']) {
265            return Err(RunnerEnvError::LineBreak {
266                line: None,
267                name: name.to_owned(),
268            });
269        }
270        for line in &mut self.lines {
271            if let Line::Entry {
272                name: existing,
273                value: current,
274            } = line
275                && same_name(existing, name)
276            {
277                *current = value.to_owned();
278                return Ok(true);
279            }
280        }
281        self.lines.push(Line::Entry {
282            name: name.to_owned(),
283            value: value.to_owned(),
284        });
285        Ok(false)
286    }
287
288    /// Removes `name`. Returns whether it was set.
289    pub fn unset(&mut self, name: &str) -> bool {
290        let before = self.lines.len();
291        self.lines.retain(
292            |line| !matches!(line, Line::Entry { name: existing, .. } if same_name(existing, name)),
293        );
294        self.lines.len() != before
295    }
296
297    /// The value of `name`, if set.
298    #[must_use]
299    pub fn get(&self, name: &str) -> Option<&str> {
300        self.entries()
301            .find(|(existing, _)| same_name(existing, name))
302            .map(|(_, value)| value)
303    }
304
305    /// Every `(name, value)`, in file order.
306    pub fn entries(&self) -> impl Iterator<Item = (&str, &str)> {
307        self.lines.iter().filter_map(|line| match line {
308            Line::Entry { name, value } => Some((name.as_str(), value.as_str())),
309            Line::Text(_) => None,
310        })
311    }
312
313    /// How many variables are set.
314    #[must_use]
315    pub fn len(&self) -> usize {
316        self.entries().count()
317    }
318
319    /// Whether no variable is set.
320    #[must_use]
321    pub fn is_empty(&self) -> bool {
322        self.len() == 0
323    }
324}
325
326/// Splits a `NAME=VALUE` command-line argument.
327///
328/// # Errors
329/// [`RunnerEnvError::NotAnAssignment`] without an `=`.
330pub fn split_assignment(raw: &str) -> Result<(&str, &str), RunnerEnvError> {
331    raw.split_once('=')
332        .ok_or(RunnerEnvError::NotAnAssignment { line: None })
333}
334
335/// Whether `name` is one this file may set: a portable environment variable
336/// name that is not [reserved](RESERVED_NAMES).
337fn validate_name(name: &str, line: Option<usize>) -> Result<(), RunnerEnvError> {
338    let mut chars = name.chars();
339    let valid = chars
340        .next()
341        .is_some_and(|first| first.is_ascii_alphabetic() || first == '_')
342        && chars.all(|c| c.is_ascii_alphanumeric() || c == '_');
343    if !valid {
344        return Err(RunnerEnvError::InvalidName { line });
345    }
346    if is_reserved(name) {
347        return Err(RunnerEnvError::Reserved {
348            line,
349            name: name.to_owned(),
350        });
351    }
352    Ok(())
353}
354
355/// Whether `name` is reserved, without regard to case: Windows treats `Tmp`
356/// and `TMP` as one variable.
357fn is_reserved(name: &str) -> bool {
358    let upper = name.to_ascii_uppercase();
359    upper.starts_with(RESERVED_PREFIX) || RESERVED_NAMES.contains(&upper.as_str())
360}
361
362/// Whether two names are the same variable on this platform.
363pub(crate) fn same_name(a: &str, b: &str) -> bool {
364    if cfg!(windows) {
365        a.eq_ignore_ascii_case(b)
366    } else {
367        a == b
368    }
369}
370
371// ---------------------------------------------------------------------------
372// Platform defaults
373// ---------------------------------------------------------------------------
374
375/// Which platform's defaults to compute. A parameter rather than a `cfg` so
376/// that every leg of CI tests every platform's rules.
377#[derive(Debug, Clone, Copy, PartialEq, Eq)]
378pub enum RunnerPlatform {
379    Windows,
380    MacOs,
381    Linux,
382}
383
384impl RunnerPlatform {
385    /// The platform this binary was built for.
386    #[must_use]
387    pub const fn current() -> Self {
388        if cfg!(windows) {
389            Self::Windows
390        } else if cfg!(target_os = "macos") {
391            Self::MacOs
392        } else {
393            Self::Linux
394        }
395    }
396}
397
398/// The variable that turns PowerShell 7's telemetry off. Every native runner
399/// gets it as `1` ([`POWERSHELL_TELEMETRY_OPTOUT_VALUE`]) unless the daemon's
400/// environment already sets it to a non-empty value, which the runner then
401/// inherits as it is. An empty value counts as unset, as it does for
402/// PowerShell. `runner.env` replaces it like any other default, so
403/// `POWERSHELL_TELEMETRY_OPTOUT=0` there turns telemetry back on.
404///
405/// Why: `pwsh` 7.6.6 and earlier, on a start that finds no `telemetry.uuid`
406/// in its cache directory, take the session-wide named mutex
407/// `CreateUniqueUserId` twice and release it once, so the first such shell
408/// keeps it until it exits, and every other such shell waits for it with no
409/// timeout. On Windows that cache directory follows `USERPROFILE`, which is
410/// per attempt here, so the first shell of every job has no file, and every
411/// service runner shares session 0. Concurrent jobs' step shells then hang at
412/// startup, with no output, until the first job's shell exits. PowerShell
413/// reads the opt-out before any of that work and skips all of it. macOS and
414/// Linux runners share the account's cache directory, so the file is there
415/// after the first shell ever; they get the opt-out as a precaution.
416pub const POWERSHELL_TELEMETRY_OPTOUT: &str = "POWERSHELL_TELEMETRY_OPTOUT";
417
418/// The value [`POWERSHELL_TELEMETRY_OPTOUT`] is given. PowerShell accepts
419/// `1`, `true` and `yes`, without regard to case.
420pub const POWERSHELL_TELEMETRY_OPTOUT_VALUE: &str = "1";
421
422/// What the daemon's own environment holds, as far as the defaults care.
423#[derive(Debug, Clone, Default)]
424pub struct Inherited {
425    pub path: Option<OsString>,
426    /// Whether `LANG` or `LC_ALL` is set.
427    pub has_locale: bool,
428    /// Whether [`POWERSHELL_TELEMETRY_OPTOUT`] is set to a non-empty value.
429    pub has_powershell_telemetry_optout: bool,
430    /// Whether `HOME` names a directory this process may write.
431    ///
432    /// A Linux boot service runs as `root` with `HOME=/root`, which
433    /// `ProtectSystem=strict` makes read-only and `ProtectHome=tmpfs` empties,
434    /// so a job's `~/.bun`, `~/.docker` or global npm install has nowhere to go.
435    pub home_writable: bool,
436}
437
438impl Inherited {
439    /// This process's environment.
440    #[must_use]
441    pub fn current() -> Self {
442        let mut inherited = Self::from_env(|name| std::env::var_os(name));
443        inherited.home_writable = std::env::var_os("HOME").is_some_and(|home| writable(&home));
444        inherited
445    }
446
447    /// The environment `var` reads, one variable at a time.
448    fn from_env(var: impl Fn(&str) -> Option<OsString>) -> Self {
449        Self {
450            path: var("PATH"),
451            has_locale: var("LANG").is_some() || var("LC_ALL").is_some(),
452            has_powershell_telemetry_optout: var(POWERSHELL_TELEMETRY_OPTOUT)
453                .is_some_and(|value| !value.is_empty()),
454            home_writable: false,
455        }
456    }
457}
458
459/// Whether this process may create entries in `directory`.
460fn writable(directory: &OsStr) -> bool {
461    #[cfg(unix)]
462    {
463        use std::os::unix::ffi::OsStrExt as _;
464        let Ok(path) = std::ffi::CString::new(directory.as_bytes()) else {
465            return false;
466        };
467        // SAFETY: `path` is a valid NUL-terminated string that outlives the
468        // call, and `access` only reads it.
469        unsafe { libc::access(path.as_ptr(), libc::W_OK | libc::X_OK) == 0 }
470    }
471    #[cfg(not(unix))]
472    {
473        Path::new(directory).is_dir()
474    }
475}
476
477/// The directory inside an attempt that is its runner's profile on Windows,
478/// and its home on Linux when the daemon's own cannot be written.
479pub const RUNNER_HOME_DIR: &str = "home";
480
481/// The variables [`platform_defaults`] sets on Windows, in order: the profile
482/// directory twice, then its roaming and local application data.
483pub const WINDOWS_PROFILE_VARIABLES: [&str; 4] = ["USERPROFILE", "HOME", "APPDATA", "LOCALAPPDATA"];
484
485/// The [`platform_defaults`] that name a directory the caller must create.
486/// Creating them creates the profile directory above them too.
487pub(crate) const DIRECTORY_VARIABLES: [&str; 3] = ["HOME", "APPDATA", "LOCALAPPDATA"];
488
489/// The XDG base directories, relative to `HOME`, that a Linux home from
490/// [`platform_defaults`] starts with, as a login account's does. .NET's
491/// `Environment.GetFolderPath` answers an empty string for one that does not
492/// exist, and a tool that joins onto that answer then writes relative to its
493/// working directory: Unreal Build Tool's `ApplicationData/Epic` landed in a
494/// read-only engine directory and failed every build.
495pub(crate) const LINUX_HOME_DIRECTORIES: [&str; 3] = [".config", ".local/share", ".cache"];
496
497/// The directories the caller creates before starting a runner on `platform`
498/// with `defaults`: each of [`DIRECTORY_VARIABLES`], and on Linux the
499/// [`LINUX_HOME_DIRECTORIES`] inside the home.
500#[must_use]
501pub fn directories_to_create(
502    platform: RunnerPlatform,
503    defaults: &[(&'static str, OsString)],
504) -> Vec<PathBuf> {
505    let mut directories = Vec::new();
506    for (name, value) in defaults {
507        if !DIRECTORY_VARIABLES.contains(name) {
508            continue;
509        }
510        let directory = PathBuf::from(value);
511        if platform == RunnerPlatform::Linux && *name == "HOME" {
512            directories.extend(LINUX_HOME_DIRECTORIES.map(|sub| directory.join(sub)));
513        }
514        directories.push(directory);
515    }
516    directories
517}
518
519/// The variables `platform` sets for a runner whose attempt directory is
520/// `runtime`, before `runner.env` is applied.
521///
522/// - **macOS:** `PATH` with each of [`MACOS_TOOL_DIRECTORIES`] that exists
523///   (`exists`) and is not already listed put in front, when any is; `LANG`
524///   as [`MACOS_DEFAULT_LANG`] when the daemon has no locale.
525/// - **Windows:** `USERPROFILE` and `HOME` at `<runtime>\home`, and `APPDATA`
526///   and `LOCALAPPDATA` under it, as a logged-in profile lays them out. The
527///   directories are the caller's to create. Per attempt rather than shared,
528///   so one job's caches and configuration cannot reach the next job, and
529///   they go when the attempt's directory goes. Most of .NET's known-folder
530///   APIs (`Environment.GetFolderPath`) ask Windows rather than these
531///   variables and still answer with the service account's profile. Local
532///   application data is the exception: measured on Windows 11, it follows
533///   `USERPROFILE`, while roaming application data and the profile itself do
534///   not.
535/// - **Linux:** `HOME` at `<runtime>/home` when the daemon's own `HOME` cannot
536///   be written ([`Inherited::home_writable`]); nothing otherwise. A login
537///   service's `HOME` is the operator's, and stays theirs.
538///
539/// Then, on every platform, [`POWERSHELL_TELEMETRY_OPTOUT`] unless the daemon
540/// sets it.
541#[must_use]
542pub fn platform_defaults(
543    platform: RunnerPlatform,
544    runtime: &Path,
545    inherited: &Inherited,
546    exists: impl Fn(&Path) -> bool,
547) -> Vec<(&'static str, OsString)> {
548    let mut defaults = match platform {
549        RunnerPlatform::Linux if inherited.home_writable => Vec::new(),
550        RunnerPlatform::Linux => vec![("HOME", runtime.join(RUNNER_HOME_DIR).into_os_string())],
551        RunnerPlatform::Windows => {
552            let home = runtime.join(RUNNER_HOME_DIR);
553            let app_data = home.join("AppData");
554            let [user_profile, home_name, roaming, local] = WINDOWS_PROFILE_VARIABLES;
555            vec![
556                (user_profile, home.clone().into_os_string()),
557                (home_name, home.into_os_string()),
558                (roaming, app_data.join("Roaming").into_os_string()),
559                (local, app_data.join("Local").into_os_string()),
560            ]
561        }
562        RunnerPlatform::MacOs => {
563            let mut defaults = Vec::new();
564            let listed: Vec<&OsStr> = inherited
565                .path
566                .as_deref()
567                .map(|path| split_colon_path(path))
568                .unwrap_or_default();
569            let missing: Vec<&str> = MACOS_TOOL_DIRECTORIES
570                .into_iter()
571                .filter(|dir| exists(Path::new(dir)) && !listed.contains(&OsStr::new(dir)))
572                .collect();
573            if !missing.is_empty() {
574                let mut path = OsString::from(missing.join(":"));
575                path.push(":");
576                // With no `PATH` at all a program search falls back to the
577                // system's own directories; a `PATH` naming only Homebrew would
578                // take those away, so they are spelled out instead.
579                match inherited.path.as_deref().filter(|p| !p.is_empty()) {
580                    Some(inherited) => path.push(inherited),
581                    None => path.push(MACOS_SYSTEM_PATH),
582                }
583                defaults.push(("PATH", path));
584            }
585            if !inherited.has_locale {
586                defaults.push(("LANG", OsString::from(MACOS_DEFAULT_LANG)));
587            }
588            defaults
589        }
590    };
591    if !inherited.has_powershell_telemetry_optout {
592        defaults.push((
593            POWERSHELL_TELEMETRY_OPTOUT,
594            OsString::from(POWERSHELL_TELEMETRY_OPTOUT_VALUE),
595        ));
596    }
597    defaults
598}
599
600/// The entries of a `:`-separated `PATH`, as bytes on Unix and as text
601/// elsewhere (where this is only ever exercised by tests).
602fn split_colon_path(path: &OsStr) -> Vec<&OsStr> {
603    #[cfg(unix)]
604    {
605        use std::os::unix::ffi::OsStrExt;
606        path.as_bytes()
607            .split(|byte| *byte == b':')
608            .map(OsStr::from_bytes)
609            .collect()
610    }
611    #[cfg(not(unix))]
612    {
613        path.to_str()
614            .map(|text| text.split(':').map(OsStr::new).collect())
615            .unwrap_or_default()
616    }
617}
618
619/// The variables a native runner starts with on top of the daemon's
620/// environment, in the order they must be applied: the platform defaults, then
621/// the dependency caches (`crate::dependency_cache`), then `file`. Applied in
622/// order the last value for a name wins, as it does for `Command::env`, so
623/// `file` overrides a cache or a default of the same name.
624#[must_use]
625pub fn runner_environment(
626    defaults: Vec<(&'static str, OsString)>,
627    caches: Vec<(&'static str, OsString)>,
628    file: &RunnerEnv,
629) -> Vec<(OsString, OsString)> {
630    defaults
631        .into_iter()
632        .chain(caches)
633        .map(|(name, value)| (OsString::from(name), value))
634        .chain(
635            file.entries()
636                .map(|(name, value)| (OsString::from(name), OsString::from(value))),
637        )
638        .collect()
639}
640
641#[cfg(test)]
642mod tests {
643    use super::*;
644
645    #[test]
646    fn a_file_parses_keeps_comments_and_round_trips() {
647        let text = "# caches off the boot volume\n\nELECTRON_CACHE=/Volumes/NVME/cache/electron\n\
648                    npm_config_cache=/Volumes/NVME/cache/npm\nEMPTY=\nURL=https://x/?a=b\n";
649        let env = RunnerEnv::parse(text).unwrap();
650        assert_eq!(
651            env.entries().collect::<Vec<_>>(),
652            [
653                ("ELECTRON_CACHE", "/Volumes/NVME/cache/electron"),
654                ("npm_config_cache", "/Volumes/NVME/cache/npm"),
655                ("EMPTY", ""),
656                ("URL", "https://x/?a=b"),
657            ]
658        );
659        assert_eq!(env.render(), text);
660        assert_eq!(
661            RunnerEnv::parse("A=1\r\nB=2\r\n").unwrap().get("B"),
662            Some("2")
663        );
664    }
665
666    #[test]
667    fn a_bad_line_is_named_by_number_and_never_echoed() {
668        let secret = "ghp_notarealtokenbutshapedlikeone";
669        for (text, expected) in [
670            (format!("A=1\n{secret}\n"), "line 2: is not KEY=VALUE"),
671            (format!("A=1\n1BAD={secret}\n"), "line 2: the name"),
672            (
673                format!("TMP={secret}\n"),
674                "line 1: `TMP` is set by runner-manager",
675            ),
676            (
677                format!("actions_runner_input_url={secret}\n"),
678                "`actions_runner_input_url` is set by runner-manager",
679            ),
680            (
681                format!("A=1\nA={secret}\n"),
682                "line 2 sets `A` a second time",
683            ),
684            (
685                format!("A=1\nB={secret}\0\n"),
686                "line 2: the value of `B` contains a line break or a NUL",
687            ),
688        ] {
689            let error = RunnerEnv::parse(&text).unwrap_err().to_string();
690            assert!(error.contains(expected), "{error:?} lacks {expected:?}");
691            assert!(!error.contains(secret), "an error echoed a value: {error}");
692        }
693    }
694
695    #[test]
696    fn reserved_names_cover_the_temporary_directory_and_every_runner_input() {
697        for name in [
698            "TMPDIR",
699            "TEMP",
700            "TMP",
701            "Tmp",
702            "ACTIONS_RUNNER_INPUT_JITCONFIG",
703            "ACTIONS_RUNNER_INPUT_URL",
704        ] {
705            assert!(is_reserved(name), "{name}");
706        }
707        for name in ["TMPX", "PATH", "ACTIONS_RUNNER_HOOK_JOB_STARTED", "HOME"] {
708            assert!(!is_reserved(name), "{name}");
709        }
710    }
711
712    #[test]
713    fn set_replaces_in_place_and_unset_removes_only_the_entry() {
714        let mut env = RunnerEnv::parse("# keep me\nA=1\nB=2\n").unwrap();
715        assert!(env.set("A", "one").unwrap());
716        assert!(!env.set("C", "3").unwrap());
717        assert!(env.unset("B"));
718        assert!(!env.unset("B"));
719        assert_eq!(env.render(), "# keep me\nA=one\nC=3\n");
720        assert!(matches!(
721            env.set("D", "two\nlines"),
722            Err(RunnerEnvError::LineBreak { .. })
723        ));
724        assert!(matches!(
725            env.set("TEMP", "x"),
726            Err(RunnerEnvError::Reserved { .. })
727        ));
728        assert!(matches!(
729            env.set("NOT-A-NAME", "x"),
730            Err(RunnerEnvError::InvalidName { .. })
731        ));
732    }
733
734    #[cfg(unix)]
735    #[test]
736    fn saving_keeps_the_mode_of_the_file_it_replaces() {
737        use std::os::unix::fs::PermissionsExt as _;
738        let directory = tempfile::tempdir().unwrap();
739        let path = path_in(directory.path());
740        let mut env = RunnerEnv::default();
741        env.set("A", "1").unwrap();
742        env.save(&path).unwrap();
743        let mode = |path: &Path| fs::metadata(path).unwrap().permissions().mode() & 0o777;
744        assert_eq!(mode(&path), 0o600, "a new file is owner-only");
745
746        fs::set_permissions(&path, fs::Permissions::from_mode(0o644)).unwrap();
747        env.set("B", "2").unwrap();
748        env.save(&path).unwrap();
749        assert_eq!(mode(&path), 0o644, "the replacement reset the file's mode");
750    }
751
752    #[test]
753    fn a_missing_file_is_empty_and_a_saved_file_loads_back() {
754        let directory = tempfile::tempdir().unwrap();
755        let path = path_in(directory.path());
756        assert!(RunnerEnv::load(&path).unwrap().is_empty());
757
758        let mut env = RunnerEnv::default();
759        env.set("npm_config_cache", "/cache/npm").unwrap();
760        env.save(&path).unwrap();
761        assert_eq!(RunnerEnv::load(&path).unwrap(), env);
762        assert_eq!(
763            fs::read_to_string(&path).unwrap(),
764            "npm_config_cache=/cache/npm\n"
765        );
766    }
767
768    fn defaults(platform: RunnerPlatform, inherited: &Inherited) -> Vec<(&'static str, OsString)> {
769        platform_defaults(platform, Path::new("/rman/a1"), inherited, |dir| {
770            dir != Path::new("/usr/local/bin")
771        })
772    }
773
774    #[test]
775    fn macos_puts_existing_homebrew_directories_ahead_of_the_service_path() {
776        let launchd = Inherited {
777            path: Some("/usr/bin:/bin:/usr/sbin:/sbin".into()),
778            has_locale: false,
779            ..Inherited::default()
780        };
781        assert_eq!(
782            defaults(RunnerPlatform::MacOs, &launchd),
783            [
784                (
785                    "PATH",
786                    OsString::from(
787                        "/opt/homebrew/bin:/opt/homebrew/sbin:/usr/bin:/bin:/usr/sbin:/sbin"
788                    )
789                ),
790                ("LANG", OsString::from(MACOS_DEFAULT_LANG)),
791                telemetry_optout(),
792            ]
793        );
794
795        // A directory already listed is not added twice, and a daemon with a
796        // locale keeps it.
797        let login = Inherited {
798            path: Some("/opt/homebrew/bin:/opt/homebrew/sbin:/usr/bin".into()),
799            has_locale: true,
800            ..Inherited::default()
801        };
802        assert_eq!(
803            defaults(RunnerPlatform::MacOs, &login),
804            [telemetry_optout()]
805        );
806
807        // A daemon with no PATH keeps the system directories behind Homebrew's.
808        let bare = Inherited {
809            path: None,
810            has_locale: true,
811            ..Inherited::default()
812        };
813        assert_eq!(
814            defaults(RunnerPlatform::MacOs, &bare),
815            [
816                (
817                    "PATH",
818                    OsString::from(format!(
819                        "/opt/homebrew/bin:/opt/homebrew/sbin:{MACOS_SYSTEM_PATH}"
820                    ))
821                ),
822                telemetry_optout(),
823            ]
824        );
825    }
826
827    #[test]
828    fn windows_gives_each_runner_a_profile_inside_its_attempt() {
829        let windows = defaults(RunnerPlatform::Windows, &Inherited::default());
830        let home = Path::new("/rman/a1").join(RUNNER_HOME_DIR);
831        assert_eq!(
832            windows,
833            [
834                ("USERPROFILE", home.clone().into_os_string()),
835                ("HOME", home.clone().into_os_string()),
836                (
837                    "APPDATA",
838                    home.join("AppData").join("Roaming").into_os_string()
839                ),
840                (
841                    "LOCALAPPDATA",
842                    home.join("AppData").join("Local").into_os_string()
843                ),
844                telemetry_optout(),
845            ]
846        );
847        let writable = Inherited {
848            home_writable: true,
849            ..Inherited::default()
850        };
851        assert_eq!(
852            defaults(RunnerPlatform::Linux, &writable),
853            [telemetry_optout()]
854        );
855    }
856
857    #[test]
858    fn a_linux_home_starts_with_the_xdg_base_directories() {
859        let home = Path::new("/rman/a1").join(RUNNER_HOME_DIR);
860        let linux = defaults(RunnerPlatform::Linux, &Inherited::default());
861        assert_eq!(
862            directories_to_create(RunnerPlatform::Linux, &linux),
863            [
864                home.join(".config"),
865                home.join(".local/share"),
866                home.join(".cache"),
867                home.clone(),
868            ]
869        );
870        let writable = Inherited {
871            home_writable: true,
872            ..Inherited::default()
873        };
874        let own_home = defaults(RunnerPlatform::Linux, &writable);
875        assert!(directories_to_create(RunnerPlatform::Linux, &own_home).is_empty());
876        let windows = defaults(RunnerPlatform::Windows, &Inherited::default());
877        assert_eq!(
878            directories_to_create(RunnerPlatform::Windows, &windows),
879            [
880                home.clone(),
881                home.join("AppData").join("Roaming"),
882                home.join("AppData").join("Local"),
883            ]
884        );
885    }
886
887    #[test]
888    fn linux_gives_a_runner_its_own_home_when_the_services_is_read_only() {
889        assert_eq!(
890            defaults(RunnerPlatform::Linux, &Inherited::default()),
891            [
892                (
893                    "HOME",
894                    Path::new("/rman/a1").join(RUNNER_HOME_DIR).into_os_string()
895                ),
896                telemetry_optout(),
897            ]
898        );
899        assert!(DIRECTORY_VARIABLES.contains(&"HOME"));
900        #[cfg(unix)]
901        {
902            let directory = tempfile::tempdir().unwrap();
903            assert!(writable(directory.path().as_os_str()));
904            assert!(!writable(OsStr::new("/nonexistent/runner-manager-home")));
905        }
906    }
907
908    fn telemetry_optout() -> (&'static str, OsString) {
909        (
910            POWERSHELL_TELEMETRY_OPTOUT,
911            OsString::from(POWERSHELL_TELEMETRY_OPTOUT_VALUE),
912        )
913    }
914
915    /// The daemon's own opt-out counts only when it says something: PowerShell
916    /// reads an empty value as unset, so an empty one is replaced.
917    #[test]
918    fn the_daemon_opt_out_is_read_from_its_environment_and_empty_is_unset() {
919        let with = |value: Option<&str>| {
920            Inherited::from_env(|name| {
921                (name == POWERSHELL_TELEMETRY_OPTOUT)
922                    .then_some(value)
923                    .flatten()
924                    .map(OsString::from)
925            })
926            .has_powershell_telemetry_optout
927        };
928        assert!(with(Some("0")));
929        assert!(with(Some("1")));
930        assert!(!with(Some("")));
931        assert!(!with(None));
932    }
933
934    /// A daemon that already sets the opt-out, to any non-empty value, keeps
935    /// it: nothing is set over it, so the runner inherits the daemon's own.
936    #[test]
937    fn a_daemon_powershell_telemetry_setting_is_left_alone() {
938        let daemon_decided = Inherited {
939            has_powershell_telemetry_optout: true,
940            ..Inherited::default()
941        };
942        for platform in [
943            RunnerPlatform::Windows,
944            RunnerPlatform::MacOs,
945            RunnerPlatform::Linux,
946        ] {
947            assert!(
948                defaults(platform, &daemon_decided)
949                    .iter()
950                    .all(|(name, _)| *name != POWERSHELL_TELEMETRY_OPTOUT),
951                "{platform:?} set the opt-out over the daemon's own value"
952            );
953        }
954    }
955
956    #[test]
957    fn runner_env_replaces_a_default_of_the_same_name_and_adds_the_rest() {
958        let file = RunnerEnv::parse("PATH=/custom/bin\nELECTRON_CACHE=/cache/electron\n").unwrap();
959        let defaults = vec![
960            ("PATH", OsString::from("/opt/homebrew/bin:/usr/bin")),
961            ("LANG", OsString::from(MACOS_DEFAULT_LANG)),
962        ];
963        assert_eq!(
964            runner_environment(defaults, Vec::new(), &file),
965            [
966                (
967                    OsString::from("PATH"),
968                    OsString::from("/opt/homebrew/bin:/usr/bin")
969                ),
970                (OsString::from("LANG"), OsString::from(MACOS_DEFAULT_LANG)),
971                (OsString::from("PATH"), OsString::from("/custom/bin")),
972                (
973                    OsString::from("ELECTRON_CACHE"),
974                    OsString::from("/cache/electron")
975                ),
976            ]
977        );
978    }
979
980    /// Platform defaults < dependency caches < `runner.env`: a cache variable
981    /// replaces a default of the same name, and `runner.env` replaces both.
982    #[test]
983    fn caches_sit_between_the_platform_defaults_and_runner_env() {
984        let file = RunnerEnv::parse("npm_config_cache=/operator/npm\n").unwrap();
985        let defaults = vec![("HOME", OsString::from("/attempt/home"))];
986        let caches = vec![
987            ("npm_config_cache", OsString::from("/cache/o/r/npm")),
988            ("HOME", OsString::from("/cache-would-never-set-this")),
989        ];
990        let applied = runner_environment(defaults, caches, &file);
991        let last = |name: &str| {
992            applied
993                .iter()
994                .rev()
995                .find(|(n, _)| n == name)
996                .map(|(_, v)| v.clone())
997        };
998        assert_eq!(last("npm_config_cache"), Some("/operator/npm".into()));
999        assert_eq!(last("HOME"), Some("/cache-would-never-set-this".into()));
1000        let position = |value: &str| applied.iter().position(|(_, v)| v == value).unwrap();
1001        assert!(position("/attempt/home") < position("/cache/o/r/npm"));
1002        assert!(position("/cache/o/r/npm") < position("/operator/npm"));
1003    }
1004}