API: a proposal's files and each side's bytes 3f02e5ea4f2d

/// A file a proposal changes, between the target's state and the

/// projected state (hub spec §7.2). Fetch either side's bytes from

/// `/proposals/{number}/content/{base|head}/{path}`.

pub struct ProposalFile {

    pub path: String,

    /// For a rename, the path in the target's state.

    pub from: Option<String>,

    /// `added`, `removed`, `modified`, `renamed`, `mode` or `replaced`.

    pub kind: String,

    pub added: usize,

    pub removed: usize,

}

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

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

export type ProposalFile = {

  added: number;

  from?: string | null;

  kind: string;

  path: string;

  removed: number;

};

        .route("/repos/{owner}/{name}/proposals/{number}/files", get(proposal_files))

        .route("/repos/{owner}/{name}/proposals/{number}/content/{side}/{*path}", get(proposal_content))

/// The files a proposal changes (hub spec §12.1).

async fn proposal_files(

    State(app): State<Shared>,

    headers: HeaderMap,

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

) -> Result<Json<Vec<hub_api::ProposalFile>>, ApiError> {

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

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

    let p = db::proposals::get(&app.db, row.id, number).await?.ok_or_else(|| not_found("no such proposal"))?;

    let loaded = crate::web::proposals::load(&app, &repo, p).await?;

    Ok(Json(

        loaded

            .files

            .iter()

            .map(|f| hub_api::ProposalFile {

                path: f.path.clone(),

                from: f.from.clone(),

                kind: f.kind.clone(),

                added: f.added,

                removed: f.removed,

            })

            .collect(),

    ))

}

/// One file's bytes on a side of a proposal: `base` is the target's

/// state, `head` the projected state. 404 when the file does not exist

/// on that side.

async fn proposal_content(

    State(app): State<Shared>,

    headers: HeaderMap,

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

) -> Result<Response, ApiError> {

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

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

    let p = db::proposals::get(&app.db, row.id, number).await?.ok_or_else(|| not_found("no such proposal"))?;

    let loaded = crate::web::proposals::load(&app, &repo, p).await?;

    let heads = match side.as_str() {

        "base" => loaded.target_heads,

        "head" => loaded.heads,

        _ => return Err(ApiError(StatusCode::BAD_REQUEST, "the side is base or head".into())),

    };

    let limit = app.config.limits.render_limit.0;

    let target = view::RefTarget { label: side, kind: view::RefKind::Change, heads };

    let f = app.repos.read(&repo, move |repo, cache| view::file(repo, cache, target, &path, limit)).await?;

    Ok(crate::web::raw(f.bytes, &f.name, false))

}

    pub target_heads: Vec<ChangeHash>,

                target_heads: p.target_heads.clone(),

    write(work.path(), "a.txt", b"a\nA\n");

    // Its files, and each side's bytes, for editors' diff views.

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

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

    let files: Vec<(String, String)> =

        v.as_array().unwrap().iter().map(|f| (f["path"].as_str().unwrap().to_string(), f["kind"].as_str().unwrap().to_string())).collect();

    assert_eq!(files, vec![("a.txt".into(), "modified".into()), ("b.txt".into(), "added".into())], "{v}");

    assert_eq!(v[0]["added"], 1);

    let side = |s: &str, p: &str| format!("/api/v1/repos/andy/demo/proposals/2/content/{s}/{p}");

    assert_eq!(call(app, "GET", &side("base", "a.txt"), None, None, None, None).await.body, "a\n");

    assert_eq!(call(app, "GET", &side("head", "a.txt"), None, None, None, None).await.body, "a\nA\n");

    assert_eq!(call(app, "GET", &side("head", "b.txt"), None, None, None, None).await.body, "b\n");

    assert_eq!(call(app, "GET", &side("base", "b.txt"), None, None, None, None).await.status, StatusCode::NOT_FOUND, "b.txt is new");

    assert_eq!(call(app, "GET", &side("middle", "a.txt"), None, None, None, None).await.status, StatusCode::BAD_REQUEST);

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`, `/labels`, `/milestones`, `/releases`, `/tags`, `/trust`, `/pushes`, `/hooks`, `/checks`, `/user`, `/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.