From 8eb6e587fbe8b30a4665512fccc067ea8ad1fdb6 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 12 Nov 2026 22:07:24 -0500 Subject: [PATCH] N7: Dedicated server packaging, health endpoint and graceful shutdown - packaging/server/tidewall-server: a wrapper that turns SIGTERM and SIGINT into a clean stop through the server's new --stop-file, since the engine can't catch signals. The server tells everyone it shut down, logs its statistics and exits 0; the wrapper kills it only after 15 s. - --config=PATH reads options from a file (packaging/server/server.cfg); options after it on the command line win. - --health-port answers GET /health with JSON (phase, players, tick, uptime) on loopback by default. HealthServer is non-blocking and bounded. - packaging/docker: a debian:13 image that checks the engine against tools/engine.sha512, imports the game at build time, runs as an unprivileged user, and works with a read-only root and a small /tmp. compose.yaml is project and container tidewall-server, read-only, no capabilities. - packaging/systemd: a hardened unit with a dynamic user. - make server-package-check: compose up, healthy, non-root, read-only, a real headless client joins over UDP into the drop, then SIGTERM stops it cleanly. This also covers H7 (graceful shutdown on SIGTERM). Closes #38 Closes #70 Co-Authored-By: Claude Opus 5.5 --- .dockerignore | 11 +++ CLAUDE.md | 1 + Makefile | 7 +- packaging/README.md | 70 +++++++++++++++++ packaging/docker/Dockerfile | 45 +++++++++++ packaging/docker/compose.yaml | 32 ++++++++ packaging/server/server.cfg | 34 ++++++++ packaging/server/tidewall-server | 47 +++++++++++ packaging/systemd/tidewall-server.service | 45 +++++++++++ src/server/headless_server.gd | 45 +++++++++++ src/server/health_server.gd | 95 +++++++++++++++++++++++ src/server/health_server.gd.uid | 1 + src/server/server_config.gd | 60 +++++++++++++- test/server/test_health_server.gd | 61 +++++++++++++++ test/server/test_health_server.gd.uid | 1 + test/server/test_server_config.gd | 34 ++++++++ tools/server_package_check.sh | 57 ++++++++++++++ 17 files changed, 644 insertions(+), 2 deletions(-) create mode 100644 .dockerignore create mode 100644 packaging/README.md create mode 100644 packaging/docker/Dockerfile create mode 100644 packaging/docker/compose.yaml create mode 100644 packaging/server/server.cfg create mode 100755 packaging/server/tidewall-server create mode 100644 packaging/systemd/tidewall-server.service create mode 100644 src/server/health_server.gd create mode 100644 src/server/health_server.gd.uid create mode 100644 test/server/test_health_server.gd create mode 100644 test/server/test_health_server.gd.uid create mode 100755 tools/server_package_check.sh diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..2603cea --- /dev/null +++ b/.dockerignore @@ -0,0 +1,11 @@ +# Only what packaging/docker/Dockerfile copies goes into the build context. +* +!project.godot +!LICENSE +!LICENSE-ASSETS +!src +!data +!packaging/server +!tools/engine.sha512 +!tools/godot/Godot_v4.7.2-stable_linux.x86_64 +src/**/*.tmp diff --git a/CLAUDE.md b/CLAUDE.md index bfa9583..56af142 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -39,6 +39,7 @@ continuity. | `make client-captures` | Renders what a network client sees on the barge, gliding and landed (`captures/client_.png`). Needs Docker. Look at them. | | `make soak` | The 24-client network soak (N8): a real server and 24 headless `SoakPlayer` clients in three processes, each behind a `UdpRelay` adding 60 ms, +/-20 ms jitter and 2% loss each way, for two whole matches in real time (about 30 min, under `nice`). Fails on a world-hash mismatch, errors, unreadable packets, a client that didn't play every match, memory growth between matches, or a p99 tick over budget. `SOAK_MATCHES`, `SOAK_CLIENTS`, `SOAK_PROCS`, `SOAK_LATENCY`, `SOAK_JITTER`, `SOAK_LOSS` scale it. Results in `build/soak/report.txt`. | | `make soak-selfcheck` | About a minute: tampers with one client's world and checks the soak's comparison catches it and only it. | +| `make server-package-check` | Builds the server image with `packaging/docker/compose.yaml`, waits for it to be healthy, checks it is non-root and read-only, joins it with a headless client and stops it with SIGTERM (N7, about 1.5 min). Needs Docker. See `packaging/README.md`. | | `make capture-test` | Proves the capture harness works and rejects a blank frame. Needs Docker, so it isn't part of `make check`. | Run one group of tests with `tools/run_tests.sh --root=res://test/sim` or diff --git a/Makefile b/Makefile index a6c3aae..76ef3fc 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,7 @@ # Tidewall build entry points. Everything runs headless with the repo-local engine. GODOT := tools/godot.sh -.PHONY: check import parse test test-selfcheck smoke capture-test terrain-capture binaries verify-engine bot-matches match match-captures client-check client-captures discovery-check fuzz soak soak-selfcheck +.PHONY: check import parse test test-selfcheck smoke capture-test terrain-capture binaries verify-engine bot-matches match match-captures client-check client-captures discovery-check fuzz soak soak-selfcheck server-package-check ## Everything that must pass before a push. check: verify-engine binaries parse test test-selfcheck smoke @@ -82,3 +82,8 @@ soak: import ## About a minute: proves the soak catches a client whose world has drifted. soak-selfcheck: import @SOAK_SELFCHECK=1 tools/soak.sh + +## Builds the server image with packaging/docker/compose.yaml, starts it, joins it with a +## headless client and stops it with SIGTERM. Needs Docker. About a minute and a half. +server-package-check: import + @tools/server_package_check.sh diff --git a/packaging/README.md b/packaging/README.md new file mode 100644 index 0000000..b3f1dd4 --- /dev/null +++ b/packaging/README.md @@ -0,0 +1,70 @@ +# Running a Tidewall dedicated server + +A dedicated server is the game's engine running headless with `--server`. It needs no +display, GPU or sound, and logs one JSON object per line on stdout. + +## What is here + +| File | What it is | +|---|---| +| `server/tidewall-server` | The wrapper that starts the server. It turns SIGTERM and SIGINT into a clean stop, which the engine can't do itself. | +| `server/server.cfg` | An example configuration, one command-line option per line. Every option is described in `src/server/server_config.gd`. | +| `docker/Dockerfile` | A server image on `debian:13`. It runs as an unprivileged user, and the game is imported at build time, so the filesystem can be read-only. | +| `docker/compose.yaml` | An example Compose project, `tidewall-server`. | +| `systemd/tidewall-server.service` | A hardened systemd unit for running it without containers. | + +## With Docker Compose + +The image is built from the repository, which needs the pinned engine in `tools/godot/` +(see `tools/godot.sh`). + +```bash +cd packaging/docker +docker compose up -d +``` + +Players connect to UDP port 24650 on the host (`TIDEWALL_PORT=24700 docker compose up -d` +picks another). `docker compose logs -f` follows the log, and `docker compose down` +stops the server cleanly: everyone connected is told it shut down. + +To change settings, copy `server/server.cfg`, edit it and mount it over +`/etc/tidewall/server.cfg` (the commented `volumes` entry in `compose.yaml`). + +LAN discovery answers on the game port plus one, but Docker's default bridge network +doesn't pass broadcasts. Give the service `network_mode: host` if people on your LAN +should find it in their server list; anyone can still join by address without it. + +`make server-package-check` builds the image, starts it with Compose, joins it with a +headless client and stops it, checking each step. + +## With systemd + +The unit expects the layout the image uses: + +- `/opt/tidewall/engine/godot`: the engine binary from `tools/godot/`, +- `/opt/tidewall/game/`: `project.godot`, `src/`, `data/` and the licences, imported once + with `godot --headless --path /opt/tidewall/game --import --quit`, +- `/usr/local/bin/tidewall-server`: the wrapper, +- `/etc/tidewall/server.cfg`: the configuration. + +Then install `systemd/tidewall-server.service` and enable it. It runs under a dynamic +user with a private `/tmp`, a read-only system and no capabilities. + +## Health and shutdown + +With `health-port` set, `GET /health` on that TCP port answers 200 and a JSON body with +the match phase, player count and uptime. It listens on loopback unless `health-bind` +says otherwise; the container's health check uses it from inside. + +Stopping: send SIGTERM to the wrapper (Docker, Compose and systemd all do). It creates +the server's stop file, the server disconnects everyone with a "shut down" reason, logs +its statistics and exits 0. If it hasn't gone within 15 seconds the wrapper kills it. + +## Ports + +| Port | Protocol | What | +|---|---|---| +| 24650 | UDP | Game traffic (`port`). | +| 24651 | UDP | LAN discovery and list-server registration (`port` + 1). | +| 24650 | TCP | Health endpoint (`health-port`), loopback only by default. | +| 24660 | UDP | A list server, if you run one (`--list-server`). | diff --git a/packaging/docker/Dockerfile b/packaging/docker/Dockerfile new file mode 100644 index 0000000..8854125 --- /dev/null +++ b/packaging/docker/Dockerfile @@ -0,0 +1,45 @@ +# A Tidewall dedicated server image. Build it from the repository's root, which must +# hold the pinned engine in tools/godot/ (see tools/godot.sh): +# +# docker build -f packaging/docker/Dockerfile -t tidewall-server:dev . +# +# or let packaging/docker/compose.yaml do it. The engine is checked against +# tools/engine.sha512 before it goes in. The game is imported while building, so at +# run time the image needs no writable filesystem apart from a small /tmp. +FROM debian:13 + +ARG ENGINE=tools/godot/Godot_v4.7.2-stable_linux.x86_64 + +RUN groupadd --system --gid 10650 tidewall \ + && useradd --system --uid 10650 --gid tidewall --home-dir /nonexistent --no-create-home --shell /usr/sbin/nologin tidewall + +COPY tools/engine.sha512 /tmp/engine.sha512 +COPY ${ENGINE} /opt/tidewall/engine/godot +RUN expected="$(awk '$2 ~ /_linux\.x86_64$/ { print $1 }' /tmp/engine.sha512)" \ + && actual="$(sha512sum /opt/tidewall/engine/godot | cut -d' ' -f1)" \ + && [ -n "$expected" ] && [ "$expected" = "$actual" ] \ + && chmod 0755 /opt/tidewall/engine/godot \ + && rm /tmp/engine.sha512 + +COPY project.godot LICENSE LICENSE-ASSETS /opt/tidewall/game/ +COPY src /opt/tidewall/game/src +COPY data /opt/tidewall/game/data +COPY packaging/server/tidewall-server /usr/local/bin/tidewall-server +COPY packaging/server/server.cfg /etc/tidewall/server.cfg + +# Import once here, so the server never has to write into the game's directory. +RUN XDG_DATA_HOME=/tmp/import XDG_CONFIG_HOME=/tmp/import XDG_CACHE_HOME=/tmp/import \ + /opt/tidewall/engine/godot --headless --path /opt/tidewall/game --import --quit >/dev/null 2>&1 ; \ + test -d /opt/tidewall/game/.godot \ + && rm -rf /tmp/import \ + && chmod 0755 /usr/local/bin/tidewall-server + +USER tidewall +ENV TIDEWALL_STATE=/tmp/tidewall-server +# Game traffic, LAN discovery, and the health check (TCP, on loopback by default). +EXPOSE 24650/udp 24651/udp +STOPSIGNAL SIGTERM +HEALTHCHECK --interval=10s --timeout=3s --start-period=20s --retries=3 \ + CMD ["bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/24650 && printf 'GET /health HTTP/1.0\\r\\n\\r\\n' >&3 && head -n 1 <&3 | grep -q ' 200 '"] +ENTRYPOINT ["/usr/local/bin/tidewall-server"] +CMD ["--config=/etc/tidewall/server.cfg"] diff --git a/packaging/docker/compose.yaml b/packaging/docker/compose.yaml new file mode 100644 index 0000000..f446f2e --- /dev/null +++ b/packaging/docker/compose.yaml @@ -0,0 +1,32 @@ +# An example Tidewall dedicated server. From this directory: +# +# docker compose up -d builds the image from the repository and starts it +# docker compose logs -f the server's JSON log lines +# docker compose down stops it cleanly: players are told it shut down +# +# TIDEWALL_PORT changes the UDP port on the host (default 24650). To change anything +# else, mount your own server.cfg over /etc/tidewall/server.cfg (see the commented +# volume below) or add options to `command`. +name: tidewall-server + +services: + server: + build: + context: ../.. + dockerfile: packaging/docker/Dockerfile + image: tidewall-server:dev + container_name: tidewall-server + restart: unless-stopped + command: ["--config=/etc/tidewall/server.cfg", "--port=${TIDEWALL_PORT:-24650}"] + ports: + - "${TIDEWALL_PORT:-24650}:${TIDEWALL_PORT:-24650}/udp" + read_only: true + tmpfs: + - /tmp:size=64m,mode=1777 + cap_drop: + - ALL + security_opt: + - no-new-privileges:true + stop_grace_period: 20s + # volumes: + # - ./server.cfg:/etc/tidewall/server.cfg:ro diff --git a/packaging/server/server.cfg b/packaging/server/server.cfg new file mode 100644 index 0000000..86218aa --- /dev/null +++ b/packaging/server/server.cfg @@ -0,0 +1,34 @@ +# Tidewall dedicated server configuration. Read with --config=PATH; each line is one +# of the server's command-line options without the leading dashes (see +# src/server/server_config.gd for all of them). Options given on the command line +# after --config win over these. + +# Take players over the network. Without this the server plays a bot-only match. +listen + +# UDP port players connect to. LAN discovery answers on this port plus one. +port = 24650 + +# Fill each match's empty places with bots (any number above 0 turns it on). +bots = 1 +# bot-difficulty = mixed + +# The name shown in server browsers. +name = Tidewall server + +# Register with a list server so people outside the LAN can find this one. +# list = lists.example.org:24660 + +# Don't answer LAN discovery broadcasts. +# no-lan + +# Answer GET /health on this TCP port, on loopback unless health-bind says otherwise. +health-port = 24650 +# health-bind = 127.0.0.1 + +# A progress line in the log every this many ticks (30 a second). 0 for none. +log-every = 9000 + +# A fixed seed makes every match on the island sequence repeatable. Leave it out for a +# fresh one each start. +# seed = 12345 diff --git a/packaging/server/tidewall-server b/packaging/server/tidewall-server new file mode 100755 index 0000000..6285c01 --- /dev/null +++ b/packaging/server/tidewall-server @@ -0,0 +1,47 @@ +#!/usr/bin/env bash +# Runs a Tidewall dedicated server and turns SIGTERM or SIGINT into a clean stop: the +# server tells everyone connected it is shutting down, logs its statistics and exits 0. +# The engine can't catch signals itself, so this wrapper creates the server's +# --stop-file when one arrives, and kills the server only if it hasn't gone after +# TIDEWALL_STOP_SECONDS (default 15). +# +# tidewall-server [server options...] e.g. --config=/etc/tidewall/server.cfg +# +# Where things are, overridable from the environment: +# TIDEWALL_HOME the install: engine/godot and game/ (default /opt/tidewall) +# TIDEWALL_ENGINE the engine binary (default $TIDEWALL_HOME/engine/godot) +# TIDEWALL_GAME the game's project directory (default $TIDEWALL_HOME/game) +# TIDEWALL_STATE a writable directory for the engine's own files and the stop file +# (default $RUNTIME_DIRECTORY under systemd, else /tmp/tidewall-server) +set -u + +home="${TIDEWALL_HOME:-/opt/tidewall}" +engine="${TIDEWALL_ENGINE:-$home/engine/godot}" +game="${TIDEWALL_GAME:-$home/game}" +state="${TIDEWALL_STATE:-${RUNTIME_DIRECTORY:-/tmp/tidewall-server}}" +grace="${TIDEWALL_STOP_SECONDS:-15}" +stop_file="$state/stop" + +mkdir -p "$state/data" "$state/config" "$state/cache" +rm -f "$stop_file" +# The engine writes its user data and caches here, so the install can stay read-only. +export XDG_DATA_HOME="$state/data" XDG_CONFIG_HOME="$state/config" XDG_CACHE_HOME="$state/cache" + +"$engine" --headless --path "$game" -- --server --stop-file="$stop_file" "$@" & +child=$! + +request_stop() { + touch "$stop_file" + # If it hasn't stopped in time, stop it the hard way. + ( sleep "$grace"; kill -KILL "$child" 2>/dev/null ) & +} +trap request_stop TERM INT + +wait "$child" +code=$? +# A trapped signal interrupts wait; keep waiting until the server has really gone. +while kill -0 "$child" 2>/dev/null; do + wait "$child" + code=$? +done +exit "$code" diff --git a/packaging/systemd/tidewall-server.service b/packaging/systemd/tidewall-server.service new file mode 100644 index 0000000..62e7b36 --- /dev/null +++ b/packaging/systemd/tidewall-server.service @@ -0,0 +1,45 @@ +# A Tidewall dedicated server as a systemd service. It expects the layout the Docker +# image uses: the engine at /opt/tidewall/engine/godot, the imported game in +# /opt/tidewall/game, the wrapper at /usr/local/bin/tidewall-server and the +# configuration in /etc/tidewall/server.cfg. Then: +# +# sudo cp tidewall-server.service /etc/systemd/system/ +# sudo systemctl daemon-reload && sudo systemctl enable --now tidewall-server +# journalctl -u tidewall-server -f +# +# systemctl stop sends SIGTERM to the wrapper, which asks the server to stop cleanly. +[Unit] +Description=Tidewall dedicated server +Documentation=https://gitea.eom.dev/claude/tidewall +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple +ExecStart=/usr/local/bin/tidewall-server --config=/etc/tidewall/server.cfg +# Only the wrapper gets SIGTERM; it passes the request on and waits. +KillMode=mixed +KillSignal=SIGTERM +TimeoutStopSec=20 +Restart=on-failure +RestartSec=5 + +DynamicUser=yes +RuntimeDirectory=tidewall-server +Environment=TIDEWALL_STATE=%t/tidewall-server +ProtectSystem=strict +ProtectHome=yes +PrivateTmp=yes +PrivateDevices=yes +NoNewPrivileges=yes +ProtectKernelTunables=yes +ProtectKernelModules=yes +ProtectControlGroups=yes +RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX +RestrictNamespaces=yes +LockPersonality=yes +CapabilityBoundingSet= +SystemCallArchitectures=native + +[Install] +WantedBy=multi-user.target diff --git a/src/server/headless_server.gd b/src/server/headless_server.gd index e05ae3d..7cd3e26 100644 --- a/src/server/headless_server.gd +++ b/src/server/headless_server.gd @@ -21,10 +21,13 @@ var loop: ServerLoop var game: NetGame = null ## Makes the server findable on the LAN and in list servers, when listening. var beacon: ServerBeacon = null +## Answers GET /health, when asked for with --health-port. +var health: HealthServer = null var _errors: ErrorCounter = ErrorCounter.new() var _accumulator: float = 0.0 var _started_usec: int = 0 +var _stop_checked_msec: int = 0 var _finished: bool = false var _matches_ended: int = 0 ## When listening: microseconds each tick took including the network's share (after_tick: @@ -44,6 +47,9 @@ func _ready() -> void: _log("config_error", {"message": problem}) _finish(2) return + if not config.stop_file.is_empty() and FileAccess.file_exists(config.stop_file): + # Left over from an earlier run; it isn't a request to stop this one. + DirAccess.remove_absolute(config.stop_file) if not config.has_seed: config.match_seed = _fresh_seed() Engine.max_fps = 0 if config.unthrottled else REALTIME_MAX_FPS @@ -61,6 +67,15 @@ func _ready() -> void: return game = NetGame.new(loop, net) _open_beacon() + if config.health_port > 0: + health = HealthServer.new() + health.report = _health_report + var health_error: Error = health.listen(config.health_port, config.health_bind) + if health_error != OK: + _log("health_failed", {"port": config.health_port, "message": "couldn't listen for health checks on TCP port %d: %s" % [config.health_port, error_string(health_error)]}) + health = null + _finish(2) + return var started: Dictionary = config.to_dictionary() started["engine"] = Engine.get_version_info()["string"] started["tick_rate_hz"] = Tuning.TICK_RATE_HZ @@ -73,6 +88,12 @@ func _ready() -> void: func _process(delta: float) -> void: if _finished or loop == null: return + if health != null: + health.poll() + if _stop_requested(): + _log("stopping", {"reason": "stop file"}) + _finish(0) + return if game != null: game.poll() for event: Dictionary in game.events: @@ -108,6 +129,28 @@ func _exit_tree() -> void: _finish(0) +## True when the stop file has appeared. Looked for a few times a second. +func _stop_requested() -> bool: + if config.stop_file.is_empty(): + return false + var now: int = Time.get_ticks_msec() + if now - _stop_checked_msec < 250: + return false + _stop_checked_msec = now + return FileAccess.file_exists(config.stop_file) + + +func _health_report() -> Dictionary: + return { + "status": "ok", + "phase": loop.match_flow.phase_name(), + "players": game.net.player_count() if game != null else 0, + "max_players": loop.match_flow.rules.max_players, + "tick": loop.ticks, + "uptime_s": roundi((Time.get_ticks_usec() - _started_usec) / 1000000.0), + } + + ## True once the run has done what it was asked: its ticks, or its matches. func _done() -> bool: return (config.ticks > 0 and loop.ticks >= config.ticks) or (config.matches > 0 and _matches_ended >= config.matches) @@ -169,6 +212,8 @@ func _finish(requested_code: int) -> void: game.net.close() if beacon != null: beacon.close() + if health != null: + health.close() if loop != null: var stats: Dictionary = loop.timing_stats() stats["state_hash"] = loop.sim.state_hash() diff --git a/src/server/health_server.gd b/src/server/health_server.gd new file mode 100644 index 0000000..727180f --- /dev/null +++ b/src/server/health_server.gd @@ -0,0 +1,95 @@ +## A tiny HTTP endpoint that says whether a dedicated server is up, for container health +## checks, systemd watchers and monitoring. `GET /health` answers 200 with a JSON body: +## +## {"status":"ok","phase":"lobby","players":3,"max_players":24,"tick":1200,"uptime_s":40} +## +## Anything else gets 404, and a request that is malformed, too long or too slow is +## closed. It listens on loopback unless told otherwise, holds a handful of connections +## at most, and never blocks: call poll() once a frame. +class_name HealthServer +extends RefCounted + +const MAX_CONNECTIONS: int = 8 +const MAX_REQUEST_BYTES: int = 2048 +const TIMEOUT_MSEC: int = 2000 + +## Fills in the body: func() -> Dictionary. "status" is added if missing. +var report: Callable = func() -> Dictionary: return {} +## Requests answered, by status code, for tests and logs. +var answered: Dictionary = {} + +var _server: TCPServer = TCPServer.new() +## {"peer": StreamPeerTCP, "data": PackedByteArray, "since": int} +var _connections: Array[Dictionary] = [] + + +func listen(port: int, address: String = "127.0.0.1") -> Error: + return _server.listen(port, address) + + +func port() -> int: + return _server.get_local_port() + + +func close() -> void: + for connection: Dictionary in _connections: + (connection["peer"] as StreamPeerTCP).disconnect_from_host() + _connections.clear() + _server.stop() + + +func poll(now_msec: int = -1) -> void: + var now: int = now_msec if now_msec >= 0 else Time.get_ticks_msec() + while _server.is_connection_available(): + var peer: StreamPeerTCP = _server.take_connection() + if _connections.size() >= MAX_CONNECTIONS: + peer.disconnect_from_host() + continue + _connections.append({"peer": peer, "data": PackedByteArray(), "since": now}) + var still: Array[Dictionary] = [] + for connection: Dictionary in _connections: + if not _serve(connection, now): + still.append(connection) + _connections = still + + +## Reads what has come and answers once the request line and headers are in. Returns +## true when the connection is finished with. +func _serve(connection: Dictionary, now: int) -> bool: + var peer: StreamPeerTCP = connection["peer"] + peer.poll() + if peer.get_status() != StreamPeerTCP.STATUS_CONNECTED: + return true + # Packed arrays are values: take a copy, add to it and put it back. + var data: PackedByteArray = connection["data"] + var available: int = peer.get_available_bytes() + if available > 0: + var got: Array = peer.get_partial_data(mini(available, MAX_REQUEST_BYTES)) + if int(got[0]) == OK: + data.append_array(got[1]) + connection["data"] = data + var text: String = data.get_string_from_ascii() + if text.contains("\r\n\r\n") or text.contains("\n\n"): + _answer(peer, text.get_slice("\n", 0).strip_edges()) + return true + if data.size() >= MAX_REQUEST_BYTES or now - int(connection["since"]) > TIMEOUT_MSEC: + peer.disconnect_from_host() + return true + return false + + +func _answer(peer: StreamPeerTCP, request_line: String) -> void: + var parts: PackedStringArray = request_line.split(" ") + var code: int = 404 + var body: String = "{\"status\":\"not found\"}" + if parts.size() == 3 and parts[0] == "GET" and (parts[1] == "/health" or parts[1] == "/health/"): + code = 200 + var fields: Dictionary = report.call() + if not fields.has("status"): + fields["status"] = "ok" + body = JSON.stringify(fields) + answered[code] = int(answered.get(code, 0)) + 1 + var reason: String = "OK" if code == 200 else "Not Found" + var head: String = "HTTP/1.0 %d %s\r\nContent-Type: application/json\r\nContent-Length: %d\r\nConnection: close\r\nCache-Control: no-store\r\n\r\n" % [code, reason, body.to_utf8_buffer().size()] + peer.put_data((head + body).to_utf8_buffer()) + peer.disconnect_from_host() diff --git a/src/server/health_server.gd.uid b/src/server/health_server.gd.uid new file mode 100644 index 0000000..d0a7b76 --- /dev/null +++ b/src/server/health_server.gd.uid @@ -0,0 +1 @@ +uid://mpeamjfwg8n3 diff --git a/src/server/server_config.gd b/src/server/server_config.gd index 4cfb9e7..44bf82b 100644 --- a/src/server/server_config.gd +++ b/src/server/server_config.gd @@ -4,6 +4,18 @@ ## [--bot-difficulty=mixed|easy|normal|hard] [--ticks=N] ## [--unthrottled] [--log-every=N] [--matches=N] [--world-hash-every=N] ## [--name=NAME] [--list=HOST[:PORT]]... [--no-lan] +## [--health-port=N] [--health-bind=ADDRESS] [--stop-file=PATH] +## [--config=PATH] +## +## `--config` reads options from a file, one per line, written without the leading +## dashes: `port = 24650`, or a bare `listen` for a switch. Blank lines and lines +## starting with # are skipped. Options after `--config` on the command line win. +## See packaging/server/server.cfg. +## +## `--health-port` answers `GET /health` over HTTP on that TCP port (HealthServer), on +## `--health-bind`, loopback by default. `--stop-file` makes the server stop cleanly, +## telling everyone connected, as soon as that file exists: the packaging's wrapper +## creates it on SIGTERM, which the engine itself can't catch. ## ## With `--listen` the server takes network players on UDP `--port`, waits in the lobby ## for the first of them, and with any `--bots` above 0 fills each match's empty places @@ -55,6 +67,11 @@ var server_name: String = NetDiscovery.DEFAULT_SERVER_NAME var lists: Array[Dictionary] = [] ## Answer LAN discovery. On by default for a listening server. var lan: bool = true +## TCP port for the health endpoint; 0 for none. +var health_port: int = 0 +var health_bind: String = "127.0.0.1" +## A file whose appearance asks the server to stop; empty for none. +var stop_file: String = "" ## Human-readable problems found while parsing. Empty when the config is usable. var errors: Array[String] = [] @@ -68,7 +85,12 @@ static func parse(args: PackedStringArray) -> ServerConfig: return config config.server = true for index: int in range(start + 1, args.size()): - config._parse_one(args[index]) + var arg: String = args[index] + if arg.begins_with("--config="): + for from_file: String in config._read_file(arg.substr("--config=".length())): + config._parse_one(from_file) + else: + config._parse_one(arg) config._validate() return config @@ -147,6 +169,16 @@ func _parse_one(arg: String) -> void: errors.append("--bot-difficulty must be mixed, easy, normal or hard, got '%s'" % value) "--fault": fault = value + "--health-port": + if _check_int(key, value): + health_port = value.to_int() + "--health-bind": + if not value.is_valid_ip_address(): + errors.append("--health-bind needs an IP address, got '%s'" % value) + else: + health_bind = value + "--stop-file": + stop_file = value "--name": server_name = NetDiscovery.clean_server_name(value) "--list": @@ -185,6 +217,30 @@ static func parse_host_port(text: String, default_port: int) -> Dictionary: return {"host": host, "port": port} +## The options in a config file, as command-line arguments. +func _read_file(path: String) -> Array[String]: + var args: Array[String] = [] + var file: FileAccess = FileAccess.open(path, FileAccess.READ) + if file == null: + errors.append("couldn't read the config file '%s': %s" % [path, error_string(FileAccess.get_open_error())]) + return args + var number: int = 0 + while not file.eof_reached(): + number += 1 + var line: String = file.get_line().strip_edges() + if line.is_empty() or line.begins_with("#"): + continue + if line.begins_with("config"): + errors.append("%s:%d: a config file can't include another" % [path, number]) + continue + var at: int = line.find("=") + if at < 0: + args.append("--" + line) + else: + args.append("--%s=%s" % [line.substr(0, at).strip_edges(), line.substr(at + 1).strip_edges()]) + return args + + func _check_int(key: String, value: String) -> bool: if value.is_valid_int(): return true @@ -214,5 +270,7 @@ func _validate() -> void: errors.append("--world-hash-every is for a server started with --listen") if not listen and (not lists.is_empty() or not lan): errors.append("--list and --no-lan are for a server started with --listen") + if health_port < 0 or health_port > 65535: + errors.append("--health-port must be between 1 and 65535, or 0 for none, got %d" % health_port) if fault not in FAULTS: errors.append("unknown --fault '%s'" % fault) diff --git a/test/server/test_health_server.gd b/test/server/test_health_server.gd new file mode 100644 index 0000000..3a14b03 --- /dev/null +++ b/test/server/test_health_server.gd @@ -0,0 +1,61 @@ +extends TestCase + +## Issue N7: the dedicated server's health endpoint answers GET /health with JSON, +## refuses everything else, and drops requests that never finish. + +var health: HealthServer + + +func before_each() -> void: + health = HealthServer.new() + health.report = func() -> Dictionary: return {"phase": "lobby", "players": 2} + assert_eq(health.listen(0), OK) + + +func after_each() -> void: + health.close() + + +## Sends `request` and returns everything the server says before it closes. +func _ask(request: String, limit_msec: int = 3000) -> String: + var peer: StreamPeerTCP = StreamPeerTCP.new() + assert_eq(peer.connect_to_host("127.0.0.1", health.port()), OK) + var reply: PackedByteArray = PackedByteArray() + var sent: bool = false + var started: int = Time.get_ticks_msec() + while Time.get_ticks_msec() - started < limit_msec: + health.poll() + peer.poll() + var status: int = peer.get_status() + if status == StreamPeerTCP.STATUS_CONNECTED: + if not sent and not request.is_empty(): + peer.put_data(request.to_ascii_buffer()) + sent = true + var available: int = peer.get_available_bytes() + if available > 0: + reply.append_array(peer.get_data(available)[1]) + elif status != StreamPeerTCP.STATUS_CONNECTING: + break + OS.delay_msec(5) + peer.disconnect_from_host() + return reply.get_string_from_utf8() + + +func test_health_answers_with_json() -> void: + var reply: String = _ask("GET /health HTTP/1.1\r\nHost: x\r\n\r\n") + assert_true(reply.begins_with("HTTP/1.0 200 OK\r\n"), reply) + var body: Variant = JSON.parse_string(reply.get_slice("\r\n\r\n", 1)) + assert_eq(body, {"status": "ok", "phase": "lobby", "players": 2.0}) + assert_eq(health.answered.get(200, 0), 1) + + +func test_other_paths_and_methods_are_not_found() -> void: + assert_true(_ask("GET /admin HTTP/1.0\r\n\r\n").begins_with("HTTP/1.0 404")) + assert_true(_ask("POST /health HTTP/1.0\r\n\r\n").begins_with("HTTP/1.0 404")) + assert_eq(health.answered.get(404, 0), 2) + + +func test_unfinished_and_oversized_requests_are_dropped() -> void: + assert_eq(_ask("GET /health HTTP/1.0\r\n", 2600), "", "never finished: closed without an answer") + assert_eq(_ask("GET /" + "a".repeat(HealthServer.MAX_REQUEST_BYTES) + " HTTP/1.0\r\n\r\n"), "") + assert_eq(health.answered.size(), 0) diff --git a/test/server/test_health_server.gd.uid b/test/server/test_health_server.gd.uid new file mode 100644 index 0000000..8d71e1b --- /dev/null +++ b/test/server/test_health_server.gd.uid @@ -0,0 +1 @@ +uid://dty6o6q6x6j4t diff --git a/test/server/test_server_config.gd b/test/server/test_server_config.gd index 3cae9ba..48f8bb5 100644 --- a/test/server/test_server_config.gd +++ b/test/server/test_server_config.gd @@ -119,3 +119,37 @@ func test_soak_options() -> void: assert_false(_parse(["--server", "--world-hash-every=300"]).is_valid(), "hashes are only logged when listening") assert_false(_parse(["--server", "--matches=-1"]).is_valid()) + +func test_config_file_and_command_line_order() -> void: + var path: String = "user://test_server.cfg" + var file: FileAccess = FileAccess.open(path, FileAccess.WRITE) + file.store_string("# a comment\n\nlisten\nport = 24700\nname = Harbour Light\nhealth-port = 24700\nno-lan\n") + file.close() + var config: ServerConfig = _parse(["--server", "--config=" + path, "--port=24702"]) + assert_true(config.is_valid(), str(config.errors)) + assert_true(config.listen) + assert_false(config.lan) + assert_eq(config.port, 24702, "the command line after --config wins") + assert_eq(config.server_name, "Harbour Light") + assert_eq(config.health_port, 24700) + assert_eq(config.health_bind, "127.0.0.1") + DirAccess.remove_absolute(ProjectSettings.globalize_path(path)) + + +func test_config_file_problems_are_errors() -> void: + assert_false(_parse(["--server", "--config=user://no_such_file.cfg"]).is_valid()) + var path: String = "user://test_bad_server.cfg" + var file: FileAccess = FileAccess.open(path, FileAccess.WRITE) + file.store_string("listen\nprot = 5\nconfig = other.cfg\n") + file.close() + var config: ServerConfig = _parse(["--server", "--config=" + path]) + assert_eq(config.errors.size(), 2, str(config.errors)) + DirAccess.remove_absolute(ProjectSettings.globalize_path(path)) + + +func test_health_and_stop_options() -> void: + var config: ServerConfig = _parse(["--server", "--listen", "--health-port=8080", "--health-bind=0.0.0.0", "--stop-file=/tmp/x"]) + assert_true(config.is_valid(), str(config.errors)) + assert_eq([config.health_port, config.health_bind, config.stop_file], [8080, "0.0.0.0", "/tmp/x"]) + assert_false(_parse(["--server", "--health-bind=localhost"]).is_valid()) + assert_false(_parse(["--server", "--health-port=70000"]).is_valid()) diff --git a/tools/server_package_check.sh b/tools/server_package_check.sh new file mode 100755 index 0000000..4a56314 --- /dev/null +++ b/tools/server_package_check.sh @@ -0,0 +1,57 @@ +#!/usr/bin/env bash +# Checks the dedicated server packaging (issue N7) end to end, in Docker: +# - `docker compose up` in packaging/docker builds the image and starts the server, +# - the container reports healthy through GET /health, +# - it runs as a non-root user on a read-only filesystem, +# - a real headless client joins it over UDP and plays from the lobby into the drop, +# - `docker compose stop` stops it cleanly: SIGTERM becomes a logged, orderly stop. +# Takes about a minute and a half. Leaves the tidewall-server:dev image, removes the +# container. SERVER_CHECK_PORT picks the UDP port (default 24675). +set -uo pipefail + +repo="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "$repo" +export TIDEWALL_PORT="${SERVER_CHECK_PORT:-24675}" +compose=(docker compose -f packaging/docker/compose.yaml) +out="$repo/build/server-check" +mkdir -p "$out" + +fail() { + echo "server-package-check: $1" >&2 + "${compose[@]}" logs --no-color 2>/dev/null | tail -n 8 >&2 + "${compose[@]}" down --timeout 20 >/dev/null 2>&1 + exit 1 +} + +nice -n 15 "${compose[@]}" up -d --build --quiet-pull >"$out/up.log" 2>&1 || { cat "$out/up.log" >&2; fail "compose up failed"; } + +health="" +for _ in $(seq 1 30); do + health="$(docker inspect -f '{{.State.Health.Status}}' tidewall-server 2>/dev/null)" + [[ "$health" == "healthy" ]] && break + sleep 2 +done +[[ "$health" == "healthy" ]] || fail "the container never became healthy (it is '$health')" + +[[ "$(docker exec tidewall-server id -u)" != "0" ]] || fail "the server runs as root" +docker exec tidewall-server touch /opt/tidewall/game/probe 2>/dev/null && fail "the game's files are writable" +docker exec tidewall-server touch /etc/probe 2>/dev/null && fail "the root filesystem is writable" +reply="$(docker exec tidewall-server bash -c 'exec 3<>/dev/tcp/127.0.0.1/24650; printf "GET /health HTTP/1.0\r\n\r\n" >&3; cat <&3')" +grep -q '"status":"ok"' <<<"$reply" || fail "GET /health said: $reply" + +nice -n 15 tools/godot.sh -- --connect="127.0.0.1:$TIDEWALL_PORT" --name=Harbour --autoplay --client-seconds=45 >"$out/client.log" 2>&1 +report="$(grep -m1 '"event":"client"' "$out/client.log" || true)" +grep -q '"joined":true' <<<"$report" || fail "the client never joined: ${report:-no report}" +grep -q '"phases":\["lobby","countdown","drop"' <<<"$report" || fail "the client didn't get from the lobby into the drop: $report" +grep -q '"bad_packets":0' <<<"$report" || fail "the client got packets it couldn't read: $report" + +"${compose[@]}" stop --timeout 20 >/dev/null 2>&1 +code="$(docker inspect -f '{{.State.ExitCode}}' tidewall-server)" +"${compose[@]}" logs --no-color >"$out/server.log" 2>&1 +"${compose[@]}" down --timeout 20 >/dev/null 2>&1 +[[ "$code" == "0" ]] || fail "the server exited $code when stopped" +grep -q '"event":"player_joined".*"name":"Harbour"' "$out/server.log" || fail "the server never saw the client join" +grep -q '"event":"stopping","reason":"stop file"' "$out/server.log" || fail "SIGTERM didn't become a clean stop" +grep -q '"errors":0,"event":"stop","exit_code":0' "$out/server.log" || fail "the server didn't log a clean stop" +echo "server-package-check: ok (healthy, non-root, read-only, joined over UDP into the drop, stopped cleanly on SIGTERM)" +echo " $report"