Velocity boost

Performance, protection, and observability for Velocity proxies — without replacing the proxy's core networking.

VelocityBoost is a lightweight plugin for Velocity 3.x that reduces abusive server-list traffic, keeps players away from dead backends, and adds simple operational visibility. It is designed as a drop-in addition: no external runtime dependencies, no patching of Velocity internals, and no changes to how the proxy handles normal connections.

Features
Server-list ping cache and anti-flood
Per-IP token bucket, optional global ping budget, TTL-based response cache, and automatic cache cleanup. Excess pings receive the last cached response instead of triggering fresh work. The plugin throttles and caches responses at the API level; it cannot intercept pings before Velocity begins processing them (see Known limits).

Health-aware load balancing
P2C (power of two choices) or least-connections selection with configurable failover. Players are tracked per server, so load counters stay accurate across reconnects and disconnects.

Backend health checks
Asynchronous pings with configurable timeout and failure threshold. Unhealthy servers are excluded from selection and automatically restored after recovery.

Chat and command rate limiting
Lock-free token buckets applied per UUID and per IP. Signed chat and signed commands are handled safely to avoid kicks on 1.19.1+.

Batching scaffold
Coalescing queue for high-frequency updates — an API building block for future work.

Metrics and admin command
/vboost status (alias /vb) reports cache hits, throttled pings, denied chat/commands, tracked keys, unhealthy servers, and queue size. Permission: velocityboost.admin.

Minimal footprint
No external runtime dependencies; Netty and the Velocity API are provided by the proxy.

Benchmark results
Test setup: Velocity 3.4.0 (build 566), Java 21, loopback, 48 concurrent connections, 2,000 measured pings + 2,000 warm-up pings per run. Plugin limits: 3 pings/s per IP, 500 pings/s global, 3 s cache TTL.

Metric Without plugin With VelocityBoost Change
Throughput 12,999 ping/s 12,532 ping/s −3.5%
Server CPU per 2,000 pings 805 ms 922 ms +15%
p50 latency 2.48 ms 2.51 ms +1%
p99 latency 9.1 ms 17.0 ms +87%
Errors 0 0 —
Memory (RSS) 315 MB 329 MB +14 MB
Responses served from cache — 10,800 —
Pings actually processed 10,800 9 −99.9%
How to read these numbers. In this synthetic benchmark, VelocityBoost reduces actual ping processing by 99.9% (10,800 → 9), but because the proxy still performs its own per-request work before the plugin can respond, end-to-end throughput and latency do not improve — they regress slightly (p99 +87%). The plugin is therefore best understood as a traffic-shaping and protection layer rather than a raw throughput optimization. Real-world behavior depends heavily on traffic mix and on how much of the load is abusive.

Token bucket: previous vs. optimized implementation

Scenario Previous (2 × AtomicLong) Optimized (single CAS) Speedup
1 thread 43.3 ns/op 39.2 ns/op 1.11×
8 threads, shared bucket 149.0 ns/op 55.3 ns/op 2.70×
8 threads, per-thread buckets 19.8 ns/op 12.5 ns/op 1.58×
Compatibility
Velocity 3.x (built against Velocity API 3.4.0)

Java 17+ (class target: 17)

Netty 4.1 (provided by Velocity)

Configuration
TOML config with sections for general, ping-cache, balancer, ratelimit, batching, health, metrics, and jfr. Invalid values are clamped at startup; unknown keys are ignored.

Known limits
Velocity's public API cannot intercept server-list pings before the proxy processes them, so the ping module throttles and caches responses but cannot eliminate the proxy's per-request work.

Packet batching and JFR integration are scaffolding; they do not patch Velocity internals.

No HTTP metrics exporter is included.