71 lines
2.3 KiB
Markdown
71 lines
2.3 KiB
Markdown
# 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
|
|
1. On proxy startup, reads `ZPACK_SHARED_SECRET` from environment
|
|
2. If the secret exists, starts an HTTP server on `0.0.0.0:8081`
|
|
3. 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)
|
|
```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)
|
|
```ini
|
|
[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
|