Wait4x

<div align="center"> <img src="logo.png" alt="Wait4X Logo" width="120"> <h1>Wait4X</h1> <p><b>Wait4X</b> is a lightweight, zero-dependency tool to wait for services to be ready. Perfect for CI/CD, containers, and local development.</p>

<a href="https://github.com/wait4x/wait4x/actions/workflows/ci.yaml"><img src="https://img.shields.io/github/actions/workflow/status/wait4x/wait4x/ci.yaml?branch=main&style=flat-square" alt="CI Status"></a> <a href="https://coveralls.io/github/wait4x/wait4x?branch=main"><img src="https://img.shields.io/coverallsCoverage/github/wait4x/wait4x?branch=main&style=flat-square" alt="Coverage"></a> <a href="https://goreportcard.com/report/wait4x.dev/v3"><img src="https://goreportcard.com/badge/wait4x.dev/v3?style=flat-square" alt="Go Report"></a> <a href="https://hub.docker.com/r/wait4x/wait4x"><img src="https://img.shields.io/docker/pulls/wait4x/wait4x?logo=docker&style=flat-square" alt="Docker Pulls"></a> <a href="https://github.com/wait4x/wait4x/releases"><img src="https://img.shields.io/github/downloads/wait4x/wait4x/total?logo=github&style=flat-square" alt="Downloads"></a> <a href="https://repology.org/project/wait4x/versions"><img src="https://img.shields.io/repology/repositories/wait4x?style=flat-square" alt="Packaging"></a> <a href="https://pkg.go.dev/wait4x.dev/v3"><img src="https://img.shields.io/badge/reference-007D9C.svg?style=flat-square&logo=go&logoColor=white&labelColor=5C5C5C" alt="Go Reference"></a>

</div>

---

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

<details> <summary><b>🐳 With Docker</b></summary>

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

</details> <details> <summary><b>📦 From Package Managers</b></summary>

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

</details> <details> <summary><b>📦 From Binary</b></summary>

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

</details> <details> <summary><b>🐹 Go Install (for Go users)</b></summary>

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.

</details>

🚀 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: