wait-for-it-http.sh

Overview

wait-for-it-http.sh is a lightweight Bash script designed to check the availability and health of an HTTP endpoint by repeatedly sending HTTP requests until the endpoint responds successfully or a timeout period elapses. This script is particularly useful in deployment pipelines, container orchestration, or startup scripts where systems need to ensure that dependent HTTP services are up and running before proceeding.

The script accepts a target URL, an optional timeout duration (in seconds), and an optional quiet mode flag. It attempts an HTTP GET request every second until it receives a successful response or the timeout is reached.

Detailed Explanation

Script Purpose

Primary function: Wait for an HTTP endpoint to become available.
Use case: Prevents race conditions where dependent services start before upstream HTTP services are ready.
Exit codes:
- 0 — The HTTP endpoint is reachable within the timeout.
- 1 — The timeout elapsed without a successful response.

Inputs (Command-line Arguments)

Argument	Description	Default
`url`	The HTTP URL to check for availability.	None (required)
`timeout`	Number of seconds to wait before giving up.	`15` seconds
`quiet`	Suppresses success message if set to `1`.	`0` (verbose)

Script Workflow and Components

Reading Arguments
```
url=$1
timeout=${2:-15}
quiet=${3:-0}
```
- $url is mandatory.
- $timeout defaults to 15 seconds if not provided.
- $quiet defaults to 0 (verbose) if not provided.
Polling Loop
```
for i in $(seq "$timeout"); do
  if curl -fs "$url" >/dev/null; then
    [[ "$quiet" -ne 1 ]] && echo "✔ $url is healthy after $i seconds"
    exit 0
  fi
  sleep 1
done
```
- The script uses a for loop iterating once per second up to the timeout value.
- Each iteration performs a curl -fs command:
  - -f makes curl fail silently on HTTP errors (4xx or 5xx).
  - -s suppresses progress output.
- If curl succeeds (exit status 0), the script:
  - Prints a success message unless in quiet mode.
  - Exits with status 0.
- If curl fails, the script waits 1 second before retrying.
Timeout Handling
If the loop completes without a successful response:
```
echo "✖ Timeout after $timeout seconds waiting for $url"
exit 1
```
- Prints a failure message.
- Exits with status 1.

Usage Examples

# Wait up to 15 seconds (default) for http://localhost:8080/health
./wait-for-it-http.sh http://localhost:8080/health

# Wait up to 30 seconds for an endpoint and be verbose
./wait-for-it-http.sh http://example.com/api/status 30

# Wait silently (no success message) for 10 seconds
./wait-for-it-http.sh http://example.com/api/status 10 1

Important Implementation Details

Portability: The script relies on standard Bash and curl, which are commonly available on Unix-like systems.
Error Handling: Uses curl -f to detect HTTP errors and treats any non-success HTTP status code as a failure.
Timeout granularity: Waits in 1-second increments; thus, actual wait time may be up to one second longer than the specified timeout.
Quiet mode: Allows silent success detection in automated scripts or CI pipelines.

Integration and Interaction

Standalone utility: Can be called directly in shell scripts, Docker containers, or CI/CD pipelines.
Service dependency checks: Often integrated in startup scripts to delay execution of dependent services until HTTP-based services are ready.
Complementary to TCP wait tools: Unlike tools that wait for TCP ports, this script ensures that the HTTP service is responding correctly rather than just listening on a port.

Visual Diagram

Below is a flowchart illustrating the main workflow and decision points of wait-for-it-http.sh.

flowchart TD
    Start(["Start"])
    InputArgs["Read Input Arguments:\nurl, timeout (default 15), quiet (default 0)"]
    LoopStart["Start Loop (i=1 to timeout)"]
    CurlCheck["Execute: curl -fs $url"]
    SuccessCheck{"curl Success?"}
    PrintSuccess["Print success message\n(if quiet != 1)"]
    ExitSuccess["Exit with code 0"]
    Sleep1["Sleep 1 second"]
    LoopIncrement["Increment i"]
    TimeoutCheck{"i > timeout?"}
    PrintTimeout["Print timeout failure message"]
    ExitFail["Exit with code 1"]

    Start --> InputArgs --> LoopStart
    LoopStart --> CurlCheck --> SuccessCheck
    SuccessCheck -- Yes --> PrintSuccess --> ExitSuccess
    SuccessCheck -- No --> Sleep1 --> LoopIncrement --> TimeoutCheck
    TimeoutCheck -- No --> LoopStart
    TimeoutCheck -- Yes --> PrintTimeout --> ExitFail

Summary

wait-for-it-http.sh is a simple yet effective script to wait for an HTTP endpoint to become responsive within a timeout period. It uses curl to perform health checks and can suppress output for silent operation. This utility is ideal for orchestrating the initialization order of dependent services in automation workflows.

If integrating this script in your system, ensure curl is installed and accessible in the environment where it will run. Adjust timeout and quiet parameters to suit your specific use cases.