shawn
aa0b80b570
- Server hosting architecture overview (4-component diagram) - RCON admin console spec (TCP protocol, commands, auth) - Server config system spec (cfg format, cvars, loading pipeline) - Server browser API spec (master server REST API, heartbeat, client UI) - Anti-cheat basics spec (movement, fire rate, input validation) - Config loading pipeline, anti-cheat pipeline diagrams - Full cvar table for Phase 4 Part of Phase 4 orchestration (t_29fcfd24)
161 lines
8.5 KiB
Markdown
161 lines
8.5 KiB
Markdown
# Phase 4 — Server Hardening Architecture
|
|
|
|
## Overview
|
|
|
|
Phase 4 turns the bare dedicated server into a community-hostable, administrable, and discoverable service. Four components work together to create the full server ops experience:
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ GODOT SERVER │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
|
|
│ │ RCON Admin │ │ Config │ │ Anti-Cheat│ │
|
|
│ │ Console │ │ System │ │ Validation│ │
|
|
│ │ (TCP/28960) │ │ (cvars.cfg) │ │ Layer │ │
|
|
│ └──────┬───────┘ └──────┬───────┘ └─────┬──────┘ │
|
|
│ │ │ │ │
|
|
│ └──────────┬──────┘─────────────────┘ │
|
|
│ │ │
|
|
│ ┌──────────▼──────────┐ │
|
|
│ │ Server Browser │ │
|
|
│ │ Heartbeat Sender │ │
|
|
│ │ (POST /heartbeat) │ │
|
|
│ └──────────┬──────────┘ │
|
|
└────────────────────┼────────────────────────────────┘
|
|
│ HTTP (every 60s)
|
|
┌────────────────────▼────────────────────────────────┐
|
|
│ MASTER SERVER (Python/Go) │
|
|
│ ┌──────────────────────────────────────────────┐ │
|
|
│ │ REST API: /api/v1/heartbeat │ │
|
|
│ │ /api/v1/servers │ │
|
|
│ │ /api/v1/servers/:id │ │
|
|
│ │ /api/v1/status │ │
|
|
│ └──────────────────────────────────────────────┘ │
|
|
│ ┌──────────────────────────────────────────────┐ │
|
|
│ │ SQLite: servers table, TTL-based expiry │ │
|
|
│ └──────────────────────────────────────────────┘ │
|
|
└────────────────────┬────────────────────────────────┘
|
|
│ HTTP
|
|
┌────────────────────▼────────────────────────────────┐
|
|
│ GODOT CLIENT │
|
|
│ ┌──────────────────────────────────────────────┐ │
|
|
│ │ Server Browser UI │ │
|
|
│ │ GET /api/v1/servers → list → connect │ │
|
|
│ └──────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Dependency Graph
|
|
|
|
```
|
|
Phase 4 (orchestrator — this doc)
|
|
├── build:rcon-admin-console [coder] — TCP remote admin
|
|
├── build:server-config-system [coder] — cvars + cfg loading
|
|
├── build:server-browser-api [coder] — master server + heartbeat
|
|
└── build:anti-cheat-basics [coder] — input validation
|
|
```
|
|
|
|
All 4 tasks are **independent** — they can be worked in parallel. The only soft dependencies:
|
|
- RCON depends on the config system for its cvars (rcon_enabled, rcon_port, rcon_password) — handle by reading from the shared cvar registry
|
|
- Browser heartbeat depends on config system for `sv_master_server` cvar
|
|
- Anti-cheat depends on config system for its cvars
|
|
|
|
No hard ordering constraints. Each task creates its own files and registers its cvars.
|
|
|
|
## Communication Between Components
|
|
|
|
| Source | Target | Mechanism | Data |
|
|
|--------|--------|-----------|------|
|
|
| RCON | Game Server | GDScript signals | `rcon_command` signal (cmd, args) |
|
|
| RCON | Config System | Direct cvar read/write | `CvarRegistry.get/set` |
|
|
| Browser Heartbeat | Master Server | HTTP POST | JSON heartbeat payload |
|
|
| Client Browser | Master Server | HTTP GET | JSON server list |
|
|
| Anti-Cheat | Game Server | Per-tick validation callback | Player state snapshots |
|
|
| Config System | All | Parse-time cvar registration | cvars.gd static dict |
|
|
|
|
## File Structure
|
|
|
|
```
|
|
server/
|
|
├── scripts/
|
|
│ ├── rcon_server.gd — TCP listener, auth, command dispatch
|
|
│ ├── rcon_command_handler.gd — Command implementations
|
|
│ ├── server_browser.gd — Heartbeat sender (HTTP POST)
|
|
│ └── anti_cheat.gd — Main anti-cheat coordinator
|
|
├── data/
|
|
│ ├── server_config.gd — Cvar registry, config loader
|
|
│ ├── cvars.gd — Static cvar definitions with metadata
|
|
│ ├── server_default.cfg — Default config shipped with binary
|
|
│ └── rcon_password.cfg — RCON password file (chmod 600)
|
|
├── server-browser-api/ — Standalone master server service
|
|
│ ├── main.py — Python/FastAPI master server
|
|
│ ├── requirements.txt
|
|
│ └── master_config.json
|
|
client/
|
|
└── scripts/
|
|
└── server_browser_ui.gd — In-game server browser UI
|
|
```
|
|
|
|
## Config Loading Pipeline
|
|
|
|
```
|
|
1. Hardcoded defaults (cvars.gd)
|
|
│
|
|
2. server_default.cfg
|
|
│
|
|
3. --config <path> (default: server.cfg)
|
|
│
|
|
4. Command-line overrides (+cvar value)
|
|
│
|
|
5. Map-specific cfg (cfg/<mapname>.cfg)
|
|
│
|
|
▼
|
|
Final cvar state → Game loop
|
|
```
|
|
|
|
## Anti-Cheat Validation Pipeline (per tick)
|
|
|
|
```
|
|
Client input packet arrives
|
|
│
|
|
▼
|
|
Input sequence validation (timestamp monotonic, seq# dedup)
|
|
│
|
|
▼
|
|
Movement validation (speed limit, teleport, multi-jump)
|
|
│
|
|
▼
|
|
Fire rate validation (interval, ammo)
|
|
│
|
|
▼
|
|
Command validation (whitelist, rate limit)
|
|
│
|
|
▼
|
|
Log → Correct → Warn → Kick (based on sv_ac_level)
|
|
```
|
|
|
|
## CVars Introduced by Phase 4
|
|
|
|
| Cvar | Default | Range | Module | Description |
|
|
|------|---------|-------|--------|-------------|
|
|
| rcon_enabled | 0 | [0,1] | RCON | Enable RCON TCP server |
|
|
| rcon_port | 28960 | [1024,65535] | RCON | RCON listen port |
|
|
| sv_master_server | "" | string | Browser | Master server URL |
|
|
| sv_server_id | auto | string | Browser | Unique server token |
|
|
| sv_heartbeat_interval | 60 | [10,300] | Browser | Heartbeat period (s) |
|
|
| sv_server_tags | "" | string | Browser | Comma-separated tags |
|
|
| sv_server_password | "" | string | Browser | Server join password |
|
|
| sv_ac_level | 2 | [0,3] | Anti-Cheat | Enforcement level |
|
|
| sv_ac_speed_tolerance | 1.2 | [1.0,3.0] | Anti-Cheat | Speed violation multiplier |
|
|
| sv_ac_max_aim_snap | 180 | [10,360] | Anti-Cheat | Max deg/tick aim change |
|
|
| sv_ac_fire_tolerance_ms | 10 | [0,100] | Anti-Cheat | Fire interval tolerance |
|
|
| sv_ac_kick_threshold | 5 | [1,20] | Anti-Cheat | Violations before kick |
|
|
|
|
## Exit Criteria
|
|
|
|
- Community member can download server binary, configure via `server.cfg`, and run it
|
|
- RCON is functional: operator connects via `nc`/`telnet` and runs admin commands
|
|
- Server registers with master server via heartbeat and appears in the browser
|
|
- Client opens server browser, sees the server, and connects
|
|
- Anti-cheat corrects speed-hack attempts at enforcement level 2
|
|
- Everything is controllable via cvars in config file or command-line overrides
|