Required checks over the API: GET and PUT /repos/{o}/{n}/checks/required (admins, the whole list, audited) 961c10bee174

/// The checks a proposal needs, passed, to land on the repository's

/// default bookmark (hub spec §13.1). `GET` and `PUT

/// /repos/{o}/{n}/checks/required`.

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

pub struct RequiredChecks {

    pub names: Vec<String>,

}

        ("RequiredChecks", schemars::schema_for!(RequiredChecks)),

export type RequiredChecks = {

  names: string[];

};

        .route("/repos/{owner}/{name}/checks/required", get(required_checks).put(set_required_checks))

}

/// `GET /repos/{o}/{n}/checks/required`.

async fn required_checks(

    State(app): State<Shared>,

    headers: HeaderMap,

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

) -> Result<Json<RequiredChecks>, ApiError> {

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

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

    Ok(Json(RequiredChecks { names: db::hooks::required_checks(&app.db, row.id).await? }))

}

/// `PUT /repos/{o}/{n}/checks/required` (repository admin): the whole list.

async fn set_required_checks(

    State(app): State<Shared>,

    headers: HeaderMap,

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

    Json(body): Json<RequiredChecks>,

) -> Result<Json<RequiredChecks>, ApiError> {

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

    c.require("repo:admin")?;

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

    let mut names: Vec<String> = body.names.iter().map(|n| n.trim().to_string()).filter(|n| !n.is_empty()).collect();

    names.sort();

    names.dedup();

    if names.len() > 32 || names.iter().any(|n| n.len() > 100 || n.contains(',')) {

        return Err(ApiError(StatusCode::BAD_REQUEST, "at most 32 check names, each under 100 characters and without commas".into()));

    }

    db::hooks::set_required_checks(&app.db, row.id, &names).await?;

    db::accounts::audit(&app.db, c.account.as_ref(), "repo.required_checks", &format!("{owner}/{name}"), &names.join(", ")).await.ok();

    Ok(Json(RequiredChecks { names }))

#[tokio::test(flavor = "multi_thread")]

async fn api_required_checks() {

    let h = hub().await;

    let app = &h.app;

    let andy = call(app, "POST", "/register", None, None, None, Some("username=andy&email=a%40example.com&password=correct-horse-battery"))

        .await

        .cookie

        .unwrap();

    let page = call(app, "GET", "/settings/tokens", None, Some(&andy), None, None).await;

    let csrf = csrf_of(&page.body);

    let mint = |scopes: &'static str| {

        let (app, andy, csrf) = (app.clone(), andy.clone(), csrf.clone());

        async move {

            let r = call(&app, "POST", "/settings/tokens", None, Some(&andy), None, Some(&format!("_csrf={csrf}&name=t&{scopes}"))).await;

            r.body.split("oxyhub_").nth(1).map(|s| format!("oxyhub_{}", s.split('<').next().unwrap().trim())).unwrap()

        }

    };

    let admin = mint("scopes=repo%3Aadmin").await;

    let write = mint("scopes=repo%3Aread&scopes=repo%3Awrite").await;

    api(app, "POST", "/api/v1/repos", Some(&admin), Some(r#"{"owner":"andy","name":"demo","visibility":"public"}"#)).await;

    let (st, v) = api(app, "GET", "/api/v1/repos/andy/demo/checks/required", None, None).await;

    assert_eq!((st, v["names"].clone()), (StatusCode::OK, serde_json::json!([])));

    let (st, v) = api(

        app,

        "PUT",

        "/api/v1/repos/andy/demo/checks/required",

        Some(&admin),

        Some(r#"{"names":["flow/test"," flow/fmt ","flow/test",""]}"#),

    )

    .await;

    assert_eq!((st, v["names"].clone()), (StatusCode::OK, serde_json::json!(["flow/fmt", "flow/test"])), "trimmed, sorted, once each");

    assert_eq!(oxygenhub::db::hooks::required_checks(&app.db, 1).await.unwrap(), ["flow/fmt", "flow/test"]);

    assert_eq!(

        api(app, "GET", "/api/v1/repos/andy/demo/checks/required", None, None).await.1["names"],

        serde_json::json!(["flow/fmt", "flow/test"])

    );

    assert_eq!(

        api(app, "PUT", "/api/v1/repos/andy/demo/checks/required", Some(&write), Some(r#"{"names":[]}"#)).await.0,

        StatusCode::FORBIDDEN,

        "repo:admin only"

    );

    assert_eq!(

        api(app, "PUT", "/api/v1/repos/andy/demo/checks/required", Some(&admin), Some(r#"{"names":["a,b"]}"#)).await.0,

        StatusCode::BAD_REQUEST

    );

    // The settings page shows the same list.

    assert!(call(app, "GET", "/andy/demo/settings", None, Some(&andy), None, None).await.body.contains("flow/fmt, flow/test"));

}

JSON under `/api/v1`, bearer tokens, `application/json`, RFC 7807 problem responses, cursor pagination (`?after=`), ETags on cacheable resources, and rate limits per token. Resources mirror the pages: `/repos/{owner}/{name}`, `/bookmarks`, `/changes/{hash}`, `/tree/{ref}/{path}`, `/file/{ref}/{path}`, `/blame`, `/history`, `/compare`, `/conflicts`, `/proposals`, `/proposals/{n}/comments|reviews|checks|files|land`, `/proposals/{n}/content/{base|head}/{path}` (a changed file's bytes in the target's state or the projected state, for editor diff views), `/issues` (creating an issue can set its labels, assignees and milestone; `PATCH /issues/{n}` edits the title and body for the author or triage, and replaces labels, assignees or the milestone for triage, recording each on the timeline; unknown names are refused before anything changes), `/labels` (`POST` creates or changes one, `DELETE /labels/{name}` removes it; triage), `/milestones`, `/releases`, `/tags`, `/trust`, `/pushes`, `/hooks`, `/checks`, `/user`, `/notifications` (the caller's inbox and unread count; `/notifications/{id}/read` and `/notifications/read` mark read; scope `user:read`), `/users/{name}`, `/orgs/{name}`, `/checks/required` (`GET`, and `PUT` of the whole list by a repository admin: the checks a proposal needs, passed, to land), `/projects/{owner}` (list, create) and `/projects/{owner}/{n}` (the board as the caller may see it, `PATCH` for title, description, privacy and closing, `/cards` to add a reference or note to a column named by id or name, `/cards/{id}` to move or remove one; `repo:write` and the page's rights to change), `/search`. Shapes reuse `oxy --json` shapes wherever one exists (change, status, blame, diff) so tools written against the CLI work against the hub. `crates/hub-api` holds the types with `serde` derives and is what the runner and the VS Code extension will link.