diff --git a/docs/4-implementation/agent-tools/forge-cli.md b/docs/4-implementation/agent-tools/forge-cli.md index 8d279545f..85640399e 100644 --- a/docs/4-implementation/agent-tools/forge-cli.md +++ b/docs/4-implementation/agent-tools/forge-cli.md @@ -117,7 +117,7 @@ Deadline: hive-forge stops after HIVE_FORGE_DEADLINE seconds (default 900), prin * `attachment-get` — Download an attachment by UUID or URL. Saves to a temp file and prints the path (pass `-o -` to stream raw bytes to stdout) * `artifact-get` — Download a CI Actions artifact from a run (` --run `). Saves a zip, or pass `-o -` to stream to stdout * `ci-log` — Print a CI Actions run's job step logs (`--run [--job i] [--step i]`) -* `ci-rerun` — Re-run CI without an empty commit. Pass one of `--pr `, `--run `, or `--branch `; `--workflow` defaults to `ci.yml` +* `ci-rerun` — Re-run CI without an empty commit. Pass one of `--pr `, `--run `, or `--branch `; `--workflow` defaults to `ci.yml`. `--input key=value` (repeatable) passes workflow inputs, for example one VM test: `--workflow vm-nightly.yml --input test=` * `ci-runs` — List CI Actions runs, newest first (`--workflow`, `--branch`, `--limit`, `--page`) — the run numbers `ci-log`/`ci-rerun --run`/ `artifact-get --run` take ###### **Options:** @@ -1398,7 +1398,7 @@ Print a CI Actions run's job step logs (`--run [--job i] [--step i]`) ## `hive-forge ci-rerun` -Re-run CI without an empty commit. Pass one of `--pr `, `--run `, or `--branch `; `--workflow` defaults to `ci.yml` +Re-run CI without an empty commit. Pass one of `--pr `, `--run `, or `--branch `; `--workflow` defaults to `ci.yml`. `--input key=value` (repeatable) passes workflow inputs, for example one VM test: `--workflow vm-nightly.yml --input test=` **Usage:** `hive-forge ci-rerun [OPTIONS]` @@ -1410,6 +1410,7 @@ Re-run CI without an empty commit. Pass one of `--pr `, `--run `, or `--br * `--workflow ` — Workflow file to run (default `ci.yml`). Ignored for `--run`, which uses the run's own workflow Default value: `ci.yml` +* `--input ` — Workflow input for the dispatch, `key=value` (repeatable; the value may be empty or contain `=`). The workflow lists its inputs under `on.workflow_dispatch.inputs`; for an unknown input the forge's own error comes back unchanged. Example: `--workflow vm-nightly.yml --input test=k8s-swarm-images` runs one VM test instead of all of them diff --git a/docs/4-implementation/agent-tools/forge.md b/docs/4-implementation/agent-tools/forge.md index 58f0c0ae0..e8baa2b04 100644 --- a/docs/4-implementation/agent-tools/forge.md +++ b/docs/4-implementation/agent-tools/forge.md @@ -115,6 +115,7 @@ hive-forge attach-comment 18042 /path/to/file # upload a file attachment to a c hive-forge attachment-get # download an attachment; prints resolved path to stdout hive-forge artifact-get pr1ma-paper-pdf --run 51 # download a CI run's Actions artifact zip (run number from the run-page URL) hive-forge ci-log --run 51 # print a CI run's job step logs (run number from the run-page URL); --job i / --step i to narrow +hive-forge ci-rerun --branch foo --workflow vm-nightly.yml --input test= # dispatch one VM test (repeatable --input key=value) hive-forge ci-rerun --branch foo # re-run CI without an empty commit (dispatches a fresh run; --run n also works unless that run was PR-triggered; --pr refuses, see below) hive-forge subscription --watch # subscribe to repo notifications hive-forge subscription --unwatch # unsubscribe @@ -302,7 +303,7 @@ to discover valid label names before triaging or to audit the label set. re-runs increment it). `--json` wraps the output. - `ci-rerun` re-runs CI: it dispatches a **fresh** run of the workflow via the workflow-dispatch API - (`POST …/actions/workflows//dispatches {"ref":""}`). + (`POST …/actions/workflows//dispatches {"ref":"","inputs":{…}}`). Resolve the branch with `--run ` (the same run number `ci-log` / `artifact-get` take — resolves the branch + workflow from that run) or `--branch ` (directly). `--pr `, and `--run ` against a run @@ -310,7 +311,12 @@ to discover valid label names before triaging or to audit the label set. a workflow-dispatch run writes no commit status, so it can't clear a red `(pull_request)` check on that PR's sha — re-run from the web UI instead. `--workflow ` picks the workflow file for `--branch` - (default `ci.yml`). Dispatch re-runs the whole workflow — there is no + (default `ci.yml`). `--input key=value` (repeatable) sets workflow + inputs in the dispatch body, for example `--branch k8s/v1 --workflow + vm-nightly.yml --input test=k8s-swarm-images` runs one VM test; an input + the workflow doesn't declare comes back as the forge's own error. The + verb prints the `ci-runs` command that follows the new run. Dispatch + re-runs the whole workflow — there is no single-job variant. - `issue dependency add ` / `pr dependency add ` set "blocked by" links via Forgejo's dependency feature — the diff --git a/hive-forge/src/client.rs b/hive-forge/src/client.rs index 7b66a58c5..97b19d4af 100644 --- a/hive-forge/src/client.rs +++ b/hive-forge/src/client.rs @@ -212,6 +212,31 @@ impl Client { }) } + /// POST a JSON body to `/api/v1` and discard a 2xx response body. + /// Raw instead of through `forgejo-api` for endpoints where that crate + /// maps every non-2xx status except `404` to a bare "unexpected status + /// code", dropping the forge's explanation: here a non-2xx surfaces as a + /// [`WebStatusError`] carrying the response body. `path` starts with `/`. + /// + /// # Errors + /// Returns an error on transport failure or a non-2xx response (body + /// included). + pub fn post_api_json(&self, path: &str, body: &B) -> Result<()> { + let url = format!("{}/api/v1{path}", self.base); + let resp = self + .web + .post(&url) + .json(body) + .timeout(JSON_TIMEOUT) + .send() + .map_err(|e| { + let ctx = http_context("POST", &e, JSON_TIMEOUT); + anyhow::Error::new(e).context(ctx) + })?; + check_status(resp, &format!("POST {url}"))?; + Ok(()) + } + /// GET a raw (non-API) URL and return the response body as bytes. /// Stays on the raw `reqwest` client because these are *web-router* /// routes (`/attachments/`, Actions artifact / persisted-log diff --git a/hive-forge/src/main.rs b/hive-forge/src/main.rs index e2325de1a..e93d96f0a 100644 --- a/hive-forge/src/main.rs +++ b/hive-forge/src/main.rs @@ -158,6 +158,8 @@ enum Verb { CiLog(verbs::ci_log::Args), /// Re-run CI without an empty commit. Pass one of `--pr `, /// `--run `, or `--branch `; `--workflow` defaults to `ci.yml`. + /// `--input key=value` (repeatable) passes workflow inputs, for example one VM + /// test: `--workflow vm-nightly.yml --input test=`. CiRerun(verbs::ci_rerun::Args), /// List CI Actions runs, newest first (`--workflow`, `--branch`, /// `--limit`, `--page`) — the run numbers `ci-log`/`ci-rerun --run`/ diff --git a/hive-forge/src/verbs/ci_rerun.rs b/hive-forge/src/verbs/ci_rerun.rs index b8a38b5ee..e7b90dd52 100644 --- a/hive-forge/src/verbs/ci_rerun.rs +++ b/hive-forge/src/verbs/ci_rerun.rs @@ -23,7 +23,13 @@ //! pseudo-ref, not a real branch — that case refuses for the same reason //! `--pr` does (same underlying run, same red check, same sha). //! -//! Dispatch re-runs the whole workflow (no single-job variant). +//! Dispatch re-runs the whole workflow (no single-job variant). Repeatable +//! `--input key=value` flags travel as the dispatch body's `inputs` map, for +//! a workflow whose `workflow_dispatch` declares them (for example +//! `vm-nightly.yml`'s `test`); the forge's own rejection of an unknown input +//! is surfaced verbatim. + +use std::collections::BTreeMap; use anyhow::{Context as _, Result, bail}; use clap::Args as ClapArgs; @@ -53,6 +59,57 @@ pub struct Args { /// which uses the run's own workflow. #[arg(long, default_value = "ci.yml")] workflow: String, + /// Workflow input for the dispatch, `key=value` (repeatable; the value + /// may be empty or contain `=`). The workflow lists its inputs under + /// `on.workflow_dispatch.inputs`; for an unknown input the forge's own + /// error comes back unchanged. Example: `--workflow vm-nightly.yml + /// --input test=k8s-swarm-images` runs one VM test instead of all of + /// them. + #[arg(long = "input", value_name = "KEY=VALUE", value_parser = parse_input)] + inputs: Vec<(String, String)>, +} + +/// Parse one `--input key=value`: split at the first `=`, so a value may +/// itself contain `=`. The key must be non-empty and have no surrounding +/// whitespace; the value may be empty (`test=` is how `vm-nightly.yml` asks +/// for every test). +fn parse_input(raw: &str) -> Result<(String, String), String> { + let Some((key, value)) = raw.split_once('=') else { + return Err(format!("`{raw}` is not key=value")); + }; + if key.is_empty() || key.trim() != key { + return Err(format!( + "`{raw}`: the key before `=` must be non-empty, without surrounding whitespace" + )); + } + Ok((key.to_string(), value.to_string())) +} + +/// The dispatch request body: `ref` plus the `inputs` map, `None` when no +/// `--input` was given so the request is the same as before inputs existed. +/// Errors on a key given twice rather than letting the later one win +/// silently. +fn dispatch_body(branch: &str, inputs: &[(String, String)]) -> Result { + let mut map = BTreeMap::new(); + for (key, value) in inputs { + if map.insert(key.clone(), value.clone()).is_some() { + bail!("ci-rerun: --input {key} given more than once"); + } + } + Ok(DispatchWorkflowOption { + inputs: (!map.is_empty()).then_some(map), + r#ref: branch.to_string(), + return_run_info: None, + }) +} + +/// `k=v k2=v2` for the confirmation line, in the order given. +fn render_inputs(inputs: &[(String, String)]) -> String { + inputs + .iter() + .map(|(k, v)| format!("{k}={v}")) + .collect::>() + .join(" ") } /// # Errors @@ -60,9 +117,10 @@ pub struct Args { /// Returns an error if none of `--pr` / `--run` / `--branch` is given, if /// `--pr` is given or `--run` names a PR-triggered run (refuses before /// dispatching — see the module doc), if a `--run` handle can't otherwise -/// be resolved (unknown run, or a run missing its ref), or if the dispatch -/// POST fails (network, or a non-2xx such as `404` for an unknown workflow -/// file or branch). +/// be resolved (unknown run, or a run missing its ref), if an `--input` key +/// is repeated, or if the dispatch POST fails (network, or a non-2xx such as +/// `404` for an unknown workflow file or branch, or the forge's rejection of +/// an input the workflow doesn't declare). pub fn run(client: &Client, args: Args) -> Result<()> { if let Some(pr) = args.pr { bail!(pr_refusal_message(pr)); @@ -78,23 +136,29 @@ pub fn run(client: &Client, args: Args) -> Result<()> { }; let (owner, name) = client.owner_repo()?; - let body = DispatchWorkflowOption { - inputs: None, - r#ref: branch.clone(), - return_run_info: None, - }; + let body = dispatch_body(&branch, &args.inputs)?; client - .api() - .dispatch_workflow(owner, name, &workflow, body) - .send() + .post_api_json( + &format!("/repos/{owner}/{name}/actions/workflows/{workflow}/dispatches"), + &body, + ) .with_context(|| { format!( "dispatch workflow {workflow} on {branch} ({repo}) — the workflow \ - file or the branch may not exist" + file or the branch may not exist, or an --input is not one the \ + workflow declares" ) })?; - println!("dispatched a fresh run of {workflow} on {branch} ({repo})"); + if args.inputs.is_empty() { + println!("dispatched a fresh run of {workflow} on {branch} ({repo})"); + } else { + println!( + "dispatched a fresh run of {workflow} on {branch} ({repo}) with inputs: {}", + render_inputs(&args.inputs) + ); + } + println!("follow it: hive-forge -r {repo} ci-runs --workflow {workflow} --branch {branch}"); Ok(()) } @@ -164,7 +228,10 @@ fn pr_number_from_run_ref(value: &str) -> Option { #[cfg(test)] mod tests { - use super::{ActionRun, pr_number_from_run_ref, pr_refusal_message, run_dispatch_target}; + use super::{ + ActionRun, dispatch_body, parse_input, pr_number_from_run_ref, pr_refusal_message, + render_inputs, run_dispatch_target, + }; use serde_json::json; /// Build a typed run record from an API-shaped JSON fixture. The @@ -265,4 +332,83 @@ mod tests { .expect("a PR-triggered run's dispatch target is a PR pseudo-ref"); assert_eq!(pr_refusal_message(pr), pr_refusal_message(4199)); // lint:allow: PR-shaped test fixture, not a tracker reference } + + #[test] + fn input_splits_at_the_first_equals() { + assert_eq!( + parse_input("test=k8s-swarm-images"), + Ok(("test".to_string(), "k8s-swarm-images".to_string())) + ); + assert_eq!( + parse_input("flags=a=b"), + Ok(("flags".to_string(), "a=b".to_string())) + ); + assert_eq!( + parse_input("test="), + Ok(("test".to_string(), String::new())) + ); + } + + #[test] + fn malformed_inputs_are_rejected() { + assert!(parse_input("test").is_err()); + assert!(parse_input("=value").is_err()); + assert!(parse_input(" test=x").is_err()); + assert!(parse_input("test =x").is_err()); + assert!(parse_input("").is_err()); + } + + #[test] + fn body_carries_ref_and_inputs_map() { + let body = dispatch_body( + "k8s/v1", + &[ + ("test".to_string(), "k8s-swarm-images".to_string()), + ("other".to_string(), String::new()), + ], + ) + .unwrap(); + assert_eq!( + serde_json::to_value(&body).unwrap(), + json!({ + "ref": "k8s/v1", + "inputs": { "test": "k8s-swarm-images", "other": "" }, + "return_run_info": null, + }) + ); + } + + #[test] + fn body_without_inputs_has_none() { + let body = dispatch_body("main", &[]).unwrap(); + assert_eq!(body.inputs, None); + assert_eq!(body.r#ref, "main"); + } + + #[test] + fn repeated_input_key_is_refused() { + let err = dispatch_body( + "main", + &[ + ("test".to_string(), "a".to_string()), + ("test".to_string(), "b".to_string()), + ], + ) + .unwrap_err(); + assert!( + err.to_string() + .contains("--input test given more than once") + ); + } + + #[test] + fn inputs_render_in_given_order() { + assert_eq!( + render_inputs(&[ + ("b".to_string(), "1".to_string()), + ("a".to_string(), "2".to_string()) + ]), + "b=1 a=2" + ); + } } diff --git a/hive-forge/tests/ci_rerun_inputs.rs b/hive-forge/tests/ci_rerun_inputs.rs new file mode 100644 index 000000000..4e78c4a66 --- /dev/null +++ b/hive-forge/tests/ci_rerun_inputs.rs @@ -0,0 +1,179 @@ +//! `ci-rerun --branch … --input k=v` against a mock forge: the dispatch POST +//! must carry the `inputs` map and `ref`, and a forge rejection must reach +//! the caller verbatim. + +use std::io::{BufRead as _, BufReader, Read as _, Write as _}; +use std::net::{TcpListener, TcpStream}; +use std::path::PathBuf; +use std::process::Command; +use std::sync::mpsc; + +/// A unique scratch `HYPERHIVE_STATE_DIR` holding a `forge-token` file, +/// same manual-tmpdir pattern as `pr_edit.rs`. +fn scratch_state_dir(tag: &str) -> PathBuf { + let ts = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .map_or(0, |d| d.as_nanos()); + let dir = std::env::temp_dir().join(format!("hive-forge-ci-rerun-test-{tag}-{ts}")); + std::fs::create_dir_all(&dir).expect("create scratch state dir"); + std::fs::write(dir.join("forge-token"), "test-token\n").expect("seed forge-token"); + dir +} + +/// Read one request, send `(request line, body)` down `tx`, answer with +/// `status_line` and a JSON `body`. +fn serve( + mut stream: TcpStream, + tx: &mpsc::Sender<(String, String)>, + status_line: &str, + reply: &str, +) { + let mut reader = BufReader::new(stream.try_clone().expect("clone stream")); + let mut request_line = String::new(); + reader + .read_line(&mut request_line) + .expect("read request line"); + let mut content_length = 0usize; + loop { + let mut line = String::new(); + if reader.read_line(&mut line).expect("read header") == 0 || line == "\r\n" { + break; + } + if let Some((name, value)) = line.split_once(':') + && name.eq_ignore_ascii_case("content-length") + { + content_length = value.trim().parse().expect("numeric content-length"); + } + } + let mut raw = vec![0u8; content_length]; + reader.read_exact(&mut raw).expect("read body"); + tx.send(( + request_line.trim().to_owned(), + String::from_utf8_lossy(&raw).into_owned(), + )) + .expect("send captured request"); + let response = format!( + "HTTP/1.1 {status_line}\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{reply}", + reply.len() + ); + stream + .write_all(response.as_bytes()) + .expect("write response"); +} + +struct Outcome { + ok: bool, + stdout: String, + stderr: String, + request_line: String, + body: serde_json::Value, +} + +/// Run `hive-forge -r o/r ci-rerun ` against a forge answering the +/// dispatch with `status_line` / `reply`. +fn dispatch(tag: &str, args: &[&str], status_line: &'static str, reply: &'static str) -> Outcome { + let listener = TcpListener::bind("127.0.0.1:0").expect("bind mock forge"); + let addr = listener.local_addr().expect("mock forge addr"); + let (tx, rx) = mpsc::channel(); + std::thread::spawn(move || { + for stream in listener.incoming() { + serve(stream.expect("accept"), &tx, status_line, reply); + } + }); + let out = Command::new(env!("CARGO_BIN_EXE_hive-forge")) + .args(["-r", "o/r", "ci-rerun"]) + .args(args) + .env("HIVE_FORGE_URL", format!("http://{addr}")) + .env("HYPERHIVE_STATE_DIR", scratch_state_dir(tag)) + .env_remove("HIVE_FORGE_TOKEN_FILE") + .env_remove("HIVE_LABEL") + .output() + .expect("run hive-forge"); + let (request_line, body) = rx.try_recv().unwrap_or_default(); + Outcome { + ok: out.status.success(), + stdout: String::from_utf8_lossy(&out.stdout).into_owned(), + stderr: String::from_utf8_lossy(&out.stderr).into_owned(), + request_line, + body: serde_json::from_str(&body).unwrap_or(serde_json::Value::Null), + } +} + +#[test] +fn inputs_travel_in_the_dispatch_body() { + let o = dispatch( + "inputs", + &[ + "--branch", + "k8s/v1", + "--workflow", + "vm-nightly.yml", + "--input", + "test=k8s-swarm-images", + "--input", + "extra=a=b", + ], + "204 No Content", + "", + ); + assert!(o.ok, "{}", o.stderr); + assert_eq!( + o.request_line, + "POST /api/v1/repos/o/r/actions/workflows/vm-nightly.yml/dispatches HTTP/1.1" + ); + assert_eq!(o.body["ref"], "k8s/v1"); + assert_eq!( + o.body["inputs"], + serde_json::json!({ "test": "k8s-swarm-images", "extra": "a=b" }) + ); + assert!( + o.stdout + .contains("with inputs: test=k8s-swarm-images extra=a=b"), + "{}", + o.stdout + ); + assert!( + o.stdout + .contains("ci-runs --workflow vm-nightly.yml --branch k8s/v1"), + "{}", + o.stdout + ); +} + +#[test] +fn no_input_sends_no_inputs_key() { + let o = dispatch("none", &["--branch", "main"], "204 No Content", ""); + assert!(o.ok, "{}", o.stderr); + assert_eq!(o.body["ref"], "main"); + assert!(o.body["inputs"].is_null(), "{}", o.body); +} + +#[test] +fn forge_rejection_of_an_input_is_printed_verbatim() { + let o = dispatch( + "reject", + &["--branch", "main", "--input", "bogus=1"], + "400 Bad Request", + r#"{"message":"input bogus is not defined in the workflow"}"#, + ); + assert!(!o.ok, "{}", o.stdout); + assert!( + o.stderr + .contains("input bogus is not defined in the workflow"), + "{}", + o.stderr + ); +} + +#[test] +fn malformed_input_is_refused_before_any_request() { + let o = dispatch( + "malformed", + &["--branch", "main", "--input", "nokey"], + "204 No Content", + "", + ); + assert!(!o.ok); + assert!(o.stderr.contains("not key=value"), "{}", o.stderr); + assert!(o.request_line.is_empty(), "{}", o.request_line); +}