Local load-testing dashboard for Eaglercraft Minecraft servers (WebSocket). For authorized testing only — you must own the target server or have written permission.

What it does

Spawns a configurable number of fake MC 1.12.2 (Protocol 340) clients over WebSocket, routes them through a SOCKS proxy pool, performs the EaglerV2 + MC login handshake, optionally sends /register//login and chat messages, and keeps them alive on keep-alive packets. The dashboard shows live bot state, proxy health, and structured logs.

What's new in v2

• MC protocol fix: proper length-prefixed packet framing, Set Compression handling, and correct Position and Look parsing (Little Endian, bitmask, VarInt teleport ID).
• Compression-aware: bots negotiate compression when the server enables it (zlib raw).
• Auth state machine: structured matching on translate keys (commands.register.success, etc.) instead of brittle substring search.
• Proxy registry v2: JSON persistence, scoring (0–100), weighted picking strategies (best-score, round-robin, least-used, random), per-proxy inflight caps, EMA latency, automatic retest-after-cooldown.
• Per-bot inspector: click "Inspect" on any bot to see packets, proxy, last error, and chat from a single bot.
• Rate limits: login, proxy upload, test start, broadcast chat all rate-limited.
• Security: helmet CSP, httpOnly + sameSite=strict cookies, HMAC-SHA256 session tokens, constant-time password compare, refuses to boot with default SESSION_SECRET.
• Observability: /healthz, /metrics (Prometheus), /api/diagnostics, structured JSON daily logs, log throttling.
• Frontend: score-colored proxy table, log filter, search, level toggles, per-bot inspector panel.

Quick start

cp .env.example .env  # if you don't have one
# Edit .env: set SITE_PASSWORD and SESSION_SECRET

npm install
npm start

Open http://localhost:6070 and enter your SITE_PASSWORD.

Tests

npm run check   # syntax check on all source files
npm test        # unit tests (packets, codec, compression, auth, registry)
npm run smoke   # boot the server, hit endpoints, verify shape

Project layout

src/
  config.js          config loading + env validation
  state.js           shared mutable state + event bus
  auth.js            HMAC tokens, cookie parser, constant-time compare
  io.js              Socket.IO + throttled broadcaster
  validate.js        input validation
  server.js          bootstrap (express, helmet, routes, lifecycle)
  proxy/
    registry.js      ProxyRegistry class (scoring, persistence, picking)
    lease.js         per-test proxy lease
    workerPool.js    generic async worker pool
  bot/
    packets.js       VarInt, strings, MC framing helpers
    codec.js         Eagler + MC 1.12.2 packet parsers/builders
    compression.js   zlib threshold handling
    auth.js          AuthStateMachine
    bot.js           Bot class — state machine
  routes/
    auth.js          /api/auth/*
    test.js          /api/test/*
    proxy.js         /api/proxy/*
    bots.js          /api/bots/*
    stats.js         /api/stats, /api/logs
    health.js        /healthz, /metrics, /diagnostics
  util/
    log.js           structured logger (daily rotation)
    throttle.js      throttle + coalescer
test/                node:test unit tests
scripts/
  smoke.js           end-to-end smoke test
  migrate-proxies.js one-shot proxies.txt → proxies.json

Environment

Var	Required	Description
SITE_PASSWORD	yes	Dashboard login password
SESSION_SECRET	yes	Random secret for HMAC-signed cookies. Refuse to boot if unset or default.
PORT	no	Override config.yaml server.port
HOST	no	Override config.yaml server.host

Configuration

config.yaml is non-sensitive. Top-level keys:

• server.{port, host} — defaults to 6070 / 0.0.0.0
• bots.{max_bots, default_rate, default_spawn_delay, max_spawn_delay, max_packet_rate, password, join_delay_ms, chat_messages, auth_phrases, auth_timeout_ms} — bot limits and defaults
• proxy.{test_timeout_ms, concurrency, max_list_size, probe_host, probe_port, score_decay_ms, score_penalty_per_fail, score_recovery_after_ms, alive_latency_max_ms, per_proxy_inflight_cap, default_strategy} — proxy pipeline tuning
• logging.{max_log_entries, max_dom_logs, daily_log_dir} — log buffering
• auth.session_hours — cookie lifetime
• rate_limits.* — per-route limits
• cors.origins — CORS allowlist; empty = same-origin only
• quick_commands — list of /command strings available in the dashboard's quick-actions panel

Threat model

This tool is intended for local development and authorized load testing of servers you own or have explicit written permission to test. Use against systems without authorization is illegal.

The dashboard binds to 0.0.0.0 by default; if you're on a multi-tenant host, override HOST in config.yaml to 127.0.0.1. The default rate limits and CORS are tuned for single-user local use; if you expose this beyond localhost, add a reverse proxy with auth and tighten further.

License

MIT