runner_manager_agent/lib.rs
1// owner: e1-reconciliation-capacity
2//
3// e1 owns `reconcile` and this crate root, e2 owns `package`, e3 owns
4// `lifecycle`. The module list is `a1`'s, so neither of the other two has to
5// edit this file.
6
7//! The host agent: demand reconciliation, the runner package cache, and the
8//! just-in-time runner lifecycle.
9//!
10//! * [`reconcile`] — the loop that turns GitHub demand into a decision to start
11//! runners, and the two ceilings that bound it. It owns no I/O of its own:
12//! every effect it has reaches the world through a port, which is what makes
13//! the whole decision path testable with no process, no filesystem and no
14//! network.
15//! * [`package`] — the cached, checksum-verified GitHub runner package. `e2`
16//! owns it, and it is an ownership stub today.
17//! * [`lifecycle`] — the JIT registration, the child process, and restart
18//! recovery. `e3` owns it and **will** implement
19//! [`reconcile::RunnerLauncher`]; it is an ownership stub today, so the port
20//! has no production implementation yet. Written in the future tense on
21//! purpose: a crate root that describes a stub as if it were finished is how
22//! a reader concludes the wiring exists and goes looking for the bug
23//! somewhere else.
24//!
25//! # Every ceiling in this product is enforced in this crate
26//!
27//! `max_capacity` beats reported demand and `Host.host_capacity` beats
28//! `max_capacity`, across **all** policies on the machine (D7, D9). The
29//! arithmetic belongs to
30//! [`runner_manager_domain::capacity::HostAllocator`]; what this crate adds is
31//! the two things the arithmetic cannot supply for itself — the attempt set the
32//! host actually holds, and the host-wide allocation lock that makes reading it
33//! and acting on it one indivisible step.
34//!
35//! **There is no job reservation anywhere in this crate, and none may be
36//! added.** `AcquireJobs` has no REST equivalent, so demand is advisory and a
37//! second host may take a job this one has already started a runner for. The
38//! surplus runner that results exits on its idle timeout and is cleaned like any
39//! other attempt; it is an accepted, bounded cost rather than a defect to
40//! engineer around. [`reconcile`] states the full reasoning and carries a
41//! tripwire against the shape being reintroduced.
42
43pub mod lifecycle;
44pub mod package;
45pub mod reconcile;