bench.sh

#!/usr/bin/env bash
#
# Pyxle Framework Benchmark Suite — one-command runner
#
# Sets up every target app in a reproducible environment, starts the servers the
# chosen suite needs, verifies endpoint parity, and runs the load generator.
#
# SAME-BOX (quick local check — autocannon, harness shares the CPU):
#   ./bench.sh                              # API suite
#   ./bench.sh --suite=ssr                  # SSR suite
#   ./bench.sh --suite=all --workers=auto   # all cores
#
# OFF-BOX (publishable numbers — generator on a SEPARATE box, oha):
#   on the SERVER box:   ./bench.sh --serve-only --workers=auto
#   on the CLIENT box:   ./bench.sh --generate-only --target=<server-ip> \
#                          --generator=oha --suite=all --reps=5 \
#                          --duration=30 --warmup-duration=20 --connections=100
#
# Run ./bench.sh --help for the full option list.

set -o pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "$SCRIPT_DIR"

# ── defaults ──────────────────────────────────────────────────────
SUITE="api"
DURATION=""
CONNECTIONS=""
WARMUP=""
REPS=""
LATENCY_RATE=""
FRAMEWORKS=""
OUTPUT=""
SKIP_INSTALL=0
SKIP_BUILD=0
SKIP_PARITY=0
ALLOW_PARTIAL=0
WORKERS=""
HOST=""              # host the servers BIND to (default 127.0.0.1; serve-only → 0.0.0.0)
TARGET=""            # host the generator points AT (generate-only)
GENERATOR=""         # autocannon | oha
SERVE_ONLY=0
GENERATE_ONLY=0
FLASK_THREADS="${FLASK_THREADS:-8}"   # gthread threads per Flask worker (disclosed)

# ── output helpers ────────────────────────────────────────────────
if [ -t 1 ]; then
  GREEN='\033[0;32m'; RED='\033[0;31m'; YELLOW='\033[0;33m'; CYAN='\033[0;36m'; BOLD='\033[1m'; RESET='\033[0m'
else
  GREEN=''; RED=''; YELLOW=''; CYAN=''; BOLD=''; RESET=''
fi
info() { echo -e "${CYAN}[bench]${RESET} $*"; }
ok()   { echo -e "${GREEN}[bench]${RESET} $*"; }
warn() { echo -e "${YELLOW}[bench]${RESET} $*"; }
fail() { echo -e "${RED}[bench]${RESET} $*" >&2; }

usage() {
  cat <<'EOF'
Pyxle Framework Benchmark Suite

Usage: ./bench.sh [options]

Topology:
  (default)               Same box: start servers on 127.0.0.1 and generate load
                            locally with autocannon. Convenient, but the harness
                            shares the CPU — NOT for published numbers.
  --serve-only            Only start + health-check the servers (bound to 0.0.0.0
                            by default) and idle until Ctrl-C. Run on the SERVER box.
  --generate-only         Only run the generator against --target. Run on the
                            dedicated CLIENT box (defaults to --generator=oha).

Options:
  --suite=api|ssr|all     Which suite to run (default: api)
  --frameworks=a,b,...    (api) Only benchmark these frameworks
  --host=HOST             Host the servers bind to (default 127.0.0.1;
                            serve-only defaults to 0.0.0.0)
  --target=HOST           (generate-only) Server host/IP to generate load against
  --generator=NAME        autocannon (same-box only) or oha (off-box / published)
  --duration=N            Measured seconds per repetition (default 10)
  --connections=N,M,...   Concurrency levels (e.g. 10,50,100)
  --reps=N                Measured repetitions per cell; median reported (default 1)
  --warmup-duration=N     Seconds of warmup load before measuring (default 5)
  --latency-rate=QPS      (ssr, oha only) Extra fixed-rate latency pass at QPS,
                            coordinated-omission corrected
  --workers=N|auto        Run every framework with N worker processes (auto = nproc)
  --output=FILE           Save JSON results to FILE
  --skip-install          Don't (re)install dependencies
  --skip-build            Don't (re)build the Pyxle / Next.js apps
  --skip-parity           Don't run the pre-run parity verification
  --allow-partial         Continue even if some servers fail to come up
                            (default: abort, so a missing framework is never
                            silently dropped from the ranking)
  -h, --help              Show this help

Ports: pyxle 8001 · fastapi 8002 · django 8003 · flask 8004 · express 8005
       hono 8006 · pyxle-ssr 8011 · next.js 3000
EOF
}

# ── parse args ────────────────────────────────────────────────────
for arg in "$@"; do
  case "$arg" in
    --suite=*)            SUITE="${arg#*=}" ;;
    --frameworks=*)       FRAMEWORKS="${arg#*=}" ;;
    --host=*)             HOST="${arg#*=}" ;;
    --target=*)           TARGET="${arg#*=}" ;;
    --generator=*)        GENERATOR="${arg#*=}" ;;
    --duration=*)         DURATION="${arg#*=}" ;;
    --connections=*)      CONNECTIONS="${arg#*=}" ;;
    --warmup-duration=*)  WARMUP="${arg#*=}" ;;
    --warmup=*)           WARMUP="${arg#*=}" ;;
    --reps=*)             REPS="${arg#*=}" ;;
    --latency-rate=*)     LATENCY_RATE="${arg#*=}" ;;
    --output=*)           OUTPUT="${arg#*=}" ;;
    --skip-install)       SKIP_INSTALL=1 ;;
    --skip-build)         SKIP_BUILD=1 ;;
    --skip-parity)        SKIP_PARITY=1 ;;
    --allow-partial)      ALLOW_PARTIAL=1 ;;
    --serve-only)         SERVE_ONLY=1 ;;
    --generate-only)      GENERATE_ONLY=1 ;;
    --workers=*)          WORKERS="${arg#*=}" ;;
    -h|--help)            usage; exit 0 ;;
    *) fail "Unknown argument: $arg"; echo; usage; exit 1 ;;
  esac
done

case "$SUITE" in
  api|ssr|all) ;;
  *) fail "Invalid --suite: '$SUITE' (expected api, ssr, or all)"; exit 1 ;;
esac

if [ "$SERVE_ONLY" -eq 1 ] && [ "$GENERATE_ONLY" -eq 1 ]; then
  fail "--serve-only and --generate-only are mutually exclusive."; exit 1
fi

need_api=0; need_ssr=0
if [ "$SUITE" = "api" ] || [ "$SUITE" = "all" ]; then need_api=1; fi
if [ "$SUITE" = "ssr" ] || [ "$SUITE" = "all" ]; then need_ssr=1; fi

# The runners execute from bench/, so make a relative --output absolute against
# the repo root (where the user gave it) before passing it through.
if [ -n "$OUTPUT" ]; then
  case "$OUTPUT" in
    /*) : ;;                                   # already absolute
    *)  OUTPUT="$SCRIPT_DIR/$OUTPUT" ;;
  esac
fi

# api.mjs and ssr.mjs each write the file at --output. When BOTH suites run with
# a single --output they would clobber each other (api written, then overwritten
# by ssr), so give each suite its own file: <name>-api.<ext> / <name>-ssr.<ext>.
API_OUT="$OUTPUT"; SSR_OUT="$OUTPUT"
if [ -n "$OUTPUT" ] && [ "$need_api" -eq 1 ] && [ "$need_ssr" -eq 1 ]; then
  ext="${OUTPUT##*.}"
  if [ "$ext" = "$OUTPUT" ]; then          # no extension
    API_OUT="${OUTPUT}-api"; SSR_OUT="${OUTPUT}-ssr"
  else
    API_OUT="${OUTPUT%.*}-api.${ext}"; SSR_OUT="${OUTPUT%.*}-ssr.${ext}"
  fi
fi

# ── resolve topology defaults ─────────────────────────────────────
# BIND_HOST: where servers listen. GEN_TARGET: where the generator points.
if [ "$SERVE_ONLY" -eq 1 ]; then
  BIND_HOST="${HOST:-0.0.0.0}"          # accept off-box traffic by default
else
  BIND_HOST="${HOST:-127.0.0.1}"
fi
if [ "$GENERATE_ONLY" -eq 1 ]; then
  if [ -z "$TARGET" ]; then fail "--generate-only requires --target=<server-host>"; exit 1; fi
  GEN_TARGET="$TARGET"
  GENERATOR="${GENERATOR:-oha}"          # off-box → multithreaded generator
else
  GEN_TARGET="${TARGET:-127.0.0.1}"
  GENERATOR="${GENERATOR:-autocannon}"
fi

# ── multi-core mode ───────────────────────────────────────────────
MULTICORE=0
if [ -n "$WORKERS" ]; then
  if [ "$WORKERS" = "auto" ]; then
    WORKERS="$( (command -v nproc >/dev/null 2>&1 && nproc) || sysctl -n hw.ncpu 2>/dev/null || echo 4 )"
  fi
  case "$WORKERS" in
    ''|*[!0-9]*) fail "Invalid --workers: '$WORKERS' (expected a positive integer or 'auto')"; exit 1 ;;
  esac
  [ "$WORKERS" -lt 1 ] && { fail "--workers must be >= 1"; exit 1; }
  MULTICORE=1
fi
export PYXLE_BENCH_WORKERS="${WORKERS:-1}"   # surfaced in result metadata

# ── server lifecycle ──────────────────────────────────────────────
PIDS=()
cleanup() {
  echo
  info "Stopping servers..."
  for pid in "${PIDS[@]}"; do kill "$pid" 2>/dev/null; done
  wait 2>/dev/null
  ok "All servers stopped."
}
start() {  # start <name> <port> <dir> <command...>
  local name="$1" port="$2" dir="$3"; shift 3
  ( cd "$dir" && exec "$@" ) >/dev/null 2>&1 &
  PIDS+=($!)
  info "Started ${name} on ${BIND_HOST}:${port}"
}

echo
echo -e "${BOLD}═══════════════════════════════════════════════════════${RESET}"
echo -e "${BOLD}  Pyxle Benchmark Suite${RESET}  ·  suite: ${SUITE}"
if   [ "$SERVE_ONLY" -eq 1 ];    then echo -e "  mode: ${BOLD}serve-only${RESET} · bind ${BIND_HOST}"
elif [ "$GENERATE_ONLY" -eq 1 ]; then echo -e "  mode: ${BOLD}generate-only${RESET} · target ${GEN_TARGET} · generator ${GENERATOR}"
else echo -e "  mode: same-box · generator ${GENERATOR}"; fi
echo -e "${BOLD}═══════════════════════════════════════════════════════${RESET}"
echo

# ════════════════════════════════════════════════════════════════
#  GENERATE-ONLY: no servers here — just drive load against --target.
# ════════════════════════════════════════════════════════════════
if [ "$GENERATE_ONLY" -eq 1 ]; then
  command -v node >/dev/null 2>&1 || { fail "Node.js is required."; exit 1; }
  if [ "$GENERATOR" = "oha" ] && ! command -v oha >/dev/null 2>&1; then
    fail "--generator=oha but 'oha' is not installed (brew install oha / cargo install oha)."; exit 1
  fi
  ( cd bench && npm install --silent ) >/dev/null 2>&1 || warn "npm install (bench runner) failed"

  if [ "$SKIP_PARITY" -eq 0 ]; then
    info "Verifying endpoint parity against ${GEN_TARGET}..."
    parity_suite="$SUITE"; [ "$SUITE" = "all" ] && parity_suite="all"
    ( cd bench && node verify-parity.mjs --suite="$parity_suite" --host="$GEN_TARGET" \
        --pyxle-url="http://${GEN_TARGET}:8011" --nextjs-url="http://${GEN_TARGET}:3000" ) \
      || { fail "Parity check failed — fix framework parity or pass --skip-parity."; exit 1; }
  fi

  api_args=("--host=$GEN_TARGET" "--generator=$GENERATOR")
  ssr_args=("--pyxle-url=http://${GEN_TARGET}:8011" "--nextjs-url=http://${GEN_TARGET}:3000" "--generator=$GENERATOR")
  [ -n "$DURATION" ]    && { api_args+=("--duration=$DURATION"); ssr_args+=("--duration=$DURATION"); }
  [ -n "$CONNECTIONS" ] && { api_args+=("--connections=$CONNECTIONS"); ssr_args+=("--connections=$CONNECTIONS"); }
  [ -n "$WARMUP" ]      && { api_args+=("--warmup-duration=$WARMUP"); ssr_args+=("--warmup-duration=$WARMUP"); }
  [ -n "$REPS" ]        && { api_args+=("--reps=$REPS"); ssr_args+=("--reps=$REPS"); }
  [ -n "$LATENCY_RATE" ] && ssr_args+=("--latency-rate=$LATENCY_RATE")
  [ -n "$FRAMEWORKS" ]  && api_args+=("--only=$FRAMEWORKS")
  [ -n "$OUTPUT" ]      && { api_args+=("--output=$API_OUT"); ssr_args+=("--output=$SSR_OUT"); }

  rc=0
  if [ "$need_api" -eq 1 ]; then info "Running API throughput suite..."; ( cd bench && node api.mjs "${api_args[@]}" ) || rc=$?; fi
  if [ "$need_ssr" -eq 1 ]; then info "Running SSR suite...";            ( cd bench && node ssr.mjs "${ssr_args[@]}" ) || rc=$?; fi
  echo
  [ "$rc" -eq 0 ] && ok "Benchmark complete. Results under results/." || fail "Benchmark finished with INVALID cells (exit $rc) — see output above."
  exit "$rc"
fi

# ════════════════════════════════════════════════════════════════
#  SERVE-ONLY and SAME-BOX both need the servers up.
# ════════════════════════════════════════════════════════════════
trap cleanup EXIT

# ── preflight ─────────────────────────────────────────────────────
command -v node    >/dev/null 2>&1 || { fail "Node.js is required but not found."; exit 1; }
command -v python3 >/dev/null 2>&1 || { fail "Python 3 is required but not found."; exit 1; }

# ── python venv (reproducible) ────────────────────────────────────
if [ ! -d .venv ]; then
  info "Creating .venv ..."
  python3 -m venv .venv || { fail "Could not create .venv"; exit 1; }
fi
# shellcheck disable=SC1091
source .venv/bin/activate

# Pyxle needs Python >= 3.10. On AL2023 `python3` is 3.9 unless the setup shim
# is on PATH — fail loud rather than silently building a broken venv.
pyok="$(python -c 'import sys; print(1 if sys.version_info[:2] >= (3,10) else 0)' 2>/dev/null || echo 0)"
if [ "$pyok" != "1" ]; then
  fail "Python in .venv is $(python --version 2>&1) — Pyxle needs >= 3.10."
  fail "On Amazon Linux run scripts/ec2-setup.sh and start a NEW shell (it puts python3.11 on PATH), then delete .venv and re-run."
  exit 1
fi

# ── install ───────────────────────────────────────────────────────
if [ "$SKIP_INSTALL" -eq 0 ]; then
  info "Installing dependencies (pass --skip-install to reuse)..."
  pip install -q --upgrade pip >/dev/null 2>&1
  # PYXLE_LOCAL_SRC=/path/to/pyxle installs an editable local checkout instead of
  # the published wheel — used to benchmark unreleased framework changes.
  # Pyxle itself is required — a failed install would silently benchmark a
  # broken/absent server, so this one is fatal (others stay best-effort warns).
  if [ -n "${PYXLE_LOCAL_SRC:-}" ]; then
    info "Installing editable pyxle from ${PYXLE_LOCAL_SRC}"
    pip install -q -e "$PYXLE_LOCAL_SRC" >/dev/null 2>&1 || { fail "editable install of $PYXLE_LOCAL_SRC failed"; exit 1; }
  else
    pip install -q pyxle-framework >/dev/null 2>&1 || { fail "pip install pyxle-framework failed — is it published?"; exit 1; }
  fi
  for fw in fastapi django flask pyxle-ssr; do
    [ -f "frameworks/$fw/requirements.txt" ] && { pip install -q -r "frameworks/$fw/requirements.txt" >/dev/null 2>&1 || warn "pip install for $fw failed"; }
  done
  ( cd bench && npm install --silent ) || warn "npm install (bench runner) failed"
  if [ "$need_api" -eq 1 ]; then
    for fw in express hono pyxle; do
      ( cd "frameworks/$fw" && npm install --silent ) || warn "npm install for $fw failed"
    done
  fi
  # Next.js is used by BOTH suites (it serves the API endpoints AND the SSR pages).
  ( cd frameworks/nextjs && npm install --silent ) || warn "npm install for nextjs failed"
  [ "$need_ssr" -eq 1 ] && { ( cd frameworks/pyxle-ssr && npm install --silent ) || warn "npm install for pyxle-ssr failed"; }
  ok "Dependencies installed."
fi

# ── capture framework versions (disclosure) ───────────────────────
capture_versions() {
  mkdir -p results
  py_ver()   { python -c "import importlib.metadata as m;print(m.version('$1'))" 2>/dev/null || echo "?"; }
  node_ver() { node -e "try{console.log(require('./frameworks/$1/node_modules/$2/package.json').version)}catch(e){console.log('?')}" 2>/dev/null || echo "?"; }
  cat > results/.framework-versions.json <<EOF
{
  "oha": "$(oha --version 2>/dev/null | awk '{print $2}' || echo '?')",
  "flask-gthread-threads": "${FLASK_THREADS}",
  "pyxle-framework": "$(py_ver pyxle-framework)",
  "fastapi": "$(py_ver fastapi)",
  "starlette": "$(py_ver starlette)",
  "uvicorn": "$(py_ver uvicorn)",
  "gunicorn": "$(py_ver gunicorn)",
  "django": "$(py_ver django)",
  "flask": "$(py_ver flask)",
  "node": "$(node --version)",
  "express": "$(node_ver express express)",
  "hono": "$(node_ver hono hono)",
  "hono-node-server": "$(node_ver hono @hono/node-server)",
  "better-sqlite3": "$(node_ver express better-sqlite3)",
  "next": "$(node_ver nextjs next)",
  "react": "$(node_ver nextjs react)"
}
EOF
}
capture_versions
ok "Captured framework versions → results/.framework-versions.json"

# ── build ─────────────────────────────────────────────────────────
if [ "$SKIP_BUILD" -eq 0 ]; then
  info "Building apps (pass --skip-build to reuse)..."
  if [ "$need_api" -eq 1 ]; then
    ( cd frameworks/pyxle && pyxle build >/dev/null 2>&1 ) && ok "Built Pyxle (API)." || warn "Pyxle (API) build failed."
  fi
  if [ "$need_ssr" -eq 1 ]; then
    ( cd frameworks/pyxle-ssr && pyxle build >/dev/null 2>&1 ) && ok "Built Pyxle SSR." || warn "Pyxle SSR build failed."
  fi
  ( cd frameworks/nextjs && ./node_modules/.bin/next build >/dev/null 2>&1 ) && ok "Built Next.js." || warn "Next.js build failed."
fi

# ── start servers ─────────────────────────────────────────────────
info "Starting servers (bind ${BIND_HOST})..."
[ "$MULTICORE" -eq 1 ] && ok "Multi-core mode: ${WORKERS} worker(s)/framework — saturating all CPU cores."

if [ "$need_api" -eq 1 ]; then
  if [ "$MULTICORE" -eq 1 ]; then
    # Each framework scaled to ${WORKERS} OS processes via its standard production
    # multi-process model — Python: uvicorn/gunicorn --workers; Node: cluster
    # (workers share one listen socket, kernel round-robins, no extra proxy hop).
    start "Pyxle"   8001 frameworks/pyxle   pyxle serve --host "$BIND_HOST" --port 8001 --skip-build --workers "$WORKERS" --ssr-workers 1
    start "FastAPI" 8002 frameworks/fastapi uvicorn main:app --host "$BIND_HOST" --port 8002 --workers "$WORKERS" --log-level error
    start "Django"  8003 frameworks/django  env DJANGO_SETTINGS_MODULE=benchapp.settings uvicorn benchapp.asgi:application --host "$BIND_HOST" --port 8003 --workers "$WORKERS" --log-level error
    # Flask is synchronous: one gunicorn worker PER core (matching everyone
    # else's process count) with a fixed, disclosed gthread thread count for
    # intra-process concurrency (its production model). Threads are NOT extra
    # processes — total worker processes = $WORKERS, same as the others.
    start "Flask"   8004 frameworks/flask   gunicorn -w "$WORKERS" -k gthread --threads "$FLASK_THREADS" -b "$BIND_HOST:8004" app:app --log-level error
    start "Express" 8005 frameworks/express env PORT=8005 HOST="$BIND_HOST" WORKERS="$WORKERS" node cluster.mjs
    start "Hono"    8006 frameworks/hono    env PORT=8006 HOST="$BIND_HOST" WORKERS="$WORKERS" node cluster.mjs
  else
    start "Pyxle"   8001 frameworks/pyxle   pyxle serve --host "$BIND_HOST" --port 8001 --skip-build
    start "FastAPI" 8002 frameworks/fastapi uvicorn main:app --host "$BIND_HOST" --port 8002 --log-level error
    start "Django"  8003 frameworks/django  env DJANGO_SETTINGS_MODULE=benchapp.settings uvicorn benchapp.asgi:application --host "$BIND_HOST" --port 8003 --log-level error
    # ONE Flask worker (the single-worker / per-core baseline), same as every
    # other framework here, with the disclosed gthread thread count.
    start "Flask"   8004 frameworks/flask   gunicorn -w 1 -k gthread --threads "$FLASK_THREADS" -b "$BIND_HOST:8004" app:app --log-level error
    start "Express" 8005 frameworks/express env PORT=8005 HOST="$BIND_HOST" node app.mjs
    start "Hono"    8006 frameworks/hono    env PORT=8006 HOST="$BIND_HOST" node app.mjs
  fi
fi

if [ "$need_ssr" -eq 1 ]; then
  if [ "$MULTICORE" -eq 1 ]; then
    start "Pyxle SSR" 8011 frameworks/pyxle-ssr pyxle serve --host "$BIND_HOST" --port 8011 --skip-build --workers "$WORKERS" --ssr-workers 1
  else
    start "Pyxle SSR" 8011 frameworks/pyxle-ssr pyxle serve --host "$BIND_HOST" --port 8011 --skip-build
  fi
fi

# Next.js serves both API endpoints and SSR pages — start once for either suite.
if [ "$MULTICORE" -eq 1 ]; then
  start "Next.js" 3000 frameworks/nextjs env PORT=3000 HOST="$BIND_HOST" WORKERS="$WORKERS" node cluster-server.mjs
else
  start "Next.js" 3000 frameworks/nextjs ./node_modules/.bin/next start -p 3000 -H "$BIND_HOST"
fi

boot_wait=8; [ "$MULTICORE" -eq 1 ] && boot_wait=15
info "Waiting for servers to boot..."
sleep "$boot_wait"

# ── health check (always via loopback; a 0.0.0.0 bind answers there too) ──
HEALTH=()
if [ "$need_api" -eq 1 ]; then
  HEALTH+=("http://127.0.0.1:8001/api/healthz" "http://127.0.0.1:8002/health" "http://127.0.0.1:8003/health" "http://127.0.0.1:8004/health" "http://127.0.0.1:8005/health" "http://127.0.0.1:8006/health")
fi
[ "$need_ssr" -eq 1 ] && HEALTH+=("http://127.0.0.1:8011/api/healthz")
HEALTH+=("http://127.0.0.1:3000/health")

ready=0
for url in "${HEALTH[@]}"; do
  code=000
  for _ in $(seq 1 40); do
    code=$(curl -s -o /dev/null -w "%{http_code}" "$url" 2>/dev/null || echo 000)
    [ "$code" = "200" ] && break
    sleep 1
  done
  if [ "$code" = "200" ]; then ready=$((ready + 1)); else warn "not responding (HTTP $code): $url"; fi
done
ok "${ready}/${#HEALTH[@]} servers ready."
if [ "$ready" -lt "${#HEALTH[@]}" ] && [ "$ALLOW_PARTIAL" -eq 0 ]; then
  fail "Only ${ready}/${#HEALTH[@]} servers came up — aborting so a missing framework isn't silently dropped from the results."
  fail "Pass --allow-partial to benchmark the servers that did start."
  exit 1
fi
echo

# ── parity verification (gate) ────────────────────────────────────
if [ "$SKIP_PARITY" -eq 0 ]; then
  info "Verifying endpoint parity..."
  ( cd bench && node verify-parity.mjs --suite="$SUITE" --host=127.0.0.1 \
      --pyxle-url=http://127.0.0.1:8011 --nextjs-url=http://127.0.0.1:3000 ) \
    || warn "Parity check reported issues (see above). The runner's correctness gate will still exclude any erroring cell."
  echo
fi

# ════════════════════════════════════════════════════════════════
#  SERVE-ONLY: hold the servers up for an off-box client, then idle.
# ════════════════════════════════════════════════════════════════
if [ "$SERVE_ONLY" -eq 1 ]; then
  echo
  ok "Servers are up on ${BIND_HOST}. Drive load from the client box, e.g.:"
  echo -e "    ${BOLD}./bench.sh --generate-only --target=<this-box-ip> --generator=oha --suite=${SUITE} --reps=5 --duration=30 --warmup-duration=20 --connections=100${RESET}"
  echo
  info "Idling (Ctrl-C to stop the servers)..."
  wait
  exit 0
fi

# ════════════════════════════════════════════════════════════════
#  SAME-BOX: run the generator locally (quick check; autocannon).
# ════════════════════════════════════════════════════════════════
api_args=("--host=$GEN_TARGET" "--generator=$GENERATOR")
ssr_args=("--pyxle-url=http://${GEN_TARGET}:8011" "--nextjs-url=http://${GEN_TARGET}:3000" "--generator=$GENERATOR")
[ -n "$DURATION" ]    && { api_args+=("--duration=$DURATION"); ssr_args+=("--duration=$DURATION"); }
[ -n "$CONNECTIONS" ] && { api_args+=("--connections=$CONNECTIONS"); ssr_args+=("--connections=$CONNECTIONS"); }
[ -n "$WARMUP" ]      && { api_args+=("--warmup-duration=$WARMUP"); ssr_args+=("--warmup-duration=$WARMUP"); }
[ -n "$REPS" ]        && { api_args+=("--reps=$REPS"); ssr_args+=("--reps=$REPS"); }
[ -n "$LATENCY_RATE" ] && ssr_args+=("--latency-rate=$LATENCY_RATE")
[ -n "$FRAMEWORKS" ]  && api_args+=("--only=$FRAMEWORKS")
[ -n "$OUTPUT" ]      && { api_args+=("--output=$API_OUT"); ssr_args+=("--output=$SSR_OUT"); }

rc=0
if [ "$need_api" -eq 1 ]; then
  info "Running API throughput suite..."
  ( cd bench && node api.mjs "${api_args[@]}" ) || rc=$?
fi
if [ "$need_ssr" -eq 1 ]; then
  info "Running SSR latency suite..."
  ( cd bench && node ssr.mjs "${ssr_args[@]}" ) || rc=$?
fi

echo
if [ "$rc" -eq 0 ]; then
  ok "Benchmark complete. Results saved under results/."
else
  fail "Benchmark finished with INVALID cells (exit $rc). Those cells are excluded; see output above."
fi
exit "$rc"