rtp-proxy-ADR-013 - RTPProxyAccessor Registration (Mirror of RTPServerAccessor)¶
Status: Accepted (2026-05-18) Date: 2026-05-18 Refines: rtp-proxy-ADR-001, rtp-proxy-ADR-002 Depends on: rtp-proxy-ADR-001
Context¶
rtp-proxy-common must answer two questions at runtime that no platform-agnostic code can answer:
- "What proxy platform am I running on?" (
role: autoresolution per ADR-002). - "How do I push a player from this server to that server?" (cross-server transfer; only the proxy adapter knows the call - Velocity's
Player#createConnectionRequest(), Bungee'sProxiedPlayer#connect()).
The earlier ADR-002 text resolved (1) by reflective classpath probing (Class.forName("com.velocitypowered.api.proxy.ProxyServer")). This worked but mixed two unrelated concerns: it leaked Velocity-API class-name strings into the proxy-agnostic module, and it did not answer (2) at all.
The rest of the project already has a clean precedent: RTPServerAccessor is a public interface in rtp-api, every platform adapter (rtp-bukkit-common, rtp-paper-common, rtp-folia-common, rtp-fabric-common) contributes a concrete implementation, and rtp-core reads RTP.serverAccessor without ever reflecting on a platform class. Reflection lives only at the outer bootstrap (rtp-plugin's BootstrapSupport, MetricsBindingDispatcher) where the platform identity is genuinely ambiguous.
rtp-proxy-common should mirror that pattern.
Decision¶
A new public interface RTPProxyAccessor is added to rtp-proxy-common (package io.github.dailystruggle.rtp.proxy.common.platform). A new public holder class RtpProxy in the same module exposes:
public final class RtpProxy {
public static volatile RTPProxyAccessor proxyAccessor;
private RtpProxy() {}
}
Each proxy adapter (rtp-proxy-velocity, future rtp-proxy-bungee) constructs its concrete RTPProxyAccessor during its bootstrap event and assigns RtpProxy.proxyAccessor before the network config loader runs. rtp-proxy-common performs no classpath probing; it reads RtpProxy.proxyAccessor and consults the abstraction.
RTPProxyAccessor shape (target; final signatures pinned during the Phase 2b code turn)¶
public interface RTPProxyAccessor {
Role role();
String proxyId();
void sendMessage(UUID playerId, MessageKey key, Map<String, String> placeholders);
CompletableFuture<Void> transferPlayer(UUID playerId, String targetServerId);
enum Role {
PROXY_VELOCITY,
PROXY_BUNGEE
}
}
Method names and exact signatures are illustrative; the Phase 2b code-landing turn finalises them. The shape constraint is: every method is something only a platform adapter can answer.
S-006 null-guard contract¶
rtp-proxy-common consumers (NetworkConfigLoader, BackendSelector, RtpDispatcher, ProxyStatePublisher, the /rtp Brigadier registrar) shall check RtpProxy.proxyAccessor and throw IllegalStateException("RTPProxyAccessor not registered; addon called before adapter bootstrap") if null. This mirrors S-006 ("No NPE when addons call API before core loads"): a deterministic, attributable failure rather than a silent no-op.
Tests that instantiate rtp-proxy-common components without an adapter shall install a FakeProxyAccessor (a test fixture) before exercising the components.
Registration order requirement¶
In RtpVelocityPlugin#onProxyInitializeEvent:
1. Construct VelocityProxyAccessor(proxyServer)
2. Assign RtpProxy.proxyAccessor = velocityProxyAccessor
3. Load network.yml via NetworkConfigLoader
4. Open NetworkTransport
5. (... rest of Phase 2b/2e wiring per ADR-006 ...)
Steps 1 and 2 must complete before step 3. The Phase 2a no-op shell (already shipped, REQ-RTP-PROXY-VELOCITY-001) does not register an accessor because it does not load the config; it remains a strict no-op until Phase 2b lands.
What this ADR does not standardise¶
- The exact method set of
RTPProxyAccessor(finalised during Phase 2b code-landing). - Whether
transferPlayerreturnsCompletableFuture<Void>orCompletableFuture<TransferOutcome>. Both are defensible; pinned later. - Hot-swap of the accessor at runtime. v1 disallows this (assignment after first read logs WARNING and is rejected); revisit if a
/rtp reloadscenario surfaces.
Alternatives Considered¶
| Alternative | Why Rejected |
|---|---|
Reflective Class.forName probe in rtp-proxy-common (status quo per ADR-002 pre-amendment) |
Bakes Velocity-API class-name strings into the proxy-agnostic module; does not solve transferPlayer / sendMessage; requires editing rtp-proxy-common for every new proxy adapter. |
Slot on RTP itself (RTP.proxyAccessor in rtp-core) |
Bleeds proxy concerns into rtp-core, which is platform-and-proxy-agnostic; violates the architecture-boundary rule in .junie/AGENTS.md. |
Encapsulated setProxyAccessor(...) on the config loader |
More encapsulated but less symmetric with RTP.serverAccessor; harder to discover. The static holder pattern is the established project idiom (see RTP.java:83). |
Service-loader registration (ServiceLoader<RTPProxyAccessor>) |
Standard JVM mechanism but adds a META-INF/services file per adapter and obscures the boot-order requirement; project does not use ServiceLoader elsewhere. |
Consequences¶
- Positive: symmetric with the rest of the codebase (
RTPServerAccessor); no platform-name strings inrtp-proxy-common; future proxy adapters (Bungee, anything else) are purely additive; testable via aFakeProxyAccessorfixture. - Negative: introduces a new public static field, which is a project-style convention that newcomers may flag as a singleton anti-pattern; documented as the established
RTP.serverAccessorprecedent. - Neutral: does not change ADR-001 (SPI shape) or ADR-006 (Velocity bootstrap); only adds a registration channel.
References¶
- ADR-002 (network.yml schema; section Validation Rules amended 2026-05-18 to consult this accessor).
- ADR-012 (proxy-role default; the wiring matrix consults
RTPProxyAccessor.role()). rtp-core/src/main/java/.../RTP.javaline 83 (public static RTPServerAccessor serverAccessor;precedent).rtp-api/src/main/java/.../api/server/RTPServerAccessor.java(shape precedent).- S-006 (REQ-RTP-S-006) - null-guard contract.