Wait4X service readiness checks for TCP, HTTP, and databases

Wait4X readiness gates for automation scripts

Wait4X solves a narrow but recurring automation problem: a process must not continue merely because another process exists. A database container may have started while its server still rejects connections, an HTTP service may expose a port before its health endpoint returns the expected response, or a queue may accept TCP traffic before the application can consume messages. The CLI waits and retries until the requested condition succeeds.

The intended users are engineers working with CI/CD pipelines, container startup sequences, deployment scripts, and local development. A test job can wait for its database dependency, while an application entrypoint can wait for an API. The README also identifies Redis, MySQL, PostgreSQL, MongoDB, Kafka, RabbitMQ, InfluxDB, and Temporal as service integrations. This matters because a generic TCP connection proves that something accepts a socket, not that the expected service protocol is usable.

Wait4X is both a command-line tool and a Go package. The repository is organized around checker and waiter directories, with command entry points under cmd. Based on that layout and the documented commands, checking is separated from the retrying wait operation rather than being embedded in shell scripts. The result is a small readiness gate that can return control or run a command after its conditions are met.

How Wait4X turns protocol checks into retry gates

The documented command surface begins with a checker type, an address or connection string, and an expected state. A TCP check accepts a host and port. An HTTP check can expect a status code and body pattern. A DNS check names the record type and domain. Service checks accept formats specific to that service, such as a PostgreSQL URL or a Redis URL with an expected key.

Multiple TCP targets can be supplied in one invocation. The README describes this as a parallel check, so the command acts as a gate for the listed services rather than merely checking them serially. The same command model also supports `--invert-check`, which changes a positive condition such as port availability into its inverse. That is useful when the desired state is that a port becomes free, but it should not be confused with a health check.

Retries are part of the design. The README lists exponential backoff among the features, so attempts are spaced increasingly rather than performed in a tight loop. A successful check releases the gate. A command placed after `--` runs only after the check succeeds, as shown by the documented pattern for starting an application. The README does not document every timeout, retry count, logging field, or exit code, so engineers needing exact automation behavior must inspect the CLI reference or command implementation rather than assume conventional defaults.

Installing Wait4X and running the first port check

Package-manager installation is the shortest documented route when the target platform is supported. The commands differ by operating system, and the project also publishes Docker images. For Go users, the README describes a source installation command, although its stated Go 1.16+ requirement conflicts with the repository's current go.mod declaration of Go 1.26.0. Treat the module file as the stricter source-build constraint.

On macOS, Homebrew installs the packaged binary:

brew install wait4x

After installation, verify that the CLI is reachable through `PATH`, then wait for MySQL on the conventional local example endpoint:

wait4x tcp localhost:3306

The command should remain in progress while the target refuses connections and exit after the TCP endpoint becomes available. It does not establish that MySQL is ready for application queries; the separate `mysql` checker is the documented option for that service.

For a container-only workflow, the project directs users to Docker Hub and supplies these commands:

docker pull wait4x/wait4x:latest
docker run --rm wait4x/wait4x:latest --help

The first command retrieves the image, and the second runs its help output in a temporary container. Users who need reproducible upgrades should pin an image tag or digest in automation. The README labels `latest` as automatically updated but does not define a retention policy for image versions.

HTTP and service-specific checks beyond open ports

An HTTP readiness gate is more informative than a port check because the documented command can assert a status code and a regular expression over the response body. The README gives this example:

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

This form waits for both a successful HTTP status and a body indicating that the service reports itself up. The quoted regex is part of the command syntax, not a required replacement value. It illustrates the difference between infrastructure reachability and application readiness.

Database-oriented checks use their native connection formats. PostgreSQL accepts a URL:

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

Redis can combine endpoint readiness with an expected key:

wait4x redis redis://localhost:6379 --expect-key "session:active"

That key assertion waits for data that must exist, so it is a different class of check from merely connecting. It can be the wrong choice when key creation is controlled by later application logic. In that case it creates a dependency between startup and the process that is supposed to create the key.

The README also lists DNS checks and integrations for MySQL, MongoDB, Kafka, RabbitMQ, InfluxDB, and Temporal. The README does not describe authentication options or service-specific readiness queries for each integration, so connection strings should not be assumed to prove every application-level invariant.

Go package usage and compatibility constraints

The repository is a Go module named `wait4x.dev/v3`, with reusable code organized under `checker` and `waiter`. The README explicitly includes Go package usage, and the `examples/pkg` directory provides a package-oriented example area. This makes Wait4X usable when a deployment program needs a programmatic gate instead of spawning the CLI.

The documented Go installation command installs the command package from the latest module version:

go install wait4x.dev/v3/cmd/wait4x@latest

It places `wait4x` in `$GOPATH/bin` or `$HOME/go/bin`, which must already be available to the shell or CI environment. The current `go.mod` declares Go 1.26.0. The README still says that Go 1.16+ is sufficient, creating a documented compatibility conflict. A project should resolve this before automating installation, especially because `go install` follows the module's declared language version and current build configuration.

There is also a build-time version difference worth noting. The Dockerfile uses `golang:1.27.1-alpine3.24` for its build stage and disables CGO, producing a static binary copied into a scratch image. That file describes the container build, not a promise that a Go 1.16 toolchain can reproduce the current source tree.

Wait4X limits and the bespoke retry-loop alternative

The main limitation is that Wait4X checks only the condition encoded by its command. A successful TCP check can occur before a database completes schema initialization. A successful HTTP status can come from a process that cannot yet reach its dependencies. Conversely, strict checks can deadlock startup when the condition is normally created by the application that Wait4X is supposed to release. The Redis key example makes this boundary clear.

Wait4X also does not document rollback behavior or recovery policy. It is a waiting tool, not a supervisor. The README shows how to run a command after success, but it does not say that Wait4X restarts a failed application, repairs a service, or rolls back a deployment.

The practical alternative is a custom retry loop embedded in the pipeline or application. Such code can combine several conditions, perform application-specific queries, expose structured telemetry, and make a different decision after each failure. Its cost is duplicated retry logic and harder portability across shell, CI, and container environments. Wait4X centralizes common protocol checks and offers consistent command syntax instead. For a simple port, endpoint, or service gate, that is a meaningful difference; for a domain-specific startup contract, the custom loop may represent the actual requirement more accurately.

Maintenance, releases, and Apache-2.0 obligations

The repository is not archived, and its last push was on 2026-10-16. Recent releases include v3.7.2 on 2026-09-25, v3.7.1 on 2026-08-19, and v3.7.0 on 2026-08-19. These facts indicate recent project activity, but the README does not publish a long-term support policy or a formal upgrade-compatibility window.

The README provides Linux release archives and a SHA-256 checksum file. This permits an administrator to verify the downloaded archive before moving the binary into `/usr/local/bin`. The checksum workflow is:

curl -LO https://github.com/wait4x/wait4x/releases/latest/download/wait4x-linux-amd64.tar.gz.sha256sum
sha256sum --check wait4x-linux-amd64.tar.gz.sha256sum

These commands retrieve the documented checksum file and verify the archive already downloaded. The README does not give a rollback procedure or explain compatibility between v3 patch releases, so upgrades should not be assumed non-breaking outside what the release notes state.

Wait4X is licensed under Apache-2.0. The repository includes a LICENSE file and its README lists the same license. Anyone redistributing the binary or incorporating the Go package should review that file for the applicable notices, license text, and modification requirements. This is a repository fact, not legal advice.

Editorial conclusion

Adopt Wait4X when scripts need one repeatable command for port, endpoint, or service readiness, including Go applications that import its package. Do not choose it as a substitute for transaction-level health checks or an orchestrator that owns retry policy. Before adoption, verify the exact checks supported by your service, the exit behavior for each failure mode, and the Go version required by the selected installation method. The current repository declares Go 1.26.0 in go.mod, so that requirement must be checked before using the Go package or building the repository.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. wait4x/wait4x on GitHub