Document ZpackVelocityBridge plugin behavior and known gaps

SCRATCH/velocity-plugin.md

@@ -0,0 +1,70 @@
+# 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