rtp-proxy-ADR-008 — BungeeCord / Waterfall Adapter Bootstrap¶
Status: Proposed Date: 2026-05-13 Refines: leafrtp-ADR-022 Depends on: rtp-proxy-ADR-001, rtp-proxy-ADR-002, rtp-proxy-ADR-006
Context¶
BungeeCord is the secondary proxy target (Phase 3). Waterfall (and tolerated forks Hexacord/FlameCord/Travertine) share the BungeeCord API surface — a single artifact must work on all of them (REQ-RTP-PROXY-BUNGEE-001, -007). BungeeCord differs from Velocity in three ways that drive this ADR:
- No Brigadier. BungeeCord ships a
Command/TabExecutorAPI;commands-api's non-Brigadier surface must be used. - No async event chain.
ServerConnectEventis the closest analogue to Velocity'sServerPreConnectEventbut is synchronous (handlers run on the upstream-bridge thread). - Different scheduler.
ProxyServer#getScheduler()returns aTaskSchedulerwithrunAsyncsemantics; there is no public-stable async pool size knob.
Decision¶
RTPBungeePlugin extends net.md_5.bungee.api.plugin.Plugin in rtp-proxy-bungee, single Maven coordinate, runs unchanged on BungeeCord and Waterfall.
Activation (REQ-RTP-PROXY-009)¶
onEnable():
- Load
network.yml(ADR-002). - If
network.enabled: false→ register only the admin command surface (reload, test); no listeners, no transport (REQ-RTP-PROXY-008). - If enabled → boot the same component stack as the Velocity adapter (transport → selector → reservation client → heartbeat publisher → triggers → commands).
onDisable() tears down in reverse order. BungeeCord's plugin shutdown is best-effort during proxy stop; transport close() is awaited with a 1s deadline (BungeeCord kills the JVM aggressively).
Server Rewrite via ServerConnectEvent (REQ-RTP-PROXY-BUNGEE-002)¶
The listener subscribes to ServerConnectEvent with @EventHandler(priority = HIGHEST) and uses event.registerIntent(plugin) + event.completeIntent(plugin) to defer the connection without blocking the upstream-bridge thread:
- On intercept, the listener registers an intent and dispatches the claim work to
proxy.getScheduler().runAsync(plugin, …). - When
ReservationClientresolvesRouted(serverId, tokenId), the listener callsevent.setTarget(serverInfo)and completes the intent. - On
Failed, it cancels the event (event.setCancelled(true)), surfaces the configurable message, and completes the intent so the player remains on their current backend (REQ-RTP-PROXY-VELOCITY-004 analogue).
This is the BungeeCord-idiomatic "async event continuation" pattern and is necessary because synchronous handlers cannot block on transport I/O without stalling every reconnect across the proxy.
Command Hosting (REQ-RTP-PROXY-BUNGEE-003)¶
/rtpregistered viaproxy.getPluginManager().registerCommand(plugin, new RtpBungeeCommand(...)).- The command class extends BungeeCord's
Command+ implementsTabExecutor. - Argument parsing and dispatch reuse the non-Brigadier
commands-apisurface (the same surface Spigot already targets). No Velocity-only classes are dragged in. - Tab-completion routes through
BackendTabCompletionRouter(shared with Velocity, REQ-RTP-PROXY-BUNGEE-006).
Scheduler Discipline (REQ-RTP-PROXY-BUNGEE-004)¶
- All persistence and transport calls invoked from event handlers go through
proxy.getScheduler().runAsync(plugin, runnable). - A runtime guard inspects
Thread.currentThread().getName()and throwsIllegalStateExceptionif the SPI is invoked from the upstream-bridge thread (caught in development; logged + recovered in production).
Plugin-Message Transport Eligibility (REQ-RTP-PROXY-BUNGEE-005)¶
When transport.type: plugin-message:
- The plugin emits a startup
WARNING("plugin-message transport is dev-only; enable a durable transport for production"). - A
developerMode: trueconfig knob (default false, not in the canonical schema — a guarded extension) is required to actually open the transport. Without it, network mode refuses to enable. - This satisfies D2 (durable transport required for production) without removing the developer affordance.
Waterfall / Fork Tolerance (REQ-RTP-PROXY-BUNGEE-007)¶
- No Waterfall-specific imports. The adapter uses only
net.md_5.bungee.api.*types. - A runtime detection (
Class.forName("io.github.waterfallmc.waterfall.event.…")) enables Waterfall-only event hooks defensively — if present, use them; if absent, fall back to BungeeCord behaviour. - Forks (Hexacord, FlameCord, Travertine) are not separately tested; the contract is "if BungeeCord API works, the adapter works".
Bundled Resources¶
src/main/resources/bungee.ymldeclares the entry class (BungeeCord plugin descriptor).src/main/resources/network.ymlis the byte-identical canonical default (ADR-002).src/main/resources/messages/network.<locale>.ymlcarries configurable strings (REQ-RTP-PROXY-006).
Alternatives Considered¶
| Alternative | Why Rejected |
|---|---|
Block ServerConnectEvent synchronously while claim resolves |
Stalls every other reconnect on the upstream-bridge thread; trivially DoS-able. |
Use ProxiedPlayer#connect(serverInfo) outside the event |
Bypasses event listeners other plugins rely on (anti-cheat, audit); ecosystem-unfriendly. |
| Ship Waterfall-specific build | Violates REQ-RTP-NET-003 (single artifact); operators would have to choose. |
| Inline a Brigadier shim for BungeeCord | BungeeCord's command framework is incompatible with Mojang Brigadier without protocol-level surgery; out of scope. |
Consequences¶
- Positive: Phase 3 is a thin adapter (entry + listener + command + publisher), all reusing
rtp-proxy-common. Waterfall is free via API parity. - Negative: intent-based deferred connect requires careful handling to avoid leaking intents on player disconnect (a
PlayerDisconnectEventlistener cancels pending intents); this is the primary regression-test target for Phase 3.
References¶
- ADR-036;
MULTI_SERVER_PLAN.mdPhase 3. REQ-RTP-PROXY-BUNGEE-001…007;REQ-RTP-PROXY-003,-005,-006,-009,-011.- D2 (durable transport required outside dev).