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