readiness.sh

Overview

`readiness.sh` is a lightweight Bash script designed as a readiness probe for a service that exposes an HTTP API on `localhost:8001`. Its primary function is to determine whether the service, specifically a component named "blockbook", is ready to serve requests by checking its synchronization status. The script can be used in container orchestration environments (e.g., Kubernetes) or monitoring systems to signal if the service is ready or still initializing.

The script also supports a simple manual override mechanism: if a specific file (`/data/disable_readiness`) exists, the readiness probe is disabled, and the script immediately reports readiness.

Detailed Explanation

Variables

• DISABLE_READINESS_PROBE

  • Type: String (file path)

  • Purpose: Path to the file that disables readiness checks if present.

  • Default: /data/disable_readiness

• STATUS

  • Type: String (JSON response)

  • Purpose: Holds the JSON response from the service's API endpoint.

• IN_SYNC

  • Type: String ("true" or "false")

  • Purpose: Extracted from STATUS indicating if the blockbook service is synchronized.

Script Flow and Functions

This script does not define explicit functions or classes since it is a shell script. However, it follows a procedural flow with key steps:

1. Check for Disable File

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

   • If the file /data/disable_readiness exists, the script prints "readiness probe disabled" and exits with status code 0 (success).

   • Usage: This allows manual override of readiness checks, effectively signaling the system that the service is ready regardless of actual sync status.

2. Query the Service API

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

   • Uses curl to silently (-s) fetch the API endpoint at http://localhost:8001/api/v2.

   • The -f flag ensures curl fails silently on server errors (HTTP status >= 400).

   • If the API call fails (e.g., service down or network error), the script exits immediately with status 1 (failure).

   • The JSON response is stored in the variable STATUS.

3. Parse Synchronization Status

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

   • Uses jq (a lightweight JSON processor) to extract the value of .blockbook.inSync from the JSON response.

   • The -r flag outputs raw strings without quotes.

   • Expected values: "true" or "false" (string literals).

4. Evaluate Sync Status and Exit

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

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

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

Usage Example

Suppose you want to use this script as a readiness probe in a Kubernetes pod definition:

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

• Kubernetes will run this script periodically. If the script exits 0, the pod is marked ready.

• If it exits 1, Kubernetes treats the pod as not ready and withholds traffic.

Important Implementation Details

• The script depends on two external commands:

  • curl for HTTP requests.

  • jq for JSON parsing.

• It expects the service to expose an API at http://localhost:8001/api/v2 that returns JSON including a .blockbook.inSync boolean field.

• The script uses exit codes (0 for ready, 1 for not ready) to integrate with container orchestration systems.

• The disable file mechanism provides a simple manual override without changing the script or deployment.

Interaction with Other Components

• Service API: The script queries the local service's API to determine readiness. It assumes the service listens on port 8001 and exposes an API returning sync status info.

• File System: It checks for the presence of /data/disable_readiness to optionally disable readiness checks. This file can be managed externally by scripts, operators, or deployment tools.

• Container Orchestration / Monitoring: Designed to be called as a readiness probe or health check script, signaling readiness to Kubernetes, Docker Swarm, or monitoring tools.

• JSON Processor (jq): Requires jq installed in the environment where the script runs.

Mermaid Flowchart Diagram

flowchart TD
    Start([Start])
    CheckDisableFile{Is /data/disable_readiness present?}
    PrintDisabled["Print 'readiness probe disabled'"]
    ExitSuccess0[Exit 0]

    CurlAPI["Run: curl -sf http://localhost:8001/api/v2"]
    CurlFail{Did curl succeed?}
    ExitFailure1[Exit 1]

    ParseSync["Parse '.blockbook.inSync' from JSON"]
    CheckSyncTrue{Is 'inSync' == 'true'?}
    PrintSynced["Print 'blockbook is synced'"]
    PrintSyncing["Print 'blockbook is still syncing'"]

    %% Flow connections
    Start --> CheckDisableFile
    CheckDisableFile -- Yes --> PrintDisabled --> ExitSuccess0
    CheckDisableFile -- No --> CurlAPI
    CurlAPI --> CurlFail
    CurlFail -- No --> ExitFailure1
    CurlFail -- Yes --> ParseSync --> CheckSyncTrue
    CheckSyncTrue -- Yes --> PrintSynced --> ExitSuccess0
    CheckSyncTrue -- No --> PrintSyncing --> ExitFailure1

Summary

This small but critical script provides an automated readiness check for the "blockbook" service by verifying its synchronization status via a local HTTP API. It supports disabling readiness probes via a simple file-based toggle and uses standard Unix utilities (`curl` and `jq`). Its clean exit codes and status messages make it ideal for integration with container orchestrators or monitoring frameworks to improve deployment reliability and observability.