Add comprehensive wiki documentation for RconDataBridge, covering installation, configuration, protocol details, operation references, and internal architecture.

wiki/Configuration.md

@@ -0,0 +1,83 @@
+# Configuration
+
+RconDataBridge exposes its admin-tunable settings through Project Zomboid's
+native Sandbox Options system, the same "New Game, Sandbox Settings" screen
+also reachable in-game via the server admin panel on an already running
+server. This is a separate mechanism from the RCON `ServerOptions`
+transport the protocol itself uses (see [Protocol
+Reference](Protocol-Reference)); Sandbox Options is purely for these
+runtime knobs.
+
+All values live under the RconDataBridge Sandbox Options page, and are
+applied live: an admin can change them at runtime with no server restart
+required. There is, however, no "value changed" event for Sandbox Options
+either, so a changed value takes effect the next time the relevant code
+path reads it, such as the next tick for poll cadence settings, rather than
+instantaneously.
+
+## Options
+
+### Debug Self-Tests
+
+Boolean, default `true`.
+
+Runs the mod's internal JSON and base64 codec self-tests and logs the
+result on every server boot. Diagnostic only; doesn't affect protocol
+behavior. Safe to turn off once you trust the install.
+
+### Poll Interval (ticks)
+
+Integer, default `30`, range 1 to 300.
+
+How many server ticks pass between checks of the request mailbox
+(`RconDataBridge_Request`) and the online player roster. A lower value
+means more responsiveness to incoming requests and player connect or
+disconnect changes, at the cost of doing that check more often.
+
+### Idempotency Window (seconds)
+
+Integer, default `60`, range 1 to 3600.
+
+How long a repeated request `id` replays its cached response instead of
+re-running the operation. Protects side-effecting operations, such as
+triggering a save, from duplicate execution on client retries. See
+[Protocol Reference, Idempotency](Protocol-Reference#6-idempotency).
+
+### Rate Limit: Max Requests
+
+Integer, default `10`, range 1 to 1000.
+
+Maximum number of bridge requests allowed within one rate-limit window; see
+the next setting. This limit is global, not per connection, since RCON
+requests carry no distinguishable caller identity, so it's the only way to
+bound total load.
+
+### Rate Limit: Window (seconds)
+
+Integer, default `10`, range 1 to 3600.
+
+Length of the rolling rate-limit window, in seconds. Combined with the
+setting above, the default is 10 requests per rolling 10 seconds.
+
+A running server's current values for the rate-limit pair, reflecting any
+admin change and not just the defaults, are also readable at any time via
+the `get_bridge_status` operation. This is useful for a client that wants
+to self-tune its polling instead of hardcoding assumptions. See [Operations
+Reference](Operations-Reference#get_bridge_status).
+
+## What's not configurable here, and why
+
+Two protocol-level values are intentionally not exposed as Sandbox
+Options, even though they look like they could be:
+
+- **Max request payload size** (4096 bytes decoded) and the underlying RCON
+  option's max length are hardcoded. They're sized against the fixed
+  capacity of the RCON option storing the request, after base64 expansion.
+  An admin-set larger value here, with no matching change to that
+  underlying capacity, could silently truncate a request instead of
+  cleanly rejecting it with an error. Since that failure mode is worse than
+  simply always rejecting payloads over the fixed limit, it isn't offered
+  as a tunable.
+- **Protocol identifiers**, meaning the protocol version number, the fixed
+  `RconDataBridge_*` option names, and the standard error codes, are
+  fixed, documented, client-facing constants, not server-tunable behavior.