readiness.sh

Overview

`readiness.sh` is a lightweight shell script designed to serve as a readiness probe for a service that uses a local Blockbook API. Its primary function is to determine if the Blockbook instance running on `localhost` is fully synchronized ("in sync") and ready to serve traffic. This script is typically used in container orchestration environments (e.g., Kubernetes) to indicate whether the application is ready to receive requests.

The script performs the following key actions:

• Checks if readiness probing is explicitly disabled via a file flag.

• Queries the local Blockbook API endpoint to retrieve current synchronization status.

• Parses the API response to determine if Blockbook is in sync.

• Returns an appropriate exit code (0 for ready, 1 for not ready) for integration with orchestrators.

Detailed Explanation

Script Variables and Constants

• DISABLE_READINESS_PROBE=/data/disable_readiness
  Path to a file that, if present, disables readiness probing. Useful for manual overriding or emergency bypass.

Main Logic Flow

1. Readiness Probe Disable Check

   if [[ -f "$DISABLE_READINESS_PROBE" ]]; then
     echo "readiness probe disabled"
     exit 0
   fi
   

   • If the file /data/disable_readiness exists, the script immediately outputs "readiness probe disabled" and exits with status code 0 indicating readiness (probe disabled means always ready).

   • This allows manual control over readiness status without modifying the service or the probe itself.

2. Fetch Blockbook Status

   STATUS=$(curl -sf http://localhost:8001/api/v2) || exit 1
   

   • Uses curl to silently (-s) fetch JSON status from Blockbook's local API on port 8001.

   • The -f flag makes curl fail silently on HTTP errors.

   • If the request fails, the script immediately exits with code 1 indicating the service is not ready.

3. Parse Synchronization Status

   IN_SYNC=$(echo $STATUS | jq -r '.blockbook.inSync')
   

   • Pipes the JSON response to jq to extract the .blockbook.inSync boolean field.

   • The -r flag outputs raw string without quotes.

   • This field indicates if Blockbook is fully synchronized with the blockchain.

4. Determine Readiness

   if [[ $IN_SYNC == "true" ]]; then
       echo "blockbook is synced"
       exit 0
   fi
   
   echo "blockbook is still syncing"
   exit 1
   

   • If inSync is "true", the script prints "blockbook is synced" and exits with code 0 (ready).

   • Otherwise, it prints "blockbook is still syncing" and exits with code 1 (not ready).

Usage Example

This script is intended to be used as a Kubernetes readiness probe command or similar health check mechanism.

• Example readiness probe snippet in a Kubernetes Pod spec:

readinessProbe:
  exec:
    command:
      - /bin/bash
      - /path/to/readiness.sh
  initialDelaySeconds: 10
  periodSeconds: 15

• Manual run on the host or container to check readiness:

bash readiness.sh
# Output: "blockbook is synced" (if ready) or "blockbook is still syncing"
# Exit code: 0 if ready, 1 if not

• Disable readiness probe by creating the disable file:

touch /data/disable_readiness
bash readiness.sh
# Output: "readiness probe disabled"
# Exit code: 0

Implementation Details

• The script relies on standard UNIX utilities: curl for HTTP requests and jq for JSON parsing.

• The use of curl -sf ensures the script fails fast on unreachable endpoints or HTTP errors.

• The readiness logic is a simple boolean check on .blockbook.inSync from the API response.

• The disable file mechanism provides a quick override feature without stopping the probe or the service.

• Exit codes follow convention:

  • 0 = ready (success)

  • 1 = not ready (failure)

• The script assumes Blockbook API runs locally on port 8001 and the relevant JSON path exists.

Interaction with Other System Components

• Blockbook Service: The primary dependency; readiness.sh queries the Blockbook API locally to determine sync status.

• Container Orchestrator (e.g., Kubernetes): Uses this script as a readiness probe command to control pod readiness and traffic routing.

• File System: Reads /data/disable_readiness to optionally disable probing.

• System Utilities: Utilizes curl and jq installed in the environment.

This script acts as a bridge between the internal Blockbook sync state and external load balancers or orchestrators controlling service availability.

Mermaid Flowchart Diagram

flowchart TD
    A[Start readiness.sh] --> B{Does /data/disable_readiness exist?}
    B -- Yes --> C[Print "readiness probe disabled"]
    C --> D[Exit 0]
    B -- No --> E[Send curl request to http://localhost:8001/api/v2]
    E --> F{Curl success?}
    F -- No --> G[Exit 1]
    F -- Yes --> H[Parse JSON with jq for .blockbook.inSync]
    H --> I{Is inSync == "true"?}
    I -- Yes --> J[Print "blockbook is synced"]
    J --> D[Exit 0]
    I -- No --> K[Print "blockbook is still syncing"]
    K --> G[Exit 1]

Summary

This simple but effective shell script encapsulates the readiness criteria for a Blockbook-based service by:

• Checking an override file.

• Querying local API for sync status.

• Returning appropriate exit codes and messages.

It is well suited for integration into container orchestration environments to ensure traffic is only routed to fully synced Blockbook instances. The minimal dependencies and straightforward logic make it reliable and easy to maintain.