diff --git a/README.md b/README.md index 87d348f..9e2b623 100644 --- a/README.md +++ b/README.md @@ -204,14 +204,14 @@ history. Aborts if the destination already has a drive with the same slug. | `switchboard docs list [--drive ]` | List documents (all drives, or filtered by `--drive`; add `--type` to filter) | | `switchboard docs get [--drive ] [--state] [--out ]` | Get document details (auto-detects drive; `--state` includes full state) | | `switchboard docs tree []` | Hierarchical folder/file view — all drives if no argument, single drive if slug given | -| `switchboard docs create` | Interactive creation with drive picker (or pass `--type`, `--name`, `--drive`) | +| `switchboard docs create [--parent-folder ]` | Interactive creation with drive picker (or pass `--type`, `--name`, `--drive`; `--parent-folder` places it inside a folder) | | `switchboard docs delete ` | Delete one or more documents — batch API (use `-y` to skip confirmation) | | `switchboard docs rename ` | Rename a document | | `switchboard docs parents ` | Show parent documents (reverse tree traversal) | | `switchboard docs add-to ` | Add documents as children of a parent | | `switchboard docs remove-from ` | Remove documents from a parent | | `switchboard docs move --from --to ` | Move documents between parents | -| `switchboard docs apply --actions '' [--file ] [--wait] [--allow-literal-escapes]` | Dispatch raw actions via `mutateDocument` — pass actions inline or from a file; `--wait` blocks until async completion. Refuses string fields containing a literal `\n`/`\t`/`\r` (a double-encoding bug that stores `\n` in note bodies) unless `--allow-literal-escapes` | +| `switchboard docs apply --actions '' [--file ] [--wait] [--allow-literal-escapes]` | Dispatch raw actions via `mutateDocument` — pass actions inline or from a file; `--wait` blocks until async completion and fails if any action was rejected. Refuses string fields containing a literal `\n`/`\t`/`\r` (a double-encoding bug that stores `\n` in note bodies) unless `--allow-literal-escapes` | | `switchboard docs mutate [--op ] [--input ''] [--input-file ] [--drive ] [--allow-literal-escapes]` | Interactive field-by-field editor — omit `--op` for operation picker; pass `--input` / `--input-file` for scripting. Same literal-escape guard as `apply` | ### Folders @@ -272,8 +272,8 @@ All export commands support operation filters: `--action-types ` (comma-s |---------|-------------| | `switchboard watch docs [--type ] [--drive ] [--doc ] [--exec ]` | Stream document change events via WebSocket. Enriched output includes slug, timestamps, revisions, and context. `--exec` runs a command for each event with JSON on stdin and `$SWITCHBOARD_EVENT` set | | `switchboard watch job ` | Stream job status updates | -| `switchboard jobs status ` | Get current job status with visual progression bar | -| `switchboard jobs wait [--timeout ]` | Block until a job completes via WebSocket subscription (no polling) | +| `switchboard jobs status ` | Get current job status with visual progression bar, and what became of each action the job was given | +| `switchboard jobs wait [--timeout ]` | Block until a job completes via WebSocket subscription (no polling). Exits non-zero, naming the action and the reason, when the job's actions did not all apply | | `switchboard jobs watch ` | Stream job status updates via WebSocket with visual progression bar | | `switchboard sync touch ` | Create/update a sync channel | | `switchboard sync push ` | Push sync envelopes | diff --git a/specs.md b/specs.md index 3212817..be714d6 100644 --- a/specs.md +++ b/specs.md @@ -298,7 +298,7 @@ Maps to GraphQL: switchboard docs list [--drive ] [--type ] # Also supports --format svg/png/mermaid --out switchboard docs get [--drive ] [--state] [--out ] switchboard docs tree [] -switchboard docs create [--type ] [--name ] [--drive ] +switchboard docs create [--type ] [--name ] [--drive ] [--parent-folder ] switchboard docs delete [-y] switchboard docs rename switchboard docs parents @@ -890,6 +890,27 @@ switchboard jobs watch # Stream updates vi For long-running mutations dispatched via `mutateDocumentAsync` (e.g., `docs apply`). +**Per-action outcomes.** A reducer error or a permission denial does not fail the +job — the operation is written anyway and the job still reaches `READ_READY`. The +job's `result` reports what became of each submitted action, so `jobs status` and +`jobs wait` name the ones that did not apply: + +``` +$ switchboard jobs wait abc123 +Job abc123 finished: READ_READY (1/2 applied) + ✗ a2 [global#5]: reducer error: name is required +``` + +`jobs wait` (and therefore `docs apply --wait`) exits 1 in that case. `jobs status` +only reports, and exits 0. `--format json` prints the job object as the server sent +it, `result` included — nothing is reshaped. A server that does not report +per-action outcomes prints the plain status line and exits as before. + +The tally counts the actions that produced an operation — an action that produced +none has no entry to report. So the server's own `allApplied` can say the batch fell +short while every action it detailed applied; `jobs wait` says exactly that and still +exits 1, rather than inventing a count of actions it cannot name. + --- ### 14. Sync Channels @@ -1217,6 +1238,12 @@ $ switchboard docs get Acaldas --drive builders --state --format json | jq '.sta $ switchboard docs create --type powerhouse/invoice --name "Q1 Invoice" --drive my-drive --format json [{"id": "41d2cae7-...", "name": "Q1 Invoice", ...}] +# Create inside a folder (created at the root, then moved). A failed move +# exits non-zero but still prints the id, so a script never loses it: +$ switchboard docs create --type powerhouse/invoice --name "Q1 Invoice" \ + --drive my-drive --parent-folder 8f21c0de-... --format json +{"id": "41d2cae7-...", "folderMoveFailed": "..."} + # Mutate a document $ switchboard docs mutate 41d2cae7-... --op editInvoice --input '{"amount": 2000}' --format json diff --git a/src/cli/docs.rs b/src/cli/docs.rs index 491ba05..58dac41 100644 --- a/src/cli/docs.rs +++ b/src/cli/docs.rs @@ -994,6 +994,65 @@ pub fn print_tree(nodes: &[Value], parent: Option<&str>, indent: &str) { } } +/// Bounded: the server has just failed to answer within its full request +/// timeout, and this hint only decorates a message printed either way. +const CREATE_HINT_LOOKUP: std::time::Duration = std::time::Duration::from_secs(10); + +/// Guidance for a `createDocument` timeout: the request reached the server, +/// so the document may exist. A name match is never reported as proof — the +/// drive may simply have held one already. +async fn timed_out_create_hint( + client: &crate::graphql::GraphQLClient, + drive_id: &str, + name: &str, + parent_folder: Option<&str>, +) -> String { + let at_root = tokio::time::timeout(CREATE_HINT_LOOKUP, fetch_drive_nodes(client, drive_id)) + .await + .ok() + .and_then(|fetched| fetched.ok()) + .and_then(|(_, _, nodes)| root_document_named(&nodes, name)); + + match at_root { + Some(doc_id) => { + let placement = match parent_folder { + Some(folder) => format!( + " It is at the drive root, not in folder {folder}; if it is the one just \ + created, place it with \ + `switchboard docs move {doc_id} --from {drive_id} --to {folder}`." + ), + None => String::new(), + }; + format!( + "The create may well have taken effect: drive {drive_id} holds a document \ + named \"{name}\" at its root (id {doc_id}).{placement} Check that document \ + before re-running `docs create` — if it is the one just created, re-running \ + makes a duplicate." + ) + } + None => format!( + "The create may still have been applied. Check drive {drive_id} for a document \ + named \"{name}\" (`switchboard docs list --drive {drive_id}`) before re-running \ + `docs create`, or you will end up with a duplicate." + ), + } +} + +/// Root only: `createDocument` lands the document there, and the +/// `--parent-folder` move has not run yet. +fn root_document_named(nodes: &[Value], name: &str) -> Option { + nodes + .iter() + .find(|n| { + n["kind"].as_str() == Some("file") + && matches!(n["parentFolder"].as_str(), None | Some("")) + && n["name"] + .as_str() + .is_some_and(|candidate| candidate.eq_ignore_ascii_case(name)) + }) + .and_then(|n| n["id"].as_str().map(|id| id.to_string())) +} + async fn create( doc_type: Option, name: Option, @@ -1058,13 +1117,10 @@ async fn create( // namespaced createDocument mutation that atomically adds the doc to the drive. let namespace = cache.find_model(&doc_type).map(|m| m.namespace.clone()); - let mut vars = serde_json::json!({ + let vars = serde_json::json!({ "name": name, "parentIdentifier": drive_id, }); - if let Some(ref folder_id) = parent_folder { - vars["slug"] = serde_json::json!(folder_id); // parentFolder not directly supported - } let ns = match &namespace { Some(ns) if !ns.is_empty() => ns.clone(), @@ -1079,7 +1135,17 @@ async fn create( ns, ); - let create_data = client.query(&mutation, Some(&vars)).await?; + // A read timeout does not mean the create failed; re-running it is what + // produces the duplicate "(copy) 1" documents. + let create_data = match client.query(&mutation, Some(&vars)).await { + Ok(data) => data, + Err(e) if crate::graphql::is_timeout_error(&e) => { + let hint = + timed_out_create_hint(&client, &drive_id, &name, parent_folder.as_deref()).await; + return Err(e.context(hint)); + } + Err(e) => return Err(e), + }; let doc_id = create_data .get(ns.as_str()) @@ -1098,7 +1164,34 @@ async fn create( "targetParentFolder": folder_id, } }); - let _ = client.query(move_mutation, Some(&move_vars)).await; + if let Err(e) = client.query(move_mutation, Some(&move_vars)).await { + let placement = if crate::graphql::is_timeout_error(&e) { + format!( + "the move may or may not have taken effect — check whether it is in folder \ + {folder_id} or still at the root of drive {drive_id}, and if it is at the \ + root, place it with \ + `switchboard docs move {doc_id} --from {drive_id} --to {folder_id}`" + ) + } else { + format!( + "it is sitting at the root of drive {drive_id}. Place it with \ + `switchboard docs move {doc_id} --from {drive_id} --to {folder_id}`" + ) + }; + // Returning Err skips the JSON print below, leaving a script no + // way to recover the id of a document that does exist. + if matches!(format, OutputFormat::Json | OutputFormat::Raw) { + print_json(&serde_json::json!({ + "id": doc_id, + "folderMoveFailed": format!("{e:#}"), + })); + } + return Err(e.context(format!( + "Document \"{name}\" was created (id {doc_id}) but could not be moved into \ + folder {folder_id} — {placement}; do NOT re-run `docs create`, that makes a \ + duplicate." + ))); + } } let data = serde_json::json!({ "id": doc_id }); @@ -2087,6 +2180,46 @@ fn days_to_ymd(days: u64) -> (u64, u64, u64) { (y, m, d) } +#[cfg(test)] +mod create_recovery_tests { + use super::*; + use serde_json::json; + + #[test] + fn only_the_drive_root_is_a_candidate() { + let nodes = vec![ + json!({ "id": "folder-1", "kind": "folder", "name": "Invoices" }), + json!({ "id": "nested", "kind": "file", "name": "Q1 Invoice", + "parentFolder": "folder-1" }), + ]; + assert_eq!(root_document_named(&nodes, "Q1 Invoice"), None); + + let mut with_root = nodes.clone(); + with_root.push( + json!({ "id": "root-doc", "kind": "file", "name": "q1 invoice", + "parentFolder": null }), + ); + assert_eq!( + root_document_named(&with_root, "Q1 Invoice"), + Some("root-doc".to_string()) + ); + } + + #[test] + fn an_empty_parent_is_the_root_and_a_folder_is_never_a_match() { + let empty_parent = vec![json!({ "id": "d", "kind": "file", "name": "Notes", + "parentFolder": "" })]; + assert_eq!( + root_document_named(&empty_parent, "Notes"), + Some("d".to_string()) + ); + + let folder = vec![json!({ "id": "f", "kind": "folder", "name": "Notes", + "parentFolder": null })]; + assert_eq!(root_document_named(&folder, "Notes"), None); + } +} + #[cfg(test)] mod relationship_tests { use super::*; diff --git a/src/cli/guide.rs b/src/cli/guide.rs index 9d6e900..b54a44f 100644 --- a/src/cli/guide.rs +++ b/src/cli/guide.rs @@ -220,6 +220,7 @@ COMMANDS Hierarchical folder/file view switchboard docs create Interactive document creation switchboard docs create --type --name --drive + [--parent-folder ] Scripted creation switchboard docs delete [-y] Delete one or more documents (batch) switchboard docs rename Rename a document @@ -573,6 +574,25 @@ WEBSOCKET-BASED WAITING real-time status updates, completing as soon as the job finishes. This is more efficient and responsive than periodic polling. +ACTION OUTCOMES + + A reducer error or a permission denial does not fail the job: the + operation is still written and the job still reaches READ_READY. So + `jobs status` and `jobs wait` report what became of each action the + job was given, and `jobs wait` exits non-zero when they did not all + apply: + + Job abc123 finished: READ_READY (1/2 applied) + ✗ a2 [global#5]: reducer error: name is required + + The tally counts the actions that produced an operation. An action + that produced none has no entry, so a server can report the batch as + incomplete while every action it detailed applied — `jobs wait` says + so and still exits non-zero. + + Servers that do not report per-action outcomes print the plain + status line, unchanged. + STATUS PROGRESSION `jobs status`, `jobs watch`, and `jobs wait` display a visual diff --git a/src/cli/jobs.rs b/src/cli/jobs.rs index f50207a..6ebae96 100644 --- a/src/cli/jobs.rs +++ b/src/cli/jobs.rs @@ -1,4 +1,4 @@ -use anyhow::Result; +use anyhow::{Context, Result}; use clap::Subcommand; use serde_json::Value; @@ -58,19 +58,155 @@ fn status_progress(status: &str) -> &str { } } -async fn status(job_id: &str, format: OutputFormat, profile_name: Option<&str>) -> Result<()> { - let (_name, _profile, client) = helpers::setup(profile_name)?; +#[derive(Debug, PartialEq)] +enum Outcome { + Applied, + ReducerError(String), + Denied(String), + /// Never counted as applied. + Unknown(String), +} - // NOTE: JobInfo fields are `id status result error createdAt completedAt`. - // `result` is deliberately NOT selected: the server declares it non-null - // (JSONObject!) but resolves null even for completed jobs, so selecting it - // turns every jobStatus query into an error. - let query = format!( - r#"{{ jobStatus(jobId: "{id}") {{ id status error createdAt completedAt }} }}"#, - id = job_id.replace('"', r#"\""#) +#[derive(Debug, PartialEq)] +struct SubmittedAction { + action_id: String, + scope: String, + index: Option, + outcome: Outcome, +} + +impl SubmittedAction { + fn position(&self) -> String { + match (self.scope.as_str(), self.index) { + ("", None) => String::new(), + ("", Some(i)) => format!(" [#{i}]"), + (scope, None) => format!(" [{scope}]"), + (scope, Some(i)) => format!(" [{scope}#{i}]"), + } + } +} + +/// One entry per submitted action *that produced an operation* — an action +/// producing none has no entry, so the entries are not the submitted count. +#[derive(Debug, PartialEq)] +struct JobResult { + actions: Vec, + server_all_applied: bool, +} + +impl JobResult { + fn applied_count(&self) -> usize { + self.actions + .iter() + .filter(|a| a.outcome == Outcome::Applied) + .count() + } + + fn rejected_count(&self) -> usize { + self.actions.len() - self.applied_count() + } + + fn all_applied(&self) -> bool { + self.server_all_applied && self.rejected_count() == 0 + } + + fn tally(&self) -> String { + let counted = format!("{}/{} applied", self.applied_count(), self.actions.len()); + if self.server_all_applied || self.rejected_count() > 0 { + counted + } else { + format!("{counted}, but the server reports the batch as not fully applied") + } + } + + fn failure_lines(&self) -> Vec { + self.actions + .iter() + .filter_map(|a| { + let why = match &a.outcome { + Outcome::Applied => return None, + Outcome::ReducerError(message) => format!("reducer error: {message}"), + Outcome::Denied(reason) => format!("denied: {reason}"), + Outcome::Unknown(kind) => format!("unrecognized outcome '{kind}'"), + }; + Some(format!("✗ {}{}: {why}", a.action_id, a.position())) + }) + .collect() + } +} + +/// `None` when the server reports no per-action detail, which is never +/// success — pre-fix servers omit the field or send `{}`. +fn parse_job_result(job: &Value) -> Option { + let entries = job.pointer("/result/actions")?.as_array()?; + if entries.is_empty() { + return None; + } + + let actions: Vec = entries + .iter() + .map(|entry| SubmittedAction { + action_id: entry["actionId"] + .as_str() + .unwrap_or("(unknown action)") + .to_string(), + scope: entry["scope"].as_str().unwrap_or_default().to_string(), + index: entry["index"].as_i64(), + outcome: match entry["kind"].as_str().unwrap_or_default() { + "applied" => Outcome::Applied, + "reducer-error" => Outcome::ReducerError( + entry["message"] + .as_str() + .unwrap_or("(no message)") + .to_string(), + ), + "denied" => Outcome::Denied( + entry["reason"] + .as_str() + .unwrap_or("(no reason)") + .to_string(), + ), + other => Outcome::Unknown(other.to_string()), + }, + }) + .collect(); + + Some(JobResult { + actions, + server_all_applied: job["result"]["allApplied"].as_bool().unwrap_or(true), + }) +} + +fn rejects_job_result(err: &anyhow::Error) -> bool { + let message = format!("{err:#}"); + message.contains("JobInfo") && message.contains("result") +} + +/// Older Switchboards can't serve `JobInfo.result` — they resolve the +/// non-null field to null, or lack it entirely — so retry without it. +async fn query_job_status(client: &crate::graphql::GraphQLClient, job_id: &str) -> Result { + let id = job_id.replace('"', r#"\""#); + let with_result = format!( + r#"{{ jobStatus(jobId: "{id}") {{ id status result error createdAt completedAt }} }}"# ); + match client.query(&with_result, None).await { + Ok(data) => Ok(data), + Err(e) if crate::graphql::is_server_error(&e) && rejects_job_result(&e) => { + let legacy = format!( + r#"{{ jobStatus(jobId: "{id}") {{ id status error createdAt completedAt }} }}"# + ); + client.query(&legacy, None).await.with_context(|| { + format!("the server rejected the `result` selection ({e:#}), and the query without it also failed") + }) + } + Err(e) => Err(e), + } +} + +async fn status(job_id: &str, format: OutputFormat, profile_name: Option<&str>) -> Result<()> { + let (_name, _profile, client) = helpers::setup(profile_name)?; - let data = client.query(&query, None).await?; + let data = query_job_status(&client, job_id).await?; let job = &data["jobStatus"]; // Unknown job ids come back as a synthesized FAILED job with error @@ -89,6 +225,12 @@ async fn status(job_id: &str, format: OutputFormat, profile_name: Option<&str>) let s = job["status"].as_str().unwrap_or("-"); println!("Job: {}", job["id"].as_str().unwrap_or("-")); println!("Status: {}", status_progress(s)); + if let Some(summary) = parse_job_result(job) { + println!("Actions: {}", summary.tally()); + for line in summary.failure_lines() { + println!(" {line}"); + } + } if let Some(err) = job["error"].as_str().filter(|e| !e.is_empty()) { println!("Error: {err}"); } @@ -114,12 +256,7 @@ async fn wait( let (_name, profile, client) = helpers::setup(profile_name)?; // First, check if the job is already in a terminal state. - // (`result` is not selectable — see comment in status().) - let query = format!( - r#"{{ jobStatus(jobId: "{id}") {{ id status error }} }}"#, - id = job_id.replace('"', r#"\""#) - ); - if let Ok(data) = client.query(&query, None).await { + if let Ok(data) = query_job_status(&client, job_id).await { let job = &data["jobStatus"]; let status_str = job["status"].as_str().unwrap_or("UNKNOWN"); if matches!( @@ -205,35 +342,56 @@ async fn wait( } // WebSocket closed without terminal status — fall back to a final poll - let data = client - .query( - &format!( - r#"{{ jobStatus(jobId: "{id}") {{ id status error }} }}"#, - id = job_id_owned.replace('"', r#"\""#) - ), - None, - ) - .await?; + let data = query_job_status(&client, &job_id_owned).await?; let job = &data["jobStatus"]; let status_str = job["status"].as_str().unwrap_or("UNKNOWN"); print_job_result(job, &job_id_owned, status_str, format) } +/// A reducer error or denial does not fail the job, so a partly-rejected +/// batch would otherwise read as a clean success. Exit non-zero after +/// printing. fn print_job_result( job: &Value, job_id: &str, status_str: &str, format: OutputFormat, ) -> Result<()> { + let summary = parse_job_result(job); + match format { OutputFormat::Json | OutputFormat::Raw => print_json(job), _ => { - println!("Job {job_id} finished: {status_str}"); + match &summary { + Some(s) => println!("Job {job_id} finished: {status_str} ({})", s.tally()), + None => println!("Job {job_id} finished: {status_str}"), + } if let Some(err) = job["error"].as_str().filter(|e| !e.is_empty()) { println!("Error: {err}"); } + if let Some(s) = &summary { + for line in s.failure_lines() { + println!(" {line}"); + } + } } } + + if let Some(s) = summary + && !s.all_applied() + { + return match s.rejected_count() { + 0 => Err(anyhow::anyhow!( + "the server reports the batch as not fully applied, though every action it \ + detailed applied — at least one submitted action produced no operation" + )), + rejected => Err(anyhow::anyhow!( + "{rejected} of {} reported action(s) did not apply", + s.actions.len() + )), + }; + } + Ok(()) } @@ -295,3 +453,183 @@ async fn watch( ) .await } + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + fn job_with(result: Value) -> Value { + json!({ "id": "job-1", "status": "READ_READY", "error": null, "result": result }) + } + + #[test] + fn reports_every_submitted_action() { + let job = job_with(json!({ + "allApplied": false, + "actions": [ + { "actionId": "a1", "scope": "global", "index": 4, "kind": "applied" }, + { "actionId": "a2", "scope": "global", "index": 5, + "kind": "reducer-error", "message": "name is required" }, + { "actionId": "a3", "scope": "auth", "index": 2, + "kind": "denied", "reason": "no write grant" }, + ], + })); + + let summary = parse_job_result(&job).expect("result should parse"); + assert!(!summary.all_applied()); + assert_eq!(summary.tally(), "1/3 applied"); + assert_eq!( + summary.failure_lines(), + vec![ + "✗ a2 [global#5]: reducer error: name is required".to_string(), + "✗ a3 [auth#2]: denied: no write grant".to_string(), + ] + ); + } + + #[test] + fn a_clean_batch_applies_everything() { + let job = job_with(json!({ + "allApplied": true, + "actions": [{ "actionId": "a1", "scope": "global", "index": 0, "kind": "applied" }], + })); + + let summary = parse_job_result(&job).expect("result should parse"); + assert!(summary.all_applied()); + assert_eq!(summary.tally(), "1/1 applied"); + assert!(summary.failure_lines().is_empty()); + } + + #[test] + fn an_absent_result_yields_no_summary() { + let job = json!({ "id": "job-1", "status": "READ_READY", "error": null }); + assert_eq!(parse_job_result(&job), None); + } + + #[test] + fn a_null_result_yields_no_summary() { + assert_eq!(parse_job_result(&job_with(Value::Null)), None); + } + + #[test] + fn an_empty_result_object_yields_no_summary() { + assert_eq!(parse_job_result(&job_with(json!({}))), None); + assert_eq!(parse_job_result(&job_with(json!({ "actions": [] }))), None); + } + + #[test] + fn all_applied_is_derived_when_missing() { + let job = job_with(json!({ + "actions": [ + { "actionId": "a1", "scope": "global", "index": 0, "kind": "applied" }, + { "actionId": "a2", "scope": "global", "index": 1, + "kind": "denied", "reason": "nope" }, + ], + })); + assert!(!parse_job_result(&job).unwrap().all_applied()); + } + + #[test] + fn a_rejected_action_outvotes_all_applied() { + let job = job_with(json!({ + "allApplied": true, + "actions": [{ "actionId": "a1", "scope": "global", "index": 0, + "kind": "reducer-error", "message": "boom" }], + })); + assert!(!parse_job_result(&job).unwrap().all_applied()); + } + + #[test] + fn an_unknown_kind_is_not_success() { + let job = job_with(json!({ + "actions": [{ "actionId": "a1", "scope": "global", "index": 0, "kind": "deferred" }], + })); + let summary = parse_job_result(&job).unwrap(); + assert!(!summary.all_applied()); + assert_eq!( + summary.failure_lines(), + vec!["✗ a1 [global#0]: unrecognized outcome 'deferred'".to_string()] + ); + } + + #[test] + fn missing_fields_degrade_to_placeholders() { + let job = job_with(json!({ + "actions": [{ "kind": "reducer-error" }, { "kind": "denied", "scope": "global" }], + })); + let summary = parse_job_result(&job).unwrap(); + assert_eq!( + summary.failure_lines(), + vec![ + "✗ (unknown action): reducer error: (no message)".to_string(), + "✗ (unknown action) [global]: denied: (no reason)".to_string(), + ] + ); + } + + #[test] + fn a_partial_failure_is_an_error() { + let rejected = job_with(json!({ + "allApplied": false, + "actions": [ + { "actionId": "a1", "scope": "global", "index": 0, "kind": "applied" }, + { "actionId": "a2", "scope": "global", "index": 1, + "kind": "reducer-error", "message": "boom" }, + ], + })); + let err = print_job_result(&rejected, "job-1", "READ_READY", OutputFormat::Json) + .expect_err("a partial failure must not exit clean"); + assert!(err.to_string().contains("1 of 2 reported action(s)")); + + let unknown = json!({ "id": "job-1", "status": "READ_READY", "error": null }); + assert!(print_job_result(&unknown, "job-1", "READ_READY", OutputFormat::Json).is_ok()); + } + + #[test] + fn only_a_result_rejection_earns_a_second_round_trip() { + let non_null = anyhow::anyhow!( + "GraphQL errors:\n Cannot return null for non-nullable field JobInfo.result." + ); + assert!(rejects_job_result(&non_null)); + + let unknown_field = anyhow::anyhow!( + "HTTP 400 Bad Request: GraphQL errors:\n Cannot query field \"result\" on type \"JobInfo\"." + ); + assert!(rejects_job_result(&unknown_field)); + + for unrelated in [ + "GraphQL errors:\n Job not found", + "GraphQL errors:\n Unauthorized: token expired", + ] { + assert!( + !rejects_job_result(&anyhow::anyhow!("{unrelated}")), + "{unrelated}" + ); + } + } + + #[test] + fn a_verdict_with_nothing_to_point_at_is_still_a_failure() { + let job = job_with(json!({ + "allApplied": false, + "actions": [ + { "actionId": "a1", "scope": "global", "index": 0, "kind": "applied" }, + { "actionId": "a2", "scope": "global", "index": 1, "kind": "applied" }, + ], + })); + let summary = parse_job_result(&job).expect("a summary"); + assert!(!summary.all_applied()); + assert_eq!(summary.rejected_count(), 0); + assert_eq!( + summary.tally(), + "2/2 applied, but the server reports the batch as not fully applied" + ); + + let err = print_job_result(&job, "job-1", "READ_READY", OutputFormat::Json) + .expect_err("a batch the server calls incomplete must not exit clean"); + let message = err.to_string(); + assert!(message.contains("produced no operation"), "{message}"); + assert!(!message.contains("0 of"), "{message}"); + } +} diff --git a/src/graphql/client.rs b/src/graphql/client.rs index e2b0905..9c18c99 100644 --- a/src/graphql/client.rs +++ b/src/graphql/client.rs @@ -88,9 +88,12 @@ impl GraphQLClient { ); continue; } + Err(e) if e.is_timeout() => { + return Err(anyhow::Error::new(e).context(timed_out_message(&self.url))); + } Err(e) => { return Err( - anyhow::Error::new(e).context(format!("Failed to connect to {}", self.url)) + anyhow::Error::new(e).context(format!("Request to {} failed", self.url)) ); } } @@ -103,6 +106,20 @@ impl GraphQLClient { let status = response.status(); if !status.is_success() { let body = response.text().await.unwrap_or_default(); + if status == reqwest::StatusCode::GATEWAY_TIMEOUT + || status == reqwest::StatusCode::REQUEST_TIMEOUT + { + return Err( + anyhow::Error::new(MaybeApplied(format!("HTTP {status}: {body}"))) + .context(timed_out_message(&self.url)), + ); + } + // Validation errors come back non-2xx (HTTP 400 in yoga and Apollo). + if let Some(messages) = graphql_error_messages(&body) { + return Err( + anyhow::Error::new(ServerErrors(messages)).context(format!("HTTP {status}")) + ); + } bail!("HTTP {status}: {body}"); } @@ -112,8 +129,8 @@ impl GraphQLClient { .context("Failed to parse GraphQL response")?; if let Some(errors) = gql_response.errors.filter(|e| !e.is_empty()) { - let messages: Vec<_> = errors.iter().map(|e| e.message.as_str()).collect(); - bail!("GraphQL errors:\n {}", messages.join("\n ")); + let messages = errors.into_iter().map(|e| e.message).collect(); + return Err(anyhow::Error::new(ServerErrors(messages))); } gql_response.data.context("No data in GraphQL response") @@ -123,3 +140,148 @@ impl GraphQLClient { self.token.is_some() } } + +fn graphql_error_messages(body: &str) -> Option> { + let parsed: GraphQLResponse = serde_json::from_str(body).ok()?; + let errors = parsed.errors.filter(|e| !e.is_empty())?; + Some(errors.into_iter().map(|e| e.message).collect()) +} + +fn timed_out_message(url: &str) -> String { + format!( + "Timed out waiting for a response from {url}. \ + The request reached the server and the operation may have completed \ + — check before retrying." + ) +} + +/// A gateway's 504/408: reached the server, no answer in time. +#[derive(Debug)] +pub struct MaybeApplied(String); + +impl std::fmt::Display for MaybeApplied { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(&self.0) + } +} + +impl std::error::Error for MaybeApplied {} + +/// Errors the server answered with, as opposed to ones the transport produced. +#[derive(Debug)] +pub struct ServerErrors(pub Vec); + +impl std::fmt::Display for ServerErrors { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(f, "GraphQL errors:\n {}", self.0.join("\n ")) + } +} + +impl std::error::Error for ServerErrors {} + +pub fn is_server_error(err: &anyhow::Error) -> bool { + err.chain() + .any(|cause| cause.downcast_ref::().is_some()) +} + +/// True when the request reached the server but no answer came back in time, +/// so a mutation may have been applied anyway. +pub fn is_timeout_error(err: &anyhow::Error) -> bool { + err.chain().any(|cause| { + cause.downcast_ref::().is_some() + || cause + .downcast_ref::() + .is_some_and(|e| e.is_timeout() && !e.is_connect()) + }) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_server_error_is_told_from_a_transport_one() { + let err = anyhow::Error::new(ServerErrors(vec![ + "Cannot return null for non-nullable field JobInfo.result.".to_string(), + ])) + .context("jobStatus failed"); + assert!(is_server_error(&err)); + assert!(!is_timeout_error(&err)); + assert!(format!("{err:#}").contains("JobInfo.result")); + + let transport = anyhow::anyhow!("Failed to connect to http://localhost:4001/graphql"); + assert!(!is_server_error(&transport)); + } + + #[tokio::test] + async fn timeout_survives_context_wrapping() { + let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let addr = listener.local_addr().unwrap(); + // Accept but never respond, so the request times out mid-response. + tokio::spawn(async move { + let (stream, _) = listener.accept().await.unwrap(); + tokio::time::sleep(std::time::Duration::from_secs(30)).await; + drop(stream); + }); + + let client = Client::builder() + .timeout(std::time::Duration::from_millis(300)) + .build() + .unwrap(); + let err = client + .post(format!("http://{addr}/graphql")) + .body("{}") + .send() + .await + .unwrap_err(); + assert!(err.is_timeout()); + + let wrapped = anyhow::Error::new(err).context("Timed out waiting for a response"); + assert!(is_timeout_error(&wrapped)); + } + + #[tokio::test] + async fn connect_failure_is_not_a_timeout() { + // Bind then drop, so the port is free and the connect is refused. + let addr = { + let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + listener.local_addr().unwrap() + }; + + let client = Client::builder() + .timeout(std::time::Duration::from_secs(5)) + .build() + .unwrap(); + let err = client + .post(format!("http://{addr}/graphql")) + .body("{}") + .send() + .await + .unwrap_err(); + + let wrapped = anyhow::Error::new(err).context("Failed to connect"); + assert!(!is_timeout_error(&wrapped)); + } + + // A gateway timeout is a successful HTTP exchange: no `reqwest::Error` in the chain. + #[test] + fn a_gateway_timeout_is_a_maybe_applied_timeout() { + let err = anyhow::Error::new(MaybeApplied("HTTP 504 Gateway Timeout: ".to_string())) + .context(timed_out_message("http://localhost:4001/graphql")); + assert!(is_timeout_error(&err)); + assert!(!is_server_error(&err)); + assert!(format!("{err:#}").contains("may have completed")); + } + + #[test] + fn a_non_2xx_graphql_body_is_a_server_error() { + let body = + r#"{"errors":[{"message":"Cannot query field \"result\" on type \"JobInfo\"."}]}"#; + let messages = graphql_error_messages(body).expect("a GraphQL error body"); + assert_eq!(messages.len(), 1); + assert!(messages[0].contains("JobInfo")); + + assert!(graphql_error_messages("502 Bad Gateway").is_none()); + assert!(graphql_error_messages(r#"{"data":{"x":1}}"#).is_none()); + } +} diff --git a/src/graphql/mod.rs b/src/graphql/mod.rs index 3a83347..fc6da6d 100644 --- a/src/graphql/mod.rs +++ b/src/graphql/mod.rs @@ -2,5 +2,5 @@ mod client; pub mod introspection; pub mod websocket; -pub use client::GraphQLClient; +pub use client::{GraphQLClient, is_server_error, is_timeout_error}; pub use introspection::IntrospectionCache;