feat: prepare go build for connected chains healthchecks

Author: gallindic-flare

.github/workflows/release-bitcoind.yml

@@ -7,9 +7,6 @@ on:
     branches: [main]
     paths: ["images/bitcoind/**"]
 
-# Declare default permissions as read only.
-permissions: read-all
-
 jobs:
   call:
     uses: ./.github/workflows/release-image.yml

.github/workflows/release-chains-hc.yml

@@ -0,0 +1,18 @@
+name: Release Connected Chains Healthcheck
+on:
+  push:
+    branches: [main]
+    paths: ["images/go_chains_hc/**"]
+  pull_request:
+    branches: [main]
+    paths: ["images/go_chains_hc/**"]
+
+jobs:
+  call:
+    uses: ./.github/workflows/release-image.yml
+    with:
+      image: ghcr.io/${{ github.repository }}/go_chains_hc
+      context: images/go_chains_hc
+      dockerfile: Dockerfile
+    secrets:
+      registry-password: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release-dogecoind.yml

@@ -7,9 +7,6 @@ on:
     branches: [main]
     paths: ["images/dogecoind/**"]
 
-# Declare default permissions as read only.
-permissions: read-all
-
 jobs:
   call:
     uses: ./.github/workflows/release-image.yml

.github/workflows/release-rippled.yml

@@ -7,9 +7,6 @@ on:
     branches: [main]
     paths: ["images/rippled/**"]
 
-# Declare default permissions as read only.
-permissions: read-all
-
 jobs:
   call:
     uses: ./.github/workflows/release-image.yml

images/go_chains_hc/Dockerfile

@@ -0,0 +1,14 @@
+FROM golang AS builder
+
+WORKDIR /app
+COPY go.mod ./
+RUN go mod download
+COPY *.go ./
+RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags="-s -w" -o /node-healthcheck
+
+FROM gcr.io/distroless/cc-debian13:nonroot@sha256:4cf9e68a5cbd8c9623480b41d5ed6052f028c44cc29f91b21590613ab8bec824
+
+COPY --from=builder /node-healthcheck /node-healthcheck
+
+EXPOSE 8080
+ENTRYPOINT ["/node-healthcheck"]

images/go_chains_hc/README.md

@@ -0,0 +1,75 @@
+## Connected Chains Healthcheck
+
+A minimal Go binary/container that exposes a `/readyz` HTTP endpoint for blockchain node readiness probes. Designed to be used alongside any compatible node (Bitcoin, Dogecoin, Litecoin, etc.) in a Kubernetes pod.
+
+### How it works
+
+On each `/readyz` request, the sidecar runs a configurable set of checks against the node's JSON-RPC API. It returns 200 OK when all checks pass, or an error with a message on the first failing check.
+
+### Checks
+
+| Check | RPC Method | Description |
+|---|---|---|
+| `blockdownload` | `getblockchaininfo` | Passes when `initialblockdownload` is `false`. Default for all chains. |
+| `txindex` | `getindexinfo` | Passes when `txindex.synced` is `true`. |
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `NODE_URL` | yes | — | RPC endpoint, e.g. `http://localhost:8332` |
+| `NODE_USER` | no | — | RPC auth username |
+| `NODE_PASS` | no | — | RPC auth password |
+| `CHECKS` | no | `blockdownload` | Comma-separated list of checks to run (blockdownload,txindex) |
+
+### Running Locally
+
+```bash
+go build -o node-healthcheck .
+NODE_URL=http://localhost:8332 NODE_USER=user NODE_PASS=secret CHECKS=blockdownload,txindex ./node-healthcheck
+```
+
+```bash
+# Readiness
+curl http://localhost:8080/readyz
+```
+
+Example Output:
+```json
+{"time":"2026-03-04T08:43:48.697Z","level":"INFO","msg":"starting","addr":":8080","checks":["blockdownload"],"node":"http://localhost:8332"}
+{"time":"2026-03-04T08:44:01.123Z","level":"DEBUG","msg":"rpc response","method":"getblockchaininfo","body":"{\"result\":{\"initialblockdownload\":false,...}}"}
+```
+
+### Kubernetes Sidecar Setup
+
+```yaml
+containers:
+  - name: bitcoin
+    ...
+  - name: healthcheck
+    image: node-healthcheck:latest
+    env:
+      - name: NODE_URL
+        value: "http://bitcoin:8332"
+      - name: NODE_USER
+        value: "admin"
+      - name: NODE_PASS
+        valueFrom:
+          secretKeyRef:
+            name: node-rpc-secret
+            key: password
+      - name: CHECKS
+        value: blockdownload,txindex
+    ports:
+      - containerPort: 8080
+
+readinessProbe:
+  httpGet:
+    path: /readyz
+    port: 8080
+  initialDelaySeconds: 60
+  periodSeconds: 30
+  timeoutSeconds: 20
+  failureThreshold: 10
+```
+

images/go_chains_hc/checks.go

@@ -0,0 +1,119 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+)
+
+type Check func(ctx context.Context, client *http.Client, cfg Config) error
+
+var registry = map[string]Check{
+	"blockdownload": checkBlockDownload,
+	"txindex":       checkTxIndex,
+}
+
+type rpcRequest struct {
+	JSONRPC string `json:"jsonrpc"`
+	ID      string `json:"id"`
+	Method  string `json:"method"`
+	Params  []any  `json:"params"`
+}
+
+func doRPC(ctx context.Context, client *http.Client, cfg Config, method string) (json.RawMessage, error) {
+	logger := slog.Default()
+	body, err := json.Marshal(rpcRequest{JSONRPC: "1.0", ID: "hc", Method: method, Params: []any{}})
+	if err != nil {
+		return nil, fmt.Errorf("marshal request: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, cfg.NodeURL, bytes.NewReader(body))
+	if err != nil {
+		return nil, fmt.Errorf("build request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	if cfg.NodeUser != "" {
+		req.SetBasicAuth(cfg.NodeUser, cfg.NodePass)
+	}
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("node unreachable: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("node returned HTTP %d", resp.StatusCode)
+	}
+
+	data, err := io.ReadAll(resp.Body)
+
+	if err != nil {
+		return nil, fmt.Errorf("read response: %w", err)
+	}
+
+	logger.Debug("rpc response", "method", method, "body", string(data))
+
+	var envelope struct {
+		Result json.RawMessage `json:"result"`
+		Error  any             `json:"error"`
+	}
+
+	if err := json.Unmarshal(data, &envelope); err != nil {
+		return nil, fmt.Errorf("invalid JSON from node: %w", err)
+	}
+
+	if envelope.Error != nil {
+		return nil, fmt.Errorf("node RPC error: %v", envelope.Error)
+	}
+
+	return envelope.Result, nil
+}
+
+func checkBlockDownload(ctx context.Context, client *http.Client, cfg Config) error {
+	result, err := doRPC(ctx, client, cfg, "getblockchaininfo")
+	if err != nil {
+		return err
+	}
+
+	var info struct {
+		InitialBlockDownload bool `json:"initialblockdownload"`
+	}
+
+	if err := json.Unmarshal(result, &info); err != nil {
+		return fmt.Errorf("parse getblockchaininfo: %w", err)
+	}
+
+	if info.InitialBlockDownload {
+		return fmt.Errorf("node is still syncing (initialblockdownload=true)")
+	}
+
+	return nil
+}
+
+func checkTxIndex(ctx context.Context, client *http.Client, cfg Config) error {
+	result, err := doRPC(ctx, client, cfg, "getindexinfo")
+	if err != nil {
+		return err
+	}
+
+	var info struct {
+		TxIndex struct {
+			Synced bool `json:"synced"`
+		} `json:"txindex"`
+	}
+
+	if err := json.Unmarshal(result, &info); err != nil {
+		return fmt.Errorf("parse getindexinfo: %w", err)
+	}
+
+	if !info.TxIndex.Synced {
+		return fmt.Errorf("txindex is not synced")
+	}
+
+	return nil
+}

images/go_chains_hc/go.mod

@@ -0,0 +1,3 @@
+module go_hc
+
+go 1.25.5

images/go_chains_hc/main.go

@@ -0,0 +1,100 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+)
+
+type Config struct {
+	NodeURL  string
+	NodeUser string
+	NodePass string
+	Checks   []string
+	Addr     string
+}
+
+func configFromEnv() (Config, error) {
+	nodeURL := os.Getenv("NODE_URL")
+	if nodeURL == "" {
+		return Config{}, fmt.Errorf("NODE_URL is required")
+	}
+
+	checks := []string{"blockdownload"}
+	if raw := os.Getenv("CHECKS"); raw != "" {
+		checks = strings.Split(raw, ",")
+	}
+
+	for _, name := range checks {
+		if _, ok := registry[name]; !ok {
+			return Config{}, fmt.Errorf("unknown check %q (available: %s)", name, availableChecks())
+		}
+	}
+
+	return Config{
+		NodeURL:  nodeURL,
+		NodeUser: os.Getenv("NODE_USER"),
+		NodePass: os.Getenv("NODE_PASS"),
+		Checks:   checks,
+		Addr:     ":8080",
+	}, nil
+}
+
+func availableChecks() string {
+	names := make([]string, 0, len(registry))
+	for k := range registry {
+		names = append(names, k)
+	}
+	return strings.Join(names, ", ")
+}
+
+func main() {
+	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelDebug}))
+	slog.SetDefault(logger)
+
+	cfg, err := configFromEnv()
+	if err != nil {
+		logger.Error("invalid configuration", "error", err)
+		os.Exit(1)
+	}
+
+	logger.Info("starting", "addr", cfg.Addr, "checks", cfg.Checks, "node", cfg.NodeURL)
+
+	client := &http.Client{Timeout: 10 * time.Second}
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/readyz", handleReadyz(client, cfg, logger))
+
+	srv := &http.Server{
+		Addr:         cfg.Addr,
+		Handler:      mux,
+		ReadTimeout:  15 * time.Second,
+		WriteTimeout: 15 * time.Second,
+	}
+
+	if err := srv.ListenAndServe(); err != nil {
+		logger.Error("server error", "error", err)
+		os.Exit(1)
+	}
+}
+
+func handleReadyz(client *http.Client, cfg Config, logger *slog.Logger) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		ctx, cancel := context.WithTimeout(r.Context(), 10*time.Second)
+		defer cancel()
+
+		for _, name := range cfg.Checks {
+			if err := registry[name](ctx, client, cfg); err != nil {
+				logger.Warn("check failed", "check", name, "error", err)
+				http.Error(w, fmt.Sprintf("check %q failed: %v", name, err), http.StatusServiceUnavailable)
+				return
+			}
+		}
+
+		w.WriteHeader(http.StatusOK)
+	}
+}