docs/rust-link/PROTOCOL.md

rust-link — the wire protocol

Canonical. This document defines the two contracts that make up the Rust bridge. Code in three repositories is held against it, and a change here is a change in all of them.

Contract	Between	Transport
The game link	the Oxide bridge plugin ↔ the sidecar	loopback TCP, newline-delimited JSON
The website API	the sidecar ↔ module-rust	HTTP + WebSocket, bearer token

Mirrors link/, which is the same pair of contracts for Ultima Online. Where this document is silent, that one is not a fallback: the two protocols are independent and share only their shape.

---

1. Why the game does not listen

The plugin is the TCP client; the sidecar owns the listener. A Rust server therefore opens no extra port, and the only component the website can reach is the sidecar. This is inherited unchanged from the ServUO bridge — the footing changed (Oxide hooks instead of game source) and the invariant did not.

Rust server + Oxide  (Rust-Plugins, C#)
   │  the plugin DIALS OUT  ·  127.0.0.1:7799  ·  newline-delimited JSON, bidirectional
   ▼
rust-link sidecar  (Rust-Link)          ← the only network-facing bridge component
   │  WebSocket (live feed) + REST (point-in-time reads), bearer-token auth
   ▼
module-rust, inside a website core

One game server, one sidecar, on that server's own host. A community running six servers runs six pairs; module-rust holds six clients and the website core never learns there is more than one. Nothing in the sidecar is multiplexed and nothing in it should become multiplexed — the serverId on every frame exists so the module can tell its clients apart, not so the sidecar can.

1.1 Loopback is the trust boundary on the game link

There is no token on the game link. The plugin and the sidecar share a host, and the sidecar binds 127.0.0.1 — that is the authentication, exactly as on the ServUO bridge. Binding [game].bind to a routable address puts an unauthenticated command channel on the network.

The website-facing surface is the opposite: authentication there is always on and cannot be turned off. The sidecar generates and persists a token on first start, so there is no state in which it is listening without one.

---

2. Versioning

The wire version is a single integer, declared in four places that must agree:

Where	Repo
PROTOCOL_VERSION in sidecar/src/main.rs	Rust-Link
ProtocolVersion in overlay/oxide/plugins/RunicGateway.cs	Rust-Plugins
protocol in overlay.toml	Rust-Plugins
PROTOCOL_VERSION in server/sidecarClient.js	Module-Rust

Bump all four in the same change as the emitters, together with this document.

The two halves of the contract enforce it differently, and the asymmetry is the reason overlay.toml exists at all:

• On the website API the check is live. Every response carries X-RustLink-Version; a client that declares a different one in its request header is refused 409 with both numbers in the body, rather than served something it will mis-parse.
• On the game link there is no such check, and a mismatched plugin would simply mis-parse. The plugin announces its protocol in server.hello, which is readable only after the game server has booted with it loaded — far too late for an installer to refuse a bad pairing. So overlay.toml declares it statically, and the installer refuses to pair an overlay and a sidecar whose numbers disagree. A bump landing in one repo and not the others fails to compose rather than half-deploying.

---

3. Protocol 1 — the transport

Everything phase 1 defines, and deliberately nothing more.

3.1 Framing

Newline-delimited JSON over TCP, both directions, UTF-8. One complete JSON object per line, no embedded newlines.

• Outbound frames (plugin → sidecar) carry kind.
• Inbound frames (sidecar → plugin) carry cmd.

Both ends cap an inbound line at 1 MiB. An over-long line is discarded, not buffered, and the connection stays up: a single malformed frame is not a reason to tear down a link that live events are flowing over, and a dropped reply simply times out on the caller's side and is re-requested.

The cap exists from protocol 1 rather than being added after the first large frame arrives. An unbounded read facing a peer that will one day send a map image is a memory-exhaustion shape we would be inventing ourselves.

3.2 server.hello — plugin → sidecar

Sent on every successful connect, not once at game-server start. The sidecar restarts independently of the game, so anything it needs up front has to be re-sent per connection.

{
  "kind": "server.hello",
  "t": 1789510452152,
  "protocol": 1,
  "serverId": "main",
  "bootId": "boot-20260915T194502Z",
  "plugin": "0.1.0",
  "hostname": "Test Server",
  "description": "No server description has been provided.",
  "level": "Procedural Map",
  "seed": 1234,
  "worldSize": 4000,
  "maxPlayers": 10,
  "players": 0,
  "joining": 0,
  "queued": 0,
  "uptimeSec": 8947,
  "saveCreatedAt": "2026-09-15T19:58:17Z"
}

Field	Meaning
t	epoch milliseconds, stamped when the world was read
serverId	this server's stable identity across wipes and restarts, from the plugin's config. Not derived from the hostname — an operator renames a server for a season and the site must not lose its history for it
bootId	see §3.2.1
saveCreatedAt	when the current save was created. Raw material for a wipe id, not a wipe id — deriving one is the website's job and is not yet specified, and emitting a guess now would bake a wrong one into stored rows

Everything from hostname down is read from ConVar.Server and BasePlayer.activePlayerList on the game's main thread. A field the game cannot answer is absent, never zero.

3.2.1 bootId identifies the server PROCESS

It is the server process's start instant, formatted boot-yyyyMMddTHHmmssZ, and it must change when and only when the world started over.

That makes three things it is deliberately not:

• Not a fresh value per plugin load. oxide.reload RunicGateway must not change it. The website watches this value to tell a game restart — where everything an event put in the world is gone — from a bridge reconnect, which loses nothing; a plugin reload is the second kind, and a boot id regenerated at Init would ask the site to reconcile its whole ledger for no news.
• Not the sidecar's identity. The sidecar restarting is invisible to the world.
• Not the wipe. A wipe is saveCreatedAt changing; a restart is not a wipe.

The plugin reads it from Process.StartTime, which is exact and identical on every read.

3.3 ping / pong — the heartbeat

The sidecar sends {"cmd":"ping"} every 30 seconds while a plugin is connected; the plugin answers {"kind":"pong","t":…}.

A pong is never persisted. It only moves the sidecar's last_event, which is the whole point: a Rust server with nobody on it is very quiet, and without a heartbeat "the game has said nothing for six hours" would be indistinguishable from "the link died six hours ago".

3.4 server.status — the request/reply verb

The one correlated round trip in protocol 1. It exists so the correlation path is exercised by something before anything depends on it.

sidecar → plugin   {"cmd":"server.status","reqId":"r-1"}
plugin  → sidecar  {"kind":"server.status","reqId":"r-1","t":…, …the §3.2 body…}

Correlation is by reqId, a process-unique counter minted by the sidecar. The plugin echoes it verbatim and only when one was supplied: a reply that invented one would be routed to nobody, and a reply that omitted one the caller sent would leave that caller waiting out its whole timeout.

server.hello and server.status share a body by construction, in one function in the plugin. They differ in what wraps them, not in what they say about the server, and letting them drift is how a site ends up showing two different player counts.

3.5 link.down — the sidecar's own observation

Not a frame the plugin sends. When a plugin connection ends the sidecar synthesises {"kind":"link.down"} onto its broadcast channel, so the website sees the drop without polling. It is never persisted: it is this process's observation, not something the game said.

---

4. The website API

Served by the sidecar. Everything except /health requires the token, which may arrive as Authorization: Bearer <t>, X-Api-Key: <t>, or ?token=<t> — the last so browser WebSocket clients, which cannot set handshake headers, can still authenticate. The compare is constant-time.

Every response carries X-RustLink-Version, including /health and including error responses.

Route	Backed by	Notes
GET /health	—	Unauthenticated, so monitoring can reach it
GET /server	the store	The last server.hello. 204 when the game has never connected
GET /events?kind=&limit=	the store	Newest first; limit clamped to 1–1000
GET /status	the plugin (RPC)	A live round trip. 503 with no plugin, 504 on no reply
GET /ws	broadcast	The live feed; sends {"kind":"ws.hello","protocol":1} on connect

4.1 The split between store-backed and live is deliberate

The store-backed reads answer while the game server is off, which is what lets the website render a server list during a wipe or a restart. /status is the one route that fails when the game is down, because "what is it doing right now" has no stale answer worth giving.

4.2 204 is an answer

GET /server answers 204, not 200 with a null, when the game has never connected. "We have never heard from this server" and "this server reports nothing" are different answers, and a client that cannot tell them apart renders a server that does not exist. module-rust maps the two onto distinct stored states (reachable without online, versus neither).

4.3 Status codes carry the diagnosis

A wrong URL, a wrong token and a mismatched protocol all present to an operator as "the site says my server is offline", and each has a different fix. The codes keep them apart:

Code	Means	Where the fix is
409	protocol mismatch, both numbers in the body	upgrade one component
401	wrong or missing token	the admin form
503	no plugin connected	the game server
504	the plugin did not reply in time	the game server, differently
(transport error)	nothing is listening	the sidecar, or the URL

4.4 The RPC timeout is a ceiling on every later command budget

The sidecar waits 10 seconds for a correlated reply (rpc::REPLY_TIMEOUT). module-rust's own client waits 12 seconds (TIMEOUT_MS).

Core's event dispatcher classifies a budgetMs overrun as retryable unconditionally — it cannot ask the action, which is still awaiting a socket. So an action whose budgetMs does not exceed the module's client timeout can never report retry: false, and that code is unreachable. The ordering is:

sidecar RPC timeout (10s)  <  module client timeout (12s)  <  an action's budgetMs

Derive one from another rather than writing all three down independently.

---

5. What the plugin owes the game

Three rules, and each has a failure behind it. They are the ServUO bridge's, unchanged.

1. Emit is called from the main thread. It formats nothing, blocks on nothing, and touches no socket. It enqueues and returns. A slow, wedged, or absent sidecar cannot stall the game.
2. One link thread owns the socket. A single writer keeps event ordering intact. It reconnects with bounded backoff, and the backoff waits on a handle rather than sleeping — an uninterruptible sleep there is a stall of up to the backoff on every plugin reload, on the main thread.
3. A reader thread parses inbound lines and marshals each to the main thread via Interface.Oxide.NextTick. The reader touches no Unity object, no BasePlayer and no ConVar.

The outbound queue is bounded, drop-oldest: on overflow the oldest record goes and is counted, because telemetry is worth less than the server's memory.

5.1 Diagnosing the link

rg.link

from the game server's console or over RCON:

protocol=1 serverId=main connected=True depth=0 sent=3 dropped=0 received=2
connects=1 writeErrors=0 bootId=boot-20260915T194502Z

This separates "the plugin is not loaded", "the plugin cannot reach the sidecar" and "the website cannot reach the sidecar", which look identical from the site.

---

6. Configuration

6.1 The plugin — oxide/config/RunicGateway.json

Written by Oxide on first load; edited like any other plugin's config.

{
  "Host": "127.0.0.1",
  "Port": 7799,
  "QueueCap": 5000,
  "ServerId": "main"
}

6.2 The sidecar — sidecar.toml

Resolved as --config <PATH>, else $RUSTLINK_CONFIG, else ./sidecar.toml. Environment variables override the file.

Key	Env	Default
[game].bind	RUSTLINK_GAME_BIND	127.0.0.1:7799
[game].server_id	RUSTLINK_SERVER_ID	(empty)
[web].bind	RUSTLINK_WEB_BIND	127.0.0.1:8090
[web].auth_token	RUSTLINK_WEB_TOKEN	(generated on first start)
[store].path	RUSTLINK_DB_PATH	rust-link.db

Two things about those are load-bearing:

• A relative [store].path resolves against the directory holding sidecar.toml, not the working directory. A service manager's working directory must not decide where the database lands — on Windows that can be %SystemRoot%\System32, or a silently redirected VirtualStore copy.
• [game].server_id is a cross-check, not a second source of truth. The plugin announces its own serverId and that is the authority; when both are set and they disagree, the sidecar logs the disagreement loudly and keeps the plugin's. Two game servers pointed at one sidecar by a copied config is the mistake this catches, and it is silent in every other design.

rust-link-sidecar --print-config resolves the configuration exactly as a normal start would — writing the file and generating the token if they are missing — and prints it as JSON on stdout, including the token in clear text. That is the supported way for an installer to read it back.

---

7. What is deliberately not here yet

Protocol 1 is the transport. Every one of these arrives with the phase that needs it, and each is a version bump:

• the read path — player events, kills, clans, presence
• identity and the in-game link code
• the permission mirror
• leases, budgets and the event actions
• the map image over the asset-bridge shape

The rule that governs all of them: the sidecar is a dumb forwarder. It defines no schema for a frame's contents, so a version that adds fields to an event needs no change there — only one that adds a new indexed column does.