Skip to main content

runnerd_core/
buildcache.rs

1//! The build cache every runner shares (ADR 0052, 0053, 0083): the entries of Gradle's HTTP build cache, and of the
2//! other tools the runner image points at it, Turborepo's and Nx's among them, kept per repository in a directory of
3//! the daemon's and served to each runner on a Unix socket of its own, which the runner image forwards to
4//! `127.0.0.1`. Owns the entries, the size limit, the sockets, and what each runner was served and stored. Which
5//! socket a request came in on is who sent it; no job can claim another's. It never decides whether a job may write:
6//! the engine tells it (`Writes`), from what GitHub says of the job. It never logs a request's headers, which may
7//! carry a tool's token. Where the config turns it on, the same socket serves GitHub Actions' cache (`actions`, ADR
8//! 0082) from the same entries' directory and limits.
9
10pub(crate) mod actions;
11mod serve;
12mod turbo;
13
14use std::collections::{BTreeSet, HashMap};
15use std::io;
16use std::os::unix::fs::PermissionsExt;
17use std::path::{Path, PathBuf};
18use std::sync::{Arc, Mutex};
19
20use tokio::net::UnixListener;
21use tokio::sync::Notify;
22use tokio::task::{JoinHandle, JoinSet};
23use tracing::warn;
24
25use crate::api::BuildCacheCounts;
26use crate::config::BuildCacheWriters;
27use crate::github::{PullRequest, RunTrigger};
28use crate::sync::lock;
29
30/// Where a runner container mounts its socket's directory, read-only (`image/entrypoint.sh`).
31pub const MOUNT: &str = "/run/runnerd-build-cache";
32
33/// The socket's name in that directory.
34pub const SOCKET: &str = "cache.sock";
35
36/// A file in that directory when the runner's socket serves GitHub Actions' cache too: the image forwards it for
37/// node actions and BuildKit only then (`image/build-cache.sh`).
38pub const ACTIONS_MARKER: &str = "actions";
39
40/// The directory of the entries, in the build cache's directory: nothing else there is counted or trimmed.
41const ENTRIES: &str = "entries";
42
43/// Where uploads are written before they become entries, in the build cache's directory; emptied at start.
44const UPLOADS: &str = "uploads";
45
46/// What an entry or upload counts for at least against the size limit, in bytes: its file's inode and directory
47/// entry cost the disk and the index something even when it is empty, so the limit also bounds how many there are.
48const MIN_CHARGE: u64 = 4 << 10;
49
50/// The uploads one runner may hold while its writes are undecided; past them, its uploads are refused.
51const MAX_HELD: usize = 10_000;
52
53/// The connections one runner's socket serves at once; more wait to be accepted. Above the connection pools of the
54/// tools it serves (Bazel opens 100).
55const MAX_CONNECTIONS: usize = 256;
56
57/// What `bytes` of an entry or upload count for against the size limit.
58fn charge(bytes: u64) -> u64 {
59    bytes.max(MIN_CHARGE)
60}
61
62/// Whether a runner's job may write entries.
63#[derive(Debug, Clone, Copy, PartialEq, Eq)]
64pub enum Writes {
65    /// Not known yet: what it sends is held until it is.
66    Undecided,
67    /// GitHub says it runs a push, scheduled or manually started run of a branch that may write, or, where the
68    /// repository lets them, a pull request of its own branches that people opened.
69    Allowed,
70    /// Anything else: another pull request, another branch, or a job GitHub does not place on this runner.
71    Refused,
72}
73
74/// Whether a runner's socket serves GitHub Actions' cache besides the build cache's tools (ADR 0082).
75#[derive(Debug, Clone, Copy, PartialEq, Eq)]
76pub enum ActionsCache {
77    /// It does: the image points the job's `actions/cache`, `setup-*` caches and BuildKit's `type=gha` at it.
78    Served,
79    /// It does not: the job uses GitHub's cache service.
80    Off,
81}
82
83/// The scopes of a runner's GitHub Actions cache entries, as GitHub's: refs, `refs/heads/<branch>` or
84/// `refs/pull/<number>/merge`, from what GitHub said of its job (ADR 0082).
85#[derive(Debug, Clone, Default, PartialEq, Eq)]
86pub struct Scopes {
87    /// Its run's own ref, where its entries go and what it reads first when its writes are `Allowed`: its branch's
88    /// for a branch's run, its pull request's for a pull request's. `None` when it has none, as a run GitHub ties
89    /// to several pull requests.
90    pub own: Option<String>,
91    /// What it reads next when its writes are `Allowed`: the branch its pull request merges into.
92    pub base: Option<String>,
93    /// Its repository's default branch, whose entries every job of the repository reads last.
94    pub default: Option<String>,
95}
96
97/// The events whose runs may write: they run code that reached a branch, never a pull request's.
98const WRITING_EVENTS: [&str; 3] = ["push", "schedule", "workflow_dispatch"];
99
100/// The event of a pull request's run that `BuildCacheWriters::PullRequests` lets write. Never
101/// `pull_request_target`, which runs with the repository's secrets whatever the pull request's head is.
102pub const PULL_REQUEST_EVENT: &str = "pull_request";
103
104/// Whether `runner`'s job may write, from what GitHub says: the runner it placed the job on (`job_runner`, which
105/// a job cannot forge as it can its runner's log), and its run's trigger. A push, scheduled or manually started run
106/// of `repository` itself on one of `branches` may. With `writers` at `PullRequests`, so may a `pull_request` run of
107/// one of the repository's own branches that people started, once GitHub also says each of its pull requests was
108/// opened by one (`opened_by_user`). `Undecided` while GitHub places the job on no runner.
109pub fn writes(
110    runner: &str,
111    job_runner: Option<&str>,
112    repository: &str,
113    trigger: &RunTrigger,
114    branches: &[String],
115    writers: BuildCacheWriters,
116) -> Writes {
117    match job_runner {
118        None => Writes::Undecided,
119        Some(placed) if placed != runner => Writes::Refused,
120        Some(_) if !same_repository(trigger.head_repository.as_deref(), repository) => {
121            Writes::Refused
122        }
123        Some(_) => {
124            let Some(branch) = &trigger.head_branch else {
125                return Writes::Refused;
126            };
127            let event = trigger.event.as_str();
128            let branch_run = WRITING_EVENTS.contains(&event) && branches.contains(branch);
129            let pull_request = writers == BuildCacheWriters::PullRequests
130                && event == PULL_REQUEST_EVENT
131                && trigger.by_user
132                && !trigger.pull_requests.is_empty();
133            if branch_run || pull_request {
134                Writes::Allowed
135            } else {
136                Writes::Refused
137            }
138        }
139    }
140}
141
142/// Whether a pull request `trigger` runs lets it write: a person opened it, from `trigger`'s head branch in
143/// `repository` itself. A bot's, such as Renovate's or Dependabot's, only reads.
144pub fn opened_by_user(pull: &PullRequest, repository: &str, trigger: &RunTrigger) -> bool {
145    pull.by_user
146        && same_repository(pull.head_repository.as_deref(), repository)
147        && trigger.head_branch.as_ref() == Some(&pull.head_branch)
148}
149
150/// Whether GitHub's `head` names `repository`, as GitHub does whatever the case.
151fn same_repository(head: Option<&str>, repository: &str) -> bool {
152    head.is_some_and(|head| head.eq_ignore_ascii_case(repository))
153}
154
155/// The build cache's size now.
156#[derive(Debug, Clone, Copy, PartialEq, Eq)]
157pub struct Size {
158    /// The entries' bytes.
159    pub bytes: u64,
160    /// How many entries there are.
161    pub entries: u64,
162}
163
164/// What `trim` removed.
165#[derive(Debug, Clone, Copy, PartialEq, Eq)]
166pub struct Trimmed {
167    /// The size before.
168    pub before: Size,
169    /// The size after.
170    pub after: Size,
171}
172
173/// The shared build cache. Cloning shares it.
174#[derive(Debug, Clone)]
175pub struct BuildCache {
176    inner: Arc<Inner>,
177}
178
179#[derive(Debug)]
180struct Inner {
181    /// The entries, under `<owner>/<name>/<tool>/<key>`.
182    root: PathBuf,
183    /// The uploads not yet entries.
184    uploads: PathBuf,
185    /// One directory per runner, holding its socket.
186    sockets: PathBuf,
187    /// Where requests for GitHub's results service it does not answer go.
188    results: actions::Results,
189    /// Where turbo's requests with a workflow's own token go.
190    vercel: turbo::Vercel,
191    // A panic midway leaves at worst an entry counted that is gone, or a file not counted, which `open` counts at
192    // the next start.
193    state: Mutex<State>,
194}
195
196#[derive(Debug, Default)]
197struct State {
198    max_size: u64,
199    entries: HashMap<PathBuf, Entry>,
200    /// The entries' bytes.
201    bytes: u64,
202    /// What the entries count for against `max_size` (`charge`).
203    charged: u64,
204    runners: HashMap<String, Runner>,
205    next_upload: u64,
206    /// What the uploads not yet entries, being received or held, count for (`charge`): at most `max_size`, so jobs
207    /// whose writes are undecided cannot fill the disk.
208    uploading: u64,
209    /// Each repository's default branch's ref, as the last decision said: what an undecided job's GitHub Actions
210    /// cache lookups read.
211    default_branches: HashMap<String, String>,
212    /// When the last GitHub Actions cache entry was created, in ms: each is created later than any before, those of
213    /// earlier runs included, so its creation time names it.
214    last_created: u64,
215    /// The GitHub Actions cache entries of `entries`, by the directory of their scope and version.
216    actions: HashMap<PathBuf, BTreeSet<PathBuf>>,
217}
218
219impl State {
220    /// Indexes `path` among the GitHub Actions cache entries, if it is one.
221    fn index(&mut self, path: &Path) {
222        if let Some(scope) = actions::scope_of(path) {
223            self.actions
224                .entry(scope)
225                .or_default()
226                .insert(path.to_owned());
227        }
228    }
229
230    /// Takes `path` out of the GitHub Actions cache entries' index.
231    fn unindex(&mut self, path: &Path) {
232        if let Some(scope) = actions::scope_of(path)
233            && let Some(paths) = self.actions.get_mut(&scope)
234        {
235            paths.remove(path);
236            if paths.is_empty() {
237                self.actions.remove(&scope);
238            }
239        }
240    }
241}
242
243#[derive(Debug, Clone, Copy)]
244struct Entry {
245    bytes: u64,
246    /// When it was last written or served, in ms: the least recently used go first.
247    used: u64,
248}
249
250#[derive(Debug)]
251struct Runner {
252    repository: String,
253    writes: Writes,
254    counts: BuildCacheCounts,
255    /// Uploads waiting for `Writes` to be decided, at most `MAX_HELD`.
256    held: Vec<Upload>,
257    /// What its uploads not yet entries, being received or held, count for: at most a quarter of `max_size` while
258    /// its writes are undecided, so one job cannot take the room another's uploads need.
259    uploading: u64,
260    dir: PathBuf,
261    serving: JoinHandle<()>,
262    /// Whether it serves GitHub Actions' cache.
263    actions: ActionsCache,
264    /// Its GitHub Actions cache scopes, once its writes are decided.
265    scopes: Scopes,
266    /// Woken when its writes are decided, for the GitHub Actions cache saves that wait for that.
267    decided: Arc<Notify>,
268    /// Its GitHub Actions cache saves not yet entries, by the number in their upload URL.
269    saves: HashMap<u64, actions::Save>,
270    /// The entries its GitHub Actions cache lookups found, by their creation time, the number in their download URL.
271    found: HashMap<u64, PathBuf>,
272}
273
274/// An upload written to a file of its own, not an entry yet.
275#[derive(Debug)]
276struct Upload {
277    file: PathBuf,
278    entry: PathBuf,
279    bytes: u64,
280    /// The uploads' room it took (`reserve`).
281    room: u64,
282}
283
284impl BuildCache {
285    /// Opens the build cache in `directory`, counting the entries an earlier run left, with each runner's socket
286    /// under `sockets`.
287    pub fn open(directory: &Path, sockets: &Path, max_size: u64) -> io::Result<BuildCache> {
288        std::fs::create_dir_all(directory)?;
289        let (root, uploads) = (directory.join(ENTRIES), directory.join(UPLOADS));
290        match std::fs::remove_dir_all(&uploads) {
291            Err(error) if error.kind() != io::ErrorKind::NotFound => return Err(error),
292            _ => {}
293        }
294        private_dir(&root)?;
295        private_dir(&uploads)?;
296        private_dir(sockets)?;
297        let mut entries = HashMap::new();
298        count_entries(&root, &root, &mut entries)?;
299        let bytes = entries.values().map(|entry: &Entry| entry.bytes).sum();
300        let charged = entries.values().map(|entry| charge(entry.bytes)).sum();
301        let mut state = State {
302            max_size,
303            bytes,
304            charged,
305            ..State::default()
306        };
307        for path in entries.keys() {
308            state.index(path);
309            state.last_created = state
310                .last_created
311                .max(actions::created_of(path).unwrap_or(0));
312        }
313        state.entries = entries;
314        Ok(BuildCache {
315            inner: Arc::new(Inner {
316                root,
317                uploads,
318                sockets: sockets.to_owned(),
319                results: actions::Results::new(),
320                vercel: turbo::Vercel::new(),
321                state: Mutex::new(state),
322            }),
323        })
324    }
325
326    /// Where the entries are: `entries` in the build cache's directory.
327    pub fn directory(&self) -> &Path {
328        &self.inner.root
329    }
330
331    /// Sends the requests for GitHub's results service it does not answer to `origin` instead of GitHub's.
332    #[cfg(test)]
333    pub(crate) fn set_results_origin(&self, origin: &str) {
334        self.inner.results.set_origin(origin);
335    }
336
337    /// Sends turbo's requests with a workflow's own token to `origin` instead of Vercel's API.
338    #[cfg(test)]
339    pub(crate) fn set_vercel_origin(&self, origin: &str) {
340        self.inner.vercel.set_origin(origin);
341    }
342
343    /// Sets the size `trim` brings it under.
344    pub fn set_max_size(&self, max_size: u64) {
345        lock(&self.inner.state).max_size = max_size;
346    }
347
348    /// Opens `runner`'s socket for a job of `repository` and returns the directory its container mounts at `MOUNT`,
349    /// with `ACTIONS_MARKER` in it when it serves GitHub Actions' cache too. A runner already open, as after a
350    /// restart, gets its socket back in the directory its container mounts.
351    pub fn attach(
352        &self,
353        runner: &str,
354        repository: &str,
355        actions: ActionsCache,
356    ) -> io::Result<PathBuf> {
357        if !valid_repository(repository) {
358            return Err(io::Error::new(
359                io::ErrorKind::InvalidInput,
360                format!("{repository} is not a repository name"),
361            ));
362        }
363        let dir = self.inner.sockets.join(socket_dir(runner));
364        std::fs::create_dir_all(&dir)?;
365        // The container's root, which forwards to it, is not the daemon's user under sysbox.
366        std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o755))?;
367        let marker = dir.join(ACTIONS_MARKER);
368        match actions {
369            ActionsCache::Served => {
370                std::fs::write(&marker, b"")?;
371                std::fs::set_permissions(&marker, std::fs::Permissions::from_mode(0o644))?;
372            }
373            ActionsCache::Off => match std::fs::remove_file(&marker) {
374                Err(error) if error.kind() != io::ErrorKind::NotFound => return Err(error),
375                _ => {}
376            },
377        }
378        let socket = dir.join(SOCKET);
379        match std::fs::remove_file(&socket) {
380            Err(error) if error.kind() != io::ErrorKind::NotFound => return Err(error),
381            _ => {}
382        }
383        let listener = UnixListener::bind(&socket)?;
384        std::fs::set_permissions(&socket, std::fs::Permissions::from_mode(0o666))?;
385        let serving = tokio::spawn(accept(self.inner.clone(), runner.to_owned(), listener));
386        let old = lock(&self.inner.state).runners.insert(
387            runner.to_owned(),
388            Runner {
389                repository: repository.to_owned(),
390                writes: Writes::Undecided,
391                counts: BuildCacheCounts::default(),
392                held: Vec::new(),
393                uploading: 0,
394                dir: dir.clone(),
395                serving,
396                actions,
397                scopes: Scopes::default(),
398                decided: Arc::new(Notify::new()),
399                saves: HashMap::new(),
400                found: HashMap::new(),
401            },
402        );
403        if let Some(mut old) = old {
404            old.serving.abort();
405            self.inner.remove_uploads(None, &old.held);
406            self.inner.remove_saves(None, &mut old.saves);
407        }
408        Ok(dir)
409    }
410
411    /// Removes the socket directories of runners not in `keep`, which an earlier run left.
412    pub fn forget_others(&self, keep: &[&str]) {
413        let keep: Vec<String> = keep.iter().map(|runner| socket_dir(runner)).collect();
414        let Ok(dirs) = std::fs::read_dir(&self.inner.sockets) else {
415            return;
416        };
417        for dir in dirs.flatten() {
418            if !keep
419                .iter()
420                .any(|name| *name == dir.file_name().to_string_lossy())
421            {
422                let _ = std::fs::remove_dir_all(dir.path());
423            }
424        }
425    }
426
427    /// Whether `runner` is open and its writes undecided.
428    pub fn undecided(&self, runner: &str) -> bool {
429        lock(&self.inner.state)
430            .runners
431            .get(runner)
432            .is_some_and(|runner| runner.writes == Writes::Undecided)
433    }
434
435    /// Decides whether `runner`'s job may write, once, with the scopes of its GitHub Actions cache entries: what it
436    /// sent meanwhile becomes entries or is dropped.
437    pub fn decide(&self, runner: &str, writes: Writes, scopes: Scopes) {
438        let held = {
439            let mut state = lock(&self.inner.state);
440            let Some(open) = state.runners.get_mut(runner) else {
441                return;
442            };
443            if open.writes != Writes::Undecided || writes == Writes::Undecided {
444                return;
445            }
446            open.writes = writes;
447            open.decided.notify_waiters();
448            let held = std::mem::take(&mut open.held);
449            let repository = open.repository.clone();
450            if let Some(default) = &scopes.default {
451                state.default_branches.insert(repository, default.clone());
452            }
453            if let Some(open) = state.runners.get_mut(runner) {
454                open.scopes = scopes;
455            }
456            held
457        };
458        match writes {
459            Writes::Allowed => {
460                for upload in held {
461                    self.inner.store(runner, upload);
462                }
463            }
464            Writes::Refused | Writes::Undecided => {
465                if let Some(open) = lock(&self.inner.state).runners.get_mut(runner) {
466                    open.counts.refused += held.len() as u64;
467                }
468                self.inner.remove_uploads(Some(runner), &held);
469            }
470        }
471    }
472
473    /// Closes the socket of `runner` if its writes are undecided and it holds uploads, and says whether it did: the
474    /// uploads stay until `decide` and `detach`.
475    pub fn close(&self, runner: &str) -> bool {
476        let dir = {
477            let state = lock(&self.inner.state);
478            let Some(open) = state.runners.get(runner) else {
479                return false;
480            };
481            if open.writes != Writes::Undecided || open.held.is_empty() {
482                return false;
483            }
484            open.serving.abort();
485            open.dir.clone()
486        };
487        if let Err(error) = std::fs::remove_dir_all(&dir)
488            && error.kind() != io::ErrorKind::NotFound
489        {
490            warn!("cannot remove {}: {error}", dir.display());
491        }
492        true
493    }
494
495    /// Closes `runner`'s socket and returns what it was served and stored, and whether it could write. What it sent
496    /// while undecided is dropped.
497    pub fn detach(&self, runner: &str) -> Option<BuildCacheCounts> {
498        let Some(mut open) = lock(&self.inner.state).runners.remove(runner) else {
499            // One a restart kept the directory of without opening it again, as with the cache turned off since.
500            let dir = self.inner.sockets.join(socket_dir(runner));
501            if let Err(error) = std::fs::remove_dir_all(&dir)
502                && error.kind() != io::ErrorKind::NotFound
503            {
504                warn!("cannot remove {}: {error}", dir.display());
505            }
506            return None;
507        };
508        open.serving.abort();
509        self.inner.remove_uploads(None, &open.held);
510        self.inner.remove_saves(None, &mut open.saves);
511        open.counts.refused += open.held.len() as u64;
512        open.counts.writer = open.writes == Writes::Allowed;
513        if let Err(error) = std::fs::remove_dir_all(&open.dir)
514            && error.kind() != io::ErrorKind::NotFound
515        {
516            warn!("cannot remove {}: {error}", open.dir.display());
517        }
518        Some(open.counts)
519    }
520
521    /// The size of the entries now.
522    pub fn size(&self) -> Size {
523        let state = lock(&self.inner.state);
524        Size {
525            bytes: state.bytes,
526            entries: state.entries.len() as u64,
527        }
528    }
529
530    /// Removes the entries used least recently until the rest fit in the size limit, each counted at least
531    /// `MIN_CHARGE`, with the directories that leaves empty under a tool's. Blocks on the file system: call it off the
532    /// engine's loop, and only while no runner runs, so no job finds an entry gone midway.
533    pub fn trim(&self) -> Trimmed {
534        let limit = lock(&self.inner.state).max_size;
535        self.trim_to(limit)
536    }
537
538    /// Removes every entry; call it only while no runner runs, as `trim`.
539    pub fn clear(&self) -> Trimmed {
540        self.trim_to(0)
541    }
542
543    fn trim_to(&self, limit: u64) -> Trimmed {
544        let (before, victims) = {
545            let mut state = lock(&self.inner.state);
546            let before = Size {
547                bytes: state.bytes,
548                entries: state.entries.len() as u64,
549            };
550            let mut by_use: Vec<(PathBuf, Entry)> = state
551                .entries
552                .iter()
553                .map(|(path, entry)| (path.clone(), *entry))
554                .collect();
555            by_use.sort_by_key(|(path, entry)| (entry.used, path.clone()));
556            let mut victims = Vec::new();
557            for (path, entry) in by_use {
558                if state.charged <= limit && (limit > 0 || state.entries.is_empty()) {
559                    break;
560                }
561                state.entries.remove(&path);
562                state.unindex(&path);
563                state.bytes -= entry.bytes;
564                state.charged -= charge(entry.bytes);
565                victims.push(path);
566            }
567            (before, victims)
568        };
569        for path in victims {
570            // Under the lock, and only while the index still lacks it: an upload `store` renamed to the same path
571            // since is an entry again, and stays.
572            let state = lock(&self.inner.state);
573            if state.entries.contains_key(&path) {
574                continue;
575            }
576            match std::fs::remove_file(self.inner.root.join(&path)) {
577                Err(error) if error.kind() != io::ErrorKind::NotFound => {
578                    warn!(
579                        "cannot remove build cache entry {}: {error}",
580                        path.display()
581                    );
582                }
583                _ => self.inner.remove_empty_parents(&path),
584            }
585            drop(state);
586        }
587        Trimmed {
588            before,
589            after: self.size(),
590        }
591    }
592}
593
594impl Inner {
595    /// Makes an upload of `runner`'s, whose job may write, an entry; refuses it when the entries already take twice
596    /// the size limit, which only a busy hour between two trims reaches. Renames under the lock: quick, on the
597    /// daemon's own file system.
598    fn store(&self, runner: &str, upload: Upload) {
599        // One lock from the check to the index: two uploads of one entry renamed in one order and indexed in the
600        // other would leave the index counting the size of the file replaced.
601        let mut state = lock(&self.state);
602        let replaced = state
603            .entries
604            .get(&upload.entry)
605            .map_or(0, |entry| charge(entry.bytes));
606        let fits =
607            state.charged - replaced + charge(upload.bytes) <= state.max_size.saturating_mul(2);
608        let path = self.root.join(&upload.entry);
609        let stored = fits
610            && path
611                .parent()
612                .is_none_or(|parent| std::fs::create_dir_all(parent).is_ok())
613            && std::fs::rename(&upload.file, &path).is_ok();
614        Self::give_back(&mut state, Some(runner), upload.room);
615        if stored {
616            let entry = Entry {
617                bytes: upload.bytes,
618                used: crate::time::now_ms(),
619            };
620            state.index(&upload.entry);
621            if let Some(old) = state.entries.insert(upload.entry, entry) {
622                state.bytes -= old.bytes;
623                state.charged -= charge(old.bytes);
624            }
625            state.bytes += upload.bytes;
626            state.charged += charge(upload.bytes);
627        } else {
628            let _ = std::fs::remove_file(&upload.file);
629        }
630        if let Some(open) = state.runners.get_mut(runner) {
631            if stored {
632                open.counts.written_bytes += upload.bytes;
633            } else {
634                open.counts.refused += 1;
635            }
636        }
637    }
638
639    /// Takes `bytes` more of the uploads' room for `runner`, unless they would take more than `max_size`, or, while
640    /// its writes are undecided, its own more than a quarter of it. `max_size` is the one the upload started with: a
641    /// lower one a reload set since holds back the uploads that start after it.
642    fn reserve(&self, runner: &str, bytes: u64, max_size: u64) -> bool {
643        let mut state = lock(&self.state);
644        let total = state.uploading;
645        let Some(open) = state.runners.get_mut(runner) else {
646            return false;
647        };
648        let fits = total + bytes <= max_size
649            && (open.writes != Writes::Undecided || open.uploading + bytes <= max_size / 4);
650        if fits {
651            open.uploading += bytes;
652            state.uploading += bytes;
653        }
654        fits
655    }
656
657    /// Gives back what `reserve` took for an upload of `runner`'s, if it is still open, that became an entry or was
658    /// removed.
659    fn release(&self, runner: Option<&str>, bytes: u64) {
660        Self::give_back(&mut lock(&self.state), runner, bytes);
661    }
662
663    fn give_back(state: &mut State, runner: Option<&str>, bytes: u64) {
664        state.uploading = state.uploading.saturating_sub(bytes);
665        if let Some(open) = runner.and_then(|runner| state.runners.get_mut(runner)) {
666            open.uploading = open.uploading.saturating_sub(bytes);
667        }
668    }
669
670    /// Removes uploads of `runner`'s, or of a runner no longer open, and gives back their room.
671    fn remove_uploads(&self, runner: Option<&str>, uploads: &[Upload]) {
672        for upload in uploads {
673            let _ = std::fs::remove_file(&upload.file);
674            self.release(runner, upload.room);
675        }
676    }
677
678    /// Removes the GitHub Actions cache saves of `runner`'s, or of a runner no longer open, that did not become
679    /// entries, with their blocks, and gives back their room.
680    fn remove_saves(&self, runner: Option<&str>, saves: &mut HashMap<u64, actions::Save>) {
681        for (_, save) in saves.drain() {
682            self.remove_uploads(runner, &save.into_uploads());
683        }
684    }
685
686    /// Removes the directories above the removed entry `entry` that it leaves empty, up to its tool's
687    /// (`<owner>/<name>/<tool>`). Call it holding the lock, as `store` makes them under it.
688    fn remove_empty_parents(&self, entry: &Path) {
689        let mut dir = entry.parent();
690        while let Some(parent) = dir
691            && parent.components().count() > 3
692            && std::fs::remove_dir(self.root.join(parent)).is_ok()
693        {
694            dir = parent.parent();
695        }
696    }
697
698    /// Marks an entry used now, in the index and, so the order survives a restart, in its file's time.
699    fn touch(&self, entry: &Path) {
700        if let Some(used) = lock(&self.state).entries.get_mut(entry) {
701            used.used = crate::time::now_ms();
702        }
703        let path = self.root.join(entry);
704        tokio::task::spawn_blocking(move || {
705            if let Ok(file) = std::fs::File::open(&path) {
706                let _ = file.set_modified(std::time::SystemTime::now());
707            }
708        });
709    }
710}
711
712/// Serves `runner`'s connections, at most `MAX_CONNECTIONS` at once, until it is detached, which aborts this task and
713/// with it every connection.
714async fn accept(inner: Arc<Inner>, runner: String, listener: UnixListener) {
715    let mut connections = JoinSet::new();
716    loop {
717        let full = connections.len() >= MAX_CONNECTIONS;
718        tokio::select! {
719            accepted = listener.accept(), if !full => match accepted {
720                Ok((stream, _)) => {
721                    connections.spawn(serve::connection(inner.clone(), runner.clone(), stream));
722                }
723                Err(error) => {
724                    warn!("{runner}: the build cache's socket failed: {error}");
725                    return;
726                }
727            },
728            Some(_) = connections.join_next() => {}
729        }
730    }
731}
732
733/// The directory of a runner's socket: a hash of its name, as a socket's path must stay under 108 bytes.
734fn socket_dir(runner: &str) -> String {
735    // FNV-1a, as `HostIdentity` hashes.
736    let hash = runner
737        .bytes()
738        .fold(0xcbf2_9ce4_8422_2325_u64, |hash, byte| {
739            (hash ^ u64::from(byte)).wrapping_mul(0x0000_0100_0000_01b3)
740        });
741    format!("{hash:016x}")
742}
743
744/// Whether `name` is a path segment of an entry: letters, digits, `.`, `_` and `-`, not `.` or `..`.
745fn valid_segment(name: &str) -> bool {
746    !name.is_empty()
747        && name.len() <= 200
748        && name != "."
749        && name != ".."
750        && name
751            .bytes()
752            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-'))
753}
754
755/// Whether `repository` is `owner/name` with no other segment.
756fn valid_repository(repository: &str) -> bool {
757    repository.split_once('/').is_some_and(|(owner, name)| {
758        valid_segment(owner) && valid_segment(name) && !owner.starts_with('.')
759    })
760}
761
762fn private_dir(path: &Path) -> io::Result<()> {
763    std::fs::create_dir_all(path)?;
764    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o700))
765}
766
767/// Counts the entries under `dir`, by their path under `root`, last used when last modified.
768fn count_entries(root: &Path, dir: &Path, entries: &mut HashMap<PathBuf, Entry>) -> io::Result<()> {
769    for item in std::fs::read_dir(dir)? {
770        let item = item?;
771        let path = item.path();
772        let metadata = item.metadata()?;
773        if metadata.is_dir() {
774            count_entries(root, &path, entries)?;
775        } else if metadata.is_file()
776            && let Ok(relative) = path.strip_prefix(root)
777        {
778            entries.insert(
779                relative.to_owned(),
780                Entry {
781                    bytes: metadata.len(),
782                    used: metadata.modified().map_or(0, crate::time::ms),
783                },
784            );
785        }
786    }
787    Ok(())
788}
789
790#[cfg(test)]
791mod tests;
792
793/// Sends one request to a runner's socket in `dir`, as a tool in its container would through the forwarder, and
794/// returns the response's status and body.
795#[cfg(test)]
796#[allow(
797    clippy::unwrap_used,
798    reason = "a test helper: a socket that does not answer fails the test"
799)]
800pub(crate) async fn request(dir: &Path, method: &str, path: &str, body: &[u8]) -> (u16, Vec<u8>) {
801    use tokio::io::{AsyncReadExt, AsyncWriteExt};
802    let mut stream = tokio::net::UnixStream::connect(dir.join(SOCKET))
803        .await
804        .unwrap();
805    let head = format!(
806        "{method} {path} HTTP/1.1\r\nHost: 127.0.0.1\r\nAuthorization: Basic dG9rZW46c2VjcmV0\r\n\
807         Content-Length: {}\r\nConnection: close\r\n\r\n",
808        body.len()
809    );
810    stream.write_all(head.as_bytes()).await.unwrap();
811    stream.write_all(body).await.unwrap();
812    let mut response = Vec::new();
813    stream.read_to_end(&mut response).await.unwrap();
814    let split = response
815        .windows(4)
816        .position(|window| window == b"\r\n\r\n")
817        .unwrap();
818    let status = String::from_utf8_lossy(&response[9..12]).parse().unwrap();
819    (status, response[split + 4..].to_vec())
820}