From 8da9ef340e050631a2e6a3ec03689718145cc786 Mon Sep 17 00:00:00 2001 From: Benjamin Jordan Date: Tue, 15 Sep 2026 09:54:18 -0500 Subject: [PATCH 01/10] fix(client): a read timeout is not a connect failure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A request that connected fine and whose mutation the server fully executed was reported as "Failed to connect to : operation timed out". The connection succeeded and the work may be done — saying otherwise sends the caller straight into a retry that double-applies. Split the timeout arm out: it now says the request reached the server and the operation may have completed, so check before retrying. The no-retry-on-timeout policy is unchanged. The catch-all arm stops claiming "Failed to connect" for errors that are neither. `is_timeout_error` lets callers of mutating operations key recovery off the same distinction; tests cover that it survives `.context()` wrapping. Co-Authored-By: Claude Opus 5 --- src/graphql/client.rs | 83 ++++++++++++++++++++++++++++++++++++++++++- src/graphql/mod.rs | 2 +- 2 files changed, 83 insertions(+), 2 deletions(-) diff --git a/src/graphql/client.rs b/src/graphql/client.rs index e2b0905..a617722 100644 --- a/src/graphql/client.rs +++ b/src/graphql/client.rs @@ -88,9 +88,21 @@ impl GraphQLClient { ); continue; } + Err(e) if e.is_timeout() => { + // The connection succeeded; only the response timed out. + // The server received the request and may have executed + // it, so this is never retried and must not be reported + // as a connection failure. + return Err(anyhow::Error::new(e).context(format!( + "Timed out waiting for a response from {}. \ + The request reached the server and the operation may have completed \ + — check before retrying.", + 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)) ); } } @@ -123,3 +135,72 @@ impl GraphQLClient { self.token.is_some() } } + +/// True when `err` was caused by a request timing out after the connection +/// was established — the server received the request and may have executed +/// it. Callers of mutating operations use this to report a maybe-applied +/// write instead of a plain failure. +pub fn is_timeout_error(err: &anyhow::Error) -> bool { + err.chain().any(|cause| { + cause + .downcast_ref::() + .is_some_and(|e| e.is_timeout() && !e.is_connect()) + }) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// A read timeout must stay recognizable after `.context()` wrapping — + /// `docs create` keys its "the document may exist" recovery off this. + #[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)); + } +} diff --git a/src/graphql/mod.rs b/src/graphql/mod.rs index 3a83347..1703a8a 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_timeout_error}; pub use introspection::IntrospectionCache; From dfe2fe5aa96dde072fed7620b5699ff861163dd9 Mon Sep 17 00:00:00 2001 From: Benjamin Jordan Date: Tue, 15 Sep 2026 09:54:27 -0500 Subject: [PATCH 02/10] fix(docs): stop losing the document when `create --parent-folder` half-succeeds MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `docs create --parent-folder` is two server calls: the namespaced createDocument, then a separate moveNode that actually places the document. Both failure paths left an orphan at the drive root: - moveNode's result was thrown away with `let _ = ...`, so a failing placement printed "✓ Document created" and the folder it never reached. Now it errors with the document id and the exact `docs move` that finishes the job. - A createDocument timeout aborted the command, but the server had often already created the document. The error now looks the drive up by name and reports the id if it is there — and either way says not to re-run create, which is what produces the duplicates. Also drops the `vars["slug"]` assignment: the mutation declares only $name and $parentIdentifier, so GraphQL variable coercion ignored it. It never placed anything. Co-Authored-By: Claude Opus 5 --- src/cli/docs.rs | 77 +++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 71 insertions(+), 6 deletions(-) diff --git a/src/cli/docs.rs b/src/cli/docs.rs index 491ba05..32c50e2 100644 --- a/src/cli/docs.rs +++ b/src/cli/docs.rs @@ -994,6 +994,55 @@ pub fn print_tree(nodes: &[Value], parent: Option<&str>, indent: &str) { } } +/// Build the guidance appended to a `createDocument` timeout. +/// +/// The request reached the server, so the document may exist. Look for one +/// with the name just attempted so the error can name its id instead of +/// leaving the user to guess between "retry" and "clean up". +async fn timed_out_create_hint( + client: &crate::graphql::GraphQLClient, + drive_id: &str, + name: &str, + parent_folder: Option<&str>, +) -> String { + let existing = fetch_drive_nodes(client, drive_id) + .await + .ok() + .and_then(|(_, _, nodes)| { + nodes + .iter() + .find(|n| { + n["kind"].as_str() == Some("file") + && n["name"] + .as_str() + .is_some_and(|n| n.eq_ignore_ascii_case(name)) + }) + .and_then(|n| n["id"].as_str().map(|id| id.to_string())) + }); + + match existing { + Some(doc_id) => { + let placement = match parent_folder { + Some(folder) => format!( + " It is at the drive root, not in folder {folder}; place it with \ + `switchboard docs move {doc_id} --from {drive_id} --to {folder}`." + ), + None => String::new(), + }; + format!( + "The create DID take effect: drive {drive_id} now holds a document named \ + \"{name}\" (id {doc_id}).{placement} Do NOT re-run `docs create` — that \ + 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." + ), + } +} + async fn create( doc_type: Option, name: Option, @@ -1058,13 +1107,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 +1125,19 @@ async fn create( ns, ); - let create_data = client.query(&mutation, Some(&vars)).await?; + // A read timeout here does NOT mean the create failed — the server may + // have executed it. Re-running `docs create` is what produces the + // duplicate "(copy) 1" documents, so instead look the document up by name + // and tell the user what to do with it. + 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 +1156,14 @@ 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 { + return Err(e.context(format!( + "Document \"{name}\" was created (id {doc_id}) but could not be moved into \ + folder {folder_id} — it is sitting at the root of drive {drive_id}. \ + Place it with `switchboard docs move {doc_id} --from {drive_id} --to {folder_id}`; \ + do NOT re-run `docs create`, that makes a duplicate." + ))); + } } let data = serde_json::json!({ "id": doc_id }); From 6698a9308e701b2b143d47cef75dd35dc4adbd05 Mon Sep 17 00:00:00 2001 From: Benjamin Jordan Date: Tue, 15 Sep 2026 11:32:16 -0500 Subject: [PATCH 03/10] fix(client): tell a server's errors from the transport's MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A caller that wants to retry a query with a narrower selection — because an older Switchboard rejects a field this CLI now asks for — had no way to ask whether the server answered at all. The GraphQL errors arrived as a bare `bail!`, indistinguishable from a refused connection, so the only safe retry was a blind one that dials a dead host twice. Carry them in a `ServerErrors` type instead, matching `is_timeout_error`'s existing shape, with the same rendering as before. Co-Authored-By: Claude Opus 5 --- src/graphql/client.rs | 42 ++++++++++++++++++++++++++++++++++++++++-- src/graphql/mod.rs | 2 +- 2 files changed, 41 insertions(+), 3 deletions(-) diff --git a/src/graphql/client.rs b/src/graphql/client.rs index a617722..ed30858 100644 --- a/src/graphql/client.rs +++ b/src/graphql/client.rs @@ -124,8 +124,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") @@ -136,6 +136,27 @@ impl GraphQLClient { } } +/// Errors the server answered with, as opposed to ones the transport +/// produced. A schema mismatch — an older Switchboard rejecting a field this +/// CLI selects — lands here, which lets a caller retry with a narrower +/// selection instead of retrying a dead connection. +#[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 {} + +/// True when the server answered with GraphQL errors. +pub fn is_server_error(err: &anyhow::Error) -> bool { + err.chain() + .any(|cause| cause.downcast_ref::().is_some()) +} + /// True when `err` was caused by a request timing out after the connection /// was established — the server received the request and may have executed /// it. Callers of mutating operations use this to report a maybe-applied @@ -152,6 +173,23 @@ pub fn is_timeout_error(err: &anyhow::Error) -> bool { mod tests { use super::*; + /// An older Switchboard rejecting `JobInfo.result` must stay recognizable + /// after `.context()` wrapping — `jobs status` keys its narrower-selection + /// retry off this, and must not retry a dead connection that way. + #[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)); + } + /// A read timeout must stay recognizable after `.context()` wrapping — /// `docs create` keys its "the document may exist" recovery off this. #[tokio::test] diff --git a/src/graphql/mod.rs b/src/graphql/mod.rs index 1703a8a..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, is_timeout_error}; +pub use client::{GraphQLClient, is_server_error, is_timeout_error}; pub use introspection::IntrospectionCache; From 107cffd16472dfc3613d5008cafec3414f848e83 Mon Sep 17 00:00:00 2001 From: Benjamin Jordan Date: Tue, 15 Sep 2026 11:32:26 -0500 Subject: [PATCH 04/10] fix(jobs): report what became of each action a job was given MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A reducer error or a denial does not fail the job: the operation is still written, the rest of the batch still applies, and the job still reaches READ_READY with no error. So `jobs wait` printed `READ_READY` and exited 0 for a batch one of whose actions was rejected, and `docs apply --wait` inherited exactly that — the caller was told its write succeeded when part of it had been thrown away. The job now carries the per-action outcomes (powerhouse#3027), so select and report them: a tally on the status line, a line naming each action that did not apply and why, and a non-zero exit from `jobs wait` when they did not all apply. `jobs status` reports the same detail but still exits 0 — it is asking a question, not performing a write. JSON output is the job object as the server sent it, `result` included; nothing is reshaped. Against a Switchboard without that fix there is nothing to report, and nothing to report is not success: absent, null and `{}` results all fall back to the plain status line and the old exit code. `jobStatus` there declares `result` non-null and resolves it null, which errors the whole selection — hence the workaround this replaces — so that one query retries without the field, but only when the server is the one that answered. Co-Authored-By: Claude Opus 5 --- README.md | 6 +- specs.md | 16 +++ src/cli/docs.rs | 3 + src/cli/guide.rs | 14 ++ src/cli/jobs.rs | 358 +++++++++++++++++++++++++++++++++++++++++++---- 5 files changed, 368 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 87d348f..21fe4d8 100644 --- a/README.md +++ b/README.md @@ -211,7 +211,7 @@ history. Aborts if the destination already has a drive with the same slug. | `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..ab2ab5c 100644 --- a/specs.md +++ b/specs.md @@ -890,6 +890,22 @@ 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. + --- ### 14. Sync Channels diff --git a/src/cli/docs.rs b/src/cli/docs.rs index 32c50e2..15b96f2 100644 --- a/src/cli/docs.rs +++ b/src/cli/docs.rs @@ -1806,6 +1806,9 @@ async fn apply( "documentIdentifier": resolved_id, "actions": actions, }); + // `result` is not selected: the job has just been submitted, so it + // has none, and older servers declare the field non-null and error + // the whole mutation over it. `--wait` reads it off `jobStatus`. let data = client .query( "mutation($documentIdentifier: String!, $actions: [ActionInput!]!) { \ diff --git a/src/cli/guide.rs b/src/cli/guide.rs index 9d6e900..8317bc5 100644 --- a/src/cli/guide.rs +++ b/src/cli/guide.rs @@ -573,6 +573,20 @@ 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 + + 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..66bccf0 100644 --- a/src/cli/jobs.rs +++ b/src/cli/jobs.rs @@ -58,19 +58,153 @@ 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)?; +/// What became of one action the caller submitted. +#[derive(Debug, PartialEq)] +enum Outcome { + Applied, + ReducerError(String), + Denied(String), + /// A kind this CLI does not know. 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}]"), + } + } +} + +/// `JobInfo.result`: one entry per submitted action that produced an +/// operation, plus whether every one of them applied. +#[derive(Debug, PartialEq)] +struct JobResult { + actions: Vec, + all_applied: bool, +} + +impl JobResult { + fn applied_count(&self) -> usize { + self.actions + .iter() + .filter(|a| a.outcome == Outcome::Applied) + .count() + } + + fn tally(&self) -> String { + format!("{}/{} applied", self.applied_count(), self.actions.len()) + } + + /// One line per action that did not apply, saying which and why. + 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() + } +} + +/// Read `result` off a `JobInfo` or a `jobChanges` event. +/// +/// Returns `None` when there is no per-action information to report, which is +/// what every Switchboard before the job-result fix gives: `jobStatus` omits +/// the field and `jobChanges` sends `{}`, because its `result` was declared +/// non-null. Absence is never reported as success — the caller falls back to +/// the plain status line. +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(); + + // The per-action detail is authoritative: a summary claiming everything + // applied cannot outvote an entry that says otherwise. + let all_applied = job["result"]["allApplied"].as_bool().unwrap_or(true) + && actions.iter().all(|a| a.outcome == Outcome::Applied); + + Some(JobResult { + actions, + all_applied, + }) +} + +/// Query `jobStatus`, selecting `result`. +/// +/// `JobInfo.result` carries what became of each submitted action. Older +/// Switchboards declare it `JSONObject!` and resolve it null, which nullifies +/// the whole selection and errors the query; fall back to the result-less +/// selection there, so this CLI keeps working against a server that simply has +/// no per-action detail to give. Only a server-answered error triggers the +/// retry — a dead connection is reported as-is rather than dialled twice. +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) => { + let legacy = format!( + r#"{{ jobStatus(jobId: "{id}") {{ id status error createdAt completedAt }} }}"# + ); + client.query(&legacy, None).await.map_err(|_| e) + } + 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 +223,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 +254,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!( @@ -146,6 +281,10 @@ async fn wait( .trim_start_matches("http://"); let ws_url = format!("{ws_scheme}://{host}/graphql/subscriptions"); + // `result` is safe to select here on every server: the pre-fix ones declare + // `JobChangeEvent.result` non-null and publish `{}` rather than null, which + // `parse_job_result` reads as "no per-action detail". It was only + // `jobStatus` that errored on it. let subscription = format!( r#"subscription {{ jobChanges(jobId: "{id}") {{ jobId status result error }} }}"#, id = job_id.replace('"', r#"\""#) @@ -205,35 +344,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) } +/// Print a finished job, then fail if the actions it was given did not all +/// apply. +/// +/// A reducer error or a denial does not fail the job — the operation is still +/// written, the job still reaches READ_READY — so the status line alone would +/// report a partly-rejected batch as a clean success. Exit non-zero instead, +/// after printing, so both a human and a script see it. JSON output is the job +/// object as the server sent it, `result` included: nothing is reshaped. 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 + { + let rejected = s.actions.len() - s.applied_count(); + anyhow::bail!( + "{rejected} of {} submitted action(s) did not apply", + s.actions.len() + ); + } + Ok(()) } @@ -295,3 +455,149 @@ 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()); + } + + /// A pre-fix Switchboard cannot select `result` on `jobStatus` at all, so + /// the field is simply absent. That is missing information, not success. + #[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); + } + + /// What a pre-fix server publishes on the `jobChanges` subscription, where + /// `result` is declared non-null: an empty object standing in for nothing. + #[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); + } + + /// `allApplied` is derived when the server omits it, so an older shape of + /// the field cannot turn a rejection into a success. + #[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); + } + + /// And a summary that contradicts its own entries does not get the benefit + /// of the doubt. + #[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); + } + + /// A kind added after this CLI shipped is reported verbatim, never counted + /// as 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()] + ); + } + + /// Missing detail must not panic or read as success. + #[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(), + ] + ); + } + + /// A partly-rejected batch exits non-zero; the same job with no result + /// reported keeps today's exit code. + #[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 submitted 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()); + } +} From 3818d395d77506c3f7822ceaf27a004214289410 Mon Sep 17 00:00:00 2001 From: Benjamin Jordan Date: Tue, 15 Sep 2026 12:04:42 -0500 Subject: [PATCH 05/10] fix(client): a 504 is a maybe-applied timeout, not an opaque HTTP error MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A gateway timeout is a successful HTTP exchange, so it fell through to `bail!("HTTP {status}: {body}")` and `is_timeout_error` said no — there is no `reqwest::Error` in that chain. That is the most common way a slow upstream surfaces on a hosted Switchboard, and it meant `docs create` printed a bare `HTTP 504` with none of the "the document may exist, do not re-run" guidance the read-timeout path had just been given. Classify 504/408 as maybe-applied, sharing one wording with the socket timeout. While in the same branch: a GraphQL error can arrive with a non-2xx status — a query naming a field the schema lacks fails validation, which yoga and Apollo answer with HTTP 400. Parse the body and report it as `ServerErrors` so callers keying a narrower-selection fallback off `is_server_error` see it, instead of an opaque HTTP failure. Co-Authored-By: Claude Opus 5 --- src/graphql/client.rs | 101 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 91 insertions(+), 10 deletions(-) diff --git a/src/graphql/client.rs b/src/graphql/client.rs index ed30858..a308592 100644 --- a/src/graphql/client.rs +++ b/src/graphql/client.rs @@ -93,12 +93,7 @@ impl GraphQLClient { // The server received the request and may have executed // it, so this is never retried and must not be reported // as a connection failure. - return Err(anyhow::Error::new(e).context(format!( - "Timed out waiting for a response from {}. \ - The request reached the server and the operation may have completed \ - — check before retrying.", - self.url - ))); + return Err(anyhow::Error::new(e).context(timed_out_message(&self.url))); } Err(e) => { return Err( @@ -115,6 +110,29 @@ impl GraphQLClient { let status = response.status(); if !status.is_success() { let body = response.text().await.unwrap_or_default(); + // 504/408 are the other half of "reached the server, no answer + // came back in time" — a gateway saying so on the upstream's + // behalf. The operation may have executed, exactly as with a read + // timeout, so it must carry the same warning and not read as a + // plain HTTP failure. + 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)), + ); + } + // A GraphQL error can arrive with a non-2xx status: a query that + // names a field the schema lacks fails validation, which both + // graphql-yoga and Apollo answer with HTTP 400. The server did + // answer, so report it as a server error — callers key their + // narrower-selection fallbacks off that. + if let Some(messages) = graphql_error_messages(&body) { + return Err( + anyhow::Error::new(ServerErrors(messages)).context(format!("HTTP {status}")) + ); + } bail!("HTTP {status}: {body}"); } @@ -136,6 +154,38 @@ impl GraphQLClient { } } +/// The GraphQL error messages carried by a response body, if it is a GraphQL +/// error response at all. A gateway's HTML error page is not. +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()) +} + +/// The one wording for "the request reached the server and no answer came +/// back in time", shared by the read-timeout and gateway-timeout paths. +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 request that reached the server with no answer coming back in time, +/// reported by a gateway rather than by the socket. Carries the same +/// maybe-applied warning as a read timeout. +#[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. A schema mismatch — an older Switchboard rejecting a field this /// CLI selects — lands here, which lets a caller retry with a narrower @@ -158,14 +208,16 @@ pub fn is_server_error(err: &anyhow::Error) -> bool { } /// True when `err` was caused by a request timing out after the connection -/// was established — the server received the request and may have executed +/// was established — whether the socket gave up waiting or a gateway answered +/// 504/408. Either way the server received the request and may have executed /// it. Callers of mutating operations use this to report a maybe-applied /// write instead of a plain failure. pub fn is_timeout_error(err: &anyhow::Error) -> bool { err.chain().any(|cause| { - cause - .downcast_ref::() - .is_some_and(|e| e.is_timeout() && !e.is_connect()) + cause.downcast_ref::().is_some() + || cause + .downcast_ref::() + .is_some_and(|e| e.is_timeout() && !e.is_connect()) }) } @@ -241,4 +293,33 @@ mod tests { let wrapped = anyhow::Error::new(err).context("Failed to connect"); assert!(!is_timeout_error(&wrapped)); } + + /// A gateway timeout is a successful HTTP exchange, so nothing in the + /// error chain is a `reqwest::Error` — it still has to reach the + /// maybe-applied path that stops `docs create` being re-run. + #[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")); + } + + /// A schema with no `JobInfo.result` fails *validation*, which yoga and + /// Apollo answer with HTTP 400 — `jobs status` must still see a server + /// error there, not an opaque HTTP failure. + #[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")); + + // A gateway's HTML error page is not a GraphQL answer. + assert!(graphql_error_messages("502 Bad Gateway").is_none()); + // Neither is a 200-shaped body with no errors. + assert!(graphql_error_messages(r#"{"data":{"x":1}}"#).is_none()); + } } From 5dc2fdc0d1b6a1202efd7cf42168847f2ac7edd3 Mon Sep 17 00:00:00 2001 From: Benjamin Jordan Date: Tue, 15 Sep 2026 12:05:47 -0500 Subject: [PATCH 06/10] fix(jobs): stop reporting "0 of N submitted action(s) did not apply" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `result.actions` holds one entry per submitted action *that produced an operation* — an action producing none has no entry. So `allApplied: false` can arrive over a set of entries that all applied, and the rejected count, computed as `actions.len() - applied_count()`, came out zero: a job printed a clean-looking `(2/2 applied)` and then bailed with "0 of 2 submitted action(s) did not apply". Both numbers were wrong and the message was nonsense. Keep the server's verdict separate from the entries, say so in the tally when it is the only thing objecting, and word the failure off what is actually known. The count is now labelled "reported action(s)", since the entries were never the submitted count. Co-Authored-By: Claude Opus 5 --- specs.md | 5 +++ src/cli/guide.rs | 5 +++ src/cli/jobs.rs | 100 +++++++++++++++++++++++++++++++++++++---------- 3 files changed, 89 insertions(+), 21 deletions(-) diff --git a/specs.md b/specs.md index ab2ab5c..f285822 100644 --- a/specs.md +++ b/specs.md @@ -906,6 +906,11 @@ only reports, and exits 0. `--format json` prints the job object as the server s 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 diff --git a/src/cli/guide.rs b/src/cli/guide.rs index 8317bc5..68f121d 100644 --- a/src/cli/guide.rs +++ b/src/cli/guide.rs @@ -584,6 +584,11 @@ ACTION OUTCOMES 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. diff --git a/src/cli/jobs.rs b/src/cli/jobs.rs index 66bccf0..bf35deb 100644 --- a/src/cli/jobs.rs +++ b/src/cli/jobs.rs @@ -88,11 +88,15 @@ impl SubmittedAction { } /// `JobInfo.result`: one entry per submitted action that produced an -/// operation, plus whether every one of them applied. +/// operation, plus the server's own verdict on the batch. #[derive(Debug, PartialEq)] struct JobResult { actions: Vec, - all_applied: bool, + /// The server's `allApplied`, kept separate from the entries. False here + /// with every entry applied is not a contradiction: an action that + /// produced no operation has no entry at all, so the entries cannot + /// account for it. + server_all_applied: bool, } impl JobResult { @@ -103,8 +107,28 @@ impl JobResult { .count() } + /// Entries that say the action did not apply. Never the whole story — + /// see `server_all_applied`. + fn rejected_count(&self) -> usize { + self.actions.len() - self.applied_count() + } + + /// The per-action detail is authoritative in one direction only: an entry + /// that says "did not apply" outvotes a summary claiming success, and the + /// summary outvotes entries that are all clean. + fn all_applied(&self) -> bool { + self.server_all_applied && self.rejected_count() == 0 + } + fn tally(&self) -> String { - format!("{}/{} applied", self.applied_count(), self.actions.len()) + let counted = format!("{}/{} applied", self.applied_count(), self.actions.len()); + // Every action the server detailed applied, yet it says the batch did + // not. Printing the bare count here would read as a clean success. + if self.server_all_applied || self.rejected_count() > 0 { + counted + } else { + format!("{counted}, but the server reports the batch as not fully applied") + } } /// One line per action that did not apply, saying which and why. @@ -165,14 +189,10 @@ fn parse_job_result(job: &Value) -> Option { }) .collect(); - // The per-action detail is authoritative: a summary claiming everything - // applied cannot outvote an entry that says otherwise. - let all_applied = job["result"]["allApplied"].as_bool().unwrap_or(true) - && actions.iter().all(|a| a.outcome == Outcome::Applied); - Some(JobResult { actions, - all_applied, + // Absent means the server has no verdict to give; the entries decide. + server_all_applied: job["result"]["allApplied"].as_bool().unwrap_or(true), }) } @@ -385,13 +405,22 @@ fn print_job_result( } if let Some(s) = summary - && !s.all_applied + && !s.all_applied() { - let rejected = s.actions.len() - s.applied_count(); - anyhow::bail!( - "{rejected} of {} submitted action(s) did not apply", - s.actions.len() - ); + // `actions` holds only the submitted actions that produced an + // operation, so it cannot be used as the submitted count. When the + // server's verdict is the only thing objecting, say that instead of + // reporting "0 of N did not apply". + 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(()) @@ -479,7 +508,7 @@ mod tests { })); let summary = parse_job_result(&job).expect("result should parse"); - assert!(!summary.all_applied); + assert!(!summary.all_applied()); assert_eq!(summary.tally(), "1/3 applied"); assert_eq!( summary.failure_lines(), @@ -498,7 +527,7 @@ mod tests { })); let summary = parse_job_result(&job).expect("result should parse"); - assert!(summary.all_applied); + assert!(summary.all_applied()); assert_eq!(summary.tally(), "1/1 applied"); assert!(summary.failure_lines().is_empty()); } @@ -535,7 +564,7 @@ mod tests { "kind": "denied", "reason": "nope" }, ], })); - assert!(!parse_job_result(&job).unwrap().all_applied); + assert!(!parse_job_result(&job).unwrap().all_applied()); } /// And a summary that contradicts its own entries does not get the benefit @@ -547,7 +576,7 @@ mod tests { "actions": [{ "actionId": "a1", "scope": "global", "index": 0, "kind": "reducer-error", "message": "boom" }], })); - assert!(!parse_job_result(&job).unwrap().all_applied); + assert!(!parse_job_result(&job).unwrap().all_applied()); } /// A kind added after this CLI shipped is reported verbatim, never counted @@ -558,7 +587,7 @@ mod tests { "actions": [{ "actionId": "a1", "scope": "global", "index": 0, "kind": "deferred" }], })); let summary = parse_job_result(&job).unwrap(); - assert!(!summary.all_applied); + assert!(!summary.all_applied()); assert_eq!( summary.failure_lines(), vec!["✗ a1 [global#0]: unrecognized outcome 'deferred'".to_string()] @@ -595,9 +624,38 @@ mod tests { })); 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 submitted action(s)")); + 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()); } + + /// An action that produced no operation gets no entry, so the server can + /// say `allApplied: false` over a set of entries that all applied. The + /// entries must not be mistaken for the submitted count: doing so + /// printed a clean `2/2 applied` and then bailed with the nonsense + /// "0 of 2 submitted action(s) did not apply". + #[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}"); + } } From b60eeb1654e707de28b7f9363d44a856cbb7d0e7 Mon Sep 17 00:00:00 2001 From: Benjamin Jordan Date: Tue, 15 Sep 2026 12:06:29 -0500 Subject: [PATCH 07/10] fix(jobs): fall back to the result-less query only when `result` is why MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `is_server_error` fires on any GraphQL error, so a bad job id or an expired token sent `jobs status` round the loop twice — and `map_err(|_| e)` then threw the second, live failure away in favour of the first. Narrow the guard to errors that actually name `JobInfo.result`, and report the fallback's own error with the first one as context instead of discarding it. This also picks up the case the guard used to miss entirely: a schema with no `JobInfo.result` at all fails validation rather than resolution, which arrives as HTTP 400. Now that the client classifies such a body as a server error, those servers get the fallback the doc comment always promised them. Co-Authored-By: Claude Opus 5 --- src/cli/jobs.rs | 56 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 49 insertions(+), 7 deletions(-) diff --git a/src/cli/jobs.rs b/src/cli/jobs.rs index bf35deb..26cdde4 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; @@ -196,14 +196,28 @@ fn parse_job_result(job: &Value) -> Option { }) } +/// True when the server's complaint is specifically about `JobInfo.result`: +/// an older Switchboard resolving its non-null `result` to null, or a schema +/// with no such field, which fails validation instead. Both name the field. +/// +/// Anything else — a bad job id, an expired token — is the caller's to see. +/// Retrying those costs a second round trip and then reports whichever of the +/// two failures is less accurate. +fn rejects_job_result(err: &anyhow::Error) -> bool { + let message = format!("{err:#}"); + message.contains("JobInfo") && message.contains("result") +} + /// Query `jobStatus`, selecting `result`. /// /// `JobInfo.result` carries what became of each submitted action. Older /// Switchboards declare it `JSONObject!` and resolve it null, which nullifies -/// the whole selection and errors the query; fall back to the result-less -/// selection there, so this CLI keeps working against a server that simply has -/// no per-action detail to give. Only a server-answered error triggers the -/// retry — a dead connection is reported as-is rather than dialled twice. +/// the whole selection and errors the query; older ones still have no such +/// field, which fails validation (HTTP 400). Fall back to the result-less +/// selection in both cases, so this CLI keeps working against a server that +/// simply has no per-action detail to give. Only a server answering about +/// that field triggers the retry — a dead connection is reported as-is rather +/// than dialled twice. async fn query_job_status(client: &crate::graphql::GraphQLClient, job_id: &str) -> Result { let id = job_id.replace('"', r#"\""#); let with_result = format!( @@ -211,11 +225,13 @@ async fn query_job_status(client: &crate::graphql::GraphQLClient, job_id: &str) ); match client.query(&with_result, None).await { Ok(data) => Ok(data), - Err(e) if crate::graphql::is_server_error(&e) => { + 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.map_err(|_| e) + 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), } @@ -630,6 +646,32 @@ mod tests { assert!(print_job_result(&unknown, "job-1", "READ_READY", OutputFormat::Json).is_ok()); } + /// The `result`-less retry exists for one server bug. Spending a second + /// round trip on a bad job id or an expired token only buys a second + /// failure, and the first one is then thrown away. + #[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}" + ); + } + } + /// An action that produced no operation gets no entry, so the server can /// say `allApplied: false` over a set of entries that all applied. The /// entries must not be mistaken for the submitted count: doing so From 6b7c9ffe3a580ea39c87e8a12587a26e3d553d76 Mon Sep 17 00:00:00 2001 From: Benjamin Jordan Date: Tue, 15 Sep 2026 12:07:34 -0500 Subject: [PATCH 08/10] fix(docs): don't call a pre-existing document proof the create landed MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit After a `createDocument` timeout the recovery lookup matched any node with `kind == "file"` and the same name, anywhere in the drive. A drive that already held a document called "Q1 Invoice" — in any folder — got told "The create DID take effect ... Do NOT re-run `docs create`", naming an unrelated id, when the create may never have run at all. That is a confident false positive that suppresses the correct retry. Search only the drive root, which is where `createDocument` puts the document and where it still is until the `--parent-folder` move runs, and report the match as something to check rather than as proof. The lookup is also bounded at 10s now: it was issued through the same 120s client against the server that had just failed to answer, so the user could wait a second full timeout before seeing any message at all. Co-Authored-By: Claude Opus 5 --- src/cli/docs.rs | 101 ++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 85 insertions(+), 16 deletions(-) diff --git a/src/cli/docs.rs b/src/cli/docs.rs index 15b96f2..81d0ad2 100644 --- a/src/cli/docs.rs +++ b/src/cli/docs.rs @@ -994,44 +994,51 @@ pub fn print_tree(nodes: &[Value], parent: Option<&str>, indent: &str) { } } +/// How long to spend looking the document up after a create timed out. The +/// server just failed to answer within its full request timeout; waiting that +/// long again before saying anything would double the silence, and the hint +/// is only an aid to a message that is printed either way. +const CREATE_HINT_LOOKUP: std::time::Duration = std::time::Duration::from_secs(10); + /// Build the guidance appended to a `createDocument` timeout. /// /// The request reached the server, so the document may exist. Look for one /// with the name just attempted so the error can name its id instead of /// leaving the user to guess between "retry" and "clean up". +/// +/// Only the drive root is searched, and the match is never reported as proof: +/// `createDocument` puts the document at the root and the `--parent-folder` +/// move has not run yet, so a same-named document in some folder is somebody +/// else's — and a same-named document at the root may be too, if the drive +/// already had one. Telling the user "the create took effect" about a +/// pre-existing document would point them at the wrong id and talk them out +/// of the retry they actually need. async fn timed_out_create_hint( client: &crate::graphql::GraphQLClient, drive_id: &str, name: &str, parent_folder: Option<&str>, ) -> String { - let existing = fetch_drive_nodes(client, drive_id) + let at_root = tokio::time::timeout(CREATE_HINT_LOOKUP, fetch_drive_nodes(client, drive_id)) .await .ok() - .and_then(|(_, _, nodes)| { - nodes - .iter() - .find(|n| { - n["kind"].as_str() == Some("file") - && n["name"] - .as_str() - .is_some_and(|n| n.eq_ignore_ascii_case(name)) - }) - .and_then(|n| n["id"].as_str().map(|id| id.to_string())) - }); + .and_then(|fetched| fetched.ok()) + .and_then(|(_, _, nodes)| root_document_named(&nodes, name)); - match existing { + match at_root { Some(doc_id) => { let placement = match parent_folder { Some(folder) => format!( - " It is at the drive root, not in folder {folder}; place it with \ + " 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 DID take effect: drive {drive_id} now holds a document named \ - \"{name}\" (id {doc_id}).{placement} Do NOT re-run `docs create` — that \ + "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." ) } @@ -1043,6 +1050,21 @@ async fn timed_out_create_hint( } } +/// The id of a document sitting at the drive root under this name. Folders +/// and anything nested are not candidates — see `timed_out_create_hint`. +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, @@ -2155,6 +2177,53 @@ fn days_to_ymd(days: u64) -> (u64, u64, u64) { (y, m, d) } +#[cfg(test)] +mod create_recovery_tests { + use super::*; + use serde_json::json; + + /// After a create times out, only a root-level name match is a candidate: + /// `createDocument` lands the document at the root, and the + /// `--parent-folder` move has not run yet. Matching anywhere in the drive + /// made an unrelated document in some folder look like proof the create + /// took effect, which suppressed the retry the user actually needed. + #[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()) + ); + } + + /// Some servers say "" rather than null for a root node, and a folder of + /// the same name is never the document that was created. + #[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::*; From cf6196a66343f215817f8ad8623889b6702ab54f Mon Sep 17 00:00:00 2001 From: Benjamin Jordan Date: Tue, 15 Sep 2026 12:08:36 -0500 Subject: [PATCH 09/10] fix(docs): hedge the move failure, and keep the id on the JSON path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two problems with the `--parent-folder` failure path, both of which the create path twenty lines above had already solved for itself. The message asserted the document "is sitting at the root of drive X". The move can fail with exactly the read timeout this branch teaches the create to distrust, in which case it may have applied — so the same failure mode got a categorical claim here and a hedged one there. Check `is_timeout_error` and say what is actually known. And returning Err skipped the JSON print, so `docs create --parent-folder ... --format json | jq -r .id` produced nothing: the id of a document that definitely exists survived only as prose inside a stderr error chain. Emit `{id, folderMoveFailed}` before failing, so automation can recover it. `--parent-folder` was also missing from all three doc sources; add it. Co-Authored-By: Claude Opus 5 --- README.md | 2 +- specs.md | 9 ++++++++- src/cli/docs.rs | 31 ++++++++++++++++++++++++++++--- src/cli/guide.rs | 1 + 4 files changed, 38 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 21fe4d8..9e2b623 100644 --- a/README.md +++ b/README.md @@ -204,7 +204,7 @@ 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) | diff --git a/specs.md b/specs.md index f285822..8e38405 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 @@ -1238,6 +1238,13 @@ $ 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. The document is made at the drive root and then +# moved, so if the move fails the command exits non-zero — and still prints +# the id, with the reason, so the document is never lost to a script: +$ 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 81d0ad2..2506f93 100644 --- a/src/cli/docs.rs +++ b/src/cli/docs.rs @@ -1179,11 +1179,36 @@ async fn create( } }); if let Err(e) = client.query(move_mutation, Some(&move_vars)).await { + // A read timeout is the one failure that may have applied + // anyway, so it gets a question about where the document ended + // up rather than an assertion. + 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}`" + ) + }; + // The document exists whatever became of the move, but returning + // Err skips the JSON print below — so a script piping stdout to + // `jq` would get nothing and the id would survive only as prose + // in the error chain. Emit it before failing. + 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} — it is sitting at the root of drive {drive_id}. \ - Place it with `switchboard docs move {doc_id} --from {drive_id} --to {folder_id}`; \ - do NOT re-run `docs create`, that makes a duplicate." + folder {folder_id} — {placement}; do NOT re-run `docs create`, that makes a \ + duplicate." ))); } } diff --git a/src/cli/guide.rs b/src/cli/guide.rs index 68f121d..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 From 55ef592177fe8cc955c6b16868771411e45ae135 Mon Sep 17 00:00:00 2001 From: Benjamin Jordan Date: Tue, 15 Sep 2026 12:32:33 -0500 Subject: [PATCH 10/10] style: cut the commentary on this branch back to what isn't in the code 165 lines of comment removed across the four source files this branch touched. Most of it restated the line below it, re-argued a decision the code already makes, or narrated a test whose name said the same thing. What survives is the handful of facts the code cannot state: that a name match after a create timeout is not proof, that `result.actions` is not the submitted count, that validation errors arrive non-2xx, and the two socket tricks in the client tests. Co-Authored-By: Claude Opus 5 --- specs.md | 5 +-- src/cli/docs.rs | 51 ++++++------------------- src/cli/jobs.rs | 88 +++++-------------------------------------- src/graphql/client.rs | 50 +++--------------------- 4 files changed, 29 insertions(+), 165 deletions(-) diff --git a/specs.md b/specs.md index 8e38405..be714d6 100644 --- a/specs.md +++ b/specs.md @@ -1238,9 +1238,8 @@ $ 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. The document is made at the drive root and then -# moved, so if the move fails the command exits non-zero — and still prints -# the id, with the reason, so the document is never lost to a script: +# 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": "..."} diff --git a/src/cli/docs.rs b/src/cli/docs.rs index 2506f93..58dac41 100644 --- a/src/cli/docs.rs +++ b/src/cli/docs.rs @@ -994,25 +994,13 @@ pub fn print_tree(nodes: &[Value], parent: Option<&str>, indent: &str) { } } -/// How long to spend looking the document up after a create timed out. The -/// server just failed to answer within its full request timeout; waiting that -/// long again before saying anything would double the silence, and the hint -/// is only an aid to a message that is printed either way. +/// 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); -/// Build the guidance appended to a `createDocument` timeout. -/// -/// The request reached the server, so the document may exist. Look for one -/// with the name just attempted so the error can name its id instead of -/// leaving the user to guess between "retry" and "clean up". -/// -/// Only the drive root is searched, and the match is never reported as proof: -/// `createDocument` puts the document at the root and the `--parent-folder` -/// move has not run yet, so a same-named document in some folder is somebody -/// else's — and a same-named document at the root may be too, if the drive -/// already had one. Telling the user "the create took effect" about a -/// pre-existing document would point them at the wrong id and talk them out -/// of the retry they actually need. +/// 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, @@ -1050,8 +1038,8 @@ async fn timed_out_create_hint( } } -/// The id of a document sitting at the drive root under this name. Folders -/// and anything nested are not candidates — see `timed_out_create_hint`. +/// 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() @@ -1147,10 +1135,8 @@ async fn create( ns, ); - // A read timeout here does NOT mean the create failed — the server may - // have executed it. Re-running `docs create` is what produces the - // duplicate "(copy) 1" documents, so instead look the document up by name - // and tell the user what to do with it. + // 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) => { @@ -1179,9 +1165,6 @@ async fn create( } }); if let Err(e) = client.query(move_mutation, Some(&move_vars)).await { - // A read timeout is the one failure that may have applied - // anyway, so it gets a question about where the document ended - // up rather than an assertion. 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 \ @@ -1195,10 +1178,8 @@ async fn create( `switchboard docs move {doc_id} --from {drive_id} --to {folder_id}`" ) }; - // The document exists whatever became of the move, but returning - // Err skips the JSON print below — so a script piping stdout to - // `jq` would get nothing and the id would survive only as prose - // in the error chain. Emit it before failing. + // 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, @@ -1853,9 +1834,6 @@ async fn apply( "documentIdentifier": resolved_id, "actions": actions, }); - // `result` is not selected: the job has just been submitted, so it - // has none, and older servers declare the field non-null and error - // the whole mutation over it. `--wait` reads it off `jobStatus`. let data = client .query( "mutation($documentIdentifier: String!, $actions: [ActionInput!]!) { \ @@ -2207,11 +2185,6 @@ mod create_recovery_tests { use super::*; use serde_json::json; - /// After a create times out, only a root-level name match is a candidate: - /// `createDocument` lands the document at the root, and the - /// `--parent-folder` move has not run yet. Matching anywhere in the drive - /// made an unrelated document in some folder look like proof the create - /// took effect, which suppressed the retry the user actually needed. #[test] fn only_the_drive_root_is_a_candidate() { let nodes = vec![ @@ -2232,8 +2205,6 @@ mod create_recovery_tests { ); } - /// Some servers say "" rather than null for a root node, and a folder of - /// the same name is never the document that was created. #[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", diff --git a/src/cli/jobs.rs b/src/cli/jobs.rs index 26cdde4..6ebae96 100644 --- a/src/cli/jobs.rs +++ b/src/cli/jobs.rs @@ -58,13 +58,12 @@ fn status_progress(status: &str) -> &str { } } -/// What became of one action the caller submitted. #[derive(Debug, PartialEq)] enum Outcome { Applied, ReducerError(String), Denied(String), - /// A kind this CLI does not know. Never counted as applied. + /// Never counted as applied. Unknown(String), } @@ -87,15 +86,11 @@ impl SubmittedAction { } } -/// `JobInfo.result`: one entry per submitted action that produced an -/// operation, plus the server's own verdict on the batch. +/// 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, - /// The server's `allApplied`, kept separate from the entries. False here - /// with every entry applied is not a contradiction: an action that - /// produced no operation has no entry at all, so the entries cannot - /// account for it. server_all_applied: bool, } @@ -107,23 +102,16 @@ impl JobResult { .count() } - /// Entries that say the action did not apply. Never the whole story — - /// see `server_all_applied`. fn rejected_count(&self) -> usize { self.actions.len() - self.applied_count() } - /// The per-action detail is authoritative in one direction only: an entry - /// that says "did not apply" outvotes a summary claiming success, and the - /// summary outvotes entries that are all clean. 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()); - // Every action the server detailed applied, yet it says the batch did - // not. Printing the bare count here would read as a clean success. if self.server_all_applied || self.rejected_count() > 0 { counted } else { @@ -131,7 +119,6 @@ impl JobResult { } } - /// One line per action that did not apply, saying which and why. fn failure_lines(&self) -> Vec { self.actions .iter() @@ -148,13 +135,8 @@ impl JobResult { } } -/// Read `result` off a `JobInfo` or a `jobChanges` event. -/// -/// Returns `None` when there is no per-action information to report, which is -/// what every Switchboard before the job-result fix gives: `jobStatus` omits -/// the field and `jobChanges` sends `{}`, because its `result` was declared -/// non-null. Absence is never reported as success — the caller falls back to -/// the plain status line. +/// `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() { @@ -191,33 +173,17 @@ fn parse_job_result(job: &Value) -> Option { Some(JobResult { actions, - // Absent means the server has no verdict to give; the entries decide. server_all_applied: job["result"]["allApplied"].as_bool().unwrap_or(true), }) } -/// True when the server's complaint is specifically about `JobInfo.result`: -/// an older Switchboard resolving its non-null `result` to null, or a schema -/// with no such field, which fails validation instead. Both name the field. -/// -/// Anything else — a bad job id, an expired token — is the caller's to see. -/// Retrying those costs a second round trip and then reports whichever of the -/// two failures is less accurate. fn rejects_job_result(err: &anyhow::Error) -> bool { let message = format!("{err:#}"); message.contains("JobInfo") && message.contains("result") } -/// Query `jobStatus`, selecting `result`. -/// -/// `JobInfo.result` carries what became of each submitted action. Older -/// Switchboards declare it `JSONObject!` and resolve it null, which nullifies -/// the whole selection and errors the query; older ones still have no such -/// field, which fails validation (HTTP 400). Fall back to the result-less -/// selection in both cases, so this CLI keeps working against a server that -/// simply has no per-action detail to give. Only a server answering about -/// that field triggers the retry — a dead connection is reported as-is rather -/// than dialled twice. +/// 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!( @@ -317,10 +283,6 @@ async fn wait( .trim_start_matches("http://"); let ws_url = format!("{ws_scheme}://{host}/graphql/subscriptions"); - // `result` is safe to select here on every server: the pre-fix ones declare - // `JobChangeEvent.result` non-null and publish `{}` rather than null, which - // `parse_job_result` reads as "no per-action detail". It was only - // `jobStatus` that errored on it. let subscription = format!( r#"subscription {{ jobChanges(jobId: "{id}") {{ jobId status result error }} }}"#, id = job_id.replace('"', r#"\""#) @@ -386,14 +348,9 @@ async fn wait( print_job_result(job, &job_id_owned, status_str, format) } -/// Print a finished job, then fail if the actions it was given did not all -/// apply. -/// -/// A reducer error or a denial does not fail the job — the operation is still -/// written, the job still reaches READ_READY — so the status line alone would -/// report a partly-rejected batch as a clean success. Exit non-zero instead, -/// after printing, so both a human and a script see it. JSON output is the job -/// object as the server sent it, `result` included: nothing is reshaped. +/// 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, @@ -423,10 +380,6 @@ fn print_job_result( if let Some(s) = summary && !s.all_applied() { - // `actions` holds only the submitted actions that produced an - // operation, so it cannot be used as the submitted count. When the - // server's verdict is the only thing objecting, say that instead of - // reporting "0 of N did not apply". return match s.rejected_count() { 0 => Err(anyhow::anyhow!( "the server reports the batch as not fully applied, though every action it \ @@ -548,8 +501,6 @@ mod tests { assert!(summary.failure_lines().is_empty()); } - /// A pre-fix Switchboard cannot select `result` on `jobStatus` at all, so - /// the field is simply absent. That is missing information, not success. #[test] fn an_absent_result_yields_no_summary() { let job = json!({ "id": "job-1", "status": "READ_READY", "error": null }); @@ -561,16 +512,12 @@ mod tests { assert_eq!(parse_job_result(&job_with(Value::Null)), None); } - /// What a pre-fix server publishes on the `jobChanges` subscription, where - /// `result` is declared non-null: an empty object standing in for nothing. #[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); } - /// `allApplied` is derived when the server omits it, so an older shape of - /// the field cannot turn a rejection into a success. #[test] fn all_applied_is_derived_when_missing() { let job = job_with(json!({ @@ -583,8 +530,6 @@ mod tests { assert!(!parse_job_result(&job).unwrap().all_applied()); } - /// And a summary that contradicts its own entries does not get the benefit - /// of the doubt. #[test] fn a_rejected_action_outvotes_all_applied() { let job = job_with(json!({ @@ -595,8 +540,6 @@ mod tests { assert!(!parse_job_result(&job).unwrap().all_applied()); } - /// A kind added after this CLI shipped is reported verbatim, never counted - /// as applied. #[test] fn an_unknown_kind_is_not_success() { let job = job_with(json!({ @@ -610,7 +553,6 @@ mod tests { ); } - /// Missing detail must not panic or read as success. #[test] fn missing_fields_degrade_to_placeholders() { let job = job_with(json!({ @@ -626,8 +568,6 @@ mod tests { ); } - /// A partly-rejected batch exits non-zero; the same job with no result - /// reported keeps today's exit code. #[test] fn a_partial_failure_is_an_error() { let rejected = job_with(json!({ @@ -646,9 +586,6 @@ mod tests { assert!(print_job_result(&unknown, "job-1", "READ_READY", OutputFormat::Json).is_ok()); } - /// The `result`-less retry exists for one server bug. Spending a second - /// round trip on a bad job id or an expired token only buys a second - /// failure, and the first one is then thrown away. #[test] fn only_a_result_rejection_earns_a_second_round_trip() { let non_null = anyhow::anyhow!( @@ -672,11 +609,6 @@ mod tests { } } - /// An action that produced no operation gets no entry, so the server can - /// say `allApplied: false` over a set of entries that all applied. The - /// entries must not be mistaken for the submitted count: doing so - /// printed a clean `2/2 applied` and then bailed with the nonsense - /// "0 of 2 submitted action(s) did not apply". #[test] fn a_verdict_with_nothing_to_point_at_is_still_a_failure() { let job = job_with(json!({ diff --git a/src/graphql/client.rs b/src/graphql/client.rs index a308592..9c18c99 100644 --- a/src/graphql/client.rs +++ b/src/graphql/client.rs @@ -89,10 +89,6 @@ impl GraphQLClient { continue; } Err(e) if e.is_timeout() => { - // The connection succeeded; only the response timed out. - // The server received the request and may have executed - // it, so this is never retried and must not be reported - // as a connection failure. return Err(anyhow::Error::new(e).context(timed_out_message(&self.url))); } Err(e) => { @@ -110,11 +106,6 @@ impl GraphQLClient { let status = response.status(); if !status.is_success() { let body = response.text().await.unwrap_or_default(); - // 504/408 are the other half of "reached the server, no answer - // came back in time" — a gateway saying so on the upstream's - // behalf. The operation may have executed, exactly as with a read - // timeout, so it must carry the same warning and not read as a - // plain HTTP failure. if status == reqwest::StatusCode::GATEWAY_TIMEOUT || status == reqwest::StatusCode::REQUEST_TIMEOUT { @@ -123,11 +114,7 @@ impl GraphQLClient { .context(timed_out_message(&self.url)), ); } - // A GraphQL error can arrive with a non-2xx status: a query that - // names a field the schema lacks fails validation, which both - // graphql-yoga and Apollo answer with HTTP 400. The server did - // answer, so report it as a server error — callers key their - // narrower-selection fallbacks off that. + // 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}")) @@ -154,16 +141,12 @@ impl GraphQLClient { } } -/// The GraphQL error messages carried by a response body, if it is a GraphQL -/// error response at all. A gateway's HTML error page is not. 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()) } -/// The one wording for "the request reached the server and no answer came -/// back in time", shared by the read-timeout and gateway-timeout paths. fn timed_out_message(url: &str) -> String { format!( "Timed out waiting for a response from {url}. \ @@ -172,9 +155,7 @@ fn timed_out_message(url: &str) -> String { ) } -/// A request that reached the server with no answer coming back in time, -/// reported by a gateway rather than by the socket. Carries the same -/// maybe-applied warning as a read timeout. +/// A gateway's 504/408: reached the server, no answer in time. #[derive(Debug)] pub struct MaybeApplied(String); @@ -186,10 +167,7 @@ impl std::fmt::Display for MaybeApplied { impl std::error::Error for MaybeApplied {} -/// Errors the server answered with, as opposed to ones the transport -/// produced. A schema mismatch — an older Switchboard rejecting a field this -/// CLI selects — lands here, which lets a caller retry with a narrower -/// selection instead of retrying a dead connection. +/// Errors the server answered with, as opposed to ones the transport produced. #[derive(Debug)] pub struct ServerErrors(pub Vec); @@ -201,17 +179,13 @@ impl std::fmt::Display for ServerErrors { impl std::error::Error for ServerErrors {} -/// True when the server answered with GraphQL errors. pub fn is_server_error(err: &anyhow::Error) -> bool { err.chain() .any(|cause| cause.downcast_ref::().is_some()) } -/// True when `err` was caused by a request timing out after the connection -/// was established — whether the socket gave up waiting or a gateway answered -/// 504/408. Either way the server received the request and may have executed -/// it. Callers of mutating operations use this to report a maybe-applied -/// write instead of a plain failure. +/// 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() @@ -225,9 +199,6 @@ pub fn is_timeout_error(err: &anyhow::Error) -> bool { mod tests { use super::*; - /// An older Switchboard rejecting `JobInfo.result` must stay recognizable - /// after `.context()` wrapping — `jobs status` keys its narrower-selection - /// retry off this, and must not retry a dead connection that way. #[test] fn a_server_error_is_told_from_a_transport_one() { let err = anyhow::Error::new(ServerErrors(vec![ @@ -242,8 +213,6 @@ mod tests { assert!(!is_server_error(&transport)); } - /// A read timeout must stay recognizable after `.context()` wrapping — - /// `docs create` keys its "the document may exist" recovery off this. #[tokio::test] async fn timeout_survives_context_wrapping() { let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); @@ -294,9 +263,7 @@ mod tests { assert!(!is_timeout_error(&wrapped)); } - /// A gateway timeout is a successful HTTP exchange, so nothing in the - /// error chain is a `reqwest::Error` — it still has to reach the - /// maybe-applied path that stops `docs create` being re-run. + // 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())) @@ -306,9 +273,6 @@ mod tests { assert!(format!("{err:#}").contains("may have completed")); } - /// A schema with no `JobInfo.result` fails *validation*, which yoga and - /// Apollo answer with HTTP 400 — `jobs status` must still see a server - /// error there, not an opaque HTTP failure. #[test] fn a_non_2xx_graphql_body_is_a_server_error() { let body = @@ -317,9 +281,7 @@ mod tests { assert_eq!(messages.len(), 1); assert!(messages[0].contains("JobInfo")); - // A gateway's HTML error page is not a GraphQL answer. assert!(graphql_error_messages("502 Bad Gateway").is_none()); - // Neither is a 200-shaped body with no errors. assert!(graphql_error_messages(r#"{"data":{"x":1}}"#).is_none()); } }