ZpackVelocityBridge — Plugin Documentation

Overview

A small HTTP bridge plugin for Velocity that dynamically adds/removes backend game servers and routes new players to the most recently registered server.

Startup Behavior

On proxy startup, reads ZPACK_SHARED_SECRET from environment
If the secret exists, starts an HTTP server on 0.0.0.0:8081
Exposes two POST endpoints for server registration/unregistration

HTTP Endpoints

POST /zpack/register

Registers a backend server in Velocity and marks it as the current join target.

Request body:

server_name=mc-vanilla-5129
address=10.200.0.15
port=25565

POST /zpack/unregister

Unregisters a backend server from Velocity. Clears join target if it was the active one.

Request body:

server_name=mc-vanilla-5129

Authentication

All requests must include the header:

X-Zpack-Secret: <sha256(ZPACK_SHARED_SECRET) in hex>

The secret is set via environment variable ZPACK_SHARED_SECRET in the Velocity service file.

Player Routing

On PostLoginEvent, if a "latest registered" backend exists, the player is immediately sent to that backend. If no server is registered, the player gets: "There are no available servers to connect you to."

Important Notes

Server registrations are in-memory only — lost on Velocity restart
After a Velocity restart, all active containers must be re-registered via the API
ZpackCommands class exists (/zpack status/list/reload) but is not currently registered — commands won't work unless command registration is added

Configuration (config.properties)

http.bind=0.0.0.0
http.enabled=true
http.port=8081
# ZPACK_SHARED_SECRET set via environment variable in systemd service

Environment Setup (systemd service)

[Service]
Environment="ZPACK_SHARED_SECRET=zpackplugin"
ExecStart=/usr/bin/java -Xms128M -Xmx512M -jar velocity.jar

Known Gaps / Future Work

No persistence — Velocity restart requires re-registration of all active containers
API should have a /velocity/resync endpoint to re-register all running containers after restart
ZpackCommands not registered — add command registration for ops/admin use
Only one "latest" server tracked — last registered wins for new player routing

2.3 KiB Raw Blame History