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¶
- Umbrella:
docs/adr/ADR-036 - Plan:
docs/dev/MULTI_SERVER_PLAN.md - Requirements:
rtp-proxy/REQUIREMENTS.md,rtp-proxy-common/REQUIREMENTS.md,rtp-proxy-velocity/REQUIREMENTS.md,rtp-proxy-bungee/REQUIREMENTS.md - Network REQs:
docs/dev/REQUIREMENTS.md section 1.6(REQ-RTP-NET-001…014)