startup.sh

Overview

`startup.sh` is a Bash shell script designed as a startup probe for a daemon process that exposes a JSON-RPC interface, specifically targeting an Ethereum-like node running on `localhost:8545`. The script checks whether the daemon is actively listening for network connections and whether it has any active peers connected. This is typically used in containerized environments (e.g., Kubernetes) as a readiness or liveness probe to determine if the daemon is ready to serve requests.

Key features:

Checks for a "disable" flag file (/data/disable_startup) to optionally bypass the startup probe.
Queries the daemon's JSON-RPC interface for network listening status and peer count.
Interprets JSON-RPC responses and exits with appropriate status codes:
- 0 when the daemon is ready (listening and has peers).
- 1 when not ready.
Provides user-friendly output messages describing the daemon state.

Detailed Explanation

Key Variables

DISABLE_STARTUP_PROBE: Path to a file (/data/disable_startup) whose presence disables the startup probe.
NET_LISTENING: Stores the JSON-RPC response for the net_listening method.
NET_PEER_COUNT: Stores the JSON-RPC response for the net_peerCount method.
LISTENING: Parsed boolean value from NET_LISTENING indicating if the daemon is listening.
PEER_COUNT_HEX: Raw hexadecimal string from net_peerCount RPC.
PEER_COUNT: Decimal conversion of PEER_COUNT_HEX.

Script Workflow and Logic

Disable Check
The script first checks if the file /data/disable_startup exists. If present, it outputs:
```
startup probe disabled
```
and exits with status 0, bypassing all further checks.
RPC Calls
The script sends two HTTP POST requests to the daemon's JSON-RPC endpoint at http://localhost:8545:
- net_listening: Checks whether the node is listening for network connections.
- net_peerCount: Retrieves the number of connected peers, returned as a hex string.
Both requests use `curl` with silent fail mode (`-sf`), and if either fails (e.g., no response), the script exits with status `1`.
Parsing Responses
The responses are JSON objects. The script uses jq to extract the .result field from each:
- LISTENING holds "true" or "false" as a string.
- PEER_COUNT_HEX is a hexadecimal string representing the peer count (e.g., "0x3").
The peer count hex string is converted to a decimal integer (`PEER_COUNT`).

Decision Logic

If LISTENING is true:

If PEER_COUNT > 0:

daemon is listening, with <PEER_COUNT> peers

Exit 0.

Else:
```
daemon is listening, but has no peers
```
Exit 1.

If LISTENING is not true:
```
daemon is not listening
```
Exit 1.

Usage Example

This script is intended to be run as part of a container startup probe or manually to check daemon readiness.

# Run the probe manually
./startup.sh

# Possible outputs:
# "startup probe disabled" (exit 0)
# "daemon is listening, with 5 peers" (exit 0)
# "daemon is listening, but has no peers" (exit 1)
# "daemon is not listening" (exit 1)

Implementation Details

JSON-RPC Protocol: The script uses JSON-RPC 2.0 standard requests with methods net_listening and net_peerCount to query daemon state.
Hexadecimal Conversion: Peer count is returned as a hex string (e.g., "0x2"), which the script converts to a decimal number using Bash arithmetic.
Fail-fast Behavior: If either RPC call fails (e.g., network error, daemon down), the script exits immediately with status 1.
Dependency on jq: The script requires the jq command-line JSON processor to extract values from the JSON responses.

Interaction with Other System Components

Daemon Process: The script interacts exclusively with the daemon exposing the JSON-RPC endpoint on port 8545 on localhost.
Container Orchestration: In Kubernetes or similar environments, this script is likely configured as a readiness or liveness probe command to determine when the daemon is ready to receive traffic.
File System: Presence of /data/disable_startup flags skipping the probe, allowing manual override or conditional startup behavior.

Visual Diagram: Flowchart of Script Workflow

flowchart TD
    Start([Start])
    CheckDisable{Is /data/disable_startup present?}
    ExitDisabled["Echo 'startup probe disabled'\nExit 0"]
    RPCNetListening["POST net_listening RPC\nGet LISTENING"]
    RPCNetPeerCount["POST net_peerCount RPC\nGet PEER_COUNT_HEX"]
    ConvertHex["Convert PEER_COUNT_HEX to PEER_COUNT"]
    CheckListening{Is LISTENING == true?}
    CheckPeers{Is PEER_COUNT > 0?}
    ListeningWithPeers["Echo 'daemon is listening, with PEER_COUNT peers'\nExit 0"]
    ListeningNoPeers["Echo 'daemon is listening, but has no peers'\nExit 1"]
    NotListening["Echo 'daemon is not listening'\nExit 1"]
    CurlFail["Curl failed\nExit 1"]

    Start --> CheckDisable
    CheckDisable -- Yes --> ExitDisabled
    CheckDisable -- No --> RPCNetListening
    RPCNetListening -- Success --> RPCNetPeerCount
    RPCNetListening -- Fail --> CurlFail
    RPCNetPeerCount -- Success --> ConvertHex
    RPCNetPeerCount -- Fail --> CurlFail
    ConvertHex --> CheckListening
    CheckListening -- Yes --> CheckPeers
    CheckListening -- No --> NotListening
    CheckPeers -- Yes --> ListeningWithPeers
    CheckPeers -- No --> ListeningNoPeers

Summary

`startup.sh` is a concise and effective startup probe script that verifies the readiness of a JSON-RPC enabled daemon by checking network listening status and connected peer count. It provides clear exit codes and messages for integration with container orchestration systems or deployment automation. The script's simplicity and reliance on standard tools (`curl`, `jq`, Bash) make it portable and easy to maintain.