rtp-proxy-ADR-018: Cross-server teleport execution on the proxy-direct tier¶
- Status: Superseded by rtp-proxy-ADR-019 (teleport leg only; the permissions decision below still stands)
- Date: 2026-06-13
- Supersedes: none
- Related: rtp-proxy-ADR-017 (proxy-direct transport), rtp-proxy-ADR-014 (backend-owned
/rtpwith network queue), ADR-024 (rtp-lite assembly)
Context¶
rtp-proxy-ADR-017 introduced the proxy-direct transport: each backend opens its OWN
outbound TCP socket to the Velocity companion to publish its real region list and read
the merged availability snapshot, with zero players and no operator config. That work
made cross-server /rtp region= tab-completion converge on a lobby. It deliberately
stopped at region NAME discovery: the tier carried no teleport request.
On the durable tiers (Redis/SQL), cross-server teleport works because both the backend
and the proxy connect to the same external store: the backend writes an enrolment, the
proxy's TransportRequestTriggerSource drains it and moves the player, and the
destination backend redeems a per-player reservation token (findReservation /
redeem) on join. The lite / DB-free tier has no such shared store, and an in-memory
queue cannot bridge two JVMs, so on proxy-direct the backend's enrolment was dropped
(NetworkModeBootstrap.openRequestQueue returns null for these tiers) and arrivals
were never redeemed.
The user constraint for lite is explicit: cross-server /rtp is teleport EXECUTION
on arrival, not load-balancing. There must be no per-player coordinate reservation and
no "confirm a specific coordinate" round-trip; the proxy simply relocates the player and
the destination backend runs /rtp locally.
Decision¶
Carry the cross-server teleport over the EXISTING proxy-direct socket using two new
opcodes, reusing the BackendHeartbeatCodec HMAC framing (ProxyDirectWire). No shared
store, no reservation tokens, no load-balancing.
-
Leg 1 - ENROL (backend -> proxy). When the router decides CROSS_SERVER, the backend's enrolment flush sink calls
ProxyDirectNetworkBinding.enrol(playerId, server, region), which dials the proxy with anOP_ENROLframe carryingplayerId\u0001server\u0001region. The proxy'sProxyDirectListenerrelocates the player withplayer.createConnectionRequest(targetServer).fireAndForget()and parks the requested region in a transient in-memory map keyed by player UUID (60s TTL). This is player-independent on the lobby side (the lobby dials the proxy on its own socket), so no carrier player is required to start the move. -
Leg 2 - REDEEM-QUERY (destination backend -> proxy). On the destination backend,
ProxyDirectRedeemListener(registered on the player-join lifecycle hook) callsProxyDirectNetworkBinding.pollRedeem(playerId)over the backend's OWN outbound socket with anOP_REDEEM_QUERYframe. The proxy returns and clears the parked region. If present, the backend re-issues the player's intent locally:rtp region=<region>(or a barertpwhen no region was named), hopping to the player's owning thread first (Folia entity scheduler / Bukkit main thread).
The proxy's parked entry is NOT a coordinate reservation - it is a transient region hand-off, has a TTL, and never blocks a backend coordinate.
Permissions¶
A qualified server:region target is now gated by TWO independent permissions, mirroring
the local rtp.regions.<region> model: rtp.servers.<server> (destination backend) AND
rtp.regions.<region> (region). rtp.servers.* defaults to op in both plugin.yml
descriptors. The gate is enforced in the RegionParameter validator (which also filters
tab-completion), so a forged argument cannot bypass it.
Consequences¶
- Cross-server
/rtpexecutes on lite with zero players on any backend and no operatorservers:config, using only the proxy-direct socket already used for discovery. - No durable store, no reservation tokens, no load-balancing on this tier - by design. Operators who want coordinate-accurate reservation / load-balancing use Redis/SQL.
- The proxy-direct wire gained a one-byte opcode prefix (
OP_PUSH/OP_ENROL/OP_REDEEM_QUERY); both ends ship together, so there is no mixed-version concern. - The existing
JoinTriggerSourcestill runs onproxy-directbut is a benign no-op there (findReservationdefaults to empty); the new redeem path is independent.