readiness.sh

Overview

`readiness.sh` is a lightweight shell script designed to serve as a **readiness probe** for a Blockbook-based blockchain indexer service. Its primary function is to determine if the Blockbook indexer is fully synchronized with the blockchain and hence ready to serve accurate data to clients.

This script is typically used in containerized environments (e.g., Kubernetes) where it runs repeatedly to inform the orchestration system whether the indexer instance should receive traffic. If the indexer is still syncing, the script signals that the pod is not ready, preventing premature routing of requests.

Functionality Summary

• Checks for an explicit disablement flag file (/data/disable_readiness). If present, the readiness probe is bypassed.

• Queries the local Blockbook API endpoint (http://localhost:8001/api/v2) for its synchronization status.

• Parses the JSON response to extract the .blockbook.inSync boolean flag.

• Exits with status code 0 (success) if the indexer is synced (inSync == true).

• Exits with status code 1 (failure) if the indexer is still syncing or if any error occurs.

Detailed Breakdown

Constants

Script Logic

1. Check for Probe Disablement

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

• Purpose: Allows operators or automation to disable the readiness probe temporarily by placing a file at /data/disable_readiness.

• Effect: If the file exists, the script outputs a message and exits successfully (exit 0), signaling readiness regardless of sync status.

2. Query Blockbook API for Status

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

• Command: curl -sf silently fetches JSON data from the local Blockbook API endpoint.

• Behavior:

  • -s suppresses progress and errors.

  • -f fails silently on server errors (non-2xx HTTP codes).

• Failure Handling: If the HTTP request fails, the script exits with 1 (not ready).

3. Extract Synchronization Status

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

• Tool: jq parses the JSON output.

• Value: Extracts the boolean value of the .blockbook.inSync field, which indicates if the Blockbook indexer is fully synced.

• Example JSON snippet:

{
  "blockbook": {
    "inSync": true,
    ...
  }
}

4. Decision and Exit

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 reports readiness and exits with success code 0.

• Otherwise, it reports that syncing is ongoing and exits with failure code 1.

Usage Example

Assuming this script is run by Kubernetes as a readiness probe, the configuration might look like:

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

• Kubernetes will run the script every 10 seconds after an initial delay.

• The pod will be marked ready only when the script exits 0.

Implementation Details and Algorithms

• The probe relies on querying a local HTTP API exposed by the Blockbook indexer.

• The synchronization state is determined solely by a boolean flag in the JSON response (.blockbook.inSync).

• The script uses file presence as a simple feature toggle to disable the readiness check.

• It uses standard Unix tools (curl, jq) ensuring minimal dependencies and quick execution.

• Exit codes strictly follow Unix conventions: 0 for success (ready), non-zero for failure (not ready).

Interactions with Other System Components

• Blockbook API (http://localhost:8001/api/v2): The script depends on this local service endpoint to retrieve the sync status. If the API is down or unreachable, the probe fails.

• Kubernetes (or other orchestrators): The script is invoked by the container orchestration platform as a readiness probe, influencing pod readiness and traffic routing.

• File system (/data/disable_readiness): External processes or operators can create/delete this file to temporarily disable or enable the readiness check.

• Container environment: Assumes curl and jq are installed in the container image.

Visual Diagram

flowchart TD
    Start[Start Readiness Probe]
    CheckDisable[Check if disable readiness file exists (/data/disable_readiness)]
    Disabled[Probe Disabled - Exit 0]
    QueryAPI[Query Blockbook API /api/v2 via curl]
    ParseSync[Parse .blockbook.inSync Flag using jq]
    InSyncTrue{Is inSync == true?}
    Ready[Indexer Ready - Exit 0]
    NotReady[Indexer Syncing or Error - Exit 1]

    Start --> CheckDisable
    CheckDisable -->|Exists| Disabled
    CheckDisable -->|Not exists| QueryAPI
    QueryAPI -->|Success| ParseSync
    QueryAPI -->|Fail| NotReady
    ParseSync --> InSyncTrue
    InSyncTrue -->|Yes| Ready
    InSyncTrue -->|No| NotReady

**Diagram Explanation:**

• The probe starts by checking if it is disabled via a sentinel file.

• If disabled, it immediately exits successfully.

• Otherwise, it queries the local Blockbook API.

• On successful API response, it extracts the inSync status.

• Depending on the boolean flag, it either exits successfully or with failure, indicating readiness or not.

Summary

`readiness.sh` is a concise, reliable readiness probe script that integrates with Kubernetes or similar platforms to verify whether a Blockbook blockchain indexer is fully synchronized and ready to handle requests. It balances simplicity with operational flexibility by including a disable flag mechanism, leveraging the Blockbook API, and using standard Unix tooling for JSON parsing and HTTP requests.

This script plays a crucial role in ensuring that only fully synced indexer pods receive traffic, thereby maintaining data consistency and application stability.

End of Documentation for readiness.sh