Wait4X allows you to wait for a port or a service to enter the requested state

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 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 : Ensure dependencies are up before tests run Containers & orchestration : Health check services before startup : Health check services before startup Deployments : Verify readiness before rollout : 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! See Detailed Usage for advanced options and more protocols. 📖 Detailed Usage Jump to: 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 " GJSON Path Syntax. 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 currentSchema=myschema connection string parameter, for example: wait4x postgresql ' postgres://user:password@localhost:5432/mydb?sslmode=disable¤tSchema=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 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 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 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 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 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 --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: Fork the repository Create a feature branch: git checkout -b feature/your-feature-name Make your changes (add tests if possible) Run tests: make test Commit: git commit -am 'Describe your change' Push: git push origin feature/your-feature-name Open a Pull Request Found a bug or have a feature request? For more details, see CONTRIBUTING.md (if available). 💬 Community & Support 💡 Questions or ideas? Use GitHub Discussions Use GitHub Discussions 🐞 Bugs or feature requests? Open an issue 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.