rtp-proxy-ADR-006 — Velocity Adapter Bootstrap¶
Status: Accepted Date: 2026-05-13 (Accepted 2026-05-18) Refines: leafrtp-ADR-022 Depends on: rtp-proxy-ADR-001, rtp-proxy-ADR-002, rtp-proxy-ADR-005
Context¶
Velocity is the primary proxy target (Phase 2). It is the only proxy in the v1 plan that hosts a Brigadier command manager, supports ServerPreConnectEvent mid-session backend rewrites, and ships a public Scheduler async pool. This ADR pins how rtp-proxy-velocity plugs into the host runtime.
Decision¶
Plugin Identity (REQ-RTP-PROXY-VELOCITY-007)¶
@Plugin(id = "rtp", name = "RTP", version = <umbrella>, authors = …, dependencies = {}).- Version coupled to the
rtp-pluginumbrella version. Mismatched proxy/backend versions are detected at first heartbeat viaschemaVersion(ADR-010) and produce a configurable warning. - Target: Velocity 3.3.x or later, Java 21+ (REQ-RTP-PROXY-VELOCITY-001).
Activation (REQ-RTP-PROXY-009)¶
The plugin's @Subscribe ProxyInitializeEvent handler:
- Loads
network.yml(ADR-002). - If
network.enabled: false→ no listeners registered, no scheduler tasks, no transport opened. Plugin remains loaded so/rtpadmin commands (reload,test) still function, but every operational path no-ops (REQ-RTP-PROXY-008). - If enabled → boot in this order:
NetworkTransport(pertransport.type) →BackendSelector→ReservationClient→ProxyStatePublisher→ trigger sources → command registration.
Shutdown (@Subscribe ProxyShutdownEvent) tears down in reverse order; NetworkTransport.close() is awaited with a 2s deadline.
Server Rewrite via ServerPreConnectEvent (REQ-RTP-PROXY-VELOCITY-003)¶
Network teleports flow through the ServerPreConnectEvent listener:
- Listener intercepts; if the event already targets the player's RTP-resolved destination (tagged via a
correlationIdmap keyed byplayerId), pass through. - Otherwise, do not block the event. Call
event.setResult(ServerPreConnectEvent.ServerResult.denied())only when the dispatcher has surfaced aFailedoutcome. - The dispatcher's coordination work runs entirely on
proxyServer.getScheduler().buildTask(plugin, …).schedule()(async pool). The listener returns immediately. - Once
ReservationClientresolvesRouted(serverId, tokenId), the listener emits a freshplayer.createConnectionRequest(target).fireAndForget()(or re-fires the original viaServerResult.allowed(target)if still in flight).
Player Session Continuity (REQ-RTP-PROXY-VELOCITY-004)¶
- A failed transfer never disconnects the player. The dispatcher's
Failedoutcome callsProxySender.sendMessage(playerId, messageKey, placeholders)and leaves the player on their current backend. isConnected(playerId)is checked before every transport claim attempt; disconnected players have their pending claim released immediately (REQ-RTP-NET-011 TTL is the secondary safety net).
Command Hosting (REQ-RTP-PROXY-VELOCITY-002)¶
/rtpregistered throughproxyServer.getCommandManager().register(meta, new BrigadierCommand(rootNode)).- Root node built by the shared
commands-apiBrigadier bridge (commands-api-ADR-001); the adapter contributes only the VelocityBrigadierBridgeContext(sender adapter, permission lookup, locale resolver). - Tab-completion goes through
BackendTabCompletionRouter, which fan-outs a bounded query (REQ-RTP-PROXY-011) and serves from a per-proxy time-bounded cache.
Telemetry (REQ-RTP-PROXY-VELOCITY-006)¶
- Built with
proxyServer.getScheduler().buildTask(plugin, runnable).repeat(heartbeat.intervalMs, TimeUnit.MILLISECONDS).schedule(). - Writes
proxy_staterow keyed byproxyId(UPSERT semantics on the transport). - Snapshots include:
proxyId,schemaVersion,playerCount,connectedBackends[],pendingTokens,lastSeenEpochMs. No netty-internal stats in v1. - Runs only on the async pool; a runtime check (
Thread.currentThread().getName().startsWith("Netty")) fails fast in development with anIllegalStateException.
Threading Discipline¶
- All consumer-side hops from transport listeners use
scheduler.buildTask(plugin, runnable).schedule(), nevereventManager.fireAndForgetfrom a transport thread. - The plugin maintains zero per-tick state; all caches use
Caffeinewith explicitexpireAfterWrite.
Bundled Resources¶
src/main/resources/velocity-plugin.jsondeclares the entry class.src/main/resources/network.ymlships the canonical default (ADR-002) so a new deployment is one copy.src/main/resources/messages/network.<locale>.ymlcarries the configurable strings (REQ-RTP-PROXY-006).
Alternatives Considered¶
| Alternative | Why Rejected |
|---|---|
Register a Velocity-only RawCommand and skip Brigadier |
Loses argument-level tab-completion; diverges from Paper/Folia behaviour; defeats commands-api consolidation. |
Block in ServerPreConnectEvent until claim resolves |
Stalls the netty event loop; trivially DoS-able by sending many transfer requests. |
Issue player.createConnectionRequest directly without ServerPreConnectEvent integration |
Plugins that hook the event (anti-abuse, audit) miss our transfer; ecosystem-unfriendly. |
Per-player ScheduledTask for claim work |
Memory/CPU overhead at scale; one shared async pool is sufficient (Velocity sizes it appropriately). |
Consequences¶
- Positive: the Velocity adapter is small (entry + listener + publisher + tab router); most logic lives in
rtp-proxy-common. Operators get a single-JAR install. - Negative: Brigadier coupling means
commands-apiregressions can break the proxy too; mitigated by the bridge's own contract tests in Phase 1.
References¶
- ADR-036;
MULTI_SERVER_PLAN.mdPhase 2 acceptance. REQ-RTP-PROXY-VELOCITY-001…007;REQ-RTP-PROXY-003,-005,-006,-009,-011.commands-api-ADR-001(Brigadier bridge).