Wait4X

Wait4X is a lightweight, zero-dependency tool to wait for services to be ready. Perfect for CI/CD, containers, and local development.

---

📑 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 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

📦 From Package Managers

Alpine Linux:

apk add wait4x

Arch Linux (AUR):

yay -S wait4x-bin

NixOS:

nix-env -iA nixpkgs.wait4x

Windows (Scoop):

scoop install wait4x

🐹 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 a port to become free:

  wait4x tcp localhost:8080 --invert-check

• Wait for a service to stop:

  wait4x http https://service.local/health --expect-status-code 200 --invert-check

  Use for shutdown/cleanup workflows or to ensure a port is not in use.

---

Command Execution

Run a command after a successful check (great for CI/CD or startup scripts).

• Run a script after waiting:

  wait4x tcp localhost:3306 -- ./deploy.sh

• Chain multiple commands:

  wait4x redis redis://localhost:6379 -- echo "Redis is ready" && ./init-redis.sh

  Automate your workflow after dependencies are ready.

---

Parallel Checking

Wait for multiple services at once (all must be ready to continue).

• Check several services in parallel:

  wait4x tcp localhost:3306 localhost:6379 localhost:27017

  Use for microservices, integration tests, or complex startup dependencies.

---

See CLI Reference for all available flags and options.

📦 Go Package Usage

🔌 Installing as a Go Package

Add Wait4X to your Go project:

go get wait4x.dev/v3

Import the packages you need:

import (
    "context"
    "time"

    "wait4x.dev/v3/checker/tcp"      // TCP checker
    "wait4x.dev/v3/checker/http"     // HTTP checker
    "wait4x.dev/v3/checker/redis"    // Redis checker
    "wait4x.dev/v3/waiter"           // Waiter functionality
)

🌟 Example: TCP Checking

// Create a context with timeout
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

// Create a TCP checker
tcpChecker := tcp.New("localhost:6379", tcp.WithTimeout(5*time.Second))

// Wait for the TCP port to be available
err := waiter.WaitContext(
    ctx,
    tcpChecker,
    waiter.WithTimeout(time.Minute),
    waiter.WithInterval(2*time.Second),
    waiter.WithBackoffPolicy("exponential"),
)
if err != nil {
    log.Fatalf("Failed to connect: %v", err)
}

fmt.Println("Service is ready!")

🌟 Example: HTTP with Advanced Options

// Create HTTP headers
headers := http.Header{}
headers.Add("Authorization", "Bearer token123")
headers.Add("Content-Type", "application/json")

// Create an HTTP checker with validation
checker := http.New(
    "https://api.example.com/health",
    http.WithTimeout(5*time.Second),
    http.WithExpectStatusCode(200),
    http.WithExpectBodyJSON("status"),
    http.WithExpectBodyRegex(`"healthy":\s*true`),
    http.WithExpectHeader("Content-Type=application/json"),
    http.WithRequestHeaders(headers),
)

// Wait for the API to be ready
err := waiter.WaitContext(ctx, checker, options...)

🌟 Example: Parallel Service Checking

// Create checkers for multiple services
checkers := []checker.Checker{
    redis.New("redis://localhost:6379"),
    postgresql.New("postgres://user:pass@localhost:5432/db"),
    http.New("http://localhost:8080/health"),
}

// Wait for all services in parallel
err := waiter.WaitParallelContext(
    ctx,
    checkers,
    waiter.WithTimeout(time.Minute),
    waiter.WithBackoffPolicy(waiter.BackoffPolicyExponential),
)

🌟 Example: Custom Checker Implementation

// Define your custom checker
type FileChecker struct {
    filePath string
    minSize  int64
}

// Implement Checker interface
func (f *FileChecker) Identity() (string, error) {
    return fmt.Sprintf("file(%s)", f.filePath), nil
}

func (f *FileChecker) Check(ctx context.Context) error {
    // Check if context is done
    select {
    case <-ctx.Done():
        return ctx.Err()
    default:
        // Continue checking
    }

    fileInfo, err := os.Stat(f.filePath)
    if err != nil {
        if os.IsNotExist(err) {
            return checker.NewExpectedError(
                "file does not exist",
                err,
                "path", f.filePath,
            )
        }
        return err
    }

    if fileInfo.Size() < f.minSize {
        return checker.NewExpectedError(
            "file is smaller than expected",
            nil,
            "path", f.filePath,
            "actual_size", fileInfo.Size(),
            "expected_min_size", f.minSize,
        )
    }

    return nil
}

For more detailed examples with complete code, see the examples/pkg directory. Each example is in its own directory with a runnable main.go file.

📝 CLI Reference

Wait4X provides a flexible CLI with many commands and options. Here is a summary of the main commands and global flags. For the most up-to-date and detailed information, use the built-in help:

wait4x --help
wait4x <command> --help

Main Commands

Command	Description
tcp	Wait for a TCP port to become available
http	Wait for an HTTP(S) endpoint with advanced checks
dns	Wait for DNS records (A, AAAA, CNAME, MX, etc.)
kafka	Wait for Kafka server
mysql	Wait for a MySQL database to be ready
postgresql	Wait for a PostgreSQL database to be ready
mongodb	Wait for a MongoDB database to be ready
redis	Wait for a Redis server or key
influxdb	Wait for an InfluxDB server
rabbitmq	Wait for a RabbitMQ server
temporal	Wait for a Temporal server or worker
exec	Wait for a shell command to succeed

Each command supports its own set of flags. See examples above or run wait4x <command> --help for details.

Global Flags

Flag	Description
--timeout, -t	Set the maximum wait time (e.g., 30s, 2m)
--interval, -i	Set the interval between checks (default: 1s)
--invert-check	Invert the check (wait for NOT ready)
--backoff-policy	Retry policy: linear or exponential
--backoff-exponential-coefficient	Exponential backoff multiplier (default: 2.0)
--backoff-exponential-max-interval	Max interval for exponential backoff
--quiet	Suppress output except errors
--no-color	Disable colored output

Getting Help

For a full list of commands and options, run:

wait4x --help
wait4x <command> --help

🤝 Contributing

We welcome contributions of all kinds! Whether you want to fix a bug, add a feature, improve documentation, or help others, you're in the right place.

How to contribute:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes (add tests if possible)
4. Run tests: make test
5. Commit: git commit -am 'Describe your change'
6. Push: git push origin feature/your-feature-name
7. Open a Pull Request

Found a bug or have a feature request?

• Report an issue

For more details, see CONTRIBUTING.md (if available).

💬 Community & Support

• 💡 Questions or ideas? Use GitHub Discussions
• 🐞 Bugs or feature requests? Open an issue
• ⭐ Star the repo to support the project!

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Copyright 2019-2025 The Wait4X Authors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Credits

The project logo is based on the "Waiting Man" character (Zhdun) and is used with attribution to the original creator.