Awesome
Wait4X
Introduction
Wait4X is a versatile command-line tool designed to wait for various ports or services to reach a specified state. It supports multiple protocols and services, making it an essential tool for CI/CD pipelines, automated testing, and deployment processes.
Features
- Supports various protocols:
- TCP
- HTTP
- Supports various services:
- Redis
- MySQL
- PostgreSQL
- InfluxDB
- MongoDB
- RabbitMQ
- Temporal
- Reverse Checking: Invert the sense of checking to find a free port or non-ready services
- Parallel Checking: You can define multiple inputs to be checked
- Exponential Backoff Checking: Retry using an exponential backoff approach to improve efficiency and reduce errors
- CI/CD Friendly: Well-suited to be part of a CI/CD pipeline step
- Cross Platform: One single pre-built binary for Linux, Mac OSX, and Windows
- Importable: Beside the CLI tool, Wait4X can be imported as a pkg in your Go app
- Command Execution: Execute your desired command after a successful wait
Installation
There are several ways to install Wait4X.
With Docker
Wait4X provides automatically updated Docker images within Docker Hub. It is possible to always use the latest stable tag.
Pull the image from Docker Hub:
docker pull atkrad/wait4x:latest
Then launch the wait4x container:
docker run --rm --name='wait4x' atkrad/wait4x:latest --help
From Binary
Choose the file matching your platform from the release page, then run the following commands:
Linux
curl -#LO https://github.com/atkrad/wait4x/releases/latest/download/wait4x-linux-amd64.tar.gz
tar --one-top-level -xvf wait4x-linux-amd64.tar.gz
sudo cp ./wait4x-linux-amd64/wait4x /usr/local/bin/wait4x
Mac OSX
curl -#LO https://github.com/atkrad/wait4x/releases/latest/download/wait4x-darwin-amd64.tar.gz
tar --one-top-level -xvf wait4x-darwin-amd64.tar.gz
sudo cp ./wait4x-darwin-amd64/wait4x /usr/local/bin/wait4x
Windows
curl -#LO https://github.com/atkrad/wait4x/releases/latest/download/wait4x-windows-amd64.tar.gz
tar --one-top-level -xvf wait4x-windows-amd64.tar.gz
Verify SHA256 Checksum
Wait4X generates checksums for all binaries with sha256sum to prevent against unwanted modification of binaries. To validate the archive files, download the checksum file which ends in .sha256sum for the archive file that you downloaded and use the sha256sum command line tool.
curl -#LO https://github.com/atkrad/wait4x/releases/latest/download/wait4x-linux-amd64.tar.gz.sha256sum
sha256sum --check wait4x-linux-amd64.tar.gz.sha256sum
From Package
You can find the Wait4X package in some Linux distributions.
On Alpine Linux
Wait4X is available in the Alpine Linux community repository.
apk add wait4x
On Arch Linux (AUR)
Wait4X is available in the Arch User Repository (AUR).
yay -S wait4x-bin
On NixOS
Wait4X is available in the NixOS repository.
nix-env -iA nixpkgs.wait4x
On Scoop (Windows)
Wait4X is available in the Scoop bucket.
scoop install wait4x
Examples
TCP
Check TCP connection:
wait4x tcp 127.0.0.1:9090
This command waits until the TCP port 9090 on 127.0.0.1 is available.
HTTP
Check HTTP connection and expect a specific status code:
wait4x http https://ifconfig.co --expect-status-code 200
This command waits until the URL https://ifconfig.co returns an HTTP status code of 200.
Check HTTP connection, status code, and match the response body:
wait4x http https://ifconfig.co/json --expect-status-code 200 --expect-body='"country":\s"Netherlands"'
Check an HTTP response header value:
wait4x http https://ifconfig.co --expect-header "Authorization=Token\s.+"
This command waits until the URL https://ifconfig.co returns an HTTP status code of 200 and the response header matches the provided regex pattern.
Check a body JSON value (value in expected JSON will be processed by gjson):
wait4x http https://ifconfig.co/json --expect-body-json "user_agent.product"
This command waits until the URL https://ifconfig.co/json returns an HTTP status code of 200 and the response body matches the provided GJSON path.
Check body XPath value:
wait4x http https://www.kernel.org/ --expect-body-xpath "//*[@id='tux-gear']"
This command waits until the URL https://www.kernel.org/ returns an HTTP status code of 200 and the response body matches the provided XPath path.
Set request headers:
wait4x http https://ifconfig.co --request-header "Content-Type: application/json" --request-header "Authorization: Token 123"
This command sets the Content-Type and Authorization HTTP request headers and waits until the URL https://ifconfig.co returns an HTTP status code of 200.
Redis
Check Redis connection:
wait4x redis redis://127.0.0.1:6379
This command waits until the Redis server on 127.0.0.1:6379 is ready.
Check Redis connection (with database and credentials):
wait4x redis redis://user:password@localhost:6379/1
This command waits until the Redis server on localhost:6379 is ready to accept connections to the 1 database.
Check Redis connection (Unix socket):
wait4x redis unix://user:password@/path/to/redis.sock?db=1
This command waits until the Redis server on /path/to/redis.sock is ready to accept connections to the 1 database.
Check Redis connection and match a key:
wait4x redis redis://127.0.0.1:6379 --expect-key FOO
This command waits until the Redis server on 127.0.0.1:6379 is ready and the key FOO exists.
Check Redis connection and match a pair of key and value:
wait4x redis redis://127.0.0.1:6379 --expect-key "FOO=^b[A-Z]r$"
This command waits until the Redis server on 127.0.0.1:6379 is ready and the key FOO exists and the value matches the provided regex pattern.
MySQL
Check MySQL connection (TCP):
wait4x mysql 'user:password@tcp(localhost:5555)/dbname'
This command waits until the MySQL server on 127.0.0.1:3306 is ready to accept connections to the dbname database.
Check MySQL connection (Unix socket):
wait4x mysql 'username:password@unix(/tmp/mysql.sock)/myDatabase'
This command waits until the MySQL server on /tmp/mysql.sock is ready to accept connections to the myDatabase database.
Note: Syntax for the database connection string: DSN Data Source Name.
PostgreSQL
Check PostgreSQL connection (TCP):
wait4x postgresql 'postgres://bob:secret@1.2.3.4:5432/mydatabase?sslmode=disable'
This command waits until the PostgreSQL server on 127.0.0.1:5432 is ready to accept connections to the mydatabase database.
Check PostgreSQL connection (Unix socket):
wait4x postgresql 'postgres://bob:secret@/mydb?host=/var/run/postgresql'
This command waits until the PostgreSQL server on /var/run/postgresql is ready to accept connections to the mydb database.
Note: Syntax for the database DSN: lib/pq.
InfluxDB
Check InfluxDB connection:
wait4x influxdb http://localhost:8086
This command waits until the InfluxDB server on localhost:8086 is ready.
MongoDB
Check MongoDB connection (with credentials and options):
wait4x mongodb 'mongodb://user:pass@127.0.0.1:27017/?maxPoolSize=20&w=majority'
This command waits until the MongoDB server on 127.0.0.1:27017 is ready.
RabbitMQ
Check RabbitMQ connection (with credentials and vhost):
wait4x rabbitmq 'amqp://guest:guest@127.0.0.1:5672/vhost'
This command waits until the RabbitMQ server on localhost:5672 is ready.
Temporal
Check Temporal server connection:
wait4x temporal server 127.0.0.1:7233
This command waits until the Temporal server on 127.0.0.1:7233 is ready.
Check insecure Temporal server (no TLS):
wait4x temporal server 127.0.0.1:7233 --insecure-transport
Check a task queue that has registered workers (pollers):
wait4x temporal worker 127.0.0.1:7233 --namespace __YOUR_NAMESPACE__ --task-queue __YOUR_TASK_QUEUE__
This command waits until the Temporal server on 127.0.0.1:7233 is ready and the task queue __YOUR_TASK_QUEUE__ has registered workers (pollers).
#Check a specific Temporal worker (pollers):
wait4x temporal worker 127.0.0.1:7233 --namespace __YOUR_NAMESPACE__ --task-queue __YOUR_TASK_QUEUE__ --expect-worker-identity-regex ".*@__HOSTNAME__@.*"
This command waits until the Temporal server on 127.0.0.1:7233 is ready and the task queue __YOUR_TASK_QUEUE__ has a worker (poller) with an identity matching the provided regex pattern.
Advanced Features
Exponential Backoff
Enable exponential backoff retry:
wait4x http https://ifconfig.co --expect-status-code 200 --backoff-policy exponential --backoff-exponential-max-interval 120s --timeout 120s
This command retries the HTTP connection with exponential backoff until the status code 200 is returned or the timeout of 120s is reached.
Reverse Checking
Check for a free port:
wait4x tcp 127.0.0.1:9090 --reverse
This command waits until the TCP port 9090 on 127.0.0.1 is free.
Parallel Checking
Check multiple services simultaneously:
wait4x tcp 127.0.0.1:9090 127.0.0.1:8080 127.0.0.1:9050
This command waits for the TCP ports 9090, 8080 and 9050 on 127.0.0.1 to be available.
Command Execution
You can execute a command after a successful wait. Use the -- separator to separate the wait4x command from the command to execute.
Example:
wait4x tcp 127.0.0.1:9090 -- echo "Service is up!"
This command will echo "Service is up!" after the TCP port 9090 on 127.0.0.1 is available.
Reporting Issues
If you encounter any issues, please report them here.
Submitting Pull Requests
- Fork the repository
- Create a new branch (
git checkout -b feature-branch) - Make your changes
- Commit your changes (
git commit -am 'Add new feature') - Push to the branch (
git push origin feature-branch) - Create a new Pull Request
License
This project is licensed under the Apache-2.0 license - see the LICENSE file for details.
Copyright 2019-2023 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.