wait4x

---

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Usage Examples
• Advanced Features
• Go Package Usage
• CLI Reference
• Contributing
• License

---

Overview

Wait4X helps you wait for services (databases, APIs, message queues, etc.) to be ready before your app or script continues. It's ideal for:

• CI/CD pipelines: Ensure dependencies are up before tests run
• Containers & orchestration: Health check services before startup
• Deployments: Verify readiness before rollout
• Local development: Simplify service readiness checks

Features

Feature Description Multi-Protocol TCP, HTTP, DNS, and more Service Integrations Redis, MySQL, PostgreSQL, MongoDB, Kafka, RabbitMQ, InfluxDB, Temporal Reverse/Parallel Checking Invert checks or check multiple services at once Exponential Backoff Smarter retries Cross-Platform Single binary for Linux, macOS, Windows Go Package Use as a Go library Command Execution Run commands after checks

Installation

After installing, jump to Quick Start to try it out!

With Docker

Wait4X provides automatically updated Docker images within Docker Hub:

# Pull the image
docker pull wait4x/wait4x:latest

# Run the container
docker run --rm wait4x/wait4x:latest --help

From Package Managers

macOS:

brew install wait4x

Alpine Linux:

apk add wait4x

Arch Linux (AUR):

yay -S wait4x-bin

NixOS:

nix-env -iA nixpkgs.wait4x

Windows (Scoop):

scoop install wait4x

From Binary

Download the appropriate version for your platform from the releases page:

Linux:

curl -LO https://github.com/wait4x/wait4x/releases/latest/download/wait4x-linux-amd64.tar.gz
tar -xf wait4x-linux-amd64.tar.gz -C /tmp
sudo mv /tmp/wait4x-linux-amd64/wait4x /usr/local/bin/

macOS:

curl -LO https://github.com/wait4x/wait4x/releases/latest/download/wait4x-darwin-amd64.tar.gz
tar -xf wait4x-darwin-amd64.tar.gz -C /tmp
sudo mv /tmp/wait4x-darwin-amd64/wait4x /usr/local/bin/

Windows:

curl -LO https://github.com/wait4x/wait4x/releases/latest/download/wait4x-windows-amd64.tar.gz
tar -xf wait4x-windows-amd64.tar.gz
# Move to a directory in your PATH

Verify checksums:

curl -LO https://github.com/wait4x/wait4x/releases/latest/download/wait4x-linux-amd64.tar.gz.sha256sum
sha256sum --check wait4x-linux-amd64.tar.gz.sha256sum

Go Install (for Go users)

You can install Wait4X directly from source using Go (requires Go 1.16+):

go install wait4x.dev/v3/cmd/wait4x@latest

This will place the wait4x binary in your $GOPATH/bin or $HOME/go/bin directory.

Quick Start

Get started in seconds! After installing, try these common checks:

Wait for a TCP Port

wait4x tcp localhost:3306

HTTP Health Check

wait4x http https://example.com/health --expect-status-code 200

Wait for Multiple Services (Parallel)

wait4x tcp 127.0.0.1:5432 127.0.0.1:6379 127.0.0.1:27017

Database Readiness

wait4x postgresql 'postgres://user:pass@localhost:5432/mydb?sslmode=disable'

For more, see Usage Examples or Detailed Usage.

Usage Examples

Here are some of the most useful Wait4X commands. Click the links for more details!

• TCP: Wait for a port to be available
  wait4x tcp localhost:8080
• HTTP: Wait for a web endpoint with status code and body check
  wait4x http https://api.example.com/health --expect-status-code 200 --expect-body-regex '"status":"UP"'
• DNS: Wait for DNS A record
  wait4x dns A example.com
• MySQL: Wait for MySQL DB
  wait4x mysql 'user:password@tcp(localhost:3306)/mydb'
• Redis: Wait for Redis and check for a key
  wait4x redis redis://localhost:6379 --expect-key "session:active"
• Run a command after check:
  wait4x tcp localhost:8080 -- ./start-app.sh
• Reverse check (wait for port to be free):
  wait4x tcp localhost:8080 --invert-check
• Parallel check:
  wait4x tcp localhost:3306 localhost:6379 localhost:27017

See Detailed Usage for advanced options and more protocols.

Detailed Usage

Jump to:

• HTTP Checking
• DNS Checking
• Database Checking
• Message Queue Checking
• Shell Command

---

HTTP Checking

Wait for an HTTP(S) endpoint to be ready, with flexible validation options.

• Status code check:

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

• Response body regex:

  wait4x http https://api.example.com/status --expect-body-regex '"status":\s*"healthy"'
  

• JSON path check:

  wait4x http https://api.example.com/status --expect-body-json "services.database.status"
  

  Uses GJSON Path Syntax.
• XPath check:

  wait4x http https://example.com --expect-body-xpath "//div[@id='status']"
  

• Custom request headers:

  wait4x http https://api.example.com \
    --request-header "Authorization: Bearer token123" \
    --request-header "Content-Type: application/json"
  

• Response header check:

  wait4x http https://api.example.com --expect-header "Content-Type=application/json"
  

• TLS options:

  wait4x http https://www.wait4x.dev --cert-file /path/to/certfile --key-file /path/to/keyfile
  wait4x http https://www.wait4x.dev --ca-file /path/to/cafile
  

---

DNS Checking

Check for various DNS record types and values.

• A record:

  wait4x dns A example.com
  wait4x dns A example.com --expected-ip 93.184.216.34
  wait4x dns A example.com --expected-ip 93.184.216.34 -n 8.8.8.8
  

• AAAA record (IPv6):

  wait4x dns AAAA example.com --expected-ip "2606:2800:220:1:248:1893:25c8:1946"
  

• CNAME record:

  wait4x dns CNAME www.example.com --expected-domain example.com
  

• MX record:

  wait4x dns MX example.com --expected-domain "mail.example.com"
  

• NS record:

  wait4x dns NS example.com --expected-nameserver "ns1.example.com"
  

• TXT record:

  wait4x dns TXT example.com --expected-value "v=spf1 include:_spf.example.com ~all"
  

---

Database Checking

Check readiness for popular databases.

MySQL

• TCP connection:

  wait4x mysql 'user:password@tcp(localhost:3306)/mydb'
  

• Unix socket:

  wait4x mysql 'user:password@unix(/var/run/mysqld/mysqld.sock)/mydb'
  

• Check if a table exists:

  wait4x mysql 'user:password@tcp(localhost:3306)/mydb' --expect-table my_table
  

PostgreSQL

• TCP connection:

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

• Unix socket:

  wait4x postgresql 'postgres://user:password@/mydb?host=/var/run/postgresql'
  

• Check if a table exists:

  wait4x postgresql 'postgres://user:password@localhost:5432/mydb?sslmode=disable' --expect-table my_table
  

  If you need to specify a schema for the table existence check, you can use the currentSchema=myschema connection string parameter, for example:

  wait4x postgresql 'postgres://user:password@localhost:5432/mydb?sslmode=disable&currentSchema=myschema' --expect-table my_table
  

MongoDB

wait4x mongodb 'mongodb://user:password@localhost:27017/mydb?maxPoolSize=20'

Redis

• Basic connection:

  wait4x redis redis://localhost:6379
  

• With authentication and DB selection:

  wait4x redis redis://user:password@localhost:6379/0
  

• Check for key existence:

  wait4x redis redis://localhost:6379 --expect-key "session:active"
  

• Check for key with value (regex):

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

InfluxDB

wait4x influxdb http://localhost:8086

---

Message Queue Checking

RabbitMQ

wait4x rabbitmq 'amqp://guest:guest@localhost:5672/myvhost'

Temporal

• Server check:

  wait4x temporal server localhost:7233
  

• Worker check (namespace & task queue):

  wait4x temporal worker localhost:7233 \
    --namespace my-namespace \
    --task-queue my-queue
  

• Check for specific worker identity:

  wait4x temporal worker localhost:7233 \
    --namespace my-namespace \
    --task-queue my-queue \
    --expect-worker-identity-regex "worker-.*"
  

Kafka

• Basic Kafka broker readiness check:

  wait4x kafka kafka://localhost:9092
  

• Check Kafka broker with SCRAM authentication:

  wait4x kafka kafka://user:pass@localhost:9092?authMechanism=scram-sha-256
  

• Wait for multiple Kafka brokers (cluster) to be ready:

  wait4x kafka kafka://broker1:9092 kafka://broker2:9092 kafka://broker3:9092
  

Notes:

• The connection string format is: kafka://[user:pass@]host:port[?option=value&...]
• Supported options: authMechanism (scram-sha-256, scram-sha-512)

---

Shell Command

Wait for a shell command to succeed or return a specific exit code.

• Check connection:

  wait4x exec 'ping wait4x.dev -c 2'
  

• Check file existence:

  wait4x exec 'ls target/debug/main' --exit-code 2
  

---

See Advanced Features for timeout, retry, backoff, and parallel/reverse checking options.

⚙️ Advanced Features

Jump to:

• Timeout & Retry Control
• Exponential Backoff
• Reverse Checking
• Command Execution
• Parallel Checking

---

Timeout & Retry Control

Control how long Wait4X waits and how often it checks.

• Set a timeout:

  wait4x tcp localhost:8080 --timeout 30s
  

  Waits up to 30 seconds before giving up.

• Set check interval:

  wait4x tcp localhost:8080 --interval 2s
  

  Checks every 2 seconds (default: 1s).

---

Exponential Backoff

Retry with increasing delays for more efficient waiting (useful for slow-starting services).

• Enable exponential backoff:

  wait4x http https://api.example.com \
    --backoff-policy exponential \
    --backoff-exponential-coefficient 2.0 \
    --backoff-exponential-max-interval 30s
  

  Doubles the wait time between retries, up to 30 seconds.

---

Reverse Checking

Wait for a service to become unavailable (e.g., port to be free, service to stop).

• **Wait for