startup.sh

Overview

`startup.sh` is a Bash shell script designed as a startup probe for a daemon process, likely an Ethereum client or a similar JSON-RPC-based network service listening on `http://localhost:8545`. Its primary function is to determine whether the daemon is ready to accept requests by checking two key conditions:

1. Whether the daemon is actively listening for network connections.

2. Whether the daemon has any connected peers.

This script is typically used in container orchestration environments (e.g., Kubernetes) as a health check or readiness probe to decide if the service is ready to receive traffic. It exits with status `0` when the daemon is ready (listening and has peers), and with status `1` otherwise.

Additionally, the script supports a manual override to disable the startup probe check by placing a file named `/data/disable_startup`.

Detailed Explanation

Script Variables

• DISABLE_STARTUP_PROBE=/data/disable_startup
  Path to a file which, if exists, will disable the startup probe check and cause the script to exit successfully immediately.

• NET_LISTENING
  Captures the JSON-RPC response to the net_listening method, which returns a boolean indicating if the daemon is listening for network connections.

• NET_PEER_COUNT
  Captures the JSON-RPC response to the net_peerCount method, which returns a hex-encoded number of connected peers.

• LISTENING
  Extracted boolean result from NET_LISTENING.

• PEER_COUNT_HEX
  Extracted hex string result from NET_PEER_COUNT.

• PEER_COUNT
  Decimal conversion of PEER_COUNT_HEX for numeric comparison.

Script Logic and Flow

1. Disable Check

   if [[ -f "$DISABLE_STARTUP_PROBE" ]]; then
     echo "startup probe disabled"
     exit 0
   fi
   

   If the disable file exists, the script outputs a message and exits successfully, bypassing all further checks.

2. Query Daemon Status
   The script sends two JSON-RPC POST requests to the daemon's RPC endpoint at http://localhost:8545 using curl:

   • net_listening: Checks if the daemon is listening for network connections.

   • net_peerCount: Returns the number of connected peers in hex.

   If either request fails, the script exits with status `1`.

3. Parse Responses
   Uses jq to parse the JSON results from the responses.

4. Evaluate Listening and Peer Count

   • If the daemon is listening and has one or more peers, print success message and exit 0.

   • If the daemon is listening but has no peers, print a warning message and exit 1.

   • If the daemon is not listening, print a failure message and exit 1.

Usage Examples

Assuming this script is used as a Kubernetes readiness probe:

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

Manually running the script on a host where the daemon is running:

./startup.sh

Output examples:

• If startup probe disabled file exists:

  startup probe disabled
  

• If daemon is listening with peers:

  daemon is listening, with 5 peers
  

• If daemon is listening but no peers:

  daemon is listening, but has no peers
  

• If daemon is not listening:

  daemon is not listening
  

Important Implementation Details

• JSON-RPC Requests: Uses curl to POST JSON-RPC 2.0 requests to the daemon's HTTP RPC interface. The method names (net_listening and net_peerCount) are standard Ethereum JSON-RPC methods.

• Error Handling:
  The script relies on the -s (silent) and -f (fail) flags in curl. If the RPC endpoint is unreachable or returns an error HTTP status, the script exits immediately with 1.

• Hex to Decimal Conversion:
  Peer count is returned as a hexadecimal string (e.g., "0x3"). The script converts this to decimal using Bash arithmetic for numeric comparison.

• Exit Codes:

  • 0 indicates readiness (daemon listening and has peers, or probe disabled).

  • 1 indicates not ready.

Interaction with Other System Components

• Daemon Process:
  The script queries the daemon running locally on port 8545 via HTTP JSON-RPC.

• Orchestration Systems:
  Used as a readiness/startup probe by container orchestration platforms like Kubernetes to manage service lifecycle and rolling updates.

• File System:
  The presence of /data/disable_startup file acts as an external toggle to disable the probe.

• Utilities:
  Relies on external utilities:

  • curl for HTTP requests.

  • jq for JSON parsing.

Mermaid Flowchart Diagram

This flowchart illustrates the decision workflow in the `startup.sh` script.

flowchart TD
    Start([Start])
    CheckDisable{File /data/disable_startup exists?}
    ExitDisable[Print "startup probe disabled"\nExit 0]
    QueryListening[Send net_listening RPC request]
    QueryPeerCount[Send net_peerCount RPC request]
    ParseListening[Parse listening result]
    ParsePeerCount[Parse peer count result]
    CheckListening{Is daemon listening?}
    CheckPeers{Peer count > 0?}
    Ready[Print "daemon is listening, with N peers"\nExit 0]
    NoPeers[Print "daemon is listening, but has no peers"\nExit 1]
    NotListening[Print "daemon is not listening"\nExit 1]
    CurlFail1[Exit 1]
    CurlFail2[Exit 1]

    Start --> CheckDisable
    CheckDisable -- Yes --> ExitDisable
    CheckDisable -- No --> QueryListening
    QueryListening -- Success --> QueryPeerCount
    QueryListening -- Fail --> CurlFail1
    QueryPeerCount -- Success --> ParseListening
    QueryPeerCount -- Fail --> CurlFail2
    ParseListening --> ParsePeerCount
    ParsePeerCount --> CheckListening
    CheckListening -- Yes --> CheckPeers
    CheckListening -- No --> NotListening
    CheckPeers -- Yes --> Ready
    CheckPeers -- No --> NoPeers

Summary

`startup.sh` is a lightweight, robust startup readiness script tailored for a JSON-RPC daemon environment, primarily used to ensure the daemon is fully operational and network-ready before other services or clients interact with it. Its simple yet effective checks and ability to be disabled via a file make it flexible for various deployment scenarios.

**End of Documentation**