From e13a778ad2c5d235072c4e9ed97a57676634b05a Mon Sep 17 00:00:00 2001 From: sdairs Date: Fri, 13 Nov 2026 20:52:37 +0000 Subject: [PATCH] fix(local): reject equal HTTP/TCP ports and count only ClickHouse servers on start (#1452) --- crates/clickhousectl/src/local/mod.rs | 3 + crates/clickhousectl/src/local/server.rs | 130 +++++++++++++----- .../tests/local_engine_lists_test.rs | 49 +++++++ .../tests/local_server_start_args_test.rs | 29 ++++ docs/guides/local-development.md | 2 +- 5 files changed, 178 insertions(+), 35 deletions(-) diff --git a/crates/clickhousectl/src/local/mod.rs b/crates/clickhousectl/src/local/mod.rs index be2ec55a..91e986e9 100644 --- a/crates/clickhousectl/src/local/mod.rs +++ b/crates/clickhousectl/src/local/mod.rs @@ -639,6 +639,9 @@ async fn start_server( // `--foreground` streams the server's stdout/stderr and never emits a JSON // summary, so it simply ignores `json` rather than erroring on `--json`. + // A usage error, so it comes before any process scan, lock or download. + server::reject_equal_ports(http_port, tcp_port)?; + // Recover any orphaned servers so name resolution and collision checks // see processes that lost their metadata files. server::recover_current_project_servers()?; diff --git a/crates/clickhousectl/src/local/server.rs b/crates/clickhousectl/src/local/server.rs index 34189d91..13d2ac0c 100644 --- a/crates/clickhousectl/src/local/server.rs +++ b/crates/clickhousectl/src/local/server.rs @@ -853,8 +853,9 @@ pub(crate) fn list_running_servers_locked(lock: &MetadataLock) -> Result usize { - list_all_servers_locked_inner(lock, None, true) + list_all_servers_locked_inner(lock, Some(Engine::Clickhouse), true) .map(|entries| entries.iter().filter(|entry| entry.running).count()) .unwrap_or_default() } @@ -1382,9 +1383,29 @@ fn is_loopback_listener(ip: std::net::IpAddr, port: u16) -> bool { } } -/// Find a free port starting from `start`, incrementing by 1. -fn find_free_port(start: u16) -> Option { - (start..=start.saturating_add(100)).find(|&p| is_port_available(p)) +/// Refuse one port for both listeners. Only one of them can bind it, and the +/// readiness probe would then pass against the HTTP listener alone (#1452). +pub(crate) fn reject_equal_ports(http_port: Option, tcp_port: Option) -> Result<()> { + match (http_port, tcp_port) { + (Some(http), Some(tcp)) if http == tcp => Err(Error::usage( + clap::error::ErrorKind::ArgumentConflict, + format!( + "--http-port and --tcp-port must be different ports; both are {http}. \ + Omit one to have a free port assigned" + ), + )), + _ => Ok(()), + } +} + +/// `default` if usable, else the first usable port in the 100 above it. A port +/// the other listener has claimed is never usable. +fn pick_port(default: u16, claimed: Option, available: &impl Fn(u16) -> bool) -> Option { + let usable = |port: u16| Some(port) != claimed && available(port); + if usable(default) { + return Some(default); + } + (default.saturating_add(1)..=default.saturating_add(101)).find(|&port| usable(port)) } /// Resolve the HTTP and TCP ports to use. @@ -1393,39 +1414,33 @@ fn find_free_port(start: u16) -> Option { /// Returns (http_port, tcp_port, auto_assigned) where auto_assigned is true if /// we picked non-default ports. pub fn resolve_ports(http_port: Option, tcp_port: Option) -> Result<(u16, u16, bool)> { - let http = match http_port { - Some(p) if is_port_available(p) => p, - Some(p) => { - return Err(Error::PortInUse { - kind: PortKind::Http, - port: p, - }); - } - None => { - if is_port_available(DEFAULT_HTTP_PORT) { - DEFAULT_HTTP_PORT - } else { - find_free_port(DEFAULT_HTTP_PORT + 1) - .ok_or(Error::PortUnavailable(PortKind::Http))? - } + resolve_ports_with(http_port, tcp_port, is_port_available) +} + +fn resolve_ports_with( + http_port: Option, + tcp_port: Option, + available: impl Fn(u16) -> bool, +) -> Result<(u16, u16, bool)> { + reject_equal_ports(http_port, tcp_port)?; + for (kind, port) in [(PortKind::Http, http_port), (PortKind::Tcp, tcp_port)] { + if let Some(port) = port + && !available(port) + { + return Err(Error::PortInUse { kind, port }); } - }; + } + // An omitted port skips the one the other listener uses, explicit or not. + let http = match http_port { + Some(port) => port, + None => pick_port(DEFAULT_HTTP_PORT, tcp_port, &available) + .ok_or(Error::PortUnavailable(PortKind::Http))?, + }; let tcp = match tcp_port { - Some(p) if is_port_available(p) => p, - Some(p) => { - return Err(Error::PortInUse { - kind: PortKind::Tcp, - port: p, - }); - } - None => { - if is_port_available(DEFAULT_TCP_PORT) { - DEFAULT_TCP_PORT - } else { - find_free_port(DEFAULT_TCP_PORT + 1).ok_or(Error::PortUnavailable(PortKind::Tcp))? - } - } + Some(port) => port, + None => pick_port(DEFAULT_TCP_PORT, Some(http), &available) + .ok_or(Error::PortUnavailable(PortKind::Tcp))?, }; let auto_assigned = http_port.is_none() && http != DEFAULT_HTTP_PORT @@ -2631,6 +2646,53 @@ mod tests { assert!(!is_process_alive(pid)); } + #[test] + fn identical_explicit_ports_are_a_usage_conflict() { + let error = resolve_ports_with(Some(18130), Some(18130), |_| true).unwrap_err(); + let Error::Usage(clap_error) = &error else { + panic!("expected a usage error, got {error}"); + }; + assert_eq!(clap_error.kind(), clap::error::ErrorKind::ArgumentConflict); + assert_eq!(error.exit_code(), 2); + let message = clap_error.to_string(); + for needle in ["--http-port", "--tcp-port", "18130"] { + assert!(message.contains(needle), "{needle}: {message}"); + } + + assert!(reject_equal_ports(Some(8123), Some(9000)).is_ok()); + assert!(reject_equal_ports(Some(9000), None).is_ok()); + assert!(reject_equal_ports(None, None).is_ok()); + } + + #[test] + fn an_omitted_port_skips_the_port_the_other_listener_claims() { + let all_free = |_| true; + assert_eq!( + resolve_ports_with(None, None, all_free).unwrap(), + (DEFAULT_HTTP_PORT, DEFAULT_TCP_PORT, false) + ); + + let (http, tcp, auto_assigned) = + resolve_ports_with(Some(DEFAULT_TCP_PORT), None, all_free).unwrap(); + assert_eq!(http, DEFAULT_TCP_PORT); + assert_ne!(tcp, http); + assert!(auto_assigned); + + let (http, tcp, auto_assigned) = + resolve_ports_with(None, Some(DEFAULT_HTTP_PORT), all_free).unwrap(); + assert_eq!(tcp, DEFAULT_HTTP_PORT); + assert_ne!(http, tcp); + assert!(auto_assigned); + + // The search past a busy default skips the claimed port too. + let (http, tcp, _) = resolve_ports_with(None, Some(DEFAULT_HTTP_PORT + 1), |port| { + port != DEFAULT_HTTP_PORT + }) + .unwrap(); + assert_eq!(tcp, DEFAULT_HTTP_PORT + 1); + assert_eq!(http, DEFAULT_HTTP_PORT + 2); + } + #[test] fn explicit_ports_must_be_available() { let listener = std::net::TcpListener::bind(("127.0.0.1", 0)).unwrap(); diff --git a/crates/clickhousectl/tests/local_engine_lists_test.rs b/crates/clickhousectl/tests/local_engine_lists_test.rs index 6f571069..fada248d 100644 --- a/crates/clickhousectl/tests/local_engine_lists_test.rs +++ b/crates/clickhousectl/tests/local_engine_lists_test.rs @@ -324,3 +324,52 @@ async fn stopped_postgres_error_points_at_a_list_that_shows_it() { "{listed}" ); } + +/// `local clickhouse start` counts only running ClickHouse servers for its +/// "already running" note, so a running Postgres instance is never inspected +/// (#1452). Recovery lists containers but never inspects one by ID. +#[tokio::test(flavor = "multi_thread")] +async fn clickhouse_start_never_inspects_a_postgres_instance() { + use std::os::unix::fs::PermissionsExt; + + let project = seeded_project(); + let docker = running_postgres_docker().await; + let home = tempfile::tempdir().unwrap(); + let version = "25.12.9.61"; + let binary = home + .path() + .join(format!(".clickhouse/versions/{version}/clickhouse")); + std::fs::create_dir_all(binary.parent().unwrap()).unwrap(); + std::fs::write(&binary, b"#!/bin/sh\nexec sleep 30\n").unwrap(); + std::fs::set_permissions(&binary, std::fs::Permissions::from_mode(0o755)).unwrap(); + + let output = run_in_home( + project.path(), + home.path(), + &docker.uri(), + &[ + "local", + "clickhouse", + "start", + "--no-wait", + "--version", + version, + "--json", + ], + ); + let body = json_ok(&output); + let pid = body["pid"].as_u64().unwrap() as i32; + unsafe { + libc::kill(pid, libc::SIGKILL); + } + + let inspected: Vec<_> = docker + .received_requests() + .await + .unwrap() + .into_iter() + .map(|request| request.url.path().to_string()) + .filter(|path| path.ends_with("/containers/pg-container/json")) + .collect(); + assert_eq!(inspected, Vec::::new()); +} diff --git a/crates/clickhousectl/tests/local_server_start_args_test.rs b/crates/clickhousectl/tests/local_server_start_args_test.rs index 063868f7..4d57be68 100644 --- a/crates/clickhousectl/tests/local_server_start_args_test.rs +++ b/crates/clickhousectl/tests/local_server_start_args_test.rs @@ -113,3 +113,32 @@ fn both_name_forms_keep_following_version_and_passthrough_separate() { assert!(!child_args.lines().any(|arg| arg == "--version")); } } + +/// One port for both listeners is a usage error found before anything else +/// in `start` runs: no project state, version lookup or download (#1452). +#[test] +fn identical_http_and_tcp_ports_fail_before_any_side_effect() { + for json in [false, true] { + let project = tempfile::tempdir().expect("create project tempdir"); + let home = tempfile::tempdir().expect("create home tempdir"); + let mut command = Command::new(clickhousectl_binary()); + command + .env_clear() + .env("DO_NOT_TRACK", "1") + .env("CHCTL_UPDATE_CHECK_TIMEOUT_MS", "0") + .env("HOME", home.path()) + .env("PATH", "/usr/bin:/bin") + .current_dir(project.path()) + .args(["local", "clickhouse", "start"]) + .args(["--http-port", "18130", "--tcp-port", "18130"]); + if json { + command.arg("--json"); + } + let output = command.output().expect("run clickhousectl"); + + assert_eq!(output.status.code(), Some(2), "json={json}: {output:?}"); + assert!(output.stdout.is_empty(), "json={json}: {output:?}"); + assert!(!project.path().join(".clickhouse").exists(), "json={json}"); + assert!(!home.path().join(".clickhouse").exists(), "json={json}"); + } +} diff --git a/docs/guides/local-development.md b/docs/guides/local-development.md index 2b87808b..9c79a70c 100644 --- a/docs/guides/local-development.md +++ b/docs/guides/local-development.md @@ -37,7 +37,7 @@ clickhousectl local clickhouse list `local init` marks the current directory as the project root and scaffolds `clickhouse/` and `postgres/` directories for schemas, queries, seed data, [UDF sources](user-defined-functions.md#scaffold-a-function), and [server config](#apply-a-custom-clickhouse-configuration) applied on every start. It initializes the current directory, or [`CLICKHOUSECTL_PROJECT_DIR`](#name-the-project-root-explicitly) when set: run inside an existing project, it creates a nested project and names the enclosing one. -Named starts reuse the server's data. Background starts wait up to 30 seconds for HTTP and TCP readiness; `--no-wait` returns after spawning. Failures point to `.clickhouse/servers//server.log`. Default ports are HTTP 8123 and TCP 9000, with free ports assigned when occupied. Use `--http-port` and `--tcp-port` to request specific ports. +Named starts reuse the server's data. Background starts wait up to 30 seconds for HTTP and TCP readiness; `--no-wait` returns after spawning. Failures point to `.clickhouse/servers//server.log`. Default ports are HTTP 8123 and TCP 9000, with free ports assigned when occupied. Use `--http-port` and `--tcp-port` to request specific ports; they must differ, and an omitted port never takes the one the other listener uses. Without a name, the first server is `default`; if it is already running, another start generates a new name. Use an explicit name for a repeatable workflow. Names ending in `-pg` and digits, such as `dev-pg17`, are how Postgres instances are stored on disk, so `local clickhouse` and `local udf` refuse them with a usage error (exit 2) unless an existing ClickHouse server already has that name.