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
3 changes: 3 additions & 0 deletions crates/clickhousectl/src/local/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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()?;
Expand Down
130 changes: 96 additions & 34 deletions crates/clickhousectl/src/local/server.rs
Original file line number Diff line number Diff line change
Expand Up @@ -853,8 +853,9 @@ pub(crate) fn list_running_servers_locked(lock: &MetadataLock) -> Result<Vec<Ser
}

/// Best-effort count used only for the informational notice during start.
/// Counts ClickHouse servers only, so Postgres metadata never contacts Docker.
pub(crate) fn advisory_running_server_count_locked(lock: &MetadataLock) -> 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()
}
Expand Down Expand Up @@ -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<u16> {
(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<u16>, tcp_port: Option<u16>) -> 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<u16>, available: &impl Fn(u16) -> bool) -> Option<u16> {
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.
Expand All @@ -1393,39 +1414,33 @@ fn find_free_port(start: u16) -> Option<u16> {
/// 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<u16>, tcp_port: Option<u16>) -> 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<u16>,
tcp_port: Option<u16>,
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
Expand Down Expand Up @@ -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();
Expand Down
49 changes: 49 additions & 0 deletions crates/clickhousectl/tests/local_engine_lists_test.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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::<String>::new());
}
29 changes: 29 additions & 0 deletions crates/clickhousectl/tests/local_server_start_args_test.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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}");
}
}
2 changes: 1 addition & 1 deletion docs/guides/local-development.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<name>/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/<name>/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.

Expand Down
Loading