Skip to content

armgit / muxin

Public Imported from GitHub
0

All your machines, one app. For you and your AI agents: agent sessions, desktops, files, logs and GitHub across your Macs, Linux and Windows machines, with an MCP server.

45.9 KB
Raw Blame
//! GitHub REST API: runner status for orgs/repos, plus queued and running jobs
//! from recently active repos. Requests are conditional (ETag), so polling an
//! unchanged endpoint returns 304 and doesn't count against the rate limit.

use std::collections::HashMap;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

use chrono::{DateTime, TimeZone, Utc};
use futures::stream::{self, StreamExt};
use reqwest::header::{ACCEPT, AUTHORIZATION, ETAG, IF_NONE_MATCH, LINK, USER_AGENT};
use reqwest::StatusCode;
use serde::de::DeserializeOwned;
use serde::{Deserialize, Serialize};

use crate::config::GitHubSettings;

pub mod hub;

const CONCURRENCY: usize = 6;
const ORG_REPOS_TTL: Duration = Duration::from_secs(300);
const RELEASE_TTL: Duration = Duration::from_secs(6 * 3600);

// ---------------------------------------------------------------------------
// Results handed to the fleet engine

#[derive(Debug, Clone, Default)]
pub struct GitHubData {
    pub synced_at: Option<DateTime<Utc>>,
    pub token_source: String,
    pub login: Option<String>,
    /// A problem that stopped the whole sync (e.g. no token).
    pub error: Option<String>,
    pub scopes: Vec<ScopeData>,
    pub jobs: Vec<JobData>,
    pub scanned_repos: Vec<String>,
    pub rate: Option<Rate>,
    pub latest_runner_version: Option<String>,
}

#[derive(Debug, Clone)]
pub struct ScopeData {
    pub kind: ScopeKind,
    pub name: String,
    pub runners: Vec<RunnerData>,
    pub synced_at: Option<DateTime<Utc>>,
    pub error: Option<String>,
    pub hint: Option<String>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ScopeKind {
    Org,
    Repo,
}

impl ScopeKind {
    pub fn as_str(self) -> &'static str {
        match self {
            ScopeKind::Org => "org",
            ScopeKind::Repo => "repo",
        }
    }
}

#[derive(Debug, Clone)]
pub struct RunnerData {
    pub id: u64,
    pub name: String,
    pub os: String,
    pub status: String,
    pub busy: bool,
    pub labels: Vec<String>,
}

#[derive(Debug, Clone)]
pub struct JobData {
    pub id: u64,
    pub run_id: u64,
    pub name: String,
    pub workflow: String,
    pub repo: String,
    pub branch: Option<String>,
    pub event: Option<String>,
    pub actor: Option<String>,
    pub url: String,
    pub status: String,
    pub labels: Vec<String>,
    pub runner_name: Option<String>,
    pub created_at: DateTime<Utc>,
    pub started_at: Option<DateTime<Utc>>,
}

#[derive(Debug, Clone, Copy)]
pub struct Rate {
    pub limit: u32,
    pub remaining: u32,
    pub reset_at: DateTime<Utc>,
}

#[derive(Debug, Clone)]
pub struct ScopeTest {
    pub kind: ScopeKind,
    pub name: String,
    pub runners: usize,
    pub error: Option<String>,
    pub hint: Option<String>,
}

// ---------------------------------------------------------------------------
// API shapes

#[derive(Deserialize)]
struct ApiRunners {
    runners: Vec<ApiRunner>,
}

#[derive(Deserialize)]
struct ApiRunner {
    id: u64,
    name: String,
    #[serde(default)]
    os: String,
    status: String,
    #[serde(default)]
    busy: bool,
    #[serde(default)]
    labels: Vec<ApiLabel>,
}

#[derive(Deserialize)]
struct ApiLabel {
    name: String,
}

#[derive(Deserialize)]
struct ApiRuns {
    workflow_runs: Vec<ApiRun>,
}

#[derive(Deserialize)]
struct ApiRun {
    id: u64,
    #[serde(default)]
    event: Option<String>,
    #[serde(default)]
    actor: Option<ApiUser>,
}

#[derive(Deserialize)]
struct ApiUser {
    login: String,
}

#[derive(Deserialize)]
struct ApiJobs {
    jobs: Vec<ApiJob>,
}

#[derive(Deserialize)]
struct ApiJob {
    id: u64,
    run_id: u64,
    name: String,
    status: String,
    #[serde(default)]
    labels: Vec<String>,
    #[serde(default)]
    runner_name: Option<String>,
    created_at: DateTime<Utc>,
    #[serde(default)]
    started_at: Option<DateTime<Utc>>,
    #[serde(default)]
    html_url: Option<String>,
    #[serde(default)]
    workflow_name: Option<String>,
    #[serde(default)]
    head_branch: Option<String>,
}

#[derive(Deserialize)]
struct ApiRepo {
    full_name: String,
    #[serde(default)]
    archived: bool,
    #[serde(default)]
    disabled: bool,
}

#[derive(Deserialize)]
struct ApiRelease {
    tag_name: String,
    #[serde(default)]
    body: Option<String>,
}

/// An actions/runner release, with the SHA-256 GitHub published for each package.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RunnerRelease {
    /// e.g. "2.329.0"
    pub version: String,
    /// (platform, lowercase hex), e.g. ("linux-x64", "194f…"). The platform is the
    /// package name's middle: actions-runner-<platform>-<version>.tar.gz or .zip.
    pub sha256: Vec<(String, String)>,
}

/// The checksums in a release's notes, one line per package:
/// `<!-- BEGIN SHA linux-x64 -->HEX<!-- END SHA linux-x64 -->`.
fn runner_checksums(body: &str) -> Vec<(String, String)> {
    const BEGIN: &str = "<!-- BEGIN SHA ";
    let mut out: Vec<(String, String)> = Vec::new();
    let mut rest = body;
    while let Some(at) = rest.find(BEGIN) {
        rest = &rest[at + BEGIN.len()..];
        let Some((platform, after)) = rest.split_once(" -->") else { break };
        let platform = platform.trim();
        let end = format!("<!-- END SHA {platform} -->");
        let Some((hex, _)) = after.split_once(&end) else { continue };
        let hex = hex.trim().to_ascii_lowercase();
        let platform_ok = !platform.is_empty() && platform.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-');
        let hex_ok = hex.len() == 64 && hex.bytes().all(|b| b.is_ascii_hexdigit());
        if platform_ok && hex_ok && !out.iter().any(|(p, _)| p == platform) {
            out.push((platform.to_string(), hex));
        }
    }
    out
}

#[derive(Deserialize)]
struct ApiErrorBody {
    #[serde(default)]
    message: String,
}

// ---------------------------------------------------------------------------
// Client

#[derive(Debug)]
pub struct ApiError {
    pub status: Option<StatusCode>,
    pub message: String,
}

impl std::fmt::Display for ApiError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.message)
    }
}

#[derive(Clone)]
struct Token {
    value: String,
    source: String,
    /// Logins change (a new account, more permissions); look again after a while.
    fetched: Instant,
}

/// How long a token from the GitHub CLI is reused before asking it again.
const TOKEN_TTL: Duration = Duration::from_secs(60);

struct Cached {
    etag: String,
    body: std::sync::Arc<[u8]>,
    next: Option<String>,
}

/// An account the GitHub CLI is signed in to.
#[derive(Debug, Clone, Serialize)]
pub struct Account {
    pub login: String,
    /// The CLI's own active account (what `gh` uses in a terminal).
    pub gh_active: bool,
    /// False when its login has expired or been revoked.
    pub ok: bool,
    pub scopes: String,
}

/// Gets the token of another machine's GitHub CLI login: (machine id, host).
pub type TokenFetcher = Arc<dyn Fn(String, String) -> futures::future::BoxFuture<'static, Option<String>> + Send + Sync>;

pub struct Client {
    http: reqwest::Client,
    api_url: Mutex<String>,
    account: Mutex<String>,
    account_machine: Mutex<String>,
    fetcher: Mutex<Option<TokenFetcher>>,
    token: Mutex<Option<Token>>,
    cache: Mutex<HashMap<String, Cached>>,
    rate: Mutex<Option<Rate>>,
    /// The token's OAuth scopes, from GitHub's last answer (None: unknown, e.g. a fine-grained token).
    scopes: Mutex<Option<Vec<String>>>,
    login: Mutex<Option<String>>,
    org_repos: Mutex<HashMap<String, (Instant, Vec<String>)>>,
    release: Mutex<Option<(Instant, RunnerRelease)>>,
}

impl Client {
    pub fn new() -> Client {
        let http = reqwest::Client::builder()
            .timeout(Duration::from_secs(20))
            .connect_timeout(Duration::from_secs(8))
            .build()
            .expect("building HTTP client");
        Client {
            http,
            api_url: Mutex::new("https://api.github.com".into()),
            account: Mutex::new(String::new()),
            account_machine: Mutex::new(String::new()),
            fetcher: Mutex::new(None),
            token: Mutex::new(None),
            cache: Mutex::new(HashMap::new()),
            rate: Mutex::new(None),
            scopes: Mutex::new(None),
            login: Mutex::new(None),
            org_repos: Mutex::new(HashMap::new()),
            release: Mutex::new(None),
        }
    }

    /// Points the client at the configured server and account. A different
    /// server or account means different credentials and cached responses.
    fn configure(&self, settings: &GitHubSettings) {
        let mut url = self.api_url.lock().unwrap();
        let mut account = self.account.lock().unwrap();
        let mut machine = self.account_machine.lock().unwrap();
        if *url != settings.api_url || *account != settings.account || *machine != settings.account_machine {
            *url = settings.api_url.clone();
            *account = settings.account.clone();
            *machine = settings.account_machine.clone();
            *self.token.lock().unwrap() = None;
            *self.login.lock().unwrap() = None;
            self.cache.lock().unwrap().clear();
            self.org_repos.lock().unwrap().clear();
        }
    }

    /// GitHub host for `gh auth token --hostname`.
    fn gh_hostname(&self) -> String {
        let api = self.api_url.lock().unwrap().clone();
        let host = api.split("://").nth(1).unwrap_or(&api).split('/').next().unwrap_or("github.com");
        if host == "api.github.com" { "github.com".into() } else { host.to_string() }
    }

    async fn token(&self) -> Option<Token> {
        if let Some(t) = self.token.lock().unwrap().clone().filter(|t| t.fetched.elapsed() < TOKEN_TTL) {
            return Some(t);
        }
        let account = self.account.lock().unwrap().clone();
        let machine = self.account_machine.lock().unwrap().clone();
        let api = self.api_url.lock().unwrap().clone();
        let found = match env_token(&api, |var| std::env::var(var).ok()) {
            Some(t) => Some(t),
            None if machine.is_empty() => gh_token(&self.gh_hostname(), &account).await,
            None => {
                let fetch = self.fetcher.lock().unwrap().clone();
                match fetch {
                    Some(f) => f(machine, self.gh_hostname()).await.map(|value| Token { value, source: "gh".into(), fetched: Instant::now() }),
                    None => None,
                }
            }
        };
        *self.token.lock().unwrap() = found.clone();
        found
    }

    /// How to get a token when another machine's login is chosen.
    pub fn set_token_fetcher(&self, f: TokenFetcher) {
        *self.fetcher.lock().unwrap() = Some(f);
    }

    /// The token's OAuth scopes as GitHub last reported them, if it's an OAuth token.
    pub fn scopes(&self) -> Option<Vec<String>> {
        self.scopes.lock().unwrap().clone()
    }

    /// Asks for the login again on the next request (after `gh auth refresh`).
    pub fn reload_login(&self) {
        *self.token.lock().unwrap() = None;
        *self.scopes.lock().unwrap() = None;
    }

    /// Organizations you're a member of.
    pub async fn my_orgs(&self, settings: &GitHubSettings) -> Result<Vec<String>, String> {
        #[derive(Deserialize)]
        struct Org {
            login: String,
        }
        self.configure(settings);
        let pages: Vec<Vec<Org>> = self.get_all("/user/orgs?per_page=100", 2).await.map_err(|e| e.message)?;
        Ok(pages.into_iter().flatten().map(|o| o.login).collect())
    }

    fn forget_token(&self) {
        *self.token.lock().unwrap() = None;
    }

    pub fn rate(&self) -> Option<Rate> {
        *self.rate.lock().unwrap()
    }

    /// GET a JSON endpoint, following `Link: rel="next"` up to `max_pages`.
    async fn get_all<T: DeserializeOwned>(&self, path: &str, max_pages: usize) -> Result<Vec<T>, ApiError> {
        let mut out = Vec::new();
        let mut url = self.url(path);
        for _ in 0..max_pages {
            let (page, next) = self.get_page::<T>(&url, true).await?;
            out.push(page);
            match next {
                Some(n) => url = n,
                None => break,
            }
        }
        Ok(out)
    }

    async fn get<T: DeserializeOwned>(&self, path: &str) -> Result<T, ApiError> {
        Ok(self.get_page(&self.url(path), true).await?.0)
    }

    fn url(&self, path: &str) -> String {
        if path.starts_with("http") { path.to_string() } else { format!("{}{}", self.api_url.lock().unwrap(), path) }
    }

    fn get_page<'a, T: DeserializeOwned>(
        &'a self,
        url: &'a str,
        retry_auth: bool,
    ) -> futures::future::BoxFuture<'a, Result<(T, Option<String>), ApiError>> {
        Box::pin(async move {
            let Some(token) = self.token().await else {
                return Err(ApiError { status: None, message: "No GitHub token".into() });
            };
            let cached_etag = self.cache.lock().unwrap().get(url).map(|c| c.etag.clone());
            let mut req = self
                .http
                .get(url)
                .header(AUTHORIZATION, format!("Bearer {}", token.value))
                .header(ACCEPT, "application/vnd.github+json")
                .header("X-GitHub-Api-Version", "2022-11-28")
                .header(USER_AGENT, concat!("muxen/", env!("CARGO_PKG_VERSION")));
            if let Some(etag) = &cached_etag {
                req = req.header(IF_NONE_MATCH, etag);
            }
            let resp = req.send().await.map_err(|e| ApiError {
                status: None,
                message: format!("Couldn't reach GitHub: {}", root_cause(&e)),
            })?;
            self.record_rate(resp.headers());
            let status = resp.status();

            if status == StatusCode::NOT_MODIFIED {
                let cache = self.cache.lock().unwrap();
                if let Some(c) = cache.get(url) {
                    let value = serde_json::from_slice(&c.body).map_err(|e| decode_error(url, e))?;
                    return Ok((value, c.next.clone()));
                }
            }
            let rate_limited = resp
                .headers()
                .get("x-ratelimit-remaining")
                .and_then(|v| v.to_str().ok())
                .is_some_and(|v| v == "0");
            if retry_auth && refused(status, rate_limited) {
                // The login may have changed since we read it (`gh auth refresh`
                // granting a permission, another account): look again, and retry
                // once if it did.
                self.forget_token();
                if self.token().await.is_some_and(|fresh| status == StatusCode::UNAUTHORIZED || fresh.value != token.value) {
                    return self.get_page(url, false).await;
                }
            }
            if !status.is_success() {
                let body = resp.bytes().await.unwrap_or_default();
                let message = serde_json::from_slice::<ApiErrorBody>(&body).map(|b| b.message).unwrap_or_default();
                let message = if rate_limited {
                    "GitHub API rate limit reached".to_string()
                } else if message.is_empty() {
                    format!("GitHub returned {status}")
                } else {
                    message
                };
                return Err(ApiError { status: Some(status), message });
            }

            let etag = resp.headers().get(ETAG).and_then(|v| v.to_str().ok()).map(str::to_string);
            let next = resp.headers().get(LINK).and_then(|v| v.to_str().ok()).and_then(next_link);
            let body: std::sync::Arc<[u8]> = resp
                .bytes()
                .await
                .map_err(|e| ApiError { status: None, message: format!("Reading GitHub response: {e}") })?
                .to_vec()
                .into();
            let value = serde_json::from_slice(&body).map_err(|e| decode_error(url, e))?;
            if let Some(etag) = etag {
                self.cache.lock().unwrap().insert(url.to_string(), Cached { etag, body, next: next.clone() });
            }
            Ok((value, next))
        })
    }

    fn record_rate(&self, headers: &reqwest::header::HeaderMap) {
        if let Some(s) = headers.get("x-oauth-scopes").and_then(|v| v.to_str().ok()) {
            *self.scopes.lock().unwrap() = Some(s.split(',').map(|x| x.trim().to_string()).filter(|x| !x.is_empty()).collect());
        }
        let num = |name: &str| headers.get(name).and_then(|v| v.to_str().ok()).and_then(|v| v.parse::<i64>().ok());
        if let (Some(limit), Some(remaining), Some(reset)) =
            (num("x-ratelimit-limit"), num("x-ratelimit-remaining"), num("x-ratelimit-reset"))
        {
            // Only the core REST bucket matters here.
            let resource = headers.get("x-ratelimit-resource").and_then(|v| v.to_str().ok()).unwrap_or("core");
            if resource == "core" {
                *self.rate.lock().unwrap() = Some(Rate {
                    limit: limit as u32,
                    remaining: remaining as u32,
                    reset_at: Utc.timestamp_opt(reset, 0).single().unwrap_or_else(Utc::now),
                });
            }
        }
    }

    async fn login(&self) -> Option<String> {
        if let Some(l) = self.login.lock().unwrap().clone() {
            return Some(l);
        }
        #[derive(Deserialize)]
        struct User {
            login: String,
        }
        let user: User = self.get("/user").await.ok()?;
        *self.login.lock().unwrap() = Some(user.login.clone());
        Some(user.login)
    }

    async fn runners(&self, kind: ScopeKind, name: &str) -> Result<Vec<RunnerData>, ApiError> {
        let path = match kind {
            ScopeKind::Org => format!("/orgs/{name}/actions/runners?per_page=100"),
            ScopeKind::Repo => format!("/repos/{name}/actions/runners?per_page=100"),
        };
        let pages: Vec<ApiRunners> = self.get_all(&path, 10).await?;
        Ok(pages
            .into_iter()
            .flat_map(|p| p.runners)
            .map(|r| RunnerData {
                id: r.id,
                name: r.name,
                os: r.os,
                status: r.status,
                busy: r.busy,
                labels: r.labels.into_iter().map(|l| l.name).collect(),
            })
            .collect())
    }

    /// The most recently pushed, non-archived repos of an org (cached for a few minutes).
    async fn org_repos(&self, org: &str, limit: usize) -> Vec<String> {
        if limit == 0 {
            return Vec::new();
        }
        let key = format!("{org}:{limit}");
        if let Some((at, repos)) = self.org_repos.lock().unwrap().get(&key) {
            if at.elapsed() < ORG_REPOS_TTL {
                return repos.clone();
            }
        }
        let per_page = (limit + 5).min(100);
        let path = format!("/orgs/{org}/repos?sort=pushed&direction=desc&per_page={per_page}");
        let repos: Vec<String> = match self.get::<Vec<ApiRepo>>(&path).await {
            Ok(list) => list.into_iter().filter(|r| !r.archived && !r.disabled).map(|r| r.full_name).take(limit).collect(),
            Err(e) => {
                tracing::debug!("listing repos for {org}: {e}");
                Vec::new()
            }
        };
        self.org_repos.lock().unwrap().insert(key, (Instant::now(), repos.clone()));
        repos
    }

    /// Queued and in-progress jobs for one repo.
    async fn active_jobs(&self, repo: &str) -> Vec<JobData> {
        let mut runs = Vec::new();
        for status in ["queued", "in_progress"] {
            match self.get::<ApiRuns>(&format!("/repos/{repo}/actions/runs?status={status}&per_page=30")).await {
                Ok(r) => runs.extend(r.workflow_runs),
                Err(e) => tracing::debug!("listing {status} runs for {repo}: {e}"),
            }
        }
        runs.sort_by_key(|r| r.id);
        runs.dedup_by_key(|r| r.id);

        let per_run = stream::iter(runs)
            .map(|run| async move {
                let jobs = self
                    .get::<ApiJobs>(&format!("/repos/{repo}/actions/runs/{}/jobs?per_page=100", run.id))
                    .await
                    .map(|j| j.jobs)
                    .unwrap_or_default();
                jobs.into_iter()
                    .filter(|j| matches!(j.status.as_str(), "queued" | "in_progress" | "waiting" | "pending"))
                    .map(|j| JobData {
                        id: j.id,
                        run_id: j.run_id,
                        name: j.name,
                        workflow: j.workflow_name.unwrap_or_default(),
                        repo: repo.to_string(),
                        branch: j.head_branch,
                        event: run.event.clone(),
                        actor: run.actor.as_ref().map(|a| a.login.clone()),
                        url: j.html_url.unwrap_or_else(|| format!("https://github.com/{repo}/actions/runs/{}", j.run_id)),
                        status: if j.status == "pending" { "queued".into() } else { j.status },
                        labels: j.labels,
                        runner_name: j.runner_name.filter(|n| !n.is_empty()),
                        created_at: j.created_at,
                        started_at: j.started_at,
                    })
                    .collect::<Vec<_>>()
            })
            .buffer_unordered(CONCURRENCY)
            .collect::<Vec<_>>()
            .await;
        per_run.into_iter().flatten().collect()
    }

    async fn latest_runner_version(&self) -> Option<String> {
        self.latest_release().await.map(|r| r.version)
    }

    async fn latest_release(&self) -> Option<RunnerRelease> {
        if let Some((at, r)) = self.release.lock().unwrap().clone() {
            if at.elapsed() < RELEASE_TTL {
                return Some(r);
            }
        }
        let rel: ApiRelease = self.get("/repos/actions/runner/releases/latest").await.ok()?;
        let r = RunnerRelease {
            version: rel.tag_name.trim_start_matches('v').to_string(),
            sha256: runner_checksums(rel.body.as_deref().unwrap_or_default()),
        };
        *self.release.lock().unwrap() = Some((Instant::now(), r.clone()));
        Some(r)
    }

    /// One full pass: runners for every configured scope, then active jobs.
    pub async fn sync(&self, settings: &GitHubSettings) -> GitHubData {
        self.configure(settings);
        let mut data = GitHubData::default();
        let Some(token) = self.token().await else {
            data.error = Some("No GitHub token found. Run `gh auth login` or set GITHUB_TOKEN.".into());
            return data;
        };
        data.token_source = token.source;
        data.login = self.login().await;

        let scopes: Vec<(ScopeKind, String)> = settings
            .orgs
            .iter()
            .map(|o| (ScopeKind::Org, o.clone()))
            .chain(settings.repos.iter().map(|r| (ScopeKind::Repo, r.clone())))
            .collect();

        data.scopes = stream::iter(scopes)
            .map(|(kind, name)| async move {
                let result = self.runners(kind, &name).await;
                let (runners, error, hint) = match result {
                    Ok(r) => (r, None, None),
                    Err(e) => {
                        let (msg, hint) = explain(kind, &name, &e, &data_token_source(self));
                        (Vec::new(), Some(msg), hint)
                    }
                };
                ScopeData {
                    kind,
                    synced_at: error.is_none().then(Utc::now),
                    name,
                    runners,
                    error,
                    hint,
                }
            })
            .buffered(CONCURRENCY)
            .collect()
            .await;

        // Repos to scan for jobs: the configured ones plus each org's most recently pushed repos.
        let mut repos: Vec<String> = settings.repos.clone();
        for org in &settings.orgs {
            for r in self.org_repos(org, settings.scan_repos as usize).await {
                if !repos.iter().any(|x| x.eq_ignore_ascii_case(&r)) {
                    repos.push(r);
                }
            }
        }
        data.jobs = stream::iter(repos.clone())
            .map(|repo| async move { self.active_jobs(&repo).await })
            .buffer_unordered(CONCURRENCY)
            .collect::<Vec<_>>()
            .await
            .into_iter()
            .flatten()
            .collect();
        data.scanned_repos = repos;
        data.latest_runner_version = self.latest_runner_version().await;
        data.rate = self.rate();
        data.synced_at = Some(Utc::now());
        if !data.scopes.is_empty() && data.scopes.iter().all(|s| s.error.is_some()) {
            data.error = data.scopes.first().and_then(|s| s.error.clone());
        }
        data
    }

    /// Validates an org or repo before it's added in Settings.
    pub async fn test_scope(&self, settings: &GitHubSettings, scope: &str) -> ScopeTest {
        self.configure(settings);
        let name = crate::config::strip_github_url(scope);
        let kind = if name.contains('/') { ScopeKind::Repo } else { ScopeKind::Org };
        if self.token().await.is_none() {
            return ScopeTest {
                kind,
                name,
                runners: 0,
                error: Some("No GitHub token found.".into()),
                hint: Some("gh auth login".into()),
            };
        }
        match self.runners(kind, &name).await {
            Ok(r) => ScopeTest { kind, name, runners: r.len(), error: None, hint: None },
            Err(e) => {
                let (msg, hint) = explain(kind, &name, &e, &data_token_source(self));
                ScopeTest { kind, name, runners: 0, error: Some(msg), hint }
            }
        }
    }

    // -----------------------------------------------------------------------
    // Writes, used by runner provisioning. Never cached.

    /// A short-lived token for `config.sh` (registering new runners). The scripts
    /// hand it over in ACTIONS_RUNNER_INPUT_TOKEN, never on a command line.
    pub async fn registration_token(&self, settings: &GitHubSettings, scope: &str) -> Result<String, String> {
        let (kind, name) = parse_scope(scope);
        let doing = format!("Registering runners with {name}");
        self.scoped_token(settings, kind, &name, "registration-token", &doing).await
    }

    /// A short-lived token for `config.sh remove` (deregistering a runner), handed
    /// over the same way.
    pub async fn remove_token(&self, settings: &GitHubSettings, scope: &str) -> Result<String, String> {
        let (kind, name) = parse_scope(scope);
        let doing = format!("Removing runners from {name}");
        self.scoped_token(settings, kind, &name, "remove-token", &doing).await
    }

    /// Deletes a runner registration directly, for runners whose machine is gone.
    pub async fn delete_runner(&self, settings: &GitHubSettings, scope: &str, runner_id: u64) -> Result<(), String> {
        self.configure(settings);
        let (kind, name) = parse_scope(scope);
        let path = format!("{}/actions/runners/{runner_id}", scope_path(kind, &name));
        match self.send(reqwest::Method::DELETE, &path).await {
            Ok(_) => Ok(()),
            Err(e) => Err(with_hint(explain_doing(kind, &name, &e, &data_token_source(self), &format!("Removing runners from {name}")))),
        }
    }

    /// Cancels a workflow run: every job in it that hasn't finished.
    pub async fn cancel_run(&self, settings: &GitHubSettings, repo: &str, run_id: u64) -> Result<(), String> {
        self.configure(settings);
        let path = format!("/repos/{repo}/actions/runs/{run_id}/cancel");
        match self.send(reqwest::Method::POST, &path).await {
            Ok(_) => Ok(()),
            Err(e) => Err(with_hint(explain_doing(ScopeKind::Repo, repo, &e, &data_token_source(self), &format!("Cancelling a run in {repo}")))),
        }
    }

    /// The newest actions/runner release (e.g. 2.329.0) and its packages' SHA-256.
    pub async fn latest_runner_release(&self, settings: &GitHubSettings) -> Option<RunnerRelease> {
        self.configure(settings);
        self.latest_release().await
    }

    /// The URL runners are registered against, e.g. https://github.com/acme.
    pub fn web_url(&self, settings: &GitHubSettings, scope: &str) -> String {
        self.configure(settings);
        let (_, name) = parse_scope(scope);
        format!("https://{}/{name}", self.gh_hostname())
    }

    async fn scoped_token(&self, settings: &GitHubSettings, kind: ScopeKind, name: &str, which: &str, doing: &str) -> Result<String, String> {
        #[derive(Deserialize)]
        struct TokenBody {
            token: String,
        }
        self.configure(settings);
        if self.token().await.is_none() {
            return Err("No GitHub token found. Run `gh auth login` or set GITHUB_TOKEN.".into());
        }
        let path = format!("{}/actions/runners/{which}", scope_path(kind, name));
        match self.send(reqwest::Method::POST, &path).await {
            Ok(body) => serde_json::from_slice::<TokenBody>(&body)
                .map(|b| b.token)
                .map_err(|e| format!("Unexpected response from GitHub: {e}")),
            Err(e) => Err(with_hint(explain_doing(kind, name, &e, &data_token_source(self), doing))),
        }
    }

    /// An uncached request; retries once with a fresh token on 401.
    async fn send(&self, method: reqwest::Method, path: &str) -> Result<Vec<u8>, ApiError> {
        let url = self.url(path);
        for attempt in 0..2 {
            let Some(token) = self.token().await else {
                return Err(ApiError { status: None, message: "No GitHub token".into() });
            };
            let resp = self
                .http
                .request(method.clone(), &url)
                .header(AUTHORIZATION, format!("Bearer {}", token.value))
                .header(ACCEPT, "application/vnd.github+json")
                .header("X-GitHub-Api-Version", "2022-11-28")
                .header(USER_AGENT, concat!("muxen/", env!("CARGO_PKG_VERSION")))
                .send()
                .await
                .map_err(|e| ApiError { status: None, message: format!("Couldn't reach GitHub: {}", root_cause(&e)) })?;
            self.record_rate(resp.headers());
            let status = resp.status();
            let rate_limited = resp.headers().get("x-ratelimit-remaining").and_then(|v| v.to_str().ok()).is_some_and(|v| v == "0");
            if attempt == 0 && refused(status, rate_limited) {
                // As in get_page: a changed login gets one more try.
                self.forget_token();
                if self.token().await.is_some_and(|fresh| status == StatusCode::UNAUTHORIZED || fresh.value != token.value) {
                    continue;
                }
            }
            let body = resp.bytes().await.map(|b| b.to_vec()).unwrap_or_default();
            if status.is_success() {
                return Ok(body);
            }
            let message = serde_json::from_slice::<ApiErrorBody>(&body).map(|b| b.message).unwrap_or_default();
            let message = if message.is_empty() { format!("GitHub returned {status}") } else { message };
            return Err(ApiError { status: Some(status), message });
        }
        Err(ApiError { status: Some(StatusCode::UNAUTHORIZED), message: "GitHub rejected the token.".into() })
    }

    /// The accounts the GitHub CLI is signed in to on this server.
    pub async fn accounts(&self, settings: &GitHubSettings) -> Result<Vec<Account>, String> {
        #[derive(Deserialize)]
        struct Status {
            hosts: HashMap<String, Vec<RawAccount>>,
        }
        #[derive(Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct RawAccount {
            login: String,
            #[serde(default)]
            active: bool,
            #[serde(default)]
            state: String,
            #[serde(default)]
            scopes: Option<String>,
        }
        self.configure(settings);
        let host = self.gh_hostname();
        let out = tokio::process::Command::new(gh_program())
            .args(["auth", "status", "--json", "hosts", "--hostname", &host])
            .output()
            .await
            .map_err(|e| format!("Couldn't run the GitHub CLI (gh): {e}"))?;
        // It exits 1 when an account has a problem, but still lists them all.
        let status: Status = serde_json::from_slice(&out.stdout)
            .map_err(|_| "The GitHub CLI (gh) couldn't list its accounts. It needs gh 2.40 or newer.".to_string())?;
        Ok(status
            .hosts
            .into_values()
            .flatten()
            .map(|a| Account { ok: a.state.is_empty() || a.state == "success", login: a.login, gh_active: a.active, scopes: a.scopes.unwrap_or_default() })
            .collect())
    }

    pub async fn token_source(&self) -> String {
        self.token().await.map(|t| t.source).unwrap_or_default()
    }

    /// The GitHub web host (e.g. "github.com") and the user's token, for cloning
    /// private repositories into agent workspaces. The caller must keep the token
    /// out of argv and logs.
    pub async fn git_credentials(&self, settings: &GitHubSettings) -> Option<(String, String)> {
        self.configure(settings);
        let token = self.token().await?;
        Some((self.gh_hostname(), token.value))
    }
}

/// GitHub turning the login away (not a rate limit): bad token, missing permission, or hidden.
fn refused(status: StatusCode, rate_limited: bool) -> bool {
    status == StatusCode::UNAUTHORIZED || (!rate_limited && (status == StatusCode::FORBIDDEN || status == StatusCode::NOT_FOUND))
}

fn data_token_source(client: &Client) -> String {
    client.token.lock().unwrap().as_ref().map(|t| t.source.clone()).unwrap_or_default()
}

/// Turns API failures into a sentence and, where possible, the command that fixes it.
fn explain(kind: ScopeKind, name: &str, e: &ApiError, token_source: &str) -> (String, Option<String>) {
    explain_doing(kind, name, e, token_source, &format!("Reading {name}'s runners"))
}

/// Like `explain`, for a specific action ("Registering runners with acme").
fn explain_doing(kind: ScopeKind, name: &str, e: &ApiError, token_source: &str, doing: &str) -> (String, Option<String>) {
    let via_gh = token_source == "gh";
    match (kind, e.status.map(|s| s.as_u16())) {
        (_, Some(401)) => (
            "GitHub rejected the token.".into(),
            Some(if via_gh { "gh auth login".into() } else { "Check GITHUB_TOKEN".into() }),
        ),
        (ScopeKind::Org, Some(403)) if !e.message.contains("rate limit") => (
            format!("{doing} needs an org admin token with the admin:org scope."),
            via_gh.then(|| "gh auth refresh -h github.com -s admin:org".into()),
        ),
        (ScopeKind::Org, Some(404)) => (format!("Organization {name} wasn't found, or you aren't an admin of it."), None),
        (ScopeKind::Repo, Some(403 | 404)) if !e.message.contains("rate limit") => {
            (format!("{name} wasn't found, or you don't have admin access to it."), None)
        }
        _ => (e.message.clone(), None),
    }
}

fn with_hint((msg, hint): (String, Option<String>)) -> String {
    match hint {
        Some(h) => format!("{msg} Run `{h}`."),
        None => msg,
    }
}

/// "acme", "org:acme" -> (Org, "acme"); "acme/api", "repo:acme/api" -> (Repo, "acme/api")
pub fn parse_scope(scope: &str) -> (ScopeKind, String) {
    let s = scope.trim();
    let s = s.strip_prefix("org:").or_else(|| s.strip_prefix("repo:")).unwrap_or(s);
    let name = crate::config::strip_github_url(s);
    let kind = if name.contains('/') { ScopeKind::Repo } else { ScopeKind::Org };
    (kind, name)
}

fn scope_path(kind: ScopeKind, name: &str) -> String {
    match kind {
        ScopeKind::Org => format!("/orgs/{name}"),
        ScopeKind::Repo => format!("/repos/{name}"),
    }
}

/// A token from the environment (`var` reads it), which wins over any login.
/// By gh's rule: `MUXEN_GITHUB_TOKEN`, `GITHUB_TOKEN` and `GH_TOKEN` are
/// github.com's, so they go to api.github.com only; any other server gets
/// `GH_ENTERPRISE_TOKEN` or `GITHUB_ENTERPRISE_TOKEN`. None over plain http.
fn env_token(api_url: &str, var: impl Fn(&str) -> Option<String>) -> Option<Token> {
    let url = reqwest::Url::parse(api_url).ok().filter(|u| u.scheme() == "https")?;
    let names: &[&str] = if url.host_str() == Some("api.github.com") {
        &["MUXEN_GITHUB_TOKEN", "OPENRUNNER_GITHUB_TOKEN", "GITHUB_TOKEN", "GH_TOKEN"]
    } else {
        &["GH_ENTERPRISE_TOKEN", "GITHUB_ENTERPRISE_TOKEN"]
    };
    names.iter().find_map(|name| {
        let v = var(name)?;
        (!v.trim().is_empty()).then(|| Token { value: v.trim().to_string(), source: name.to_string(), fetched: Instant::now() })
    })
}

/// `gh auth token` here, for `account`, else the GitHub CLI's active account.
async fn gh_token(hostname: &str, account: &str) -> Option<Token> {
    let mut cmd = tokio::process::Command::new(gh_program());
    cmd.args(["auth", "token", "--hostname", hostname]).kill_on_drop(true);
    if !account.is_empty() {
        cmd.args(["--user", account]);
    }
    // A locked keyring can make gh wait indefinitely.
    let out = tokio::time::timeout(Duration::from_secs(10), cmd.output()).await.ok()?.ok()?;
    let value = String::from_utf8_lossy(&out.stdout).trim().to_string();
    (out.status.success() && !value.is_empty()).then(|| Token { value, source: "gh".into(), fetched: Instant::now() })
}

/// `gh` from PATH, or from where installers usually put it. Apps started from
/// Finder, the Dock or a desktop launcher get a minimal PATH without Homebrew.
fn gh_program() -> std::path::PathBuf {
    let on_path = std::env::var_os("PATH")
        .map(|p| std::env::split_paths(&p).any(|dir| dir.join(if cfg!(windows) { "gh.exe" } else { "gh" }).is_file()))
        .unwrap_or(false);
    if on_path {
        return "gh".into();
    }
    let home = dirs::home_dir().unwrap_or_default();
    let candidates = [
        std::path::PathBuf::from("/opt/homebrew/bin/gh"),
        "/usr/local/bin/gh".into(),
        "/home/linuxbrew/.linuxbrew/bin/gh".into(),
        "/usr/bin/gh".into(),
        "/snap/bin/gh".into(),
        home.join(".local/bin/gh"),
        home.join("bin/gh"),
        r"C:\Program Files\GitHub CLI\gh.exe".into(),
    ];
    candidates.into_iter().find(|p| p.is_file()).unwrap_or_else(|| "gh".into())
}

fn next_link(header: &str) -> Option<String> {
    header.split(',').find_map(|part| {
        let (url, rel) = part.split_once(';')?;
        rel.contains("rel=\"next\"").then(|| url.trim().trim_start_matches('<').trim_end_matches('>').to_string())
    })
}

fn decode_error(url: &str, e: serde_json::Error) -> ApiError {
    ApiError { status: None, message: format!("Unexpected response from {url}: {e}") }
}

fn root_cause(e: &(dyn std::error::Error + 'static)) -> String {
    let mut cur = e;
    while let Some(next) = cur.source() {
        cur = next;
    }
    cur.to_string()
}

/// Labels GitHub uses for its own hosted runners. A job asking only for these
/// isn't waiting for one of our machines.
pub fn is_github_hosted_label(label: &str) -> bool {
    let l = label.to_ascii_lowercase();
    ["ubuntu-", "windows-", "macos-"].iter().any(|p| l.starts_with(p))
}

/// "https://github.com/acme" -> "acme", "https://github.com/acme/api" -> "acme/api"
pub fn scope_from_runner_url(url: &str) -> Option<String> {
    let rest = url.trim().strip_prefix("https://").or_else(|| url.trim().strip_prefix("http://"))?;
    let (_, path) = rest.split_once('/')?;
    let parts: Vec<&str> = path.trim_matches('/').split('/').filter(|p| !p.is_empty()).collect();
    match parts.as_slice() {
        ["enterprises", ..] => None,
        [org] => Some(org.to_string()),
        [owner, repo] => Some(format!("{owner}/{repo}")),
        _ => None,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn env_tokens_go_only_to_their_own_server() {
        let env = |name: &str| ["GH_TOKEN", "GH_ENTERPRISE_TOKEN"].contains(&name).then(|| format!("{name}-value"));
        let source = |api: &str| env_token(api, env).map(|t| t.source);
        assert_eq!(source("https://api.github.com").as_deref(), Some("GH_TOKEN"));
        assert_eq!(source("https://ghe.example.com/api/v3").as_deref(), Some("GH_ENTERPRISE_TOKEN"));
        // github.com's token goes nowhere else, whatever the URL looks like.
        let github_only = |name: &str| (name == "GITHUB_TOKEN").then(|| "secret".to_string());
        for api in ["https://ghe.example.com/api/v3", "https://api.github.com.evil.example", "https://[email protected]", "http://api.github.com"] {
            assert!(env_token(api, github_only).is_none(), "{api}");
        }
    }

    #[test]
    fn parses_link_header() {
        let h = r#"<https://api.github.com/orgs/acme/actions/runners?page=2>; rel="next", <https://api.github.com/orgs/acme/actions/runners?page=5>; rel="last""#;
        assert_eq!(next_link(h).as_deref(), Some("https://api.github.com/orgs/acme/actions/runners?page=2"));
        assert_eq!(next_link(r#"<x>; rel="prev""#), None);
    }

    #[test]
    fn scopes_from_urls() {
        assert_eq!(scope_from_runner_url("https://github.com/acme").as_deref(), Some("acme"));
        assert_eq!(scope_from_runner_url("https://github.com/acme/api/").as_deref(), Some("acme/api"));
        assert_eq!(scope_from_runner_url("https://github.com/enterprises/big"), None);
    }

    #[test]
    fn parses_scopes() {
        assert_eq!(parse_scope("org:acme"), (ScopeKind::Org, "acme".into()));
        assert_eq!(parse_scope("repo:acme/api"), (ScopeKind::Repo, "acme/api".into()));
        assert_eq!(parse_scope(" https://github.com/acme/api "), (ScopeKind::Repo, "acme/api".into()));
        assert_eq!(scope_path(ScopeKind::Org, "acme"), "/orgs/acme");
    }

    #[test]
    fn explains_registration_errors() {
        let e = ApiError { status: Some(StatusCode::FORBIDDEN), message: "Resource not accessible".into() };
        let msg = with_hint(explain_doing(ScopeKind::Org, "acme", &e, "gh", "Registering runners with acme"));
        assert_eq!(
            msg,
            "Registering runners with acme needs an org admin token with the admin:org scope. Run `gh auth refresh -h github.com -s admin:org`."
        );
    }

    /// The end of actions/runner v2.338.0's release notes (they use CRLF).
    const RUNNER_NOTES: &str = "## Using your self hosted runner\r\n\r\nSee the docs.\r\n\r\n\
## SHA-256 Checksums\r\n\r\n\
The SHA-256 checksums for the packages included in this build are shown below:\r\n\r\n\
- actions-runner-win-x64-2.338.0.zip <!-- BEGIN SHA win-x64 -->f48e0750a21812bca5f82de5f7f5aeae71abee647fab5a582f1742d07eba455f<!-- END SHA win-x64 -->\r\n\
- actions-runner-win-arm64-2.338.0.zip <!-- BEGIN SHA win-arm64 -->a57a4d29c0dcf02210a16b01906ed76cb8091b26d728c41232736c0f627a557e<!-- END SHA win-arm64 -->\r\n\
- actions-runner-osx-x64-2.338.0.tar.gz <!-- BEGIN SHA osx-x64 -->dea7a58796ce215fc424a8b27c0fdd9b813fa5fc03d109a4a1d38131d6bfa1a3<!-- END SHA osx-x64 -->\r\n\
- actions-runner-osx-arm64-2.338.0.tar.gz <!-- BEGIN SHA osx-arm64 -->df4cebda25c86a886ed204e49fee63f5c2e7cec5f447b5c98440a826bbdf9df2<!-- END SHA osx-arm64 -->\r\n\
- actions-runner-linux-x64-2.338.0.tar.gz <!-- BEGIN SHA linux-x64 -->af4b794c1bc41d73d40535e3fe092a39f9679cd8d965954c2aca25a05ca41d32<!-- END SHA linux-x64 -->\r\n\
- actions-runner-linux-arm64-2.338.0.tar.gz <!-- BEGIN SHA linux-arm64 -->628b4a7258487b80c1d3c221095a7ded349f5ae0175fd3dfab708d07428f041b<!-- END SHA linux-arm64 -->\r\n\
- actions-runner-linux-arm-2.338.0.tar.gz <!-- BEGIN SHA linux-arm -->1d6a7688d2aca1a1fecd4df5d473e4aa4226c1f1785ff915cf84049665a3483f<!-- END SHA linux-arm -->\n";

    #[test]
    fn reads_runner_checksums_from_release_notes() {
        let sums = runner_checksums(RUNNER_NOTES);
        let sha = |platform: &str| sums.iter().find(|(p, _)| p == platform).map(|(_, h)| h.as_str());
        // Every package install.sh (osx/linux: x64, arm64, arm) and install.ps1 (win: x64, arm64) picks.
        assert_eq!(sha("osx-x64"), Some("dea7a58796ce215fc424a8b27c0fdd9b813fa5fc03d109a4a1d38131d6bfa1a3"));
        assert_eq!(sha("osx-arm64"), Some("df4cebda25c86a886ed204e49fee63f5c2e7cec5f447b5c98440a826bbdf9df2"));
        assert_eq!(sha("linux-x64"), Some("af4b794c1bc41d73d40535e3fe092a39f9679cd8d965954c2aca25a05ca41d32"));
        assert_eq!(sha("linux-arm64"), Some("628b4a7258487b80c1d3c221095a7ded349f5ae0175fd3dfab708d07428f041b"));
        assert_eq!(sha("linux-arm"), Some("1d6a7688d2aca1a1fecd4df5d473e4aa4226c1f1785ff915cf84049665a3483f"));
        assert_eq!(sha("win-x64"), Some("f48e0750a21812bca5f82de5f7f5aeae71abee647fab5a582f1742d07eba455f"));
        assert_eq!(sha("win-arm64"), Some("a57a4d29c0dcf02210a16b01906ed76cb8091b26d728c41232736c0f627a557e"));
        assert_eq!(sums.len(), 7);
    }

    #[test]
    fn skips_release_notes_without_good_checksums() {
        // Notes from before the markers, or with none at all: nothing to check against.
        assert!(runner_checksums("## Features\r\n- Faster\r\n").is_empty());
        assert!(runner_checksums("").is_empty());
        let odd = "<!-- BEGIN SHA linux-x64 -->not-hex<!-- END SHA linux-x64 -->\
<!-- BEGIN SHA osx-x64 -->DEA7A58796CE215FC424A8B27C0FDD9B813FA5FC03D109A4A1D38131D6BFA1A3<!-- END SHA osx-x64 -->\
<!-- BEGIN SHA osx-x64 -->0000000000000000000000000000000000000000000000000000000000000000<!-- END SHA osx-x64 -->\
<!-- BEGIN SHA win x64 -->f48e0750a21812bca5f82de5f7f5aeae71abee647fab5a582f1742d07eba455f<!-- END SHA win x64 -->\
<!-- BEGIN SHA linux-arm -->1d6a7688d2aca1a1fecd4df5d473e4aa4226c1f1785ff915cf84049665a3483f<!-- END SHA linux-arm64 -->\
<!-- BEGIN SHA win-arm64 -->a57a4d29";
        // Short or non-hex values, names with spaces and mismatched ends are left out;
        // hex is lowercased, and the first value for a platform wins.
        assert_eq!(runner_checksums(odd), vec![("osx-x64".to_string(), "dea7a58796ce215fc424a8b27c0fdd9b813fa5fc03d109a4a1d38131d6bfa1a3".to_string())]);
    }

    #[test]
    fn explains_org_permission_errors() {
        let e = ApiError { status: Some(StatusCode::FORBIDDEN), message: "Must have admin rights".into() };
        let (msg, hint) = explain(ScopeKind::Org, "acme", &e, "gh");
        assert!(msg.contains("admin:org"));
        assert_eq!(hint.as_deref(), Some("gh auth refresh -h github.com -s admin:org"));
    }
}