# 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