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