diff --git a/crates/clickhousectl/src/cloud/output.rs b/crates/clickhousectl/src/cloud/output.rs index 5c4c257a..dde0a456 100644 --- a/crates/clickhousectl/src/cloud/output.rs +++ b/crates/clickhousectl/src/cloud/output.rs @@ -102,6 +102,23 @@ pub enum CloudErrorCode { /// `update` downloaded an archive that the release's `SHA256SUMS` does /// not list or whose digest differs, and replaced nothing (#1307). VerificationFailed, + /// `cloud service client` was pointed at a ClickHouse build whose version + /// is malformed; the same code `local client` reports (#1443). + InvalidVersion, + /// `cloud service client` found no installed local build to run, or not + /// the requested one; `command` lists or installs one. The same code + /// `local client` reports (#1443). + VersionNotInstalled, + /// `cloud service client` found several installed builds and no default; + /// pass `--version` or set a default. The same code `local client` + /// reports (#1443). + VersionSelectionRequired, + /// The selected local build is installed but cannot be launched; + /// `command` reinstalls it. The same code `local client` reports (#1443). + BinaryNotLaunchable, + /// The selected local build's client predates `--login`, which + /// `cloud service client` needs; `command` installs a newer one (#1443). + UnsupportedClientVersion, } impl CloudErrorCode { @@ -120,6 +137,20 @@ impl CloudErrorCode { } } + /// The Cloud code for a local client pre-flight failure that + /// `cloud service client` shares with `local client` (#1443). + fn from_local(code: crate::local::output::LocalErrorCode) -> Self { + use crate::local::output::LocalErrorCode; + match code { + LocalErrorCode::InvalidVersion => Self::InvalidVersion, + LocalErrorCode::VersionNotInstalled => Self::VersionNotInstalled, + LocalErrorCode::VersionSelectionRequired => Self::VersionSelectionRequired, + LocalErrorCode::BinaryNotLaunchable => Self::BinaryNotLaunchable, + LocalErrorCode::UnsupportedClientVersion => Self::UnsupportedClientVersion, + _ => Self::Other, + } + } + /// Every code, for closed-vocabulary tests. #[cfg(test)] const ALL: &'static [Self] = &[ @@ -147,6 +178,11 @@ impl CloudErrorCode { Self::ClickPipeStartNoEffect, Self::PackageManaged, Self::VerificationFailed, + Self::InvalidVersion, + Self::VersionNotInstalled, + Self::VersionSelectionRequired, + Self::BinaryNotLaunchable, + Self::UnsupportedClientVersion, ]; } @@ -209,7 +245,14 @@ impl CloudErrorDetail { return std::borrow::Cow::Owned(detail); } Error::ArchiveVerification(_) => CloudErrorCode::VerificationFailed, - _ => CloudErrorCode::Other, + _ => match crate::local::output::installed_client_error(error) { + Some((code, command)) => { + let mut detail = Self::new(CloudErrorCode::from_local(code), error.to_string()); + detail.command = command; + return std::borrow::Cow::Owned(detail); + } + None => CloudErrorCode::Other, + }, }; std::borrow::Cow::Owned(Self::new(code, error.to_string())) } @@ -821,6 +864,11 @@ mod tests { "clickpipe_start_no_effect", "package_managed", "verification_failed", + "invalid_version", + "version_not_installed", + "version_selection_required", + "binary_not_launchable", + "unsupported_client_version", ] ); } @@ -888,6 +936,97 @@ mod tests { } } + /// `cloud service client` runs the local client pre-flight, so a missing, + /// ambiguous, broken or too-old build gets the same typed code and + /// runnable repair `local client` reports, not `other` (#1443). + #[test] + fn local_client_preflight_errors_carry_a_typed_code_and_runnable_command() { + use crate::error::{BinaryLaunchProblem, Error}; + let not_launchable = |problem| Error::BinaryNotLaunchable { + version: "25.12.1.1".into(), + problem, + path: "/home/u/.clickhouse/versions/25.12.1.1/clickhouse".into(), + }; + for (error, code, command) in [ + ( + Error::InvalidVersion("bad".into()), + "invalid_version", + "clickhousectl local install --help", + ), + ( + Error::VersionNotFound("25.12.1.1".into()), + "version_not_installed", + "clickhousectl local list", + ), + ( + Error::StaleDefaultVersion("25.12.1.1".into()), + "version_not_installed", + "clickhousectl local list", + ), + ( + Error::NoClientVersionInstalled, + "version_not_installed", + "clickhousectl local install latest", + ), + ( + Error::ClientVersionNotInstalled("25.12".into()), + "version_not_installed", + "clickhousectl local install 25.12", + ), + ( + Error::NoDefaultVersion, + "version_selection_required", + "clickhousectl local list", + ), + ( + Error::AmbiguousClientVersion, + "version_selection_required", + "clickhousectl local list", + ), + ( + not_launchable(BinaryLaunchProblem::NotExecutable), + "binary_not_launchable", + "clickhousectl local install --force 25.12.1.1", + ), + ( + not_launchable(BinaryLaunchProblem::NotAFile), + "binary_not_launchable", + "clickhousectl local remove 25.12.1.1 && clickhousectl local install 25.12.1.1", + ), + ( + Error::ClientLoginUnsupported { + version: "25.11.1.1".into(), + minimum: "25.12", + }, + "unsupported_client_version", + "clickhousectl local install latest", + ), + ] { + let detail = CloudErrorDetail::from_error(&error); + let value = serde_json::to_value(CloudErrorOutput { error: &detail }).unwrap(); + assert_eq!( + value, + json!({"error": { + "code": code, + "message": error.to_string(), + "command": command, + }}), + "{error:?}" + ); + assert_eq!(error.exit_code(), 1); + for step in command.split(" && ") { + let argv = shlex::split(step).expect("shell-quoted command"); + match ::try_parse_from(&argv) { + Ok(cli) => assert!( + matches!(cli.command, crate::cli::Commands::Local(_)), + "{step}" + ), + Err(e) => assert_eq!(e.kind(), clap::error::ErrorKind::DisplayHelp, "{step}"), + } + } + } + } + #[test] fn cloud_error_detail_omits_absent_fields() { let detail = CloudErrorDetail { diff --git a/crates/clickhousectl/src/local/output.rs b/crates/clickhousectl/src/local/output.rs index ba02a4ef..5a9c1393 100644 --- a/crates/clickhousectl/src/local/output.rs +++ b/crates/clickhousectl/src/local/output.rs @@ -1025,6 +1025,33 @@ pub(crate) fn error_code(error: &Error) -> LocalErrorCode { LocalErrorBody::from_error(error).code() } +/// The code and recovery command this module reports for a failure to select +/// or launch an installed ClickHouse client, or `None` for any other error. +/// `cloud service client` runs the same pre-flight as `local client`, and +/// reuses this classification so the two report a broken local install +/// alike (#1443). Every variant here maps at parity: the message is the +/// error's own text. +pub(crate) fn installed_client_error(error: &Error) -> Option<(LocalErrorCode, Option)> { + if !matches!( + error, + Error::InvalidVersion(_) + | Error::VersionNotFound(_) + | Error::StaleDefaultVersion(_) + | Error::NoClientVersionInstalled + | Error::ClientVersionNotInstalled(_) + | Error::NoDefaultVersion + | Error::AmbiguousClientVersion + | Error::BinaryNotLaunchable { .. } + | Error::ClientLoginUnsupported { .. } + ) { + return None; + } + match LocalErrorBody::from_error(error) { + LocalErrorBody::General(detail) => Some((detail.code, detail.command)), + _ => None, + } +} + /// Write exactly one local runtime error object to stderr, and return its /// code so telemetry reuses this classification instead of building it again. /// The serialized DTO is allowlisted above; foreign text appears only in diff --git a/crates/clickhousectl/tests/cloud/query.rs b/crates/clickhousectl/tests/cloud/query.rs index 88b251e4..a88ed7ad 100644 --- a/crates/clickhousectl/tests/cloud/query.rs +++ b/crates/clickhousectl/tests/cloud/query.rs @@ -2423,6 +2423,51 @@ async fn service_client_execs_the_installed_client_against_the_native_endpoint() assert_observed_permissions_advertised(&control, &help).await; } +/// #1443: a local build too old for `--login` fails before any API call with +/// the typed code and the install command in the Cloud JSON envelope. +#[tokio::test] +async fn service_client_too_old_build_reports_a_typed_json_error() { + let control = MockServer::start().await; + let project = tempfile::tempdir().unwrap(); + let home = project.path().join("home"); + let client = home.join(".clickhouse/versions/25.11.1.1/clickhouse"); + std::fs::create_dir_all(client.parent().unwrap()).unwrap(); + std::fs::write(&client, "#!/bin/sh\nexit 0\n").unwrap(); + std::fs::set_permissions(&client, std::os::unix::fs::PermissionsExt::from_mode(0o755)).unwrap(); + + let output = Command::new(clickhousectl_binary()) + .isolated_env() + .env("DO_NOT_TRACK", "1") + .env("HOME", &home) + .env("CLICKHOUSE_CLOUD_API_KEY", "fake-key-for-tests") + .env("CLICKHOUSE_CLOUD_API_SECRET", "fake-secret-for-tests") + .current_dir(project.path()) + .args([ + "cloud", + "--url", + &control.uri(), + "--org-id", + "org-1", + "--json", + ]) + .args(["service", "client", TEST_SERVICE_ID]) + .stdin(Stdio::null()) + .output() + .expect("failed to spawn clickhousectl"); + + assert_eq!(output.status.code(), Some(1)); + assert!(output.stdout.is_empty(), "{:?}", output.stdout); + let stderr = String::from_utf8_lossy(&output.stderr); + let error: Value = serde_json::from_str(stderr.trim()) + .unwrap_or_else(|e| panic!("stderr is not one JSON object ({e}): {stderr}")); + assert_eq!(error["error"]["code"], "unsupported_client_version"); + assert_eq!( + error["error"]["command"], + "clickhousectl local install latest" + ); + assert!(control.received_requests().await.unwrap().is_empty()); +} + // ── Query timeout diagnosis after an idle/wake observation (#826) ───────── async fn invoke_service_query_for_timeout_test( diff --git a/docs/reference/automation.md b/docs/reference/automation.md index da1711dc..2a750250 100644 --- a/docs/reference/automation.md +++ b/docs/reference/automation.md @@ -78,6 +78,8 @@ Cloud generic codes are `auth_required`, `cancelled`, `http_4xx`, `http_5xx`, `r `cloud clickpipe start` exits 1 with `clickpipe_still_pausing` when the API answers with `Pausing`: a CDC pipe that is still pausing accepts the start but does not apply it. `command` is the `clickpipe get` to repeat until `state` is `Paused`; then run start again. It exits 1 with `clickpipe_start_not_applied` when the API answers with `Paused`: a pipe that has only just finished pausing drops the start too. `command` is the same start; wait a few seconds and rerun it until it returns `Running`. It exits 1 with `clickpipe_start_no_effect`, with no `command` and no `next`, when the API answers with `Completed`: start does not re-run a completed pipe, so there is nothing to retry. Only start is checked: a resync answered with `Paused` or `Completed` is applied. +`cloud service client` checks the local ClickHouse build before calling the API, and reports a problem with the same codes and `command` as `local client`: `invalid_version`, `version_not_installed` (`command` lists or installs a build), `version_selection_required` (several builds and no default; pass `--version`), `binary_not_launchable` (`command` reinstalls the build), and `unsupported_client_version` (the build predates `--login`; `command` installs `latest`). + When a local error's text comes from another program, `message` is clickhousectl's own summary and that text is in `details`: the server's startup output or log tail (`startup_exit`, `startup_timeout`), the Docker daemon's (`docker_error`), the HTTP client's, downloader's, or extractor's (`network_error`, `download_failed`), the OS's or serializer's (`io_error`, `sql_input_open_failed`, `sql_input_read_failed`), a failed subprocess's (`local_error`), and ClickHouse's, the HTTP client's, or the JSON parser's for the UDF codes `udf_definition_invalid` (invalid JSON), `udf_rejected`, `udf_reload_blocked`, `udf_query_failed`, and `udf_server_unreachable`. Human mode prints the same text. Telemetry never records it. Managed-client failures include `project_scope`, `server.selection`/`name`, and ordered `guidance`; project-local stop/remove errors can also carry scope and guidance instead of a top-level recovery command, and `server_metadata_invalid` carries `path` and `guidance`. `project_scope` always has `kind` and `path`. `path` is the project root the command acted on: the nearest directory holding `.clickhouse/` at or above the current directory (never the home directory for its subdirectories), else the current directory. `kind` is `project_root` when that `.clickhouse/` was found, `current_directory` when none was, and `env_override` when `CLICKHOUSECTL_PROJECT_DIR` named the root instead; only `current_directory` guidance suggests changing directory. Every `guidance` step has an `action`, a `message`, and, when one applies, a `command`. `action` is one of `list_project_servers`, `list_global_servers`, `return_to_project_root`, `stop_global_project_server`, `start_server`, `install_version`, `connect_directly`, `repair_project_state`, `repair_metadata`, and `verify_postgres_container`. Act on `action`, not on `message`. New optional fields, codes, and guidance actions may be added compatibly. ## Wait for completion and retry deliberately