wait4x

Wait for services to become available

TLDR

Wait for a TCP port to accept connections

$ wait4x tcp [localhost:8080]

Wait for an HTTP endpoint to return a specific status code

$ wait4x http [https://api.example.com/health] --expect-status-code [200]

Wait for multiple services in parallel

$ wait4x tcp [127.0.0.1:5432] [127.0.0.1:6379] [127.0.0.1:27017]

Wait for a service and then run a command

$ wait4x tcp [localhost:3306] -- [./start-app.sh]

Wait for a DNS record to resolve

$ wait4x dns A [example.com] --expected-ip [93.184.216.34]

Wait for PostgreSQL to be ready

$ wait4x postgresql 'postgres://[user]:[password]@[localhost]:5432/[mydb]?sslmode=disable'

Wait for Redis with key validation

$ wait4x redis redis://[localhost]:6379 --expect-key "[status]=^ready$"

Wait for a service to become unavailable

$ wait4x tcp [localhost:8080] --invert-check

SYNOPSIS

wait4x command [options] [targets] [-- command]

wait4x is a lightweight, zero-dependency tool for waiting until services reach a ready state. It supports TCP, HTTP, DNS, and direct integrations with databases and message brokers including MySQL, PostgreSQL, MongoDB, Redis, RabbitMQ, Kafka, InfluxDB, and Temporal.Multiple targets can be specified to check services in parallel. The --invert-check flag reverses the logic to wait for services to become unavailable. After a successful check, an arbitrary command can be executed by appending -- followed by the command.wait4x supports configurable timeouts, retry intervals, and exponential backoff strategies, making it suitable for CI/CD pipelines, container orchestration, deployment scripts, and local development environments.

PARAMETERS

--timeout duration

Maximum wait duration (e.g., 30s).

--interval duration

Check frequency (default: 1s).

--invert-check

Wait for service to become unavailable instead.

--backoff-policy policy

Retry strategy (e.g., exponential).

--backoff-exponential-coefficient n

Multiplier per retry (e.g., 2.0).

--backoff-exponential-max-interval duration

Maximum interval between retries.

--expect-status-code code

Expected HTTP response code (http subcommand).

--expect-body-regex pattern

Pattern match in HTTP response body.

--expect-body-json path

JSON path validation using GJSON syntax.

--expect-body-xpath expression

XPath evaluation on HTML/XML response.

--expect-header header=value

Expected HTTP response header.

--request-header header

Custom HTTP request header (repeatable).

--expect-key key

Expected Redis key, optionally with value regex (key=regex).

--expect-table table

Expected database table (mysql/postgresql subcommands).

--expected-ip ip

Expected IP address for DNS A/AAAA records.

--expected-domain domain

Expected domain for DNS CNAME/MX records.

-n server

DNS nameserver to query.

SUBCOMMANDS

tcp address...

Wait for TCP port to accept connections.

http url...

Wait for HTTP endpoint with response validation.

dns type name

Wait for DNS record resolution (A, AAAA, CNAME, MX, NS, TXT).

mysql dsn

Wait for MySQL database readiness.

postgresql dsn

Wait for PostgreSQL availability.

mongodb uri

Wait for MongoDB connection.

redis uri

Wait for Redis availability with optional key checks.

rabbitmq uri

Wait for RabbitMQ message broker.

kafka uri...

Wait for Kafka broker readiness.

influxdb url

Wait for InfluxDB service.

temporal subcommand

Wait for Temporal workflow engine (server or worker).

exec command

Execute shell command and check exit code.

CAVEATS

Database and broker connection strings are passed as command-line arguments, which may expose credentials in process listings. Use environment variables or secrets management in production. The tool exits with a non-zero status on timeout, so scripts should handle this accordingly.

HISTORY

wait4x was created as a modern, single-binary alternative to shell-based wait scripts and tools like wait-for-it and dockerize. Written in Go, it expanded beyond simple TCP/HTTP checks to include native protocol support for popular databases and message brokers. The project is actively maintained and available via Homebrew, Alpine packages, AUR, NixOS, and Docker.