Skip to main content

runnerd_core/
github.rs

1//! The GitHub REST API as the scheduler and the history need it: queued jobs, a job's steps, just-in-time runner
2//! configs, repository runners and cancelling a run. Owns the token, the pages of a listing, conditional requests and
3//! the answers kept for them, rate-limit backoff, and the count of what it asks and the limit it last read. It must
4//! never put the token in a log line, a `Debug` output or an error, nor send it anywhere but its base URL, and it
5//! decides nothing about scheduling.
6
7use std::collections::{HashMap, HashSet};
8use std::fmt;
9use std::sync::{Arc, Mutex};
10use std::time::{Duration, Instant, SystemTime};
11
12use reqwest::header::{self, HeaderMap, HeaderValue};
13use reqwest::{Method, StatusCode};
14use serde::Deserialize;
15use serde::de::DeserializeOwned;
16use tracing::info;
17
18use crate::api;
19use crate::docker::JitConfig;
20use crate::sync::lock;
21use crate::time;
22
23mod requests;
24
25use requests::Counter;
26pub use requests::{Class, RateLimit, Report, Spend, Tally};
27
28/// The public API's address.
29pub const API_URL: &str = "https://api.github.com";
30
31/// How long one request may take, connecting included. GitHub answers in well under a second; a request that hangs
32/// holds back the tick that made it.
33const REQUEST_TIMEOUT: Duration = Duration::from_secs(10);
34
35/// Items per page of a listing: GitHub's most.
36const PER_PAGE: u32 = 100;
37
38/// The most pages read of one listing: 1,000 runs, jobs of a run or runners, more than one machine serves at once
39/// and four times a matrix's 256 jobs. A listing that names a page past it is cut there, so a `Link` that never ends
40/// costs ten requests, not the rate limit.
41const MAX_PAGES: u32 = 10;
42
43/// How many requests for runs' jobs one poll of a repository starts: as many runs as a poll read before it followed
44/// pages, 100 queued and 100 in progress. A run whose first page is read is read to its last, so none of its queued
45/// jobs drops out of the listing for want of a page, and the listings of runs, however many pages they grow to, do
46/// not move where a poll stops. A repository with more active runs leaves the rest unread until earlier ones end,
47/// so following pages does not spend the rate limit faster than before.
48const JOB_REQUESTS: usize = 200;
49
50/// The most bytes of answers kept for conditional requests. A page of 100 runs is about 600 KB, a page of jobs with
51/// their steps about 350 KB, a job's details a few KB: room for what several busy repositories ask every poll.
52const CONDITIONAL_BYTES: usize = 32 * 1024 * 1024;
53
54/// An answer asked for within this long is not dropped to make room for another. Every poll asks the same paths in
55/// the same order; were the least recently used answer dropped, a poll that asks more than the limit holds would
56/// find each answer dropped just before asking for it again and pay for every request. Kept like this, the answers
57/// that fit stay conditional and only the rest cost the rate limit. It is far longer than a poll interval (15 s by
58/// default); polls further apart than this are rare enough that what they pay matters little.
59const CONDITIONAL_FRESH: Duration = Duration::from_secs(600);
60
61/// A GitHub token. Its `Debug` output never shows the value.
62#[derive(Clone)]
63pub struct Token(String);
64
65impl fmt::Debug for Token {
66    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
67        f.write_str("Token(<redacted>)")
68    }
69}
70
71/// Where the client gets a token: at start and again when GitHub answers 401.
72pub type TokenSource = Box<dyn Fn() -> Result<Token, Error> + Send + Sync>;
73
74/// The `gh` CLI's token for github.com (`gh auth token`).
75pub fn gh_token() -> Result<Token, Error> {
76    let output = std::process::Command::new("gh")
77        .args(["auth", "token", "--hostname", "github.com"])
78        .output()
79        .map_err(|error| Error::Token(format!("cannot run gh: {error}")))?;
80    if !output.status.success() {
81        return Err(Error::Token(format!(
82            "gh auth token failed: {}",
83            String::from_utf8_lossy(&output.stderr).trim()
84        )));
85    }
86    let token = String::from_utf8(output.stdout)
87        .map_err(|_| Error::Token("gh auth token printed a token that is not UTF-8".to_owned()))?;
88    Ok(Token(token.trim().to_owned()))
89}
90
91/// Makes ring the process's TLS crypto provider, which every `reqwest::Client` needs: reqwest is built without
92/// one. Calling it again does nothing.
93pub fn install_crypto_provider() {
94    // Fails only when a provider is installed already.
95    let _ = rustls::crypto::ring::default_provider().install_default();
96}
97
98/// What a GitHub request can fail with. No variant holds the token.
99#[derive(Debug, thiserror::Error)]
100pub enum Error {
101    /// GitHub's rate limit is used up; no request is sent before `until`.
102    #[error("GitHub's rate limit is used up until {}s after the epoch", secs(*until))]
103    RateLimited {
104        /// When the limit resets.
105        until: SystemTime,
106    },
107    /// GitHub answered with an error status.
108    #[error("GitHub answered {status} to {method} {path}: {message}")]
109    Status {
110        /// The request's method.
111        method: Method,
112        /// The request's path, without the host.
113        path: String,
114        /// What GitHub answered.
115        status: StatusCode,
116        /// GitHub's error message, or the body as text.
117        message: String,
118    },
119    /// The request did not get an answer.
120    #[error("{method} {path}: {source}")]
121    Http {
122        /// The request's method.
123        method: Method,
124        /// The request's path, without the host.
125        path: String,
126        /// What failed, without the URL.
127        source: reqwest::Error,
128    },
129    /// The answer is not the JSON expected.
130    #[error("{path}: unexpected response: {source}")]
131    Decode {
132        /// The request's path, without the host.
133        path: String,
134        /// What did not parse.
135        source: serde_json::Error,
136    },
137    /// No token could be read.
138    #[error("no GitHub token: {0}")]
139    Token(String),
140}
141
142impl Error {
143    /// Whether GitHub answered that what was asked is not there for this token: deleted, or the token cannot see it.
144    /// Asking again gets the same answer.
145    pub fn is_gone(&self) -> bool {
146        matches!(
147            self,
148            Error::Status {
149                status: StatusCode::NOT_FOUND | StatusCode::GONE,
150                ..
151            }
152        )
153    }
154}
155
156fn secs(time: SystemTime) -> u64 {
157    time.duration_since(SystemTime::UNIX_EPOCH)
158        .unwrap_or_default()
159        .as_secs()
160}
161
162/// A job waiting for a runner.
163#[derive(Debug, Clone, Default, PartialEq, Eq)]
164pub struct QueuedJob {
165    /// The job's ID; IDs grow with time.
166    pub id: u64,
167    /// The workflow run it belongs to.
168    pub run_id: u64,
169    /// The job's name in the workflow.
170    pub name: String,
171    /// The workflow's `runs-on` labels.
172    pub labels: Vec<String>,
173    /// When GitHub queued it, in milliseconds since the epoch; 0 if GitHub's answer did not say.
174    pub created_at: u64,
175    /// 1 for the run's first attempt.
176    pub run_attempt: u32,
177    /// The workflow's name.
178    pub workflow: Option<String>,
179    /// The branch the run is for.
180    pub branch: Option<String>,
181    /// The job's page on GitHub.
182    pub url: Option<String>,
183}
184
185/// A job as `GET /repos/{owner}/{repo}/actions/jobs/{id}` describes it: its progress and steps.
186#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
187pub struct JobDetails {
188    /// The job's ID.
189    pub id: u64,
190    /// The workflow run it belongs to.
191    pub run_id: u64,
192    /// 1 for the run's first attempt.
193    #[serde(default = "first_attempt")]
194    pub run_attempt: u32,
195    /// The job's name in the workflow.
196    pub name: String,
197    /// The workflow's name.
198    pub workflow_name: Option<String>,
199    /// The branch the run is for.
200    pub head_branch: Option<String>,
201    /// The job's page on GitHub.
202    pub html_url: Option<String>,
203    /// The workflow's `runs-on` labels.
204    #[serde(default)]
205    pub labels: Vec<String>,
206    /// When GitHub queued it.
207    pub created_at: Option<String>,
208    /// `queued`, `in_progress`, `completed`, `waiting`, ….
209    pub status: String,
210    /// Once completed: `success`, `failure`, `cancelled`, ….
211    pub conclusion: Option<String>,
212    /// When the runner started it.
213    pub started_at: Option<String>,
214    /// When it completed.
215    pub completed_at: Option<String>,
216    /// The runner that took it, if one did.
217    pub runner_name: Option<String>,
218    /// Its steps so far.
219    #[serde(default)]
220    pub steps: Vec<JobStep>,
221}
222
223/// What started a workflow run, as `GET /repos/{owner}/{repo}/actions/runs/{id}` says.
224#[derive(Debug, Clone, PartialEq, Eq)]
225pub struct RunTrigger {
226    /// `push`, `pull_request`, `schedule`, `workflow_dispatch`, ….
227    pub event: String,
228    /// The branch it ran on: a pull request's head branch, which may be a fork's.
229    pub head_branch: Option<String>,
230    /// `owner/name` of the repository its commit came from: a fork's, for a pull request from one.
231    pub head_repository: Option<String>,
232    /// The commit it ran. A tag's run gives the tag's name as `head_branch`, so only this says whether the
233    /// branch has it.
234    pub head_sha: String,
235    /// Whether people, not bots or apps, started it: GitHub's `actor` and `triggering_actor`, who re-ran it, are
236    /// both of type `User`.
237    pub by_user: bool,
238    /// The pull requests into the repository it runs, by number. GitHub lists only those whose head branch is in
239    /// the repository itself, and may list none once they are closed; those it lists into another repository of a
240    /// fork network are left out.
241    pub pull_requests: Vec<u64>,
242}
243
244/// A pull request, as `GET /repos/{owner}/{repo}/pulls/{number}` says.
245#[derive(Debug, Clone, PartialEq, Eq)]
246pub struct PullRequest {
247    /// Whether a person, not a bot or an app, opened it: its `user` is of type `User`.
248    pub by_user: bool,
249    /// `owner/name` of the repository its head branch is in; `None` once that is deleted.
250    pub head_repository: Option<String>,
251    /// Its head branch.
252    pub head_branch: String,
253    /// The branch it is to merge into, of the repository it was opened in.
254    pub base_branch: String,
255}
256
257/// A repository, as `GET /repos/{owner}/{repo}` says.
258#[derive(Debug, Clone, PartialEq, Eq)]
259pub struct RepositoryDetails {
260    /// Its default branch.
261    pub default_branch: String,
262    /// Whether it is public, private or internal.
263    pub visibility: api::Visibility,
264}
265
266fn first_attempt() -> u32 {
267    1
268}
269
270/// A step of `JobDetails`.
271#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
272pub struct JobStep {
273    /// GitHub's step number.
274    pub number: u32,
275    /// The name GitHub shows.
276    pub name: String,
277    /// `pending`, `queued`, `in_progress` or `completed`.
278    pub status: String,
279    /// Once completed: `success`, `failure`, `skipped`, ….
280    pub conclusion: Option<String>,
281    /// When it started.
282    pub started_at: Option<String>,
283    /// When it completed.
284    pub completed_at: Option<String>,
285}
286
287/// A runner registered on a repository.
288#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
289pub struct Runner {
290    /// The runner's ID.
291    pub id: u64,
292    /// Its name; runnerd's runners start with the host's prefix.
293    pub name: String,
294    /// `online` or `offline`.
295    pub status: String,
296    /// Whether it runs a job.
297    pub busy: bool,
298}
299
300/// What deleting a runner did.
301#[derive(Debug, Clone, Copy, PartialEq, Eq)]
302pub enum Deleted {
303    /// GitHub removed it.
304    Deleted,
305    /// It was gone already: an ephemeral runner removes itself after its job.
306    NotFound,
307    /// GitHub refused because the runner runs a job.
308    Busy,
309}
310
311/// The GitHub calls the scheduler makes. `Github` is the real client; the engine's tests use a fake.
312pub trait GithubApi: Send + Sync {
313    /// The repository's jobs waiting for a runner, in queued runs and in runs that started some of their jobs.
314    fn queued_jobs(
315        &self,
316        repository: &str,
317    ) -> impl Future<Output = Result<Vec<QueuedJob>, Error>> + Send;
318    /// The repository's self-hosted runners.
319    fn runners(&self, repository: &str) -> impl Future<Output = Result<Vec<Runner>, Error>> + Send;
320    /// Registers a runner for one job and returns it with the config the runner's listener takes.
321    fn jit_config(
322        &self,
323        repository: &str,
324        name: &str,
325        labels: &[String],
326    ) -> impl Future<Output = Result<(Runner, JitConfig), Error>> + Send;
327    /// Removes a runner from the repository.
328    fn delete_runner(
329        &self,
330        repository: &str,
331        id: u64,
332    ) -> impl Future<Output = Result<Deleted, Error>> + Send;
333    /// One job's progress and steps.
334    fn job(
335        &self,
336        repository: &str,
337        id: u64,
338    ) -> impl Future<Output = Result<JobDetails, Error>> + Send;
339    /// What started a workflow run.
340    fn run_trigger(
341        &self,
342        repository: &str,
343        run: u64,
344    ) -> impl Future<Output = Result<RunTrigger, Error>> + Send;
345    /// One pull request: who opened it and where its head branch is.
346    fn pull_request(
347        &self,
348        repository: &str,
349        number: u64,
350    ) -> impl Future<Output = Result<PullRequest, Error>> + Send;
351    /// The repository's default branch and visibility.
352    fn repository(
353        &self,
354        repository: &str,
355    ) -> impl Future<Output = Result<RepositoryDetails, Error>> + Send;
356    /// Whether `branch` of the repository has the commit `sha`: its head or an ancestor of it. A tag of the same
357    /// name, which git would take for it, does not count.
358    fn on_branch(
359        &self,
360        repository: &str,
361        branch: &str,
362        sha: &str,
363    ) -> impl Future<Output = Result<bool, Error>> + Send;
364    /// Cancels a workflow run, and so every job in it: GitHub cancels runs, not single jobs. A run that already
365    /// completed is left as it is.
366    fn cancel_run(
367        &self,
368        repository: &str,
369        run: u64,
370    ) -> impl Future<Output = Result<(), Error>> + Send;
371    /// What the reads are paced by (ADR 0127): the rate limit as last read, and the registrations and deletes sent.
372    fn spend(&self) -> Spend;
373}
374
375/// A GitHub API client for one token. Requests on one URL are conditional on its last `ETag`, so an unchanged
376/// answer costs no rate limit.
377pub struct Github {
378    http: reqwest::Client,
379    base: String,
380    /// Run on Tokio's blocking pool: `gh` may wait on a keyring for seconds.
381    token_source: Arc<dyn Fn() -> Result<Token, Error> + Send + Sync>,
382    /// An async lock, held while the source runs: requests that need a token wait without blocking a worker, and
383    /// concurrent 401s read it once.
384    token: tokio::sync::Mutex<Option<Token>>,
385    // Locked with `sync::lock`: a panic while holding one of these locks leaves plain data behind, still usable.
386    etags: Mutex<Conditional>,
387    blocked_until: Mutex<Option<SystemTime>>,
388    /// What was asked of GitHub: logged hourly and when the client goes.
389    requests: Mutex<Counter>,
390}
391
392impl Drop for Github {
393    /// The last window's line, as the daemon stops.
394    fn drop(&mut self) {
395        let report = lock(&self.requests).take(Instant::now());
396        if !report.is_empty() {
397            info!("{}", report.line(SystemTime::now()));
398        }
399    }
400}
401
402impl fmt::Debug for Github {
403    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
404        f.debug_struct("Github")
405            .field("base", &self.base)
406            .finish_non_exhaustive()
407    }
408}
409
410#[derive(Deserialize)]
411struct Runs {
412    workflow_runs: Vec<Run>,
413}
414
415#[derive(Deserialize)]
416struct Run {
417    id: u64,
418}
419
420/// Which listing of runs a run is in; queued ones order first.
421#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
422enum RunState {
423    Waiting,
424    Started,
425}
426
427#[derive(Deserialize)]
428struct Jobs {
429    jobs: Vec<Job>,
430}
431
432#[derive(Deserialize)]
433struct Job {
434    id: u64,
435    run_id: u64,
436    name: String,
437    status: String,
438    labels: Vec<String>,
439    created_at: Option<String>,
440    run_attempt: Option<u32>,
441    workflow_name: Option<String>,
442    head_branch: Option<String>,
443    html_url: Option<String>,
444}
445
446#[derive(Deserialize)]
447struct RunBody {
448    event: String,
449    head_branch: Option<String>,
450    head_repository: Option<RepositoryName>,
451    head_sha: String,
452    actor: Option<Account>,
453    triggering_actor: Option<Account>,
454    #[serde(default)]
455    pull_requests: Vec<PullRequestNumber>,
456}
457
458#[derive(Deserialize)]
459struct Account {
460    #[serde(rename = "type")]
461    kind: String,
462}
463
464impl Account {
465    /// Whether GitHub says `account` is a person's: `Bot` is a GitHub App's or a bot's.
466    fn is_user(account: Option<&Account>) -> bool {
467        account.is_some_and(|account| account.kind == "User")
468    }
469}
470
471#[derive(Deserialize)]
472struct PullRequestNumber {
473    number: u64,
474    base: Option<PullRequestBase>,
475}
476
477#[derive(Deserialize)]
478struct PullRequestBase {
479    repo: Option<RepositoryUrl>,
480}
481
482#[derive(Deserialize)]
483struct RepositoryUrl {
484    url: String,
485}
486
487impl PullRequestNumber {
488    /// Whether it is a pull request into `repository`: in a fork network, a run can also list one into another
489    /// repository whose head is the same branch.
490    fn targets(&self, repository: &str) -> bool {
491        let Some(url) = self
492            .base
493            .as_ref()
494            .and_then(|base| base.repo.as_ref())
495            .map(|repo| repo.url.to_ascii_lowercase())
496        else {
497            return false;
498        };
499        url.ends_with(&format!("/repos/{}", repository.to_ascii_lowercase()))
500    }
501}
502
503#[derive(Deserialize)]
504struct PullRequestBody {
505    user: Option<Account>,
506    head: PullRequestHead,
507    base: PullRequestBaseRef,
508}
509
510#[derive(Deserialize)]
511struct PullRequestBaseRef {
512    #[serde(rename = "ref")]
513    branch: String,
514}
515
516#[derive(Deserialize)]
517struct PullRequestHead {
518    #[serde(rename = "ref")]
519    branch: String,
520    repo: Option<RepositoryName>,
521}
522
523#[derive(Deserialize)]
524struct RepositoryName {
525    full_name: String,
526}
527
528#[derive(Deserialize)]
529struct CompareBody {
530    status: String,
531}
532
533#[derive(Deserialize)]
534struct BranchBody {
535    commit: CommitBody,
536}
537
538#[derive(Deserialize)]
539struct CommitBody {
540    sha: String,
541}
542
543#[derive(Deserialize)]
544struct RepositoryBody {
545    default_branch: String,
546    visibility: api::Visibility,
547}
548
549#[derive(Deserialize)]
550struct Runners {
551    runners: Vec<Runner>,
552}
553
554#[derive(Deserialize)]
555struct JitResponse {
556    runner: Runner,
557    encoded_jit_config: String,
558}
559
560#[derive(Deserialize)]
561struct ErrorBody {
562    message: String,
563}
564
565impl Github {
566    /// A client for `base` (`API_URL`, or a test server) that takes its token from `token_source`.
567    pub fn new(base: &str, token_source: TokenSource) -> Result<Github, Error> {
568        install_crypto_provider();
569        let mut headers = HeaderMap::new();
570        headers.insert(
571            header::ACCEPT,
572            HeaderValue::from_static("application/vnd.github+json"),
573        );
574        headers.insert(
575            "x-github-api-version",
576            HeaderValue::from_static("2022-11-28"),
577        );
578        let http = reqwest::Client::builder()
579            .user_agent(concat!("runnerd/", env!("CARGO_PKG_VERSION")))
580            .default_headers(headers)
581            .timeout(REQUEST_TIMEOUT)
582            .build()
583            .map_err(|source| Error::Http {
584                method: Method::GET,
585                path: base.to_owned(),
586                source,
587            })?;
588        Ok(Github {
589            http,
590            base: base.trim_end_matches('/').to_owned(),
591            token_source: Arc::from(token_source),
592            token: tokio::sync::Mutex::new(None),
593            etags: Mutex::new(Conditional::new(CONDITIONAL_BYTES, CONDITIONAL_FRESH)),
594            blocked_until: Mutex::new(None),
595            requests: Mutex::new(Counter::new(Instant::now(), requests::WINDOW)),
596        })
597    }
598
599    /// What the requests of this client counted since its last line was logged, and the rate limit as last read.
600    pub fn requests(&self) -> Report {
601        lock(&self.requests).peek(Instant::now())
602    }
603
604    /// Counts a response, and logs the window's line if its hour is over.
605    fn count(&self, class: Class, status: StatusCode, headers: &HeaderMap) {
606        let due = {
607            let mut requests = lock(&self.requests);
608            requests.record(class, status, headers);
609            requests.due(Instant::now())
610        };
611        if let Some(report) = due {
612            info!("{}", report.line(SystemTime::now()));
613        }
614    }
615
616    /// When the next request may be sent: `None` now, otherwise when the rate limit resets.
617    pub fn blocked_until(&self) -> Option<SystemTime> {
618        let blocked = *lock(&self.blocked_until);
619        blocked.filter(|until| *until > SystemTime::now())
620    }
621
622    async fn get<T: DeserializeOwned>(&self, path: &str) -> Result<T, Error> {
623        self.get_page(path).await.map(|page| page.body)
624    }
625
626    /// One answer, conditional on the last one kept for `path`, and whether GitHub's `Link` names a next page.
627    async fn get_page<T: DeserializeOwned>(&self, path: &str) -> Result<Page<T>, Error> {
628        // Taken before the request, so an answer evicted meanwhile still serves a 304.
629        let cached = lock(&self.etags).get(path, Instant::now());
630        let etag = cached.as_ref().map(|cached| &cached.etag);
631        let response = self.send(Method::GET, path, None, etag).await?;
632        let (bytes, next) = if response.status == StatusCode::NOT_MODIFIED {
633            match cached {
634                Some(cached) => (cached.body, cached.next),
635                None => {
636                    return Err(Error::Status {
637                        method: Method::GET,
638                        path: path.to_owned(),
639                        status: response.status,
640                        message: "not modified, but nothing is cached".to_owned(),
641                    });
642                }
643            }
644        } else {
645            let etag = response.etag.clone();
646            let response = expect_success(Method::GET, path, response)?;
647            let body: Arc<[u8]> = response.bytes.into();
648            if let Some(etag) = etag {
649                lock(&self.etags).insert(
650                    path,
651                    Cached {
652                        etag,
653                        body: body.clone(),
654                        next: response.next,
655                    },
656                    Instant::now(),
657                );
658            }
659            (body, response.next)
660        };
661        Ok(Page {
662            body: decode(path, &bytes)?,
663            next,
664        })
665    }
666
667    /// The pages of the listing at `path`, a query without `page`, for as long as GitHub's `Link` names a next one,
668    /// at most `MAX_PAGES`. Each page is its own conditional request. The next page's address is built here, not
669    /// taken from the `Link`, so the token goes nowhere but `base`. Items move between pages while they are read: one
670    /// may show twice, which callers dedupe by ID, or not at all until the next poll.
671    async fn get_pages<T: DeserializeOwned>(&self, path: &str) -> Result<Vec<T>, Error> {
672        let mut pages = Vec::new();
673        for page in 1..=MAX_PAGES {
674            let path = if page == 1 {
675                path.to_owned()
676            } else {
677                format!("{path}&page={page}")
678            };
679            let answer: Page<T> = self.get_page(&path).await?;
680            pages.push(answer.body);
681            if !answer.next {
682                break;
683            }
684        }
685        Ok(pages)
686    }
687
688    /// Sends a request with the token, once more with a fresh token after a 401, conditional on `etag` if given.
689    /// Records the rate limit.
690    async fn send(
691        &self,
692        method: Method,
693        path: &str,
694        body: Option<&serde_json::Value>,
695        etag: Option<&HeaderValue>,
696    ) -> Result<Response, Error> {
697        if let Some(until) = self.blocked_until() {
698            return Err(Error::RateLimited { until });
699        }
700        let class = Class::of(&method, path);
701        // The token GitHub refused, once it did.
702        let mut refused: Option<Token> = None;
703        loop {
704            let token = self.token(refused.as_ref()).await?;
705            let mut request = self
706                .http
707                .request(method.clone(), format!("{}{path}", self.base))
708                .bearer_auth(&token.0);
709            if let Some(body) = body {
710                request = request
711                    .header(header::CONTENT_TYPE, "application/json")
712                    .body(body.to_string());
713            }
714            if let Some(etag) = etag {
715                request = request.header(header::IF_NONE_MATCH, etag.clone());
716            }
717            let response = request.send().await.map_err(|source| Error::Http {
718                method: method.clone(),
719                path: path.to_owned(),
720                source: source.without_url(),
721            })?;
722            let status = response.status();
723            self.count(class, status, response.headers());
724            if status == StatusCode::UNAUTHORIZED && refused.is_none() {
725                refused = Some(token);
726                continue;
727            }
728            if let Some(until) = rate_limited_until(status, response.headers(), SystemTime::now()) {
729                *lock(&self.blocked_until) = Some(until);
730                if matches!(
731                    status,
732                    StatusCode::FORBIDDEN | StatusCode::TOO_MANY_REQUESTS
733                ) {
734                    return Err(Error::RateLimited { until });
735                }
736            }
737            let etag = response.headers().get(header::ETAG).cloned();
738            let next = names_next_page(response.headers());
739            let bytes = response.bytes().await.map_err(|source| Error::Http {
740                method: method.clone(),
741                path: path.to_owned(),
742                source: source.without_url(),
743            })?;
744            return Ok(Response {
745                status,
746                etag,
747                next,
748                bytes: bytes.to_vec(),
749            });
750        }
751    }
752
753    /// The token, read from the source if there is none yet or it is still the one GitHub `refused`: of several
754    /// requests refused at once, the first reads a new one and the others take it.
755    async fn token(&self, refused: Option<&Token>) -> Result<Token, Error> {
756        let mut token = self.token.lock().await;
757        let stale = match (&*token, refused) {
758            (None, _) => true,
759            (Some(current), Some(refused)) => current.0 == refused.0,
760            (Some(_), None) => false,
761        };
762        if stale {
763            let source = self.token_source.clone();
764            *token = Some(
765                tokio::task::spawn_blocking(move || source())
766                    .await
767                    .map_err(|error| {
768                        Error::Token(format!("the token source stopped: {error}"))
769                    })??,
770            );
771        }
772        token
773            .clone()
774            .ok_or_else(|| Error::Token("the token source returned nothing".to_owned()))
775    }
776}
777
778impl GithubApi for Github {
779    async fn queued_jobs(&self, repository: &str) -> Result<Vec<QueuedJob>, Error> {
780        // Each run once, `Started` if GitHub lists it in progress, `Waiting` if queued.
781        let mut runs = Vec::new();
782        for (state, status) in [
783            (RunState::Waiting, "queued"),
784            (RunState::Started, "in_progress"),
785        ] {
786            let pages: Vec<Runs> = self
787                .get_pages(&format!(
788                    "/repos/{repository}/actions/runs?status={status}&per_page={PER_PAGE}"
789                ))
790                .await?;
791            runs.extend(
792                pages
793                    .into_iter()
794                    .flat_map(|page| page.workflow_runs)
795                    .map(|run| (state, run.id)),
796            );
797        }
798        // A run listed under both, which moved while they were read, counts as queued.
799        runs.sort_unstable_by_key(|&(state, id)| (id, state));
800        runs.dedup_by_key(|&mut (_, id)| id);
801        // Queued runs first, whose jobs all wait, then those in progress, which may run on GitHub's own runners;
802        // oldest first within each. Should the requests run out, the runs left unread are the newest.
803        runs.sort_unstable();
804        let listed: HashSet<u64> = runs.iter().map(|&(_, id)| id).collect();
805        let mut jobs = Vec::new();
806        let mut requests = 0;
807        for &(_, run) in &runs {
808            if requests >= JOB_REQUESTS {
809                break;
810            }
811            let pages: Vec<Jobs> = self.get_pages(&jobs_path(repository, run)).await?;
812            requests += pages.len();
813            jobs.extend(
814                pages
815                    .into_iter()
816                    .flat_map(|page| page.jobs)
817                    .filter(|job| job.status == "queued")
818                    .map(|job| QueuedJob {
819                        id: job.id,
820                        run_id: job.run_id,
821                        name: job.name,
822                        labels: job.labels,
823                        created_at: job
824                            .created_at
825                            .as_deref()
826                            .and_then(time::parse_ms)
827                            .unwrap_or(0),
828                        run_attempt: job.run_attempt.unwrap_or(1),
829                        workflow: job.workflow_name,
830                        branch: job.head_branch,
831                        url: job.html_url,
832                    }),
833            );
834        }
835        // The cached pages of runs that ended: nothing asks for them again.
836        let runs_prefix = format!("/repos/{repository}/actions/runs/");
837        lock(&self.etags).retain(|path| {
838            match path
839                .strip_prefix(&runs_prefix)
840                .and_then(|rest| rest.split_once("/jobs?"))
841            {
842                Some((run, _)) => run.parse().is_ok_and(|run: u64| listed.contains(&run)),
843                None => true,
844            }
845        });
846        jobs.sort_by_key(|job| job.id);
847        jobs.dedup_by_key(|job| job.id);
848        Ok(jobs)
849    }
850
851    async fn runners(&self, repository: &str) -> Result<Vec<Runner>, Error> {
852        let pages: Vec<Runners> = self
853            .get_pages(&format!(
854                "/repos/{repository}/actions/runners?per_page={PER_PAGE}"
855            ))
856            .await?;
857        let mut seen = HashSet::new();
858        Ok(pages
859            .into_iter()
860            .flat_map(|page| page.runners)
861            .filter(|runner| seen.insert(runner.id))
862            .collect())
863    }
864
865    async fn jit_config(
866        &self,
867        repository: &str,
868        name: &str,
869        labels: &[String],
870    ) -> Result<(Runner, JitConfig), Error> {
871        let body = serde_json::json!({
872            "name": name,
873            // The repository's default runner group.
874            "runner_group_id": 1,
875            "labels": labels,
876            "work_folder": "_work",
877        });
878        let path = format!("/repos/{repository}/actions/runners/generate-jitconfig");
879        let response = self.send(Method::POST, &path, Some(&body), None).await?;
880        let response = expect_success(Method::POST, &path, response)?;
881        let jit: JitResponse = decode(&path, &response.bytes)?;
882        Ok((jit.runner, JitConfig(jit.encoded_jit_config)))
883    }
884
885    async fn delete_runner(&self, repository: &str, id: u64) -> Result<Deleted, Error> {
886        let path = format!("/repos/{repository}/actions/runners/{id}");
887        let response = self.send(Method::DELETE, &path, None, None).await?;
888        match response.status {
889            StatusCode::NOT_FOUND => Ok(Deleted::NotFound),
890            StatusCode::UNPROCESSABLE_ENTITY => Ok(Deleted::Busy),
891            _ => expect_success(Method::DELETE, &path, response).map(|_| Deleted::Deleted),
892        }
893    }
894
895    async fn job(&self, repository: &str, id: u64) -> Result<JobDetails, Error> {
896        let path = format!("/repos/{repository}/actions/jobs/{id}");
897        let job: JobDetails = self.get(&path).await?;
898        // A completed job does not change again, and the history stops asking for it.
899        if job.status == "completed" {
900            lock(&self.etags).remove(&path);
901        }
902        Ok(job)
903    }
904
905    async fn run_trigger(&self, repository: &str, run: u64) -> Result<RunTrigger, Error> {
906        let path = format!("/repos/{repository}/actions/runs/{run}");
907        let run: Result<RunBody, Error> = self.get(&path).await;
908        // Asked once per job: its large answer is not worth keeping for a conditional request.
909        lock(&self.etags).remove(&path);
910        let run = run?;
911        Ok(RunTrigger {
912            event: run.event,
913            head_branch: run.head_branch,
914            head_repository: run.head_repository.map(|head| head.full_name),
915            head_sha: run.head_sha,
916            by_user: Account::is_user(run.actor.as_ref())
917                && Account::is_user(run.triggering_actor.as_ref()),
918            pull_requests: run
919                .pull_requests
920                .into_iter()
921                .filter(|pull| pull.targets(repository))
922                .map(|pull| pull.number)
923                .collect(),
924        })
925    }
926
927    async fn pull_request(&self, repository: &str, number: u64) -> Result<PullRequest, Error> {
928        let path = format!("/repos/{repository}/pulls/{number}");
929        let pull: Result<PullRequestBody, Error> = self.get(&path).await;
930        lock(&self.etags).remove(&path);
931        let pull = pull?;
932        Ok(PullRequest {
933            by_user: Account::is_user(pull.user.as_ref()),
934            head_repository: pull.head.repo.map(|repo| repo.full_name),
935            head_branch: pull.head.branch,
936            base_branch: pull.base.branch,
937        })
938    }
939
940    async fn repository(&self, repository: &str) -> Result<RepositoryDetails, Error> {
941        let body: RepositoryBody = self.get(&format!("/repos/{repository}")).await?;
942        Ok(RepositoryDetails {
943            default_branch: body.default_branch,
944            visibility: body.visibility,
945        })
946    }
947
948    async fn on_branch(&self, repository: &str, branch: &str, sha: &str) -> Result<bool, Error> {
949        let commit =
950            |sha: &str| !sha.is_empty() && sha.bytes().all(|byte| byte.is_ascii_hexdigit());
951        if !commit(sha) {
952            return Ok(false);
953        }
954        // A branch name may hold `#`, `%` or `?`, which would end or change the path.
955        let base: String = branch
956            .bytes()
957            .map(|byte| {
958                if byte.is_ascii_alphanumeric() || matches!(byte, b'/' | b'-' | b'_' | b'.') {
959                    char::from(byte).to_string()
960                } else {
961                    format!("%{byte:02X}")
962                }
963            })
964            .collect();
965        // Compare would read a bare name as git does, a tag before a branch: a tag `main` would pass for the
966        // branch. This endpoint knows only branches.
967        let path = format!("/repos/{repository}/branches/{base}");
968        let head: Result<BranchBody, Error> = self.get(&path).await;
969        lock(&self.etags).remove(&path);
970        let head = head?.commit.sha;
971        if !commit(&head) {
972            return Ok(false);
973        }
974        // The commits it lists are not needed: one is the fewest it sends.
975        let path = format!("/repos/{repository}/compare/{head}...{sha}?per_page=1");
976        let body: Result<CompareBody, Error> = self.get(&path).await;
977        lock(&self.etags).remove(&path);
978        // `behind`: the branch has moved on past it.
979        Ok(matches!(body?.status.as_str(), "identical" | "behind"))
980    }
981
982    async fn cancel_run(&self, repository: &str, run: u64) -> Result<(), Error> {
983        let path = format!("/repos/{repository}/actions/runs/{run}/cancel");
984        let response = self.send(Method::POST, &path, None, None).await?;
985        // 409: the run completed already.
986        if response.status == StatusCode::CONFLICT {
987            return Ok(());
988        }
989        expect_success(Method::POST, &path, response).map(|_| ())
990    }
991
992    fn spend(&self) -> Spend {
993        lock(&self.requests).spend()
994    }
995}
996
997fn jobs_path(repository: &str, run: u64) -> String {
998    format!("/repos/{repository}/actions/runs/{run}/jobs?filter=latest&per_page={PER_PAGE}")
999}
1000
1001struct Response {
1002    status: StatusCode,
1003    etag: Option<HeaderValue>,
1004    /// Whether its `Link` names a next page.
1005    next: bool,
1006    bytes: Vec<u8>,
1007}
1008
1009/// A decoded answer and whether a next page follows it.
1010struct Page<T> {
1011    body: T,
1012    next: bool,
1013}
1014
1015/// Whether a `Link` header names a next page: `<https://…&page=2>; rel="next", <…>; rel="last"`.
1016fn names_next_page(headers: &HeaderMap) -> bool {
1017    headers
1018        .get_all(header::LINK)
1019        .iter()
1020        .filter_map(|value| value.to_str().ok())
1021        .flat_map(|value| value.split(','))
1022        .any(|link| {
1023            link.split(';')
1024                .skip(1)
1025                .any(|param| param.trim() == r#"rel="next""#)
1026        })
1027}
1028
1029/// An answer kept for a conditional request on its path.
1030#[derive(Clone)]
1031struct Cached {
1032    etag: HeaderValue,
1033    body: Arc<[u8]>,
1034    /// Whether its `Link` named a next page: a 304 does not say again.
1035    next: bool,
1036}
1037
1038/// The answers kept for conditional requests, by path, within `limit` bytes. Room is made only from answers unused
1039/// for `fresh`, least recently used first; without enough of those, a new answer is not kept.
1040struct Conditional {
1041    entries: HashMap<String, Use>,
1042    bytes: usize,
1043    limit: usize,
1044    fresh: Duration,
1045}
1046
1047struct Use {
1048    cached: Cached,
1049    used: Instant,
1050}
1051
1052impl Conditional {
1053    fn new(limit: usize, fresh: Duration) -> Conditional {
1054        Conditional {
1055            entries: HashMap::new(),
1056            bytes: 0,
1057            limit,
1058            fresh,
1059        }
1060    }
1061
1062    fn size(path: &str, cached: &Cached) -> usize {
1063        path.len() + cached.body.len()
1064    }
1065
1066    /// The answer kept for `path`, which counts as using it `now`.
1067    fn get(&mut self, path: &str, now: Instant) -> Option<Cached> {
1068        let entry = self.entries.get_mut(path)?;
1069        entry.used = now;
1070        Some(entry.cached.clone())
1071    }
1072
1073    /// Keeps `cached` for `path` in place of what was kept for it, if room can be made for it.
1074    fn insert(&mut self, path: &str, cached: Cached, now: Instant) {
1075        self.remove(path);
1076        let size = Conditional::size(path, &cached);
1077        if size > self.limit {
1078            return;
1079        }
1080        while self.bytes + size > self.limit {
1081            let stale = self
1082                .entries
1083                .iter()
1084                .filter(|(_, entry)| now.saturating_duration_since(entry.used) >= self.fresh)
1085                .min_by_key(|(_, entry)| entry.used)
1086                .map(|(path, _)| path.clone());
1087            let Some(stale) = stale else {
1088                return;
1089            };
1090            self.remove(&stale);
1091        }
1092        self.bytes += size;
1093        self.entries
1094            .insert(path.to_owned(), Use { cached, used: now });
1095    }
1096
1097    fn remove(&mut self, path: &str) {
1098        if let Some(entry) = self.entries.remove(path) {
1099            self.bytes -= Conditional::size(path, &entry.cached);
1100        }
1101    }
1102
1103    /// Keeps only the answers whose path `keep` accepts.
1104    fn retain(&mut self, mut keep: impl FnMut(&str) -> bool) {
1105        let bytes = &mut self.bytes;
1106        self.entries.retain(|path, entry| {
1107            let kept = keep(path);
1108            if !kept {
1109                *bytes -= Conditional::size(path, &entry.cached);
1110            }
1111            kept
1112        });
1113    }
1114}
1115
1116fn expect_success(method: Method, path: &str, response: Response) -> Result<Response, Error> {
1117    if response.status.is_success() {
1118        return Ok(response);
1119    }
1120    let message = serde_json::from_slice::<ErrorBody>(&response.bytes).map_or_else(
1121        |_| String::from_utf8_lossy(&response.bytes).into_owned(),
1122        |body| body.message,
1123    );
1124    Err(Error::Status {
1125        method,
1126        path: path.to_owned(),
1127        status: response.status,
1128        message,
1129    })
1130}
1131
1132fn decode<T: DeserializeOwned>(path: &str, bytes: &[u8]) -> Result<T, Error> {
1133    serde_json::from_slice(bytes).map_err(|source| Error::Decode {
1134        path: path.to_owned(),
1135        source,
1136    })
1137}
1138
1139/// The number a response header carries, if it has the header and it is one.
1140fn header_number(headers: &HeaderMap, name: &str) -> Option<u64> {
1141    headers
1142        .get(name)
1143        .and_then(|value| value.to_str().ok())
1144        .and_then(|value| value.trim().parse().ok())
1145}
1146
1147/// When requests may resume, if this response says the rate limit is used up: the primary limit's reset time, or
1148/// a secondary limit's `retry-after`.
1149fn rate_limited_until(
1150    status: StatusCode,
1151    headers: &HeaderMap,
1152    now: SystemTime,
1153) -> Option<SystemTime> {
1154    let number = |name: &str| header_number(headers, name);
1155    if number("x-ratelimit-remaining") == Some(0)
1156        && let Some(reset) = number("x-ratelimit-reset")
1157    {
1158        return Some(SystemTime::UNIX_EPOCH + Duration::from_secs(reset));
1159    }
1160    if matches!(
1161        status,
1162        StatusCode::FORBIDDEN | StatusCode::TOO_MANY_REQUESTS
1163    ) && let Some(seconds) = number("retry-after")
1164    {
1165        return Some(now + Duration::from_secs(seconds));
1166    }
1167    None
1168}
1169
1170#[cfg(test)]
1171mod tests;