Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 140 additions & 1 deletion crates/clickhousectl/src/cloud/output.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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] = &[
Expand Down Expand Up @@ -147,6 +178,11 @@ impl CloudErrorCode {
Self::ClickPipeStartNoEffect,
Self::PackageManaged,
Self::VerificationFailed,
Self::InvalidVersion,
Self::VersionNotInstalled,
Self::VersionSelectionRequired,
Self::BinaryNotLaunchable,
Self::UnsupportedClientVersion,
];
}

Expand Down Expand Up @@ -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()))
}
Expand Down Expand Up @@ -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",
]
);
}
Expand Down Expand Up @@ -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 <crate::cli::Cli as clap::Parser>::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 {
Expand Down
27 changes: 27 additions & 0 deletions crates/clickhousectl/src/local/output.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<String>)> {
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
Expand Down
45 changes: 45 additions & 0 deletions crates/clickhousectl/tests/cloud/query.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
2 changes: 2 additions & 0 deletions docs/reference/automation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading