Phase 2a: kamado-api Go middleware (core MVP)

Go 1.22 module that polls CKPool's Unix socket control API, queries
Bitcoin Core over JSON-RPC, merges both into a thread-safe snapshot, and
serves it over REST. Layout:

  api/
  ├── cmd/kamado-api/main.go              signal-aware entrypoint
  └── internal/
      ├── config/       env var loader with validation
      ├── ckpool/       socket client (4-byte LE length-prefixed wire
      │                 protocol verified against libckpool.c), typed
      │                 response models for poolstats/users/workers/
      │                 clients/uptime, + unit tests using a fake
      │                 unix socket server
      ├── bitcoind/     minimal JSON-RPC client, getblockchaininfo
      │                 and getnetworkhashps
      ├── state/        Aggregator that refreshes a merged Snapshot
      │                 on a ticker; readers get a copy under RWMutex
      └── httpapi/      REST handlers on Go 1.22 ServeMux:
                        /api/health /api/pool /api/users
                        /api/workers /api/clients /api/snapshot

CKPool stores hashrate as "dsps" (diff shares per second); we convert
to H/s via the 2^32 constant used by GoBrrr-Pool and other clients.
Every stat CKPool exposes to its socket API is surfaced — useragent,
IP, per-client diff, per-worker best diff — closing the gap against
Bassin which only reads the 60-second stats files.

Dockerfile does a CGO_ENABLED=0 static build on golang:1.22-bookworm
with -trimpath -ldflags=-s -w. docker-compose now runs both ckpool and
kamado-api, sharing a named volume for /run/ckpool so the API can
dial the stratifier socket directly.

Deferred to Phase 2b (called out in README):
  - Bitcoin Core ZMQ hashblock subscriber
  - WebSocket push for real-time UI updates
  - SQLite persistence (block history, best-share history)
  - CKPool log tailer for "Solved and confirmed block" detection

Tests and build NOT run in this commit — Go isn't installed in the
dev environment. Run `make api-test` or `make api` to verify.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docker-compose.yml

@@ -1,12 +1,12 @@
 # ----------------------------------------------------------------------------
 # Kamado Pool — development compose
 #
-# Spins up ckpool-solo pointing at a bitcoind. Expects bitcoind to be
-# reachable at the host/port set in the `env` block below. For local
-# testing, run bitcoind on regtest/testnet4 and set these accordingly.
+# Spins up ckpool-solo and kamado-api pointing at a bitcoind. Expects
+# bitcoind to be reachable at the host/port set in the env blocks below.
+# For local testing, run bitcoind on regtest/testnet4 and set these via .env.
 #
-# The ckpool socket dir is bind-mounted to ./data/run so the (future)
-# kamado-api can talk to it from outside the container during development.
+# ckpool and kamado-api share the `ckpool-sock` named volume so the API
+# can dial /run/ckpool/stratifier directly.
 # ----------------------------------------------------------------------------
 services:
   ckpool:
@@ -18,7 +18,7 @@ services:
     ports:
       - "3333:3333"
     volumes:
-      - ./data/run:/run/ckpool
+      - ckpool-sock:/run/ckpool
       - ./data/logs:/var/log/ckpool
     environment:
       # --- Bitcoin Core connection ---
@@ -27,7 +27,6 @@ services:
       BITCOIN_RPC_USER: "${BITCOIN_RPC_USER:-kamado}"
       BITCOIN_RPC_PASSWORD: "${BITCOIN_RPC_PASSWORD:-kamado}"
       BITCOIN_NOTIFY: "true"
-      # Optional ZMQ for instant block notifications (recommended)
       ZMQ_BLOCK: "${ZMQ_BLOCK:-}"     # e.g. tcp://host.docker.internal:28332
 
       # --- Pool settings ---
@@ -47,5 +46,37 @@ services:
       LOGDIR: "/var/log/ckpool"
       SOCKET_DIR: "/run/ckpool"
     extra_hosts:
-      # Allow containers to reach bitcoind running on the host
       - "host.docker.internal:host-gateway"
+
+  api:
+    build:
+      context: ./api
+      dockerfile: Dockerfile
+    container_name: kamado-api
+    restart: unless-stopped
+    depends_on:
+      - ckpool
+    ports:
+      - "8080:8080"
+    volumes:
+      - ckpool-sock:/run/ckpool
+      - ./data/logs:/var/log/ckpool:ro
+      - kamado-db:/var/lib/kamado
+    environment:
+      LISTEN_ADDR: ":8080"
+      CKPOOL_SOCKDIR: "/run/ckpool"
+      CKPOOL_LOGFILE: "/var/log/ckpool/ckpool.log"
+      POLL_INTERVAL: "5s"
+
+      # --- Bitcoin Core RPC (same creds as ckpool) ---
+      BITCOIN_RPC_URL: "http://host.docker.internal:48332"
+      BITCOIN_RPC_USER: "${BITCOIN_RPC_USER:-kamado}"
+      BITCOIN_RPC_PASSWORD: "${BITCOIN_RPC_PASSWORD:-kamado}"
+      BITCOIN_RPC_TIMEOUT: "10s"
+      BITCOIN_ZMQ_BLOCK: "${ZMQ_BLOCK:-}"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+
+volumes:
+  ckpool-sock:
+  kamado-db: