wait4x.dev/v3

Wait4X

A lightweight tool to wait for services to be ready

📑 Table of Contents

• 📋 Overview
• ✨ Features
• 📥 Installation
• 🚀 Quick Start
• 📖 Detailed Usage
• ⚙️ Advanced Features
• 📦 Go Package Usage
• 🤝 Contributing
• 📄 License

📋 Overview

Wait4X is a powerful, zero-dependency tool that waits for services to be ready before continuing. It supports multiple protocols and services, making it an essential component for:

• CI/CD pipelines - Ensure dependencies are available before tests run
• Container orchestration - Health checking services before application startup
• Deployment processes - Verify system readiness before deploying
• Application initialization - Validate external service availability
• Local development - Simplify localhost service readiness checks

✨ Features

Feature	Description
Multi-Protocol Support	TCP, HTTP, DNS
Service Integrations	Redis, MySQL, PostgreSQL, MongoDB, RabbitMQ, InfluxDB, Temporal
Reverse Checking	Invert checks to find free ports or non-ready services
Parallel Checking	Check multiple services simultaneously
Exponential Backoff	Retry with increasing delays to improve reliability
CI/CD Integration	Designed for automation workflows
Cross-Platform	Single binary for Linux, macOS, and Windows
Go Package	Import into your Go applications
Command Execution	Run commands after successful checks

📥 Installation

🐳 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

🚀 Quick Start

Basic TCP Check

Wait for a port to become available:

wait4x tcp localhost:3306

HTTP Health Check

Wait for a web server with specific response:

wait4x http https://example.com/health --expect-status-code 200 --expect-body-regex '"status":"UP"'

Multi-Service Check (Parallel)

Wait for multiple services simultaneously:

wait4x tcp 127.0.0.1:5432 127.0.0.1:6379 127.0.0.1:27017

Database Readiness

Wait for PostgreSQL to be ready:

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

Execute After Success

Run a command after services are ready:

wait4x tcp localhost:8080 -- echo "Service is ready!" && ./start-app.sh

📖 Detailed Usage

🌐 HTTP Checking

Checking with Status Code

Wait for an HTTP endpoint to return a specific status code:

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

Checking Response Body with Regex

Wait for an HTTP endpoint to return a response that matches a regex pattern:

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

Checking Response Body with JSON Path

Wait for a specific JSON field to exist or have a specific value:

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

This uses GJSON Path Syntax for powerful JSON querying.

Checking Response Body with XPath

Wait for an HTML/XML response to match an XPath query:

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

Custom Request Headers

Send specific headers with your HTTP request:

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

Checking Response Headers

Wait for a response header to match a pattern:

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

🔍 DNS Checking

Check A Records

# Basic existence check
wait4x dns A example.com

# With expected IP
wait4x dns A example.com --expected-ip 93.184.216.34

# Using specific nameserver
wait4x dns A example.com --expected-ip 93.184.216.34 -n 8.8.8.8

Check AAAA Records (IPv6)

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

Check CNAME Records

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

Check MX Records

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

Check NS Records

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

Check TXT Records

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

💾 Database Checking

MySQL

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

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

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'

MongoDB

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

Redis

# Basic connection
wait4x redis redis://localhost:6379

# With authentication and database 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 specific 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 (with namespace and 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-.*"

⚙️ Advanced Features

⏱️ Timeout & Retry Control

Setting Timeout

Limit the total time Wait4X will wait:

wait4x tcp localhost:8080 --timeout 30s

Setting Interval

Control how frequently Wait4X retries:

wait4x tcp localhost:8080 --interval 2s

Exponential Backoff

Use exponential backoff for more efficient retries:

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

↔️ Reverse Checking

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

⚡ Command Execution

Execute commands after successful wait:

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

Chain multiple commands:

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

🔄 Parallel Checking

Wait for multiple services simultaneously:

wait4x tcp localhost:3306 localhost:6379 localhost:27017

Note that this waits for ALL specified services to be ready.

📦 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.

🤝 Contributing

🐛 Reporting Issues

If you encounter a bug or have a feature request, please open an issue:

• Report a bug
• Request a feature

Please include as much information as possible, including:

• Wait4X version
• Command-line arguments
• Expected vs. actual behavior
• Any error messages

💻 Code Contributions

• Fork the repository
• Create a feature branch: git checkout -b feature/your-feature-name
• Make your changes
• Add tests for your changes
• Run the tests: make test
• Commit your changes: git commit -am 'Add awesome feature'
• Push the branch: git push origin feature/your-feature-name
• Create a Pull Request

📄 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.