readiness.sh

Overview

`readiness.sh` is a lightweight shell script designed as a readiness probe for a service component named **blockbook**. Its primary purpose is to determine whether the blockbook service is ready to accept traffic by checking its synchronization status. The script is intended to be used in container orchestration environments (like Kubernetes) as a readiness check endpoint.

The script performs the following key functions:

Checks if readiness probing is explicitly disabled by the presence of a specific file.
Queries the local blockbook service API to retrieve the current synchronization status.
Returns appropriate exit codes and messages based on whether the service is ready (synced) or still syncing.

This readiness check helps orchestrators decide if the service can receive traffic or if it should wait until synchronization is complete.

Detailed Explanation

Script Logic

The script performs a series of conditional checks and makes an HTTP request to the blockbook API using `curl`, then parses the JSON response with `jq`.

Variables

DISABLE_READINESS_PROBE
Path to a file (/data/disable_readiness) that, if exists, disables the readiness check, immediately marking the service as ready.
STATUS
Stores the JSON response from the blockbook API endpoint.
IN_SYNC
Extracted boolean string ("true" or "false") indicating if blockbook is fully synchronized.

Workflow & Steps

Check for readiness disable file
```
if [[ -f "$DISABLE_READINESS_PROBE" ]]; then
  echo "readiness probe disabled"
  exit 0
fi
```
If the file /data/disable_readiness exists, the script exits with code 0 (success), indicating readiness is disabled and the pod/service is considered ready.
Check blockbook API availability and get status
```
STATUS=$(curl -sf http://localhost:8001/api/v2) || exit 1
```
Performs a silent, fail-fast HTTP GET request to the blockbook API endpoint at localhost:8001/api/v2. If the request fails, the script exits with code 1 (not ready).
Parse synchronization status
```
IN_SYNC=$(echo $STATUS | jq -r '.blockbook.inSync')
```
Parses the JSON response to extract the .blockbook.inSync field, which indicates whether blockbook is synced.
Evaluate synchronization result
```
if [[ $IN_SYNC == "true" ]]; then
    echo "blockbook is synced"
    exit 0
fi

echo "blockbook is still syncing"
exit 1
```
If blockbook is synced, the script returns success (exit 0), otherwise returns failure (exit 1) indicating the service is not ready.

Exit Codes

0 — Service is ready (either disabled readiness probe or blockbook is synced).
1 — Service is not ready (blockbook is syncing or API unreachable).

Usage Example

This script is typically invoked by container orchestrators as a readiness probe command:

./readiness.sh

If the script exits with 0, the orchestrator considers the pod ready.
If the script exits with 1, the orchestrator marks the pod as not ready and may delay routing traffic.

Important Implementation Details

Dependency on External Tools:
The script relies on curl to perform HTTP requests and jq to parse JSON. Both tools must be installed in the container/environment where this script runs.
File-based readiness disable:
The presence of /data/disable_readiness file allows manual or automated disabling of the readiness check without changing the script or container configuration, useful for maintenance or debugging.
Fail-fast behavior:
The curl -sf options ensure the script immediately fails if the blockbook API is unreachable or returns an error status, preventing false positives.
JSON Parsing:
Only the .blockbook.inSync boolean field is checked to determine readiness, simplifying the logic but assuming the API response structure is stable.

Interaction with Other System Components

Blockbook Service:
The script queries the blockbook service’s local API (http://localhost:8001/api/v2) to fetch synchronization status. Blockbook is a blockchain indexing service, and its sync status is critical for determining readiness.
Container Orchestrator (e.g., Kubernetes):
The script is designed as a readiness probe script that Kubernetes or a similar orchestrator can execute to decide if the pod/container is ready to receive traffic.
Filesystem:
Checks for the existence of a file /data/disable_readiness to optionally disable readiness checks.

Mermaid Flowchart Diagram

flowchart TD
    A[Start readiness.sh] --> B{File /data/disable_readiness exists?}
    B -- Yes --> C[Print "readiness probe disabled"]
    C --> D[Exit 0 (Ready)]
    B -- No --> E[HTTP GET http://localhost:8001/api/v2]
    E --> F{Request successful?}
    F -- No --> G[Exit 1 (Not ready)]
    F -- Yes --> H[Parse .blockbook.inSync from JSON]
    H --> I{inSync == "true"?}
    I -- Yes --> J[Print "blockbook is synced"]
    J --> D
    I -- No --> K[Print "blockbook is still syncing"]
    K --> G

Summary

`readiness.sh` is a simple but effective readiness probe script that checks if the blockbook service is synced and ready. It provides an easy toggle to disable readiness checks through a file, uses robust HTTP and JSON parsing tools, and integrates smoothly with container orchestration environments to improve service reliability and traffic routing decisions.