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 <noreply@anthropic.com>
This commit is contained in:
2026-11-12 22:07:24 -05:00
co-authored by Claude Opus 5.5
parent 05c7568ec1
commit 8eb6e587fb
17 changed files with 644 additions and 2 deletions
+59 -1
View File
@@ -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)