rtp-proxy-ADR-019: proxy-direct is a remote view of the proxy's in-memory store¶
- Status: Accepted
- Date: 2026-06-13
- Supersedes: the teleport leg of rtp-proxy-ADR-018 (the bespoke
OP_ENROL/OP_REDEEM_QUERYopcodes and the backendProxyDirectRedeemListener) - Keeps: rtp-proxy-ADR-017 (the player-independent backend->proxy TCP socket)
- Related: rtp-proxy-ADR-014 (backend-owned
/rtpwith network queue), rtp-proxy-ADR-011 (transport SPI), ADR-024 (rtp-lite assembly)
Context¶
rtp-proxy-ADR-018 carried cross-server teleport over the proxy-direct socket with two
bespoke verbs (OP_ENROL, OP_REDEEM_QUERY) plus a dedicated backend
ProxyDirectRedeemListener that re-issued /rtp on arrival. That was a second, parallel
teleport protocol layered beside the existing one: it bypassed the NetworkRequestQueue
(which openRequestQueue returned null for on this tier) and re-implemented the
arrival path that JoinTriggerSource already performs on the Redis/SQL tiers.
The intended model (user, 2026-06-13) is simpler: the proxy plugin should play the role
Redis plays. proxy-direct should be "just another data-management transport like
redis/sql" - a NetworkTransport + NetworkRequestQueue binding pair whose backing
store is the proxy's own in-memory maps, reached over the socket. Everything else
(discovery, enrolment, dispatch, arrival redeem) should run through the same SPI calls
and the same proxy-side code the durable tiers use.
Decision¶
Make proxy-direct a thin RPC client/server over the existing socket:
-
Wire (
ProxyDirectWire). One opcode per SPI method invoked from a backend (the only RPC direction):OP_HEARTBEAT(publishBackendHeartbeat + readSnapshot),OP_FLUSH_PENDING,OP_POLL_STATUS,OP_CANCEL,OP_FIND_RESERVATION,OP_REDEEM,OP_LIST_ACTIVE(opcodes 1-7; any other opcode is refused). Each is the wire-v2 request header (byte opcode,byte frameVersion,long sentAtMs,UTF nonce; rtp-proxy-ADR-017) then a signed request and a signed response (single or count-framed list), reusing the HMAC framing with the response bound to its request. Proxy-local methods (claim,dequeueReady,transition,release,reapExpired) are never sent. -
Backend client (
rtp-core).ProxyDirectNetworkBindingis a full RPCNetworkTransport(heartbeat/snapshot +findReservation/redeem/listActiveForServer;claimthrows - a backend never claims). A newProxyDirectNetworkRequestQueueimplementsNetworkRequestQueue(enrol/flushPending/pollStatus/cancelvia RPC;dequeueReady/transitionare proxy-local no-ops). -
NetworkModeBootstrap. When the transport is aProxyDirectNetworkBinding, the request queue is the remote client above, so the standard flush-sink / status-poll wiring lights up unchanged. The bespokedirectBinding.enrolflush branch and theProxyDirectRedeemListenerare removed; arrival redeem returns to the standardJoinTriggerSource(which now RPCsfindReservation/redeemto the proxy). -
Proxy server (
ProxyDirectListener). Dispatches each RPC against the proxy's already-constructed in-memoryNetworkTransport+NetworkRequestQueue. The proxy's existingTransportRequestTriggerSourcedrains the queue and the dispatcher relocates the player viacreateConnectionRequest; the pre-connect/arrival reservation path is unchanged.
Consequences¶
transport.typeswitches a backend betweenredis,sql, andproxy-directwith no behavioural branch anywhere except the binding factory - the definition of a drop-in data-management option.- Net new type: one (
ProxyDirectNetworkRequestQueue). Net removed: the two teleport opcodes,ProxyDirectRedeemListener, and the proxy-side pending-region map. - Reservation tokens are retained on this tier (so
JoinTriggerSourceis reused verbatim). Slimming proxy-direct to a reservation-free pending map is a possible future cleanup, intentionally out of scope here. - RPC uses one short-lived socket per call (matching the existing heartbeat exchange); a
keep-alive pool is a later optimisation, not needed for correctness. Backend reservation
RPCs are dispatched on
RTP.scheduler's async tier / the existing buffer + status-cache timers, so no join/tick thread blocks. - Single-proxy-simple: a backend dials every configured proxy and the first definite answer wins. Cross-proxy ownership remains a durable-tier concern.