init

2026-05-26 00:11:45 -04:00
commit 296c233157
41 changed files with 2829 additions and 0 deletions
@@ -0,0 +1,96 @@
+# Configuration
+
+## Location
+
+`<plugin data dir>/config.json`. NetworkCore writes a default file on first boot if none exists, with the values shown below.
+
+## Full config
+
+```json
+{
+    "server": {
+        "id": null,
+        "role": "lobby"
+    },
+    "redis": {
+        "host": "127.0.0.1",
+        "port": 6379,
+        "password": null,
+        "database": 0,
+        "key_prefix": "network:"
+    },
+    "network": {
+        "auth_token": null
+    },
+    "metrics": {
+        "enabled": true,
+        "bind": "127.0.0.1",
+        "port": 9100,
+        "path": "/metrics"
+    },
+    "rpc": {
+        "timeout_ms": 5000
+    }
+}
+```
+
+## Fields
+
+### server
+
+| Field | Default | Meaning |
+|---|---|---|
+| `id` | `null` | Optional fixed server id. If null, auto-generated as `<role>-<8 hex chars>` (e.g. `lobby-3f2a91bd`) on every boot. Set this when you want a stable id across restarts. |
+| `role` | `"lobby"` | Logical role of this server. Used to filter via `ServerRegistry.getServersByRole(...)`. Examples: `lobby`, `bridge_duel`, `arena`. Use snake_case. |
+
+### redis
+
+| Field | Default | Meaning |
+|---|---|---|
+| `host` | `"127.0.0.1"` | Redis host |
+| `port` | `6379` | Redis port |
+| `password` | `null` | Redis AUTH password. Prefer the env var (below). |
+| `database` | `0` | Redis logical database (0-15 on stock Redis) |
+| `key_prefix` | `"network:"` | All keys NetworkCore writes start with this prefix. Server registry keys end up at `network:servers:<id>`. Change this only if you're sharing a Redis with something unrelated. |
+
+### network
+
+| Field | Default | Meaning |
+|---|---|---|
+| `auth_token` | `null` | Shared secret. When set, every outgoing envelope is stamped with this token and every inbound message is rejected unless its token matches. When null, no auth is enforced. Use the env var. |
+
+### metrics
+
+| Field | Default | Meaning |
+|---|---|---|
+| `enabled` | `true` | Turn the whole metrics system on/off. When off, `getMetrics()` returns null. |
+| `bind` | `"127.0.0.1"` | Address to bind the Prometheus HTTP server. Defaults to loopback so it's not exposed to the public internet. Set to `0.0.0.0` only if you've put auth / a reverse proxy in front. |
+| `port` | `9100` | Port for the Prometheus exporter |
+| `path` | `"/metrics"` | URL path. Standard convention is `/metrics`. |
+
+### rpc
+
+| Field | Default | Meaning |
+|---|---|---|
+| `timeout_ms` | `5000` | How long an RPC request waits for a response before completing the future exceptionally with `TimeoutException`. |
+
+## Environment variable overrides
+
+These take precedence over the config file at boot time. Use them for secrets so the config file stays safe to check into version control.
+
+| Env var | Overrides |
+|---|---|
+| `REDIS_PASSWORD` | `redis.password` |
+| `NETWORK_AUTH_TOKEN` | `network.auth_token` |
+
+## Recommended setup per environment
+
+**Local dev (single server):**
+- Defaults are fine. Run Redis on localhost, don't set the auth token.
+
+**Multi-server staging or production:**
+- `server.id` left null is fine if you're OK with the id changing on every boot. Set it to something stable like `lobby-prod-01` if you want logs and dashboards to keep continuity across restarts.
+- `server.role` set explicitly per server. This is what dashboards and routing use.
+- `redis.host` pointed at your shared Redis. `redis.password` not in the file; set `REDIS_PASSWORD` env var.
+- `network.auth_token` not in the file; set `NETWORK_AUTH_TOKEN` env var to the same value on every server.
+- `metrics.bind` stays `127.0.0.1`. Run Prometheus on the same host (or use an SSH tunnel / reverse proxy with auth to expose it elsewhere).