Approval gates and expedite for clients: a run's jobs over the API say their approval, and POST …/flow/runs/N/expedite makes a run urgent as the run page does, sharing flow::expedite (refs oxygenhub-android#5) b1860d6090ec

- **Approval gates and expedite for clients (oxygenhub-android#5).** A run's jobs over the API say `approval` (`waiting` while one waits for a person, `approved` or `rejected` after), and `POST /api/v1/repos/OWNER/NAME/flow/runs/N/expedite {"reason": …}` makes a run urgent as the run page's Expedite does (a maintainer, with a reason, within the owner's cap of urgent runs); the page and the API share it.

    /// Its approval gate (oxygenflow#57): `waiting` while it waits for a

    /// person to approve or reject it, `approved` or `rejected` after;

    /// empty for a job with no gate.

    #[serde(default, skip_serializing_if = "String::is_empty")]

    pub approval: String,

        .route("/repos/{owner}/{name}/flow/runs/{number}/expedite", post(expedite_flow_run))

                approval: j.approval,

#[derive(Deserialize)]

struct ExpediteBody {

    reason: String,

}

/// `POST /repos/{o}/{n}/flow/runs/{number}/expedite {"reason": …}`

/// (oxygenhub#244): a maintainer makes a queued or running run urgent, as

/// the run page's Expedite does, within the owner's cap of urgent runs.

async fn expedite_flow_run(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path((owner, name, number)): Path<(String, String, i64)>,

    Json(body): Json<ExpediteBody>,

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

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

    let me = c.require("repo:write")?.clone();

    let (_, row, _) = reach(&app, &c, &owner, &name, Access::Maintain).await?;

    let run = db::flow::run(&app.db, row.id, number).await?.ok_or_else(|| not_found("no such run"))?;

    crate::flow::expedite(&app, &row, &run, &me, &body.reason).await.map_err(|m| ApiError(StatusCode::CONFLICT, m))?;

    Ok(Json(serde_json::json!({ "number": number, "expedited": true })))

}

/// Make run `run` urgent (oxygenhub#244), saying why: refused without a

/// reason, or when the owner already has as many urgent runs going as the

/// site allows (Admin > Runners > Settings). Audited; every queued job's

/// place is worked out again at once (#291). For the run page and the API.

pub async fn expedite(

    app: &Shared,

    row: &db::repos::RepoRow,

    run: &fdb::Run,

    me: &db::accounts::Account,

    reason: &str,

) -> Result<(), String> {

    let reason: String = reason.chars().filter(|c| !c.is_control()).take(200).collect();

    let reason = reason.trim();

    if reason.is_empty() {

        return Err("Say why the run is urgent.".into());

    }

    let owner = &row.owner;

    // A cap on one owner's urgent runs at once, so urgent can't starve

    // everyone else.

    let cap: i64 = db::accounts::setting(&app.db, "flow_expedite_cap").await.ok().flatten().and_then(|v| v.parse().ok()).unwrap_or(2);

    let live = fdb::expedited_live(&app.db, owner).await.map_err(|e| e.to_string())?;

    if live >= cap {

        return Err(format!("{owner} already has {live} expedited run(s) going, the most at once ({cap}); wait for one to end."));

    }

    let note = format!("expedited by {}: {reason}", me.username);

    if fdb::expedite(&app.db, run.id, &note).await.map_err(|e| e.to_string())? {

        db::accounts::audit(&app.db, Some(me), "flow.expedite", &format!("{owner}/{}", row.name), &format!("#{}: {reason}", run.number))

            .await

            .ok();

        // This run's page and the pages of the runs it moved down hear of it.

        if let Err(e) = explain_waits(app).await {

            tracing::warn!("flow: placing after an expedite: {e}");

        }

        app.bus.live(&crate::events::topic::run(run.id), "jobs");

    }

    Ok(())

}

    if let Err(msg) = crate::flow::expedite(&app, &row, &run, &me.account, &f.reason).await {

    // And over the API (oxygenhub-android#5): a reason is needed; then the

    // first run is urgent too, within the cap of two.

    let andy = db::accounts::account_by_name(&h.app.db, "andy").await.unwrap().unwrap();

    let (token, hash) = oxygenhub::auth::new_token();

    db::accounts::create_token(&h.app.db, andy.id, "phone", &hash, "repo:read,repo:write", "", None).await.unwrap();

    let url = format!("/api/v1/repos/andy/first/flow/runs/{}/expedite", first.number);

    let (st, body) = call(&h.app, "POST", &url, Some(&token), Some(r#"{"reason":"  "}"#.into())).await;

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

    assert!(body.contains("Say why the run is urgent."), "{body}");

    let (st, body) = call(&h.app, "POST", &url, Some(&token), Some(r#"{"reason":"the fix for the outage"}"#.into())).await;

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

    let run = db::flow::run(&h.app.db, first.repo_id, first.number).await.unwrap().unwrap();

    assert!(

        run.priority == "urgent" && run.priority_note.contains("expedited by andy: the fix for the outage"),

        "{} {}",

        run.priority,

        run.priority_note

    );

    // The API says which job waits for a person (oxygenhub-android#5).

    let (_, v) = call(&h.app, "GET", &format!("/api/v1/repos/andy/gated/flow/runs/{}", run.number), None, None).await;

    let v: serde_json::Value = serde_json::from_str(&v).unwrap();

    let apply = v["jobs"].as_array().unwrap().iter().find(|j| j["name"] == "apply").unwrap().clone();

    assert_eq!(apply["approval"], "waiting", "{v}");

    assert!(v["jobs"].as_array().unwrap().iter().filter(|j| j["name"] != "apply").all(|j| j.get("approval").is_none()), "{v}");