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