rtp-fabric-ADR-013 - Network-mode backend parity on Fabric (reimplementation, not refactor)¶
- Status: Superseded by leafrtp-ADR-032 (2026-05-23). The "8
org.bukkit.*coupling points inNetworkModeBootstrap" estimate that drove this ADR's rejection of the refactor path was re-audited on 2026-05-23 and is incorrect: the bootstrap has zero Bukkit imports, and the platform surface reduces to a single missing SPI primitive (player join / quit) plus aPredicate<CommandSender>generic. The lift-to-rtp-corepath is the cleaner choice. This ADR is preserved for context; do not implement the parallelFabricNetworkModeBootstrap/FabricJoinTriggerSourceit proposes. - Scope:
rtp-fabric(rtp-fabric-common, optional touch on per-version carriers for join-event sources) andrtp-plugin/.../fabric/. Does not modifyrtp-proxy-common,rtp-proxy-velocity, orrtp-proxy-bungee; those layers are already platform-agnostic. - Supersedes: none. Implements the Fabric clause of leafrtp-ADR-022 and the backend-side contract of the
rtp-proxy-*subproject ADRs. - Related: leafrtp-ADR-022 (umbrella network-mode ADR), rtp-proxy-ADR-014 (backend-owned RTP with network queue; defines the
NetworkModeBootstrapcontract this ADR mirrors), rtp-proxy-ADR-015 (shared waitlist + dynamic dispatch; consumed by the join-trigger source this ADR specifies), rtp-fabric-ADR-011 (reservation-token authorization leans onhasPermission),MULTI_SERVER_PLAN.md(phase status; backend integration is Phase 2 work).
Context¶
Network-mode multi-server support landed end-to-end on Paper in this cycle (user-confirmed working 2026-05-22). The Phase 1 SPI in rtp-proxy-common is platform-agnostic and already reachable from Fabric, but the Phase 2 backend integration is wired in Bukkit-only classes:
rtp-plugin/.../bukkit/network/NetworkModeBootstrap.java(~800 lines). Selects a transport (InMemoryNetworkStateBinding,RedisNetworkStateBinding,SqlNetworkStateBinding), installs the binding, constructs aBackendStatePublisherdriven byBukkitBackendStateSampler, constructs aReservationTokenReaper, constructs aJoinTriggerSource, and exposes aLIVEsingleton so the/rtpcommand can probe live state. Deeply coupled toorg.bukkit.plugin.Plugin,org.bukkit.scheduler.BukkitScheduler, andorg.bukkit.event.Listenerregistration (lines 610-615:Bukkit.getPluginManager().registerEvents(joinTriggerSource, plugin)). Lifecycle readsnetwork.ymltwice viareadLobbyModeEarly(File)and a full load.rtp-plugin/.../bukkit/network/JoinTriggerSource.java.implements org.bukkit.event.Listener. Drains reservation tokens against the backendkeptLocations/unkeptLocationspool onPlayerJoinEvent.
A Velocity-routed player arriving on a Fabric backend with a reservation token has no listener to redeem it: the lookup happens but the redeem-side handler is Bukkit-only. The cross-server flow therefore silently degrades on Fabric (the player joins normally; no RTP is performed; no error is surfaced to the proxy). This violates the Phase 2 acceptance criterion in MULTI_SERVER_PLAN.md that says "a backend that advertises RtpTriggerSource MUST redeem reservation tokens on join".
Two paths are available:
- Refactor
NetworkModeBootstrapinto a platform-neutral base class with a Fabric subclass overriding thePlugin/Listenerhooks. Estimated touch: everyorg.bukkit.*call inNetworkModeBootstrapandJoinTriggerSourcebecomes a deferred SPI method, the class moves fromrtp-plugin/bukkit/network/to a new package shared between platforms, and the ArchUnit guard (Step H) needs an exception or the class lives outside bothbukkit/andfabric/. - Reimplement as
FabricNetworkModeBootstrapinrtp-plugin/.../fabric/network/, mirroring the Bukkit class line-by-line but binding to Fabric event hooks. The platform-agnostic logic (transport selection, publisher install, reaper install,network.ymlschema) is already minimal in the Bukkit class because the heavy lifting is inrtp-proxy-common. The duplication is bounded.
The Bukkit class has eight independent coupling points to org.bukkit.* (Plugin, BukkitScheduler, PluginManager, Listener, PlayerJoinEvent, EventHandler, EventPriority, Bukkit.getOnlinePlayers()) and a LIVE static singleton consumed by command-side code. A base-class refactor would create an awkward "platform-neutral base that exposes seven abstract hooks" with a near-equal amount of Fabric-side code anyway. The reimplementation path is cleaner and isolates Fabric platform risk from the working Paper code.
Decision¶
Reimplement, do not refactor. Add a parallel FabricNetworkModeBootstrap and FabricJoinTriggerSource under rtp-plugin/.../fabric/network/, structurally mirroring the Bukkit class but binding to Fabric Loader event APIs.
1. FabricNetworkModeBootstrap¶
A new class under rtp-plugin/src/main/java/io/github/dailystruggle/rtp/fabric/network/FabricNetworkModeBootstrap.java:
- Static
LIVEsingleton, exposed to the Fabric command tree (RTPCmdFabricRoot) so/rtpprobes work whether network mode is on or off, exactly as on Paper. - Static
readLobbyModeEarly(File networkYml)andensureNetworkYml(File dataDir)are reused from the Bukkit class. They are pure I/O on a YAML file and do not importorg.bukkit.*. Refactor them up into a newNetworkModeBootstrapSupportutility inrtp-core(or a small shared package inrtp-apiif cleaner; ArchUnit guard does not block this because the file is under neitherbukkit/norfabric/). The Bukkit class then delegates to the shared utility, which is a minor refactor on the Bukkit side and the only place this ADR touches platform-neutral code. boot()selects transport, opens binding, constructs publisher, installs reaper, constructs join trigger source - identical sequence to Bukkit.registerJoinTriggerSource(ModContainer)(mirrorsregisterJoinTriggerSource(Plugin)): hooksServerPlayConnectionEvents.JOINvia Fabric API. On the obf carrier the same event is reached through the intermediary surface per rtp-fabric-ADR-009; on the unobf carrier through the deobf API directly. The dispatch goes throughFabricVersionAdapterso the bootstrap class itself stays inrtp-pluginand does not need an obf/unobf split.shutdownDrain()is wired toServerLifecycleEvents.SERVER_STOPPING, parallel to the BukkitonDisabledrain path. Same drain sequence: stop publisher, close reservation reaper, flush in-flight reservation tokens, close binding.
2. FabricJoinTriggerSource¶
A new class under rtp-plugin/.../fabric/network/FabricJoinTriggerSource.java:
- Does not implement
org.bukkit.event.Listener. Instead, exposes anonPlayerJoin(UUID playerId)method thatFabricNetworkModeBootstrapregisters as aServerPlayConnectionEvents.JOINcallback at boot. - Reservation-token redeem logic is reused from
rtp-proxy-common(theNetworkStateBinding.consumeReservationToken(UUID, String serverId)call). The Fabric-side wrapper only translates the platform-specific join callback to the platform-neutral SPI call. - Authorization mirrors the Bukkit path: the resolved
RTPPlayeris fetched viaRTP.serverAccessor.getPlayer(uuid)and the samehasPermission("rtp.onevent.join")check is applied. The check now resolves correctly on Fabric because rtp-fabric-ADR-011 shipped the LP-primary + closed-namespace probe resolver, which covers thertp.onevent.*namespace.
3. RtpTriggerSource install marker¶
RtpTriggerSource is the network-state marker that tells a proxy "this backend speaks RTP network mode and will redeem reservation tokens". On Bukkit it is registered through NetworkModeBootstrap.boot() against the active NetworkStateBinding. The Fabric class registers the identical marker through the identical SPI call; no Fabric-specific marker type is introduced.
4. network.yml extraction on Fabric¶
FabricNetworkModeBootstrap.ensureNetworkYml(dataDir) reuses FabricJarUtils.extractDocs from Step E3 to seed the operator's config/rtp/network.yml from the bundled resource on first boot, identical to the Bukkit behavior. Gating: this is the only sub-item gated on a Step that is not yet complete; if Step E3 has not landed when this ADR is implemented, the implementation should add a minimal local copy of the extraction utility to rtp-fabric-common and merge it into the shared helper when Step E3 closes. The ADR does not pre-decide that micro-question.
5. Lifecycle and singleton parity¶
The LIVE singleton on FabricNetworkModeBootstrap and NetworkModeBootstrap is a per-process singleton (one per JVM). On a unified Bukkit+Fabric process this is impossible, but the project never ships such a target: the unified rtp-plugin shadow JAR loads exactly one of the two adapter packages at startup (per the Step H ArchUnit guard from Step H, the bukkit/ and fabric/ package trees are disjoint and only one is loaded). Therefore the singletons are effectively a single global instance per process and the cross-singleton invariant "at most one is non-null" holds by class-loading. The command tree fetches whichever singleton is non-null.
Consequences¶
Positive¶
- Closes Step J in MULTI_PLATFORM_PLAN.md. Cross-server RTP arrival on a Fabric backend now redeems reservation tokens, matching the documented Phase 2 contract.
- The reimplementation path keeps the working Paper class untouched apart from a minor pull-up of two pure-I/O methods to a shared utility; zero functional risk to Paper.
- The Fabric class is testable independently because it does not extend the Bukkit class; mockable transports + a synthetic event-firing harness suffice.
- Reservation-token authorization reuses the rtp-fabric-ADR-011 resolver, so cross-server permissions are not a second authorization path.
Negative¶
- Two
*NetworkModeBootstrapclasses must be kept in sync against futureMULTI_SERVER_PLAN.mdphases (Phase 3JoinTriggerSourcerework, PostgresLISTEN/NOTIFY, BungeeCord adapter). The duplication is bounded to ~300 lines of glue per side; the transport plumbing remains shared. - A "shared utility" tier emerges in
rtp-core(or a small newrtp-network-commonpackage) for the pure-I/Onetwork.ymlhelpers. This is a small architectural concession to avoid duplicating YAML parse code; it does not cross any existing module boundary. RTPCmdFabricRootgains a dependency onFabricNetworkModeBootstrap.LIVEanalogous to the Bukkit dependency. Acceptable; identical shape on both sides.
Limitations¶
- No proxy adapter for Fabric. This ADR concerns the backend side only. Proxies remain Velocity (working) and BungeeCord (Phase 3). A Fabric process can be a backend; it cannot be a proxy.
- No Phase 3 hooks.
JoinTriggerSourcerework, PostgresLISTEN/NOTIFY, and the BungeeCord transport are explicitly out of scope. The Fabric class implements Phase 2 only. - Single transport per process. Same as Bukkit. Multi-transport composition (
network.yml::transport.typelisted as a sequence) is aMULTI_SERVER_PLAN.mdPhase 3 follow-up and lands on both sides simultaneously when it ships. - No live
/rtp test fullon Fabric for the network suite. The Bukkit/rtp test fullharness runs network-side scenarios throughBukkitBackendStateSamplerandorg.bukkit.event.*. A Fabric equivalent is a follow-up; ADR-013 unblocks it but does not deliver it.
Implementation plan (post-acceptance)¶
The actual implementation is a separate change after this ADR is accepted. Sketch:
- Move
readLobbyModeEarly(File)andensureNetworkYml(File)fromrtp-plugin/.../bukkit/network/NetworkModeBootstrap.javato a newrtp-core/.../common/network/NetworkBootstrapSupport.java. Update Bukkit class to delegate. Add a regression test that the pulled-up methods preserve the existing seven-case behavior covered byLobbyModeEarlyReadTest. - New
rtp-plugin/.../fabric/network/FabricNetworkModeBootstrap.java. Mirror the Bukkitboot()/shutdownDrain()/LIVEshape; bind to Fabric API events. - New
rtp-plugin/.../fabric/network/FabricJoinTriggerSource.java. Plain object withonPlayerJoin(UUID); registered as aServerPlayConnectionEvents.JOINcallback by the bootstrap. - Wire
FabricNetworkModeBootstrapfromRTPFabricMod.onInitialize()(boot order: after the version adapter installs, before the command tree wires). - Wire
FabricNetworkModeBootstrap.LIVElookups intoRTPCmdFabricRootlines analogous toRTPCmdBukkit:88-89, 103-104. - New
FabricNetworkModeBootstrapTest+FabricJoinTriggerSourceTestanalogous toLobbyModeEarlyReadTestandReqRtpNet015NetworkWaitlistTest: synthetic transport, simulated player join, assert reservation-token consumption. ServerLifecycleEvents.SERVER_STOPPINGcallback hooks the shutdown drain.TRACEABILITY.mdrows for any newREQ-RTP-NET-*tests authored on the Fabric path.- CHANGELOG entry under
[3.0.0-beta.4] - Unreleased(or the cycle current at implementation time). - Devstack acceptance: spin up a 2-proxy + 2-backend devstack with one Fabric backend, run the existing cross-server round-trip suite, confirm reservation-token redeem succeeds on the Fabric backend.
Alternatives Considered¶
| Alternative | Why rejected |
|---|---|
Refactor NetworkModeBootstrap into a platform-neutral base class with a Fabric subclass |
Eight independent org.bukkit.* coupling points produce a near-equal amount of subclass code; introduces an awkward "base class with seven abstract hooks" while saving little code and adding risk to the working Paper path. Reimplementation is cleaner. |
Place FabricNetworkModeBootstrap in rtp-fabric-common |
The class consumes RTP.serverAccessor and the rtp-core SPI; it does not need carrier-specific obf/unobf binding because event registration is dispatched through FabricVersionAdapter. Keeping it in rtp-plugin/.../fabric/network/ matches the Bukkit shape and keeps Step H's ArchUnit guard (disjoint bukkit/ + fabric/ packages in rtp-plugin) cleanly satisfied. |
Share JoinTriggerSource between platforms via an interface |
JoinTriggerSource is a Listener on Bukkit; it cannot share an interface with a plain Fabric callback without breaking the Bukkit shape or forcing a non-trivial Listener-shim on Fabric. A shared SPI exists at a lower level (RtpTriggerSource marker); the per-platform JoinTriggerSource wrappers stay distinct. |
| Defer Fabric network mode until Phase 3 | Step J is the missing acceptance criterion that downgrades Fabric from "first-class platform" to "single-server only" backend. Deferring violates rtp-fabric-ADR-002. |
Skip FabricJoinTriggerSource and rely on the cold-cache unkeptLocations fallback for cross-server arrivals |
Loses the per-player coordinate hand-off that reservation tokens enable; the proxy-selected coordinate becomes a hint at best. Defeats the point of the Phase 2 reservation-token mechanism. |
References¶
- ADR-036 - Network mode (multi-server, multi-proxy)
- rtp-proxy-ADR-014 - Backend-owned RTP with network queue
- rtp-proxy-ADR-015 - Shared network waitlist and dynamic batched dispatch
- rtp-fabric-ADR-011 - Effective-permission enumeration on Fabric
- rtp-fabric-ADR-002 - Platform in scope
- MULTI_SERVER_PLAN.md
- MULTI_PLATFORM_PLAN.md Step J