startup.sh

Overview

`startup.sh` is a lightweight shell script designed to perform a startup health check on a local daemon process, specifically a JSON-RPC server running on `localhost:8545`. It verifies whether the daemon is actively listening for network connections, which is a common readiness or liveness probe in containerized or service-based environments.

The script also includes a mechanism to disable the startup probe dynamically by placing a file (`/data/disable_startup`). This feature allows operators or automated systems to skip the health check under certain conditions.

Detailed Explanation

Script Workflow

1. Check for Disable Probe File

   • Path: /data/disable_startup

   • If this file exists, the script outputs "startup probe disabled" and exits with status code 0, indicating success without performing further checks.

2. Query the Daemon's Listening Status

   • Sends a JSON-RPC request to http://localhost:8545 with the method net_listening.

   • Uses curl with silent failure mode (-sf) to POST the JSON request and retrieve the response.

   • If the curl command fails (e.g., connection refused, timeout), the script exits immediately with status 1 (failure).

3. Parse JSON Response

   • Uses jq to parse the .result field from the JSON response.

   • The expected value is a boolean true or false.

4. Determine Daemon Status

   • If .result is true, the daemon is listening, so the script outputs "daemon is listening" and exits with 0.

   • If .result is not true (including false or missing), the script outputs "daemon is not listening" and exits with 1.

Code Breakdown

DISABLE_STARTUP_PROBE=/data/disable_startup

• Defines the path to the probe disable file.

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

• Checks if the disable file exists; if so, skip the probe.

NET_LISTENING=$(curl -sf -d '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":1}' -H 'Content-Type: application/json' http://localhost:8545) || exit 1

• Sends a JSON-RPC net_listening request.

• -s for silent, -f to fail silently on HTTP errors.

• If curl fails, exit with status 1.

LISTENING=$(echo $NET_LISTENING | jq -r '.result')

• Extracts the .result field from the JSON response.

if [[ $LISTENING == true ]]; then
  echo "daemon is listening"
  exit 0
fi

echo "daemon is not listening"
exit 1

• Conditional logic to determine the daemon status and exit accordingly.

Usage

This script is intended to be run in environments where the health or readiness of a daemon must be checked before proceeding. Typical usage scenarios include:

• Kubernetes startup or readiness probes.

• Service orchestration scripts.

• Automated monitoring or deployment pipelines.

Example

./startup.sh

Possible outputs:

• "startup probe disabled" (and exit code 0) if the disable file exists.

• "daemon is listening" (exit code 0) if the daemon is responsive.

• "daemon is not listening" (exit code 1) if the daemon does not respond or returns false.

Implementation Details and Algorithms

• The script relies on a standard JSON-RPC method net_listening which is expected to return a boolean indicating whether the daemon is listening.

• It uses curl for HTTP communication and jq for JSON parsing, both common and reliable CLI tools.

• The disabling mechanism via a file is a simple yet effective way to override the probe without changing the script or environment variables.

• The script strictly follows Unix conventions for exit codes: 0 for success, non-zero for failure.

Interaction with Other System Components

• Daemon Process: The script communicates directly with a local JSON-RPC daemon listening on port 8545. This is often an Ethereum client or similar blockchain node software.

• File System: The presence of /data/disable_startup controls whether the probe runs.

• Container Orchestration / Monitoring Tools: The script is suitable for integration as a readiness/startup probe script in container platforms like Kubernetes, where the container runtime calls this script to decide if the container is ready to serve traffic.

• External Utilities: Depends on curl and jq being installed and accessible in the environment where the script runs.

Mermaid Flowchart

This flowchart illustrates the decision-making and workflow within `startup.sh`:

flowchart TD
    Start[Start: Run startup.sh]
    CheckDisable[Check if /data/disable_startup exists]
    DisabledMsg["Echo 'startup probe disabled'"]
    Exit0a[Exit 0]

    SendRequest[Send JSON-RPC net_listening request via curl]
    CurlFail{Did curl succeed?}
    Exit1a[Exit 1]

    ParseResult[Parse '.result' from JSON response]
    ListeningTrue{Is result == true?}
    DaemonListening["Echo 'daemon is listening'"]
    Exit0b[Exit 0]

    DaemonNotListening["Echo 'daemon is not listening'"]
    Exit1b[Exit 1]

    Start --> CheckDisable
    CheckDisable -- Yes --> DisabledMsg --> Exit0a
    CheckDisable -- No --> SendRequest
    SendRequest --> CurlFail
    CurlFail -- No --> Exit1a
    CurlFail -- Yes --> ParseResult
    ParseResult --> ListeningTrue
    ListeningTrue -- Yes --> DaemonListening --> Exit0b
    ListeningTrue -- No --> DaemonNotListening --> Exit1b

Summary

`startup.sh` is a concise and effective shell script for verifying whether a local daemon process is ready and listening on a specific port. It offers a simple override mechanism and leverages JSON-RPC and standard command-line tools to perform its function reliably. This makes it suitable for use as a startup or readiness probe in containerized or automated deployment environments.