Issue API: labels, assignees and milestone when creating, PATCH to edit an issue, and creating and deleting labels 76f262e1a666

    /// Label names; each must exist. Needs triage.

    #[serde(default)]

    pub labels: Vec<String>,

    /// Usernames. Needs triage.

    #[serde(default)]

    pub assignees: Vec<String>,

    /// A milestone's title. Needs triage.

    #[serde(default)]

    pub milestone: Option<String>,

/// `PATCH /repos/{o}/{n}/issues/{number}`: only the fields given change.

/// Title and body: the author or triage. The rest: triage.

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

pub struct IssueEdit {

    #[serde(default)]

    pub title: Option<String>,

    #[serde(default)]

    pub body: Option<String>,

    /// The whole set of labels.

    #[serde(default)]

    pub labels: Option<Vec<String>>,

    /// The whole set of assignees.

    #[serde(default)]

    pub assignees: Option<Vec<String>>,

    /// A milestone's title; the empty string clears it.

    #[serde(default)]

    pub milestone: Option<String>,

}

/// `POST /repos/{o}/{n}/labels`: create a label, or change one of that name.

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

pub struct NewLabel {

    pub name: String,

    /// `#rrggbb`; a default when absent.

    #[serde(default)]

    pub colour: Option<String>,

    #[serde(default)]

    pub description: String,

}

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

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

  assignees?: string[];

  labels?: string[];

  milestone?: string | null;

};

export type IssueEdit = {

  assignees?: string[] | null;

  body?: string | null;

  labels?: string[] | null;

  milestone?: string | null;

  title?: string | null;

};

export type NewLabel = {

  colour?: string | null;

  description?: string;

  name: string;

        .route("/repos/{owner}/{name}/issues/{number}", get(issue).post(issue_state).patch(issue_edit))

        .route("/repos/{owner}/{name}/labels", get(labels).post(create_label))

        .route("/repos/{owner}/{name}/labels/{label}", axum::routing::delete(delete_label))

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

    let triage = !body.labels.is_empty() || !body.assignees.is_empty() || body.milestone.is_some();

    if triage && role < Role::Triage {

        return Err(forbidden("setting labels, assignees or a milestone needs triage access"));

    }

    // Check the names before anything is created.

    resolve_triage(&app, row.id, Some(&body.labels), Some(&body.assignees), body.milestone.as_deref()).await?;

    if triage {

        let t = resolve_triage(&app, row.id, Some(&body.labels), Some(&body.assignees), body.milestone.as_deref()).await?;

        apply_triage(&app, &i, &me, t).await?;

    }

    let i = db::issues::get(&app.db, row.id, i.number).await?.unwrap_or(i);

}

/// Labels, assignees and milestone named in a request, looked up.

struct Triage {

    labels: Option<Vec<db::issues::Label>>,

    assignees: Option<Vec<Account>>,

    /// `Some(None)` clears the milestone.

    milestone: Option<Option<db::issues::Milestone>>,

}

async fn resolve_triage(

    app: &Shared,

    repo_id: i64,

    labels: Option<&[String]>,

    assignees: Option<&[String]>,

    milestone: Option<&str>,

) -> Result<Triage, ApiError> {

    let bad = |m: String| ApiError(StatusCode::BAD_REQUEST, m);

    let labels = match labels {

        Some(names) => {

            let mut out = Vec::new();

            for n in names {

                out.push(

                    db::issues::label_by_name(&app.db, repo_id, n.trim())

                        .await?

                        .ok_or_else(|| bad(format!("no label {n:?}; create it first")))?,

                );

            }

            Some(out)

        }

        None => None,

    };

    let assignees = match assignees {

        Some(names) => {

            let mut out = Vec::new();

            for n in names {

                out.push(db::accounts::account_by_name(&app.db, n.trim()).await?.ok_or_else(|| bad(format!("no account {n:?}")))?);

            }

            Some(out)

        }

        None => None,

    };

    let milestone = match milestone.map(str::trim) {

        None => None,

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

        Some(title) => Some(Some(

            db::issues::milestones(&app.db, repo_id)

                .await?

                .into_iter()

                .find(|m| m.title == title)

                .ok_or_else(|| bad(format!("no milestone {title:?}")))?,

        )),

    };

    Ok(Triage { labels, assignees, milestone })

}

/// Make an issue's labels, assignees and milestone what `t` says, with

/// timeline events for what changed.

async fn apply_triage(app: &Shared, i: &db::issues::IssueRow, me: &Account, t: Triage) -> Result<(), ApiError> {

    if let Some(want) = t.labels {

        let have = db::issues::issue_labels(&app.db, i.id).await?;

        for l in &have {

            if !want.iter().any(|w| w.id == l.id) {

                db::issues::set_issue_label(&app.db, i.id, l.id, false).await?;

            }

        }

        for w in &want {

            if !have.iter().any(|l| l.id == w.id) {

                db::issues::set_issue_label(&app.db, i.id, w.id, true).await?;

            }

        }

        let names: Vec<&str> = want.iter().map(|l| l.name.as_str()).collect();

        db::issues::add_event(&app.db, i.id, &me.username, "set labels", &names.join(", ")).await.ok();

    }

    if let Some(want) = t.assignees {

        let have = db::issues::assignees(&app.db, i.id).await?;

        for name in &have {

            if !want.iter().any(|a| &a.username == name) {

                if let Some(a) = db::accounts::account_by_name(&app.db, name).await? {

                    db::issues::set_assignee(&app.db, i.id, a.id, false).await?;

                    db::issues::add_event(&app.db, i.id, &me.username, "unassigned", name).await.ok();

                }

            }

        }

        for a in &want {

            if !have.contains(&a.username) {

                db::issues::set_assignee(&app.db, i.id, a.id, true).await?;

                db::issues::add_event(&app.db, i.id, &me.username, "assigned", &a.username).await.ok();

            }

        }

    }

    if let Some(m) = t.milestone {

        db::issues::set_milestone(&app.db, i.id, m.as_ref().map(|m| m.id)).await?;

        db::issues::add_event(&app.db, i.id, &me.username, "set milestone", m.as_ref().map(|m| m.title.as_str()).unwrap_or("")).await.ok();

    }

    Ok(())

}

/// `PATCH /repos/{o}/{n}/issues/{number}`.

async fn issue_edit(

    State(app): State<Shared>,

    headers: HeaderMap,

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

    Json(body): Json<IssueEdit>,

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

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

    let me = c.require("issues:write").or_else(|_| c.require("repo:write"))?.clone();

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

    let i = db::issues::get(&app.db, row.id, number).await?.ok_or_else(|| not_found("no such issue"))?;

    let text = body.title.is_some() || body.body.is_some();

    let triage = body.labels.is_some() || body.assignees.is_some() || body.milestone.is_some();

    if text && role < Role::Triage && Some(me.id) != i.author_id {

        return Err(forbidden("only the author or triage may edit the title and body"));

    }

    if triage && role < Role::Triage {

        return Err(forbidden("setting labels, assignees or a milestone needs triage access"));

    }

    if i.locked && role < Role::Triage {

        return Err(forbidden("this issue is locked"));

    }

    let t = resolve_triage(&app, row.id, body.labels.as_deref(), body.assignees.as_deref(), body.milestone.as_deref()).await?;

    if text {

        let title = body.title.as_deref().map(str::trim).unwrap_or(&i.title);

        if title.is_empty() {

            return Err(ApiError(StatusCode::BAD_REQUEST, "an issue needs a title".into()));

        }

        db::issues::edit(&app.db, i.id, title, body.body.as_deref().unwrap_or(&i.body)).await?;

        db::issues::add_event(&app.db, i.id, &me.username, "edited", "").await.ok();

    }

    apply_triage(&app, &i, &me, t).await?;

    db::issues::touch(&app.db, i.id).await.ok();

    let fresh = db::issues::get(&app.db, row.id, number).await?.unwrap_or(i);

    crate::web::issues::reindex(&app, row.id, &fresh).await;

    let api = issue_of(&app, &row, &fresh).await?;

    crate::hooks::emit(&app, &row, "issue.edited", &me.username, serde_json::json!({ "issue": api })).await;

    Ok(Json(api))

}

/// `POST /repos/{o}/{n}/labels` (triage).

async fn create_label(

    State(app): State<Shared>,

    headers: HeaderMap,

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

    Json(body): Json<NewLabel>,

) -> Result<(StatusCode, Json<Label>), ApiError> {

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

    c.require("issues:write").or_else(|_| c.require("repo:write"))?;

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

    if role < Role::Triage {

        return Err(forbidden("labels need triage access"));

    }

    let label = body.name.trim();

    if label.is_empty() || label.len() > 50 {

        return Err(ApiError(StatusCode::BAD_REQUEST, "a label has a name of 1 to 50 characters".into()));

    }

    let colour = match body.colour.as_deref() {

        Some(c) if c.len() == 7 && c.starts_with('#') && c[1..].chars().all(|x| x.is_ascii_hexdigit()) => c.to_string(),

        Some(c) => return Err(ApiError(StatusCode::BAD_REQUEST, format!("colour {c:?} is not #rrggbb"))),

        None => "#5aa8ff".to_string(),

    };

    let l = db::issues::upsert_label(&app.db, row.id, label, &colour, body.description.trim()).await?;

    Ok((StatusCode::CREATED, Json(Label { name: l.name, colour: l.colour, description: l.description })))

}

/// `DELETE /repos/{o}/{n}/labels/{label}` (triage).

async fn delete_label(

    State(app): State<Shared>,

    headers: HeaderMap,

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

) -> Result<StatusCode, ApiError> {

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

    c.require("issues:write").or_else(|_| c.require("repo:write"))?;

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

    if role < Role::Triage {

        return Err(forbidden("labels need triage access"));

    }

    let l = db::issues::label_by_name(&app.db, row.id, &label).await?.ok_or_else(|| not_found("no such label"))?;

    db::issues::delete_label(&app.db, l.id).await?;

    Ok(StatusCode::NO_CONTENT)

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

async fn api_issue_triage_and_labels() {

    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 bob = call(app, "POST", "/register", None, None, None, Some("username=bob&email=b%40example.com&password=correct-horse-battery"))

        .await

        .cookie

        .unwrap();

    let mint = |cookie: String, scopes: &'static str| {

        let app = app.clone();

        async move {

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

            let csrf = csrf_of(&page.body);

            let r = call(&app, "POST", "/settings/tokens", None, Some(&cookie), 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 andy_t = mint(andy, "scopes=repo%3Aadmin").await;

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

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

    assert_eq!(st, StatusCode::CREATED);

    // Labels through the API; bad colours and non-triage callers are refused.

    let (st, v) = api(

        app,

        "POST",

        "/api/v1/repos/andy/demo/labels",

        Some(&andy_t),

        Some(r##"{"name":"bug","colour":"#ff0000","description":"Broken"}"##),

    )

    .await;

    assert_eq!((st, v["name"].as_str()), (StatusCode::CREATED, Some("bug")));

    assert_eq!(api(app, "POST", "/api/v1/repos/andy/demo/labels", Some(&andy_t), Some(r#"{"name":"flow"}"#)).await.0, StatusCode::CREATED);

    assert_eq!(

        api(app, "POST", "/api/v1/repos/andy/demo/labels", Some(&andy_t), Some(r##"{"name":"x","colour":"red"}"##)).await.0,

        StatusCode::BAD_REQUEST

    );

    assert_eq!(api(app, "POST", "/api/v1/repos/andy/demo/labels", Some(&bob_t), Some(r#"{"name":"mine"}"#)).await.0, StatusCode::FORBIDDEN);

    let (_, labels) = api(app, "GET", "/api/v1/repos/andy/demo/labels", None, None).await;

    assert_eq!(labels.as_array().unwrap().len(), 2);

    // An issue created with its labels and assignee in one call.

    let (st, v) = api(

        app,

        "POST",

        "/api/v1/repos/andy/demo/issues",

        Some(&andy_t),

        Some(r#"{"title":"Crash","body":"b","labels":["bug"],"assignees":["bob"]}"#),

    )

    .await;

    assert_eq!(st, StatusCode::CREATED, "{v}");

    assert_eq!(v["labels"][0]["name"], "bug");

    assert_eq!(v["assignees"], serde_json::json!(["bob"]));

    let n = v["number"].as_i64().unwrap();

    // Unknown names are refused before anything is created.

    let (st, v) = api(app, "POST", "/api/v1/repos/andy/demo/issues", Some(&andy_t), Some(r#"{"title":"X","labels":["nope"]}"#)).await;

    assert_eq!(st, StatusCode::BAD_REQUEST);

    assert!(v["detail"].as_str().unwrap().contains("no label"));

    let (_, list) = api(app, "GET", "/api/v1/repos/andy/demo/issues?state=all", None, None).await;

    assert_eq!(list.as_array().unwrap().len(), 1, "nothing half-made");

    // Without triage, labels cannot be set, but a plain issue can be opened.

    assert_eq!(

        api(app, "POST", "/api/v1/repos/andy/demo/issues", Some(&bob_t), Some(r#"{"title":"Y","labels":["bug"]}"#)).await.0,

        StatusCode::FORBIDDEN

    );

    let (st, bobs) = api(app, "POST", "/api/v1/repos/andy/demo/issues", Some(&bob_t), Some(r#"{"title":"From Bob"}"#)).await;

    assert_eq!(st, StatusCode::CREATED);

    let bob_n = bobs["number"].as_i64().unwrap();

    // PATCH: the whole label set, assignees and milestone, with events.

    let (st, v) =

        api(app, "PATCH", &format!("/api/v1/repos/andy/demo/issues/{n}"), Some(&andy_t), Some(r#"{"labels":["flow"],"assignees":[]}"#))

            .await;

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

    assert_eq!(v["labels"].as_array().unwrap().iter().map(|l| l["name"].as_str().unwrap()).collect::<Vec<_>>(), ["flow"]);

    assert_eq!(v["assignees"], serde_json::json!([]));

    let (st, _) = api(app, "PATCH", &format!("/api/v1/repos/andy/demo/issues/{n}"), Some(&andy_t), Some(r#"{"milestone":"v9"}"#)).await;

    assert_eq!(st, StatusCode::BAD_REQUEST, "no such milestone");

    let issue_page = call(app, "GET", &format!("/andy/demo/issue/{n}"), None, None, None, None).await.body;

    assert!(issue_page.contains("set labels") && issue_page.contains("unassigned"), "timeline events");

    // The author edits their own title; others cannot; nobody but triage sets labels.

    let (st, v) =

        api(app, "PATCH", &format!("/api/v1/repos/andy/demo/issues/{bob_n}"), Some(&bob_t), Some(r#"{"title":"From Bob, clearer"}"#)).await;

    assert_eq!((st, v["title"].as_str()), (StatusCode::OK, Some("From Bob, clearer")));

    assert_eq!(

        api(app, "PATCH", &format!("/api/v1/repos/andy/demo/issues/{n}"), Some(&bob_t), Some(r#"{"title":"mine now"}"#)).await.0,

        StatusCode::FORBIDDEN

    );

    assert_eq!(

        api(app, "PATCH", &format!("/api/v1/repos/andy/demo/issues/{bob_n}"), Some(&bob_t), Some(r#"{"labels":["bug"]}"#)).await.0,

        StatusCode::FORBIDDEN

    );

    assert_eq!(

        api(app, "PATCH", &format!("/api/v1/repos/andy/demo/issues/{n}"), Some(&andy_t), Some(r#"{"title":"  "}"#)).await.0,

        StatusCode::BAD_REQUEST

    );

    // Deleting a label takes it off the issues.

    assert_eq!(api(app, "DELETE", "/api/v1/repos/andy/demo/labels/flow", Some(&andy_t), None).await.0, StatusCode::NO_CONTENT);

    let (_, v) = api(app, "GET", &format!("/api/v1/repos/andy/demo/issues/{n}"), None, None).await;

    assert_eq!(v["labels"], serde_json::json!([]));

    assert_eq!(api(app, "DELETE", "/api/v1/repos/andy/demo/labels/flow", Some(&andy_t), None).await.0, StatusCode::NOT_FOUND);

}

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}`, `/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.