oh runner-updates and the admin API for runner updates 9bbca80f777a

- **`oh runner-updates` and its API (#322):** site administrators read every level's update settings, the test groups, each runner's policy and offer, and the held builds (`GET /api/v1/admin/runner-updates`); `oh runner-updates set group:canary --updates on --window 02-05` changes one level, keeping what is not given (`PUT …/settings`, 422 saying what is wrong); `oh runner-updates lift 0.4.0` offers a held build again (`POST …/holds/{version}/lift`).

/// `GET /api/v1/admin/runner-updates` (oxygenhub#322): where runner builds

/// come from, every level's settings, the test groups, each runner's policy

/// and what it is offered, and the builds held back (#326). Site

/// administrators only.

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct RunnerUpdates {

    /// The repository whose releases carry runner builds (`owner/name`).

    pub repo: String,

    pub settings: Vec<UpdateSetting>,

    pub groups: Vec<RunnerGroup>,

    pub runners: Vec<RunnerUpdate>,

    pub holds: Vec<HeldBuild>,

}

/// One level's update settings; `None` inherits from the next level out.

/// `PUT /api/v1/admin/runner-updates/settings` takes one.

#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct UpdateSetting {

    /// `site`, `owner`, `group` or `runner`.

    pub scope: String,

    /// Empty for the site; the owner's name, the group's id, the runner's id.

    #[serde(default)]

    pub key: String,

    #[serde(default)]

    pub updates: Option<bool>,

    /// `stable`, `canary` or a version.

    #[serde(default)]

    pub channel: Option<String>,

    /// Hours (UTC) in which updates may start, `02-05`.

    #[serde(default)]

    pub window: Option<String>,

    #[serde(default)]

    pub dry_run: Option<bool>,

}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct RunnerGroup {

    pub id: i64,

    /// Empty for a group of the site's runners.

    pub owner: String,

    pub name: String,

    /// A share of the runners in reach; `None`: chosen ones.

    pub percent: Option<i64>,

    /// Its runners now, by name.

    pub members: Vec<String>,

}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct RunnerUpdate {

    pub id: i64,

    pub name: String,

    /// The owner it serves; empty for the site's.

    pub owner: String,

    pub version: String,

    pub groups: Vec<String>,

    pub updates: bool,

    pub channel: String,

    #[serde(default)]

    pub window: Option<String>,

    pub dry_run: bool,

    /// Where each setting came from, in the order updates, channel, window, dry run.

    pub from: Vec<String>,

    /// What the hub would offer it now, in words.

    pub now: String,

    /// What it last said about its update.

    pub said: String,

}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct HeldBuild {

    pub version: String,

    pub runner: String,

    pub why: String,

    pub at_ms: i64,

}

        .route("/admin/runner-updates", get(runner_updates))

        .route("/admin/runner-updates/settings", axum::routing::put(runner_update_setting))

        .route("/admin/runner-updates/holds/{version}/lift", post(runner_update_lift))

/// `GET /api/v1/admin/runner-updates` (oxygenhub#322, #326).

async fn runner_updates(State(app): State<Shared>, headers: HeaderMap) -> Result<Json<RunnerUpdates>, ApiError> {

    let c = caller(&app, &headers).await?;

    require_site_admin(&c)?;

    use crate::web::runner_updates::{views, Reach};

    let v = views(&app, &Reach::Site).await?;

    let setting = |p: &crate::web::runner_updates::PolicyView| UpdateSetting {

        scope: p.scope.clone(),

        key: p.key.clone(),

        updates: match p.updates {

            "on" => Some(true),

            "off" => Some(false),

            _ => None,

        },

        channel: Some(p.channel.clone()).filter(|c| !c.is_empty()),

        window: Some(p.window.clone()).filter(|w| !w.is_empty()),

        dry_run: match p.dry_run {

            "on" => Some(true),

            "off" => Some(false),

            _ => None,

        },

    };

    let mut settings = vec![setting(&v.site)];

    settings.extend(v.owners.iter().map(setting));

    settings.extend(v.groups.iter().map(|g| setting(&g.policy)));

    settings.extend(v.runners.iter().map(|r| setting(&r.policy)));

    settings.retain(|s| s.scope == "site" || s.updates.is_some() || s.channel.is_some() || s.window.is_some() || s.dry_run.is_some());

    Ok(Json(RunnerUpdates {

        repo: db::accounts::setting(&app.db, crate::runner_updates::SETTING_REPO).await?.unwrap_or_default(),

        settings,

        groups: v

            .groups

            .iter()

            .map(|g| RunnerGroup {

                id: g.g.id,

                owner: g.g.owner.clone(),

                name: g.g.name.clone(),

                percent: g.g.percent,

                members: g.members.clone(),

            })

            .collect(),

        runners: v

            .runners

            .iter()

            .map(|r| RunnerUpdate {

                id: r.r.id,

                name: r.r.name.clone(),

                owner: r.r.scope_owner.clone(),

                version: r.r.version.clone(),

                groups: r.groups.clone(),

                updates: r.effective.updates,

                channel: r.effective.channel.clone(),

                window: r.effective.window.map(|(a, b)| format!("{a:02}-{b:02}")),

                dry_run: r.effective.dry_run,

                from: r.effective.from.clone(),

                now: r.offer.clone(),

                said: r.r.update_note.clone(),

            })

            .collect(),

        holds: db::runner_updates::holds(&app.db)

            .await?

            .into_iter()

            .map(|h| HeldBuild { version: h.version, runner: h.runner, why: h.why, at_ms: h.at_ms })

            .collect(),

    }))

}

/// `PUT /api/v1/admin/runner-updates/settings`: one level's settings; what

/// it set, in words, or 422 saying what is wrong.

async fn runner_update_setting(

    State(app): State<Shared>,

    headers: HeaderMap,

    Json(u): Json<UpdateSetting>,

) -> Result<Json<serde_json::Value>, ApiError> {

    let c = caller(&app, &headers).await?;

    let me = require_site_admin(&c)?.clone();

    use crate::web::runner_updates::{apply_policy, PolicyForm, Reach};

    match apply_policy(&app, &me, &Reach::Site, &PolicyForm::of(&u)).await? {

        Ok(notice) => Ok(Json(serde_json::json!({ "notice": notice }))),

        Err(why) => Err(ApiError(StatusCode::UNPROCESSABLE_ENTITY, why)),

    }

}

/// `POST /api/v1/admin/runner-updates/holds/{version}/lift` (#326).

async fn runner_update_lift(State(app): State<Shared>, headers: HeaderMap, Path(version): Path<String>) -> Result<StatusCode, ApiError> {

    let c = caller(&app, &headers).await?;

    let me = require_site_admin(&c)?.clone();

    if !db::runner_updates::lift(&app.db, &version).await? {

        return Err(not_found("that build is not held"));

    }

    db::accounts::audit(&app.db, Some(&me), "runner.update.lifted", &version, "offered again").await.ok();

    Ok(StatusCode::NO_CONTENT)

}

impl PolicyForm {

    /// The form an API setting stands for.

    pub fn of(u: &hub_api::UpdateSetting) -> PolicyForm {

        let tri = |b: Option<bool>| match b {

            Some(true) => "on",

            Some(false) => "off",

            None => "inherit",

        };

        PolicyForm {

            csrf_token: String::new(),

            scope: u.scope.clone(),

            key: u.key.clone(),

            updates: tri(u.updates).into(),

            channel: u.channel.clone().unwrap_or_default(),

            window: u.window.clone().unwrap_or_default(),

            dry_run: tri(u.dry_run).into(),

        }

    }

}

    // The same through the API (`oh runner-updates`), for administrators only.

    let (_, tokens) = web("GET", "/settings/tokens", None).await;

    let tcsrf = {

        let i = tokens.find("name=\"_csrf\" value=\"").unwrap() + "name=\"_csrf\" value=\"".len();

        tokens[i..].split('"').next().unwrap().to_string()

    };

    let (_, made) = web("POST", "/settings/tokens", Some(format!("_csrf={tcsrf}&name=admin&scopes=user%3Aread"))).await;

    let i = made.find("oxyhub_").unwrap();

    let admin_token: String = made[i..].chars().take_while(|c| c.is_ascii_alphanumeric() || *c == '_').collect();

    let (st, body) = call(&h.app, "GET", "/api/v1/admin/runner-updates", Some(&admin_token), None).await;

    assert_eq!(st, StatusCode::OK, "{body}");

    let all: hub_api::RunnerUpdates = serde_json::from_str(&body).unwrap();

    assert_eq!(all.repo, "andy/oxygenflow");

    assert!(all.settings.iter().any(|s| s.scope == "group" && s.updates == Some(true) && s.window.is_some()), "{all:?}");

    let plex_row = all.runners.iter().find(|r| r.name == "plex").unwrap();

    assert!(plex_row.updates && plex_row.from[0] == "group canary" && plex_row.groups == ["canary"], "{plex_row:?}");

    let put = |body: serde_json::Value| {

        let (app, t) = (h.app.clone(), admin_token.clone());

        async move { call(&app, "PUT", "/api/v1/admin/runner-updates/settings", Some(&t), Some(body.to_string())).await }

    };

    let (st, body) =

        put(serde_json::json!({ "scope": "runner", "key": narvi.id.to_string(), "updates": true, "channel": "0.1.0", "dry_run": true }))

            .await;

    assert_eq!(st, StatusCode::OK, "{body}");

    assert!(body.contains("Saved for runner narvi: updates on, channel 0.1.0, dry run on."), "{body}");

    let (st, body) = put(serde_json::json!({ "scope": "site", "channel": "latest" })).await;

    assert_eq!(st, StatusCode::UNPROCESSABLE_ENTITY, "{body}");

    assert_eq!(

        call(&h.app, "GET", "/api/v1/admin/runner-updates", Some(&creds[0]), None).await.0,

        StatusCode::UNAUTHORIZED,

        "not a runner's"

    );

    let (_, body) = call(&h.app, "GET", "/api/v1/admin/runner-updates", Some(&admin_token), None).await;

    assert!(body.contains("\"version\":\"0.2.0\"") && body.contains("\"runner\":\"plex\""), "the hold through the API: {body}");

    let (st, _) = call(&h.app, "POST", "/api/v1/admin/runner-updates/holds/0.2.0/lift", Some(&admin_token), Some("{}".into())).await;

    assert_eq!(st, StatusCode::NOT_FOUND, "no longer held");

    /// Runners that update themselves (site administrators; oxygenhub#322):

    /// where builds come from, who takes them, what is held back

    #[command(name = "runner-updates")]

    RunnerUpdates {

        #[command(subcommand)]

        cmd: Option<RunnerUpdatesCmd>,

    },

    },

}

#[derive(Subcommand)]

enum RunnerUpdatesCmd {

    /// Every level's settings, the test groups, each runner's policy and what it is offered (the default)

    Show,

    /// Change one level's settings; what is not given stays as it is

    Set {

        /// `site`, `owner:NAME`, `group:NAME` (or `group:OWNER/NAME`, `group:ID`), `runner:NAME` (or `runner:ID`)

        scope: String,

        /// `on`, `off` or `inherit`

        #[arg(long)]

        updates: Option<String>,

        /// `stable`, `canary`, a version, or `inherit`

        #[arg(long)]

        channel: Option<String>,

        /// Hours (UTC) updates may start in, `02-05`, or `inherit`

        #[arg(long)]

        window: Option<String>,

        /// `on`, `off` or `inherit`

        #[arg(long)]

        dry_run: Option<String>,

    /// Offer a held build again (it rolled back on a runner)

    Lift { version: String },

        Cmd::RunnerUpdates { cmd } => runner_updates(&c, cmd.unwrap_or(RunnerUpdatesCmd::Show), json),

    }

}

/// `on`/`off`/`inherit` as a setting: `Some(Some(b))` to set, `Some(None)` to inherit.

fn switch(v: Option<&str>) -> Result<Option<Option<bool>>> {

    Ok(match v {

        None => None,

        Some("on") => Some(Some(true)),

        Some("off") => Some(Some(false)),

        Some("inherit") => Some(None),

        Some(other) => bail!("{other:?}: say on, off or inherit"),

    })

}

/// A scope as `oh runner-updates set` takes it, resolved to (scope, key).

fn update_scope(scope: &str, all: &hub_api::RunnerUpdates) -> Result<(String, String)> {

    let (kind, name) = scope.split_once(':').unwrap_or((scope, ""));

    Ok(match kind {

        "site" if name.is_empty() => ("site".into(), String::new()),

        "owner" if !name.is_empty() => ("owner".into(), name.into()),

        "group" => {

            let g = all

                .groups

                .iter()

                .find(|g| g.id.to_string() == name || g.name == name || format!("{}/{}", g.owner, g.name) == name)

                .with_context(|| format!("no test group {name:?} (see `oh runner-updates`)"))?;

            ("group".into(), g.id.to_string())

        }

        "runner" => {

            let r = all

                .runners

                .iter()

                .find(|r| r.id.to_string() == name || r.name == name)

                .with_context(|| format!("no runner {name:?} (see `oh runner-updates`)"))?;

            ("runner".into(), r.id.to_string())

        }

        _ => bail!("{scope:?}: say site, owner:NAME, group:NAME or runner:NAME"),

    })

}

fn runner_updates(c: &Client, cmd: RunnerUpdatesCmd, json: bool) -> Result<i32> {

    let all: hub_api::RunnerUpdates = c.get("/admin/runner-updates")?;

    match cmd {

        RunnerUpdatesCmd::Show if json => println!("{}", serde_json::to_string_pretty(&all)?),

        RunnerUpdatesCmd::Show => {

            println!(

                "{} {}",

                ui::strong("Builds from"),

                if all.repo.is_empty() { ui::dim("no repository: no runner is offered a build") } else { all.repo.clone() }

            );

            for h in &all.holds {

                println!("{} flow {} held: rolled back on {} ({})", ui::warn("!"), h.version, h.runner, h.why);

            }

            for s in &all.settings {

                let mut said = vec![];

                if let Some(u) = s.updates {

                    said.push(format!("updates {}", if u { "on" } else { "off" }));

                }

                if let Some(ch) = &s.channel {

                    said.push(format!("channel {ch}"));

                }

                if let Some(w) = &s.window {

                    said.push(format!("window {w} UTC"));

                }

                if let Some(d) = s.dry_run {

                    said.push(format!("dry run {}", if d { "on" } else { "off" }));

                }

                let level = if s.scope == "site" { "site".to_string() } else { format!("{}:{}", s.scope, s.key) };

                println!("  {:<18} {}", level, if said.is_empty() { ui::dim("off unless chosen") } else { said.join(", ") });

            }

            for g in &all.groups {

                let of = if g.owner.is_empty() { "the site's runners".to_string() } else { format!("{}'s runners", g.owner) };

                let what = g.percent.map(|p| format!("{p}% of {of}")).unwrap_or_else(|| format!("chosen, of {of}"));

                println!(

                    "  group {} ({what}): {}",

                    ui::strong(&g.name),

                    if g.members.is_empty() { "none".into() } else { g.members.join(", ") }

                );

            }

            for r in &all.runners {

                let on = if r.updates { ui::ok(&format!("on, {}", r.channel)) } else { ui::dim("off") };

                println!("  {:<16} flow {:<22} {} ({})  {}", r.name, r.version, on, r.from[0], ui::dim(&r.now));

            }

        }

        RunnerUpdatesCmd::Set { scope, updates, channel, window, dry_run } => {

            let (scope, key) = update_scope(&scope, &all)?;

            let mut s = all.settings.iter().find(|x| x.scope == scope && x.key == key).cloned().unwrap_or(hub_api::UpdateSetting {

                scope: scope.clone(),

                key: key.clone(),

                ..Default::default()

            });

            if let Some(u) = switch(updates.as_deref())? {

                s.updates = u;

            }

            if let Some(d) = switch(dry_run.as_deref())? {

                s.dry_run = d;

            }

            if let Some(ch) = channel {

                s.channel = Some(ch).filter(|c| c != "inherit");

            }

            if let Some(w) = window {

                s.window = Some(w).filter(|w| w != "inherit");

            }

            let out: serde_json::Value = serde_json::from_str(&c.send_text("PUT", "/admin/runner-updates/settings", &s)?)?;

            println!("{} {}", ui::ok("✔"), out["notice"].as_str().unwrap_or("saved"));

        }

        RunnerUpdatesCmd::Lift { version } => {

            c.send_text("POST", &format!("/admin/runner-updates/holds/{version}/lift"), &serde_json::json!({}))?;

            println!("{} flow {version} is offered again where the settings say so", ui::ok("✔"));

        }

    Ok(0)

    #[test]

    fn runner_update_scopes_resolve_by_name_or_id() {

        let all = hub_api::RunnerUpdates {

            repo: String::new(),

            settings: vec![],

            groups: vec![hub_api::RunnerGroup { id: 4, owner: "acme".into(), name: "canary".into(), percent: None, members: vec![] }],

            runners: vec![],

            holds: vec![],

        };

        assert_eq!(update_scope("site", &all).unwrap(), ("site".to_string(), String::new()));

        assert_eq!(update_scope("owner:acme", &all).unwrap(), ("owner".to_string(), "acme".to_string()));

        for g in ["group:canary", "group:acme/canary", "group:4"] {

            assert_eq!(update_scope(g, &all).unwrap(), ("group".to_string(), "4".to_string()), "{g}");

        }

        assert!(update_scope("runner:plex", &all).unwrap_err().to_string().contains("no runner"));

        assert!(update_scope("everyone", &all).is_err());

        assert_eq!(switch(Some("inherit")).unwrap(), Some(None));

        assert!(switch(Some("yes")).is_err());

    }

        match Cli::try_parse_from(["oh", "runner-updates", "set", "group:canary", "--updates", "on", "--window", "02-05"]).unwrap() {

            Cli { cmd: Cmd::RunnerUpdates { cmd: Some(RunnerUpdatesCmd::Set { scope, updates, window, channel, dry_run }) }, .. } => {

                assert_eq!((scope.as_str(), updates.as_deref(), window.as_deref()), ("group:canary", Some("on"), Some("02-05")));

                assert!(channel.is_none() && dry_run.is_none());

            }

            _ => panic!("not runner-updates set"),

        }

        assert!(matches!(Cli::try_parse_from(["oh", "runner-updates"]).unwrap().cmd, Cmd::RunnerUpdates { cmd: None }));

| `oh runner-updates [show]` | Site administrators: runners that update themselves (oxygenhub#322): where builds come from, every level's settings, test groups, each runner's policy and what it is offered, held builds |

| `oh runner-updates set SCOPE [--updates on\|off\|inherit] [--channel C] [--window 02-05] [--dry-run on\|off\|inherit]` | Change one level (`site`, `owner:NAME`, `group:NAME`, `runner:NAME`); what is not given stays; `inherit` clears a setting |

| `oh runner-updates lift VERSION` | Offer a build held after it rolled back on a runner (#326) |