Skip to content

rtp-proxy Subproject ADRs

This directory holds Architectural Decision Records scoped to the rtp-proxy/ subtree (the proxy adapter module family). Numbering is independent of the global docs/adr/ sequence and restarts at 001 here, per the Self-Updating Protocol in .junie/AGENTS.md.

Project-wide rationale for the proxy subsystem lives in the umbrella ADR-036 — Network Mode (Multi-Server, Multi-Proxy). The ADRs in this directory refine ADR-036; they do not supersede it.

Naming

Use the per-directory pattern: rtp-proxy-ADR-NNN-<slug>.md. The slug is a short kebab-case summary of the decision (e.g., spi-shape, redis-binding, velocity-bootstrap).

Add a row to the Subproject ADRs table in docs/adr/README.md whenever a new ADR lands here.

Status Lifecycle

  • Proposed — drafted, not yet ratified. No implementation may rely on the decision (D-005).
  • Accepted — ratified; implementation may proceed.
  • Superseded — replaced by a later ADR. Link the successor in the header.
  • Deprecated — no longer applies but kept for historical context.

Planned Series (from ADR-036)

The following ADR numbers originate from ADR-036's Phased Subproject ADR Plan and subsequent network-mode refinements; each refines a specific slice of the umbrella decision so adapter and transport code can proceed against pinned contracts.

ADR Slug Phase Status Scope (short)
rtp-proxy-ADR-001 spi-shape Phase 1 Accepted (2026-05-14) RtpDispatcher, BackendSelector, NetworkTransport, ProxySender, ReservationClient SPI surfaces
rtp-proxy-ADR-002 network-yml-schema Phase 1 Accepted (2026-05-14; amended 2026-05-18) Canonical network.yml schema + validation rules
rtp-proxy-ADR-003 in-memory-binding Phase 1 Accepted (2026-05-14) Reference InMemoryNetworkStateBinding for tests and enabled:false parity
rtp-proxy-ADR-004 weighted-average-selector Phase 1 Accepted (2026-05-14; amended 2026-05-22) Reference selector: metrics, curves, parameter bounds, fallback chain
rtp-proxy-ADR-005 redis-binding Phase 2 Accepted (2026-05-18) Lettuce-backed binding; Dragonfly/KeyDB parity contract; HMAC-on-wire + Lua SHA1 sidecar amendments
rtp-proxy-ADR-006 velocity-bootstrap Phase 2 Accepted (2026-05-18) Velocity plugin entry, ServerPreConnectEvent flow, Brigadier wiring
rtp-proxy-ADR-007 postgres-binding Phase 3 Superseded (by ADR-011) LISTEN/NOTIFY + SELECT … FOR UPDATE SKIP LOCKED binding
rtp-proxy-ADR-008 bungee-bootstrap Phase 3 Proposed BungeeCord/Waterfall single-artifact entry, ServerConnectEvent flow
rtp-proxy-ADR-009 generic-sql-binding Phase 4 Superseded (by ADR-011) Portable polling-based fallback binding (MySQL/MariaDB/H2/SQLite-dev)
rtp-proxy-ADR-010 security-hardening Phase 4 Accepted (2026-05-18) HMAC envelope, schemaVersion negotiation, kill switch (heartbeat boolean killSwitch field amendment)
rtp-proxy-ADR-011 sql-network-state-binding Phase 2b/2e Accepted (2026-05-18) DB-as-bus default for Phase 2e; folds ADR-007 + ADR-009 sketches; Redis (ADR-005) becomes opt-in latency upsell
rtp-proxy-ADR-012 proxy-role-participant-default Phase 2b Accepted (2026-05-18) Participant-vs-router toggle; participant default; implicit-via-wiring (no new config knob)
rtp-proxy-ADR-013 proxy-accessor-registration Phase 2b Accepted (2026-05-18) RTPProxyAccessor + RtpProxy.proxyAccessor slot (mirrors RTP.serverAccessor); replaces ADR-002's Class.forName probe
rtp-proxy-ADR-014 backend-owned-rtp-with-network-queue L6 Accepted (2026-05-21) Backend-owned /rtp + network wait-queue; proxy reduced to dispatch + reservation lifecycle
rtp-proxy-ADR-015 shared-network-waitlist-and-dynamic-batched-dispatch L6 Accepted (2026-05-21) Shared network waitlist + dynamic batched dispatch (refines ADR-014)
rtp-proxy-ADR-016 plugin-message-default-transport (amends ADR-036) Accepted (2026-06-12) Tier-1 non-durable PluginMessageNetworkBinding + transport.type: auto; DB-free cross-server RTP, ships in lite
rtp-proxy-ADR-017 proxy-direct-transport (amends ADR-036) Accepted (2026-06-13) transport.type: proxy-direct player-independent backend->proxy socket
rtp-proxy-ADR-018 proxy-direct-teleport-execution (amends ADR-036) Superseded (by ADR-019) Bespoke socket opcodes for teleport execution
rtp-proxy-ADR-019 proxy-direct-as-remote-store (amends ADR-036) Accepted (2026-06-13) proxy-direct as remote RPC view of proxy in-memory store
rtp-proxy-ADR-020 direct-database-cross-server-dispatch (refines ADR-036) Accepted (2026-10-02) Direct DB cross-server dispatch over SQL/Redis with native proxy Connect messaging
rtp-proxy-ADR-021 seamless-in-play-velocity-transfers (refines ADR-036) Proposed Seamless loading-screen-free transfers in Velocity with zero-trust packet gating

Additional ADRs may be inserted at the tail of the series (-ADR-017, -018, …) as needs arise. Do not renumber existing ADRs.

References