Flow job reports and timings over the API, oh run report and oh report; 0.9.14 (closes #348) fac6853c4e46

## 0.9.14 (2026-10-28)

- **Read a Flow job's report over the API and with `oh` (#348).** A report a job published could only be read on its web page. Now `GET /api/v1/repos/OWNER/NAME/flow/runs/N/jobs/JOB/report` gives it with its metrics, context and files, `…/report/PATH` one file as published (`data/frames.csv`), `…/jobs/JOB/reports` every report the job published, `GET …/reports` the newest run of each report (`?bookmark=`), and `GET …/reports/NAME` one run by `?id=` (the id the web page carries) or the newest on a bookmark, with `…/files/PATH`. Files come sandboxed, so a page in one runs nothing on the hub; errors name the jobs, reports and files there are. `oh run report RUN JOB` prints its `report.toml`, `--list` what it holds, `--file PATH [-o FILE]` one file; `oh report list` and `oh report show NAME` do the same by name.

- **A job's timings over the API (#348).** A run's jobs now say when each was queued and claimed, the phases its runner reported (image, prepare, run, finish, in milliseconds) and its peak disk and memory; `oh run view N --timings` prints them under each job ("waited 12.0 s · image 850 ms · run 2 min 5 s · peak disk 2.1 GiB, memory 900 MiB").

version = "0.9.14"

version = "0.9.14"

version = "0.9.14"

version = "0.9.14"

    /// When it entered the queue (made, or run again), and when a runner

    /// claimed it: its wait is `started_ms - queued_ms` (oxygenhub#348).

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub queued_ms: Option<i64>,

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub ready_ms: Option<i64>,

    /// Where its time went, as its runner reported (oxygenflow#35):

    /// `image`, `prepare`, `run` and `finish`, in that order.

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

    pub phases: Vec<FlowPhase>,

    /// The most disk and memory it took, as its runner reported, in MiB.

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub peak_disk_mib: Option<i64>,

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub peak_memory_mib: Option<i64>,

}

/// A phase of a job and its milliseconds.

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

pub struct FlowPhase {

    pub name: String,

    pub ms: u64,

}

/// A report: what a Flow job published (OxygenFlow `output { report … }`)

/// or an upload, as docs/reports.md describes (oxygenhub#348).

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

pub struct Report {

    /// Its id, as the web page's `?id=` carries it.

    pub id: i64,

    /// The name the pipeline gave it (`report "frame-timing"`).

    pub name: String,

    /// `coverage`, `tests`, `performance` or `custom`.

    pub kind: String,

    pub title: String,

    pub summary: String,

    pub metrics: Vec<ReportMetric>,

    /// Its `[context]` table.

    pub context: serde_json::Value,

    /// The run and job that published it; none for an upload.

    pub run: Option<i64>,

    pub job: String,

    pub bookmark: String,

    /// The state it measured.

    pub state: String,

    /// How many files it has and their size together.

    pub files: i64,

    pub bytes: i64,

    pub created_ms: i64,

    /// When its files expired under retention (docs/reports.md §3.3): its

    /// metrics stay, its files are gone.

    pub files_expired_ms: Option<i64>,

    /// Its page on the hub.

    pub url: String,

    /// Its files, filled when one report is asked for.

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

    pub manifest: Vec<ReportFile>,

}

/// A metric of a report.

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

pub struct ReportMetric {

    pub key: String,

    pub value: f64,

    pub unit: String,

    /// `lower`, `higher`, or empty.

    pub better: String,

    pub fail_above: Option<f64>,

    pub fail_below: Option<f64>,

}

/// A file of a report.

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

pub struct ReportFile {

    pub path: String,

    pub size: i64,

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

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

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

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

        .route("/repos/{owner}/{name}/flow/runs/{number}/jobs/{job}/reports", get(reports::job_reports))

        .route("/repos/{owner}/{name}/flow/runs/{number}/jobs/{job}/report", get(reports::job_report_one))

        .route("/repos/{owner}/{name}/flow/runs/{number}/jobs/{job}/report/{*path}", get(reports::job_report_file))

        .route("/repos/{owner}/{name}/reports", get(reports::latest_reports))

        .route("/repos/{owner}/{name}/reports/{report}", get(reports::named_report_one))

        .route("/repos/{owner}/{name}/reports/{report}/files/{*path}", get(reports::named_report_file))

                phases: j.phase_list().into_iter().map(|(name, ms)| hub_api::FlowPhase { name, ms }).collect(),

                queued_ms: j.queued_ms,

                ready_ms: j.ready_ms,

                peak_disk_mib: j.peak_disk_mib,

                peak_memory_mib: j.peak_memory_mib,

//! Coverage (oxygenhub#113), test reports (#114) and the reports Flow jobs

//! publish (#348) over the API: what the Coverage, Tests and Reports tabs

//! show, for whoever may read the repository.

use crate::{coverage, junit, reports, Shared};

use axum::http::{header, HeaderMap, HeaderValue};

use axum::response::{IntoResponse, Response};

use hub_api::{CoverageDetail, CoverageFile, CoverageReport, Report, ReportFile, ReportMetric, TestCase, TestReport, TestReportDetail};

#[derive(Deserialize, Default)]

pub struct ReportQuery {

    /// Which of a job's reports, when it published more than one.

    name: Option<String>,

    /// One run of a report, by its id (the web page's `?id=`).

    id: Option<i64>,

    /// The bookmark whose newest run of a report to take (default: the

    /// repository's default, else wherever it ran last).

    bookmark: Option<String>,

}

/// A kept report as the API shows it, with its metrics; with its files

/// when `files` says so.

async fn report_of(app: &Shared, base: &str, r: &reports::Report, files: bool) -> Result<Report, ApiError> {

    let metrics = reports::metrics(&app.db, r.id)

        .await?

        .into_iter()

        .map(|m| ReportMetric {

            key: m.key,

            value: m.value,

            unit: m.unit,

            better: m.better,

            fail_above: m.fail_above,

            fail_below: m.fail_below,

        })

        .collect();

    let manifest = if files {

        reports::files_of(&app.db, r.id).await?.into_iter().map(|(path, size)| ReportFile { path, size }).collect()

    } else {

        vec![]

    };

    Ok(Report {

        id: r.id,

        name: r.name.clone(),

        kind: r.kind.clone(),

        title: r.title.clone(),

        summary: r.summary.clone(),

        metrics,

        context: serde_json::from_str(&r.context).unwrap_or_default(),

        run: r.run_number,

        job: r.job.clone(),

        bookmark: r.bookmark.clone(),

        state: r.state.clone(),

        files: r.files,

        bytes: r.bytes,

        created_ms: r.created_ms,

        files_expired_ms: r.files_expired_ms,

        url: format!("{}{base}/reports/{}?id={}", app.config.base_url().trim_end_matches('/'), r.name, r.id),

        manifest,

    })

}

/// The report a job of run `number` published: the only one, or the one

/// `name` names. The errors say what there is.

async fn job_report(app: &Shared, repo_id: i64, number: i64, job: &str, name: Option<&str>) -> Result<reports::Report, ApiError> {

    let run = crate::db::flow::run(&app.db, repo_id, number).await?.ok_or_else(|| not_found(&format!("no run #{number}")))?;

    let jobs = crate::db::flow::jobs(&app.db, run.id).await?;

    let Some(j) = jobs.iter().find(|j| j.name == job) else {

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

        return Err(not_found(&format!("run #{number} has no job {job}; its jobs: {}", names.join(", "))));

    };

    let mut list = reports::of_job(&app.db, j.id).await?;

    let names = || list.iter().map(|r| r.name.as_str()).collect::<Vec<_>>().join(", ");

    match name {

        Some(n) => match list.iter().position(|r| r.name == n) {

            Some(i) => Ok(list.swap_remove(i)),

            None if list.is_empty() => Err(not_found(&format!("job {job} of run #{number} published no report"))),

            None => Err(not_found(&format!("job {job} of run #{number} published no report {n}; it published {}", names()))),

        },

        None if list.len() == 1 => Ok(list.remove(0)),

        None if list.is_empty() => Err(not_found(&format!("job {job} of run #{number} published no report"))),

        None => Err(ApiError(

            axum::http::StatusCode::BAD_REQUEST,

            format!("job {job} of run #{number} published {} reports ({}): say which with ?name=", list.len(), names()),

        )),

    }

}

/// Report `name`'s run `id`, or its newest on `bookmark` (default: the

/// repository's default bookmark, else wherever it ran last), as the

/// report's web page picks it.

async fn named_report(app: &Shared, row: &crate::db::repos::RepoRow, name: &str, q: &ReportQuery) -> Result<reports::Report, ApiError> {

    if let Some(id) = q.id {

        return reports::get(&app.db, row.id, id)

            .await?

            .filter(|r| r.name == name)

            .ok_or_else(|| not_found(&format!("report {name} has no run with id {id}")));

    }

    let bookmarks = reports::bookmarks_of(&app.db, row.id, name).await?;

    if bookmarks.is_empty() {

        return Err(not_found(&format!("no report {name} in {}/{}", row.owner, row.name)));

    }

    let bookmark = match q.bookmark.clone().filter(|b| !b.is_empty()) {

        Some(b) if bookmarks.contains(&b) => b,

        Some(b) => return Err(not_found(&format!("report {name} never ran on {b}; it ran on {}", bookmarks.join(", ")))),

        None => bookmarks.iter().find(|b| **b == row.default_bookmark).unwrap_or(&bookmarks[0]).clone(),

    };

    reports::history(&app.db, row.id, name, &bookmark, 1).await?.into_iter().next().ok_or_else(|| not_found("no such report"))

}

/// A report's file as it was published. It is served as a download would

/// be: under a sandbox that runs nothing, so a page in it can do nothing

/// on the hub's own origin.

async fn report_file(app: &Shared, repo: &crate::repos::RepoName, r: &reports::Report, path: &str) -> Result<Response, ApiError> {

    if let Some(when) = r.files_expired_ms {

        return Err(ApiError(

            axum::http::StatusCode::GONE,

            format!("report {} (id {}) lost its files under retention at {when} ms; its metrics stay", r.name, r.id),

        ));

    }

    let Some((blob, _)) = reports::file(&app.db, r.id, path).await? else {

        let files: Vec<String> = reports::files_of(&app.db, r.id).await?.into_iter().map(|(p, _)| p).take(20).collect();

        return Err(not_found(&format!("report {} has no file {path}; it has {}", r.name, files.join(", "))));

    };

    let oref = oxy_core::hash::ObjectRef::from_hex(&blob).ok_or_else(|| not_found("the file's blob is unreadable"))?;

    let bytes = app

        .repos

        .read(repo, move |r, _| Ok(r.read_blob(&oref)?))

        .await

        .map_err(|e| ApiError(axum::http::StatusCode::INTERNAL_SERVER_ERROR, format!("the file could not be read: {e}")))?;

    let mut res = (axum::http::StatusCode::OK, bytes).into_response();

    let h = res.headers_mut();

    h.insert(header::CONTENT_TYPE, HeaderValue::from_static(crate::web::reports::content_type(path)));

    h.insert(header::CONTENT_SECURITY_POLICY, HeaderValue::from_static("sandbox; default-src 'none'"));

    h.insert(header::X_CONTENT_TYPE_OPTIONS, HeaderValue::from_static("nosniff"));

    Ok(res)

}

/// `GET /repos/{o}/{n}/flow/runs/{number}/jobs/{job}/reports`: the reports

/// a job published (oxygenhub#348).

pub async fn job_reports(

    State(app): State<Shared>,

    headers: HeaderMap,

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

) -> Result<Json<Vec<Report>>, ApiError> {

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

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

    let run = crate::db::flow::run(&app.db, row.id, number).await?.ok_or_else(|| not_found(&format!("no run #{number}")))?;

    let j = crate::db::flow::jobs(&app.db, run.id)

        .await?

        .into_iter()

        .find(|j| j.name == job)

        .ok_or_else(|| not_found(&format!("run #{number} has no job {job}")))?;

    let base = format!("/{owner}/{name}");

    let mut out = vec![];

    for r in reports::of_job(&app.db, j.id).await? {

        out.push(report_of(&app, &base, &r, false).await?);

    }

    Ok(Json(out))

}

/// `GET /repos/{o}/{n}/flow/runs/{number}/jobs/{job}/report[?name=]`: the

/// report a job published, with its files (oxygenhub#348).

pub async fn job_report_one(

    State(app): State<Shared>,

    headers: HeaderMap,

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

    Query(q): Query<ReportQuery>,

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

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

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

    let r = job_report(&app, row.id, number, &job, q.name.as_deref()).await?;

    Ok(Json(report_of(&app, &format!("/{owner}/{name}"), &r, true).await?))

}

/// `GET /repos/{o}/{n}/flow/runs/{number}/jobs/{job}/report/{*path}[?name=]`:

/// one file of it, as published.

pub async fn job_report_file(

    State(app): State<Shared>,

    headers: HeaderMap,

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

    Query(q): Query<ReportQuery>,

) -> Result<Response, ApiError> {

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

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

    let r = job_report(&app, row.id, number, &job, q.name.as_deref()).await?;

    report_file(&app, &repo, &r, &path).await

}

/// `GET /repos/{o}/{n}/reports[?bookmark=]`: the newest run of each report,

/// on `bookmark` when given, newest first (oxygenhub#348).

pub async fn latest_reports(

    State(app): State<Shared>,

    headers: HeaderMap,

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

    Query(q): Query<ReportQuery>,

) -> Result<Json<Vec<Report>>, ApiError> {

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

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

    let base = format!("/{owner}/{name}");

    let mut out = vec![];

    for r in reports::latest(&app.db, row.id, q.bookmark.as_deref().filter(|b| !b.is_empty())).await? {

        out.push(report_of(&app, &base, &r, false).await?);

    }

    Ok(Json(out))

}

/// `GET /repos/{o}/{n}/reports/{report}[?id=|?bookmark=]`: one run of a

/// report with its files: by id, else the newest on the bookmark.

pub async fn named_report_one(

    State(app): State<Shared>,

    headers: HeaderMap,

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

    Query(q): Query<ReportQuery>,

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

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

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

    let r = named_report(&app, &row, &report, &q).await?;

    Ok(Json(report_of(&app, &format!("/{owner}/{name}"), &r, true).await?))

}

/// `GET /repos/{o}/{n}/reports/{report}/files/{*path}[?id=|?bookmark=]`.

pub async fn named_report_file(

    State(app): State<Shared>,

    headers: HeaderMap,

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

    Query(q): Query<ReportQuery>,

) -> Result<Response, ApiError> {

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

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

    let r = named_report(&app, &row, &report, &q).await?;

    report_file(&app, &repo, &r, &path).await

}

/// Report `id`'s files, by path, with their sizes.

pub async fn files_of(pool: &Pool, id: i64) -> sqlx::Result<Vec<(String, i64)>> {

    sqlx::query_as("SELECT path, size FROM report_files WHERE report_id = $1 ORDER BY path").bind(id).fetch_all(pool).await

}

/// The reports a job published, by name.

pub async fn of_job(pool: &Pool, job_id: i64) -> sqlx::Result<Vec<Report>> {

    sqlx::query_as("SELECT * FROM reports WHERE job_id = $1 ORDER BY name").bind(job_id).fetch_all(pool).await

}

pub(crate) fn content_type(path: &str) -> &'static str {

    // The same over the API (#348): the job's report with its files, one

    // file as published, the newest of each, one by id, and plain 404s.

    let n = run.number;

    let (st, body) = call(&h.app, "GET", &format!("/api/v1/repos/andy/demo/flow/runs/{n}/jobs/perf/report"), None, None).await;

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

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

    assert_eq!((r["id"].as_i64(), r["name"].as_str(), r["kind"].as_str()), (Some(first), Some("frame-timing"), Some("performance")));

    assert_eq!((r["metrics"][0]["key"].as_str(), r["metrics"][0]["fail_above"].as_f64()), (Some("median_ms"), Some(20.0)));

    assert_eq!(r["context"]["target_fps"], 30);

    let paths: Vec<&str> = r["manifest"].as_array().unwrap().iter().map(|f| f["path"].as_str().unwrap()).collect();

    assert_eq!(paths, ["data/frames.csv", "index.html", "report.toml"]);

    assert!(r["url"].as_str().unwrap().ends_with(&format!("/andy/demo/reports/frame-timing?id={first}")));

    let (st, body) = call(&h.app, "GET", &format!("/api/v1/repos/andy/demo/flow/runs/{n}/jobs/perf/reports"), None, None).await;

    assert!(st == StatusCode::OK && body.contains("\"frame-timing\"") && !body.contains("manifest"), "{st} {body}");

    let res = oxygenhub::router(h.app.clone())

        .oneshot(

            Request::get(format!("/api/v1/repos/andy/demo/flow/runs/{n}/jobs/perf/report/data/frames.csv")).body(Body::empty()).unwrap(),

        )

        .await

        .unwrap();

    assert_eq!(res.status(), StatusCode::OK);

    assert_eq!(res.headers()[header::CONTENT_TYPE], "text/csv; charset=utf-8");

    assert_eq!(res.headers()[header::CONTENT_SECURITY_POLICY], "sandbox; default-src 'none'", "a page in it runs nothing on the hub");

    assert_eq!(res.into_body().collect().await.unwrap().to_bytes().to_vec(), data_bytes);

    let toml_path = format!("/api/v1/repos/andy/demo/flow/runs/{n}/jobs/perf/report/report.toml?name=frame-timing");

    assert_eq!(get_bytes(&h.app, &toml_path).await, (StatusCode::OK, toml.to_vec()));

    let (st, body) = call(&h.app, "GET", &format!("/api/v1/repos/andy/demo/flow/runs/{n}/jobs/perf/report/nope.csv"), None, None).await;

    assert!(st == StatusCode::NOT_FOUND && body.contains("has no file nope.csv") && body.contains("report.toml"), "{st} {body}");

    let (st, body) = call(&h.app, "GET", &format!("/api/v1/repos/andy/demo/flow/runs/{n}/jobs/perf/report?name=other"), None, None).await;

    assert!(st == StatusCode::NOT_FOUND && body.contains("it published frame-timing"), "{st} {body}");

    let (st, body) = call(&h.app, "GET", &format!("/api/v1/repos/andy/demo/flow/runs/{n}/jobs/nojob/report"), None, None).await;

    assert!(st == StatusCode::NOT_FOUND && body.contains("its jobs: perf"), "{st} {body}");

    // The newest of each is the second run; ?id= reaches the first.

    let (_, body) = call(&h.app, "GET", "/api/v1/repos/andy/demo/reports", None, None).await;

    let latest: Vec<serde_json::Value> = serde_json::from_str(&body).unwrap();

    assert_eq!((latest.len(), latest[0]["id"].as_i64(), latest[0]["run"].as_i64()), (1, Some(second), Some(2)));

    assert_eq!(latest[0]["metrics"][0]["value"].as_f64(), Some(18.0));

    let (_, body) = call(&h.app, "GET", "/api/v1/repos/andy/demo/reports/frame-timing", None, None).await;

    assert_eq!(serde_json::from_str::<serde_json::Value>(&body).unwrap()["id"].as_i64(), Some(second), "newest on its bookmark");

    let (_, body) = call(&h.app, "GET", &format!("/api/v1/repos/andy/demo/reports/frame-timing?id={first}"), None, None).await;

    assert_eq!(serde_json::from_str::<serde_json::Value>(&body).unwrap()["summary"], "Median 16.4 ms");

    let page_path = format!("/api/v1/repos/andy/demo/reports/frame-timing/files/index.html?id={first}");

    assert_eq!(get_bytes(&h.app, &page_path).await, (StatusCode::OK, page_bytes.clone()), "as published, no frame script");

    let (st, body) = call(&h.app, "GET", "/api/v1/repos/andy/demo/reports/frame-timing?bookmark=elsewhere", None, None).await;

    assert!(st == StatusCode::NOT_FOUND && body.contains("never ran on elsewhere"), "{st} {body}");

    let (st, _) = call(&h.app, "GET", "/api/v1/repos/andy/demo/reports/nothing", None, None).await;

    assert_eq!(st, StatusCode::NOT_FOUND);

    // A run's jobs carry their timings, phases in the order taken.

    let phases = std::collections::BTreeMap::from([("run".to_string(), 1200u64), ("image".to_string(), 300)]);

    db::flow::set_phases(&h.app.db, id, &phases).await.unwrap();

    let (_, body) = call(&h.app, "GET", &format!("/api/v1/repos/andy/demo/flow/runs/{n}"), None, None).await;

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

    assert!(v["jobs"][0]["queued_ms"].as_i64().is_some(), "{body}");

    assert_eq!(v["jobs"][0]["phases"], serde_json::json!([{ "name": "image", "ms": 300 }, { "name": "run", "ms": 1200 }]));

    /// GET raw bytes from the API (a report's file).

    pub fn get_bytes(&self, path: &str) -> Result<Vec<u8>> {

        match self.req("GET", path).call() {

            Ok(r) => {

                let mut out = Vec::new();

                std::io::Read::read_to_end(&mut r.into_reader(), &mut out)?;

                Ok(out)

            }

            Err(e) => Self::finish(Err(e), &format!("GET {path}")).map(String::into_bytes),

        }

    }

use hub_api::{

    FlowJob, FlowLogLine, FlowRun, Issue, IssueStateChange, NewComment, NewIssue, NewProposal, NewRelease, Proposal, Release, Report, Tag,

};

    /// Reports Flow jobs publish: the newest of each, one by name (oxygenhub#348)

    Report {

        #[command(subcommand)]

        cmd: ReportCmd,

    },

    View {

        number: i64,

        /// Each job's wait, phases (image, prepare, run, finish) and peak disk and memory

        #[arg(long)]

        timings: bool,

    },

    /// A report a job published: its report.toml; --list for what it holds, --file for one file

    Report {

        number: i64,

        job: String,

        #[command(flatten)]

        pick: ReportPick,

    },

}

/// Which report of a job, and what of it to show.

#[derive(clap::Args)]

struct ReportPick {

    /// Which report, when the job published more than one

    #[arg(long)]

    name: Option<String>,

    /// What it holds: its metrics, context and files

    #[arg(long, conflicts_with = "file")]

    list: bool,

    /// One file of it (`data/frames.csv`), as published

    #[arg(long, value_name = "PATH")]

    file: Option<String>,

    /// Write the file here instead of to stdout

    #[arg(long, short, value_name = "FILE", requires = "file")]

    output: Option<std::path::PathBuf>,

enum ReportCmd {

    /// The newest run of each report, newest first

    List {

        /// Only runs on this bookmark

        #[arg(long)]

        bookmark: Option<String>,

    },

    /// One report: its newest run on the default bookmark (or --bookmark), or the run --id names

    Show {

        report: String,

        #[arg(long, conflicts_with = "bookmark")]

        id: Option<i64>,

        #[arg(long)]

        bookmark: Option<String>,

        /// What it holds: its metrics, context and files

        #[arg(long, conflicts_with = "file")]

        list: bool,

        /// One file of it, as published

        #[arg(long, value_name = "PATH")]

        file: Option<String>,

        /// Write the file here instead of to stdout

        #[arg(long, short, value_name = "FILE", requires = "file")]

        output: Option<std::path::PathBuf>,

    },

}

#[derive(Subcommand)]

        Cmd::Report { cmd } => report(&c, &t, cmd, json),

fn print_run(r: &FlowRun, timings: bool) {

        if timings {

            let t = timing_line(j);

            if !t.is_empty() {

                println!("    {}", ui::dim(&t));

            }

        }

/// Milliseconds as a person reads them: "850 ms", "3.1 s", "2 min 5 s".

fn took(ms: i64) -> String {

    match ms {

        ..=999 => format!("{ms} ms"),

        1000..=59_999 => format!("{:.1} s", ms as f64 / 1000.0),

        _ => format!("{} min {} s", ms / 60_000, (ms % 60_000) / 1000),

    }

}

/// MiB as a person reads them.

fn mib(m: i64) -> String {

    if m >= 1024 {

        format!("{:.1} GiB", m as f64 / 1024.0)

    } else {

        format!("{m} MiB")

    }

}

/// Where a job's time went (oxygenhub#348): its wait for a runner, each

/// phase its runner reported, and the most disk and memory it took.

fn timing_line(j: &FlowJob) -> String {

    let mut parts = vec![];

    if let (Some(q), Some(s)) = (j.queued_ms, j.started_ms) {

        parts.push(format!("waited {}", took((s - q).max(0))));

    }

    parts.extend(j.phases.iter().map(|p| format!("{} {}", p.name, took(p.ms as i64))));

    let peaks: Vec<String> = [("disk", j.peak_disk_mib), ("memory", j.peak_memory_mib)]

        .into_iter()

        .filter_map(|(what, m)| m.map(|m| format!("{what} {}", mib(m))))

        .collect();

    if !peaks.is_empty() {

        parts.push(format!("peak {}", peaks.join(", ")));

    }

    parts.join(" · ")

}

/// A report's path, its segments encoded and its slashes kept.

fn enc_path(path: &str) -> String {

    path.split('/').map(enc).collect::<Vec<_>>().join("/")

}

/// `oh run report` and `oh report show`: the report at `at` (JSON), whose

/// files are at `files(path)`. By default its report.toml; with `list`

/// what it holds; with `file` one file, to stdout or `output`.

fn show_report(

    c: &Client,

    at: &str,

    files: impl Fn(&str) -> String,

    list: bool,

    file: Option<String>,

    output: Option<std::path::PathBuf>,

    json: bool,

) -> Result<()> {

    use std::io::Write;

    if let Some(path) = file {

        let bytes = c.get_bytes(&files(&path))?;

        match output {

            Some(out) => {

                std::fs::write(&out, &bytes).with_context(|| format!("writing {}", out.display()))?;

                eprintln!("{} {path}: {} bytes to {}", ui::ok("✔"), bytes.len(), out.display());

            }

            None => std::io::stdout().write_all(&bytes)?,

        }

        return Ok(());

    }

    if json {

        println!("{}", c.get_text(at)?);

        return Ok(());

    }

    if !list {

        std::io::stdout().write_all(&c.get_bytes(&files("report.toml"))?)?;

        return Ok(());

    }

    let r: Report = c.get(at)?;

    print_report(&r);

    if r.files_expired_ms.is_some() {

        println!("{}", ui::warn("its files expired under retention; its metrics stay"));

    }

    for f in &r.manifest {

        println!("  {:>10}  {}", ui::dim(&f.size.to_string()), f.path);

    }

    println!("{}", ui::dim(&r.url));

    Ok(())

}

/// A report's heading, metrics and context.

fn print_report(r: &Report) {

    let from = match r.run {

        Some(n) => format!("run #{n} {} on {}", r.job, r.bookmark),

        None => format!("upload on {}", if r.bookmark.is_empty() { "a change" } else { &r.bookmark }),

    };

    println!(

        "{} {} {}",

        ui::strong(&r.name),

        ui::dim(&format!("{} · {:?}", r.kind, r.title)),

        ui::dim(&format!("· {from} · {} files", r.files))

    );

    if !r.summary.is_empty() {

        println!("  {}", r.summary);

    }

    for m in &r.metrics {

        let unit = if m.unit.is_empty() { String::new() } else { format!(" {}", m.unit) };

        let mut notes = vec![];

        if !m.better.is_empty() {

            notes.push(format!("{} is better", m.better));

        }

        if let Some(a) = m.fail_above {

            notes.push(format!("fails above {a}"));

        }

        if let Some(b) = m.fail_below {

            notes.push(format!("fails below {b}"));

        }

        let notes = if notes.is_empty() { String::new() } else { format!("  ({})", notes.join(", ")) };

        println!("  {} {}{unit}{}", m.key, m.value, ui::dim(&notes));

    }

    if let Some(ctx) = r.context.as_object().filter(|m| !m.is_empty()) {

        let line: Vec<String> =

            ctx.iter().map(|(k, v)| format!("{k}={}", v.as_str().map(String::from).unwrap_or_else(|| v.to_string()))).collect();

        println!("  {}", ui::dim(&line.join(" ")));

    }

}

/// `oh report …` (oxygenhub#348).

fn report(c: &Client, t: &Target, cmd: ReportCmd, json: bool) -> Result<i32> {

    let base = t.repo_path()?;

    match cmd {

        ReportCmd::List { bookmark } => {

            let path = format!("{base}/reports{}", bookmark.map(|b| format!("?bookmark={}", enc(&b))).unwrap_or_default());

            if json {

                println!("{}", c.get_text(&path)?);

                return Ok(0);

            }

            let list: Vec<Report> = c.get(&path)?;

            if list.is_empty() {

                println!("{}", ui::dim("No reports yet: a Flow job publishes one with `output { report \"name\" { path … } }`."));

            }

            for r in &list {

                print_report(r);

            }

        }

        ReportCmd::Show { report, id, bookmark, list, file, output } => {

            let at = format!("{base}/reports/{}", enc(&report));

            let query = match (id, bookmark) {

                (Some(id), _) => format!("?id={id}"),

                (None, Some(b)) => format!("?bookmark={}", enc(&b)),

                (None, None) => String::new(),

            };

            let files = |path: &str| format!("{at}/files/{}{query}", enc_path(path));

            show_report(c, &format!("{at}{query}"), files, list, file, output, json)?;

        }

    }

    Ok(0)

}

        RunCmd::View { number, timings } => {

            print_run(&c.get(&path)?, timings);

        }

        RunCmd::Report { number, job, pick } => {

            let at = format!("{base}/flow/runs/{number}/jobs/{}/report", enc(&job));

            let query = pick.name.as_deref().map(|n| format!("?name={}", enc(n))).unwrap_or_default();

            let files = |path: &str| format!("{at}/{}{query}", enc_path(path));

            show_report(c, &format!("{at}{query}"), files, pick.list, pick.file, pick.output, json)?;

    #[test]

    fn job_timings_and_report_commands_read_plainly() {

        use clap::Parser;

        let job = hub_api::FlowJob {

            name: "perf".into(),

            status: "passed".into(),

            depends_on: vec![],

            runner: "earth-1".into(),

            exit_code: Some(0),

            error: String::new(),

            started_ms: Some(13_000),

            finished_ms: Some(200_000),

            log_lines: 10,

            waiting: String::new(),

            placed: String::new(),

            approval: String::new(),

            queued_ms: Some(1_000),

            ready_ms: Some(12_500),

            phases: vec![hub_api::FlowPhase { name: "image".into(), ms: 850 }, hub_api::FlowPhase { name: "run".into(), ms: 125_400 }],

            peak_disk_mib: Some(2150),

            peak_memory_mib: Some(900),

        };

        assert_eq!(super::timing_line(&job), "waited 12.0 s · image 850 ms · run 2 min 5 s · peak disk 2.1 GiB, memory 900 MiB");

        let bare = hub_api::FlowJob { queued_ms: None, phases: vec![], peak_disk_mib: None, peak_memory_mib: None, ..job };

        assert_eq!(super::timing_line(&bare), "");

        assert_eq!(super::enc_path("data/frame times.csv"), "data/frame%20times.csv");

        let cli =

            super::Cli::try_parse_from(["oh", "run", "report", "26", "performance", "--file", "data/frames.csv", "-o", "f.csv"]).unwrap();

        let super::Cmd::Run { cmd: super::RunCmd::Report { number, job, pick } } = cli.cmd else { panic!("run report") };

        assert_eq!((number, job.as_str(), pick.file.as_deref(), pick.list), (26, "performance", Some("data/frames.csv"), false));

        assert!(super::Cli::try_parse_from(["oh", "run", "report", "26", "perf", "--list", "--file", "x"]).is_err(), "one or the other");

        assert!(super::Cli::try_parse_from(["oh", "run", "report", "26", "perf", "-o", "x"]).is_err(), "-o is for --file");

        let cli = super::Cli::try_parse_from(["oh", "report", "show", "performance", "--bookmark", "main", "--list"]).unwrap();

        assert!(matches!(cli.cmd, super::Cmd::Report { cmd: super::ReportCmd::Show { list: true, .. } }));

        assert!(super::Cli::try_parse_from(["oh", "run", "view", "3", "--timings"]).is_ok());

    }

Built (oxygenhub#348), read access as the repository's pages:

- `GET /repos/{o}/{n}/flow/runs/{n}/jobs/{job}/reports`: the reports a job

  published, with their metrics and context.

- `GET /repos/{o}/{n}/flow/runs/{n}/jobs/{job}/report` (`?name=` when the

  job published more than one): the report with its files (`manifest`:

  path and size), and `…/report/{path}` one file as published.

- `GET /repos/{o}/{n}/reports` (`?bookmark=`): the newest run of each.

- `GET /repos/{o}/{n}/reports/{name}` (`?id=`, the page's run id, or

  `?bookmark=`, default the repository's default bookmark, else wherever

  it ran last): one run with its files, and `…/{name}/files/{path}` one

  file of it.

A file over the API comes as published (an HTML page without the frame

script), with its type and `Content-Security-Policy: sandbox;

default-src 'none'`, so nothing in it runs on the hub's origin. A run

whose files expired answers `410` for them; its metrics stay. The errors

name what there is: the run's jobs, the job's reports, the report's files.

- `oh run report RUN JOB` prints the report's `report.toml`; `--list`

  shows its metrics, context and files; `--file data/frames.csv` writes

  one file to stdout or `-o FILE`; `--name` picks among a job's reports;

  `--json` gives the API's answer.

- `oh report list [--bookmark B]` and `oh report show NAME [--bookmark B |

  --id ID] [--list | --file PATH [-o FILE]]`.

Still to come: a report's history over the API (`?limit=&before=`) and

uploads from anywhere else (`POST /repos/{o}/{n}/reports/{name}`, `oh

report upload NAME DIR`, §2).

metrics and summary, and its page says its files expired. *2026-10-28:*

reading reports over the API and `oh run report` / `oh report` (4) are

built (§6); uploads and history over the API follow.

JSON under `/api/v1`, bearer tokens, `application/json`, RFC 7807 problem responses (an unknown route, or a known one with the wrong method, too), 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/{ref}` (`?path=`, `?offset=&limit=`, or `?r=REVSET` for the changes a revset selects, evaluated under a two-second budget and answering 400 when it does not parse or goes past it; Oxygen's docs/revset_query_language.md), `/compare`, `/conflicts`, `/proposals` (`?state=open|draft|landed|closed|all`, open ones and drafts by default; a source bookmark may hold `/`, and `owner/name:bookmark` naming the repository itself is its own bookmark), `/proposals/{n}/comments|reviews|checks|files`, `PATCH /proposals/{n}` (the title and description, for its author or a maintainer, and `labels`, the whole set by name, for triage; what is not given stays), `POST /proposals/{n}/land` (repo:write: what the Land button does, `409` with the blockers when it cannot; a landed proposal keeps the changes it landed and reports `landed` with who, how (`web`, or `api (token NAME)`) and when, which its event, the audit log and the push record also say, adding when nobody approved), `/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` (`POST` creates one or changes the description and due date of the one with that title, `PATCH /milestones/{title}` changes title, description, due date or state; triage), `/releases` (`PATCH /releases/{tag}` changes the title, notes or prerelease flag, repo:write), `/tags` (`POST` creates one, repo:write; `DELETE /tags/{tag}` withdraws one, a maintainer, `409` while a release uses it; §9), `/trust`, `/pushes`, `/hooks`, `/checks`, `/user`, `/user/repos` (the caller's own, organisations' and collaborations, `?affiliation=&after=&limit=`, #302), `/user/orgs`, `/user/sky` (Your sky's data, the dashboard backdrop's: the caller's repositories and their events of the last 30 days as `[repo, kind, at_ms, n]`, for the Android app; oxygenhub-android#23; `/repos/{owner}/{name}/sky` gives one repository's, its pages' backdrop), `/user/flow/runs` (the newest Flow runs of the caller's repositories, each with its repository and jobs, `?before=MS&limit=`; oxygenhub-android#26), `/user/starter?owner=X` and `/repos/{owner}/{name}/starter` (#347: the assistants a new repository under X may ask, and, `POST {"description", "assistant"}` by its admin, an assistant's draft of an empty repository's starting files, committed in the background as the caller, the hub signing as their delegate; `GET` says `running`, `done` with the change and files, or `failed` with why), `/notifications` (the caller's inbox and unread count, each with its repository, reason, thread and label, #305; `/notifications/{id}/read` and `/notifications/read` mark read; scope `user:read`), `/users/{name}`, `/users/{name}/drops` and `/drops` (§4.5), `/orgs/{name}`, `/checks/{state}` (the checks on a state, named by its hash, by its heads joined with `+`, by the one head of a single-head state, or by a bookmark), `/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, and `owner` to transfer it to an owner the caller may make boards under (#125: it takes the next number there, and its old address redirects), `/cards` to list them by column or add a reference or note to a column named by id or name, `/cards/{id}` to move or remove one, `POST /cards/move` (#289: `{"from", "column", "except", "state", "dry_run"}`) to move a column's cards at once, but those `except` names (card ids or issue and proposal references) and, given `state`, only those whose issue or proposal is in one, all or none and audited once, answering what moved and what was kept; `POST /cards/archive` (#293: `{"from", "older_days", "except", "state", "dry_run"}`, the same selection and an age) to archive them, `GET /cards?archived=true` to list the archived ones (each with `archived_ms`) and `POST /cards/{id}/restore` to put one back; cards carry their `labels` and `assignees`; `repo:write` and the page's rights to change), `/coverage` and `/tests` (a bookmark's coverage and JUnit test reports from Flow jobs, newest first, `?bookmark=&limit=`), `POST /coverage` (repo:write, #136: `{"bookmark"}` or `{"change"}` and `content`, an LCOV, Cobertura or JaCoCo report measured off the hub, kept for that state as uploaded by the caller, shown "uploaded by NAME" wherever a run number would be, and setting no check; `oh coverage upload FILE`), `/coverage/{id}` (a report with its files) and `/tests/{id}` (a report with its cases, `?status=failed` for the failed and errored ones), `/flow/runs` (`GET`: runs newest first, `?before=N&limit=`; `POST {"bookmark"}` or `{"change"}`, repo:write: run a bookmark's current state, the default bookmark when none is named, or one change's state; with `"jobs": [NAME..]` only those jobs and what they depend on, each one a manual run starts, else `409` naming the ones it does (#130); `oh run start --job NAME`), `/flow/runs/{n}` (a run with its jobs, each with its timings: `queued_ms`, `ready_ms`, the `phases` its runner reported (image, prepare, run, finish, in milliseconds) and its peak disk and memory; #348, `oh run view N --timings`), `/flow/runs/{n}/jobs/{job}/log` (`?after=seq&limit=`), `/flow/runs/{n}/jobs/{job}/reports` and `/flow/runs/{n}/jobs/{job}/report` (`?name=`; with its files, and `…/report/{path}` one file as published, sandboxed) and `/reports` (`?bookmark=`: the newest run of each) and `/reports/{name}` (`?id=` or `?bookmark=`; `…/files/{path}`): the reports Flow jobs publish (#348, docs/reports.md §6; `oh run report N JOB`, `oh report`) and `/flow/runs/{n}/rerun` (repo:write: a finished run again), both answering `201 {"number", "url"}` or `409` with why nothing started, `/flow/runs/{n}/jobs/{job}/rerun` (repo:write, oxygenflow#31: that job of a finished run again, in the same run, with the jobs that depend on it; what it depends on keeps its result, so a flaky test reruns without its build; their logs, artifacts and reports go, their checks return to queued and the run is running again; `{"queued": N}`, or `409` while the run is live or for a job it lacks; RE-RUN THIS JOB on the run page, `oh run rerun N --job NAME`), `/flow/runs/{n}/cancel` (repo:write: a run still going ends as `cancelled`, its running jobs stopped when their runner next reports; `409` when it had already ended; a push to a bookmark cancels the push runs of it still going), `/search`. A change's author carries the account its key is linked to, or `null` and a `note` saying the key is not linked and where its owner links it; `via` names the delegate (an agent) that signed for the author when one did, with the delegation's scope and expiry and whether it has since been revoked, and the pages show the same as an `agent` badge, a `via` row under the author on the change page, and a count under the author in Contributors (the change page shows a "key not linked" tag, with a link to Settings → Keys for signed-in viewers). 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.