feat: set default BUILDERNET_IMAGE to url and add readyz.sh helper script (#393)

Author: fkondej

custom-recipes/buildernet/mkosi/README.md

@@ -29,16 +29,16 @@ curl -sSfL https://raw.githubusercontent.com/flashbots/builder-playground/main/i
 mkdir buildernet-dev && cd buildernet-dev
 builder-playground generate buildernet/mkosi
 
-# 3. Point to the VM image
-#    - you can point to a local file or URL
-#    - alternatively you can set this in playground.yaml (see below)
+# 3. Point to the VM image — local path, https:// URL, or set in playground.yaml.
+#    Skip to download the latest pre-built image automatically.
+#    Pre-built images: https://downloads.buildernet.org/buildernet-playground-images/
 export BUILDERNET_IMAGE=/path/to/buildernet-qemu.qcow2
 
 # 4. Start (runs L1 Docker stack + VM in the background)
 builder-playground start playground.yaml --bind-external --detached
 
-# 5. Wait for the VM to boot (~60-90s) then check readiness
-./scripts/operator-api-health.sh    # repeat until you see "OK"
+# 5. Wait for the VM to be ready
+./scripts/readyz.sh
 
 # 6. Verify by sending a transaction
 builder-playground test --rpc http://localhost:18645 --el-rpc http://localhost:8545
@@ -102,7 +102,7 @@ For Docker service logs (Reth, Lighthouse, mev-boost-relay, etc.), use `builder-
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `BUILDERNET_IMAGE` | *(set in playground.yaml)* | Path or URL to the VM qcow2 image |
+| `BUILDERNET_IMAGE` | pre-built image URL (see playground.yaml) | Local path or https:// URL to the VM qcow2 image |
 | `QEMU_CPU` | `8` | Number of CPU cores |
 | `QEMU_RAM` | `32G` | Memory allocation |
 | `QEMU_ACCEL` | `kvm` | Acceleration (`kvm` or `tcg`) |
@@ -163,6 +163,7 @@ buildernet-dev/
     ├── prepare.sh            # Download/copy image + create data disk
     ├── start.sh              # Start the QEMU VM
     ├── stop.sh               # Stop the QEMU VM
+    ├── readyz.sh             # Wait for VM readiness (/readyz on HAProxy)
     ├── console.sh            # Serial console
     ├── clean.sh              # Remove runtime files
     └── operator-api-*.sh     # Operator API helpers

custom-recipes/buildernet/mkosi/playground.yaml

@@ -32,7 +32,7 @@ recipe:
       builder:
         lifecycle_hooks: true
         env:
-          BUILDERNET_IMAGE: ".flashbots-images/mkosi.output/buildernet-qemu_latest.qcow2"
+          BUILDERNET_IMAGE: "https://downloads.buildernet.org/buildernet-playground-images/dev-20260303-3059b761/buildernet-qemu_dev-20260303-3059b761.qcow2"
         init:
           - ./scripts/prepare.sh
         start: ./scripts/start.sh

custom-recipes/buildernet/mkosi/scripts/readyz.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Poll /readyz on HAProxy until the VM is ready or timeout is reached
+set -eu -o pipefail
+
+TIMEOUT=${1:-300}
+PORT=${HAPROXY_PORT:-10443}
+HOST=${HAPROXY_HOST:-localhost}
+URL="https://${HOST}:${PORT}/readyz"
+START=$(date +%s)
+
+echo "Waiting for ${URL}..."
+while true; do
+    if curl -sfk -m 2 -o /dev/null "${URL}" 2>/dev/null; then
+        echo "OK ($(( $(date +%s) - START ))s)"
+        exit 0
+    fi
+    elapsed=$(( $(date +%s) - START ))
+    if [[ "${elapsed}" -ge "${TIMEOUT}" ]]; then
+        echo "Timed out after ${elapsed}s"
+        exit 1
+    fi
+    echo "  ${elapsed}s elapsed, retrying..."
+    sleep 5
+done