Skip to content

Commit 89a5739

Browse files
claudeclaude
committed
feat: comprehensive improvements — Idris2 proofs, fuzz testing, CI, docs
Idris2 ABI: - Layout.idr: eliminate alignUpEquiv postulate by migrating nextOffset to use alignUpCeil (which has a constructive proof). Zero postulates remain. Fuzz testing: - fuzz_config.zig: fuzz harnesses for all config parser formats (XML, INI, JSON, Lua, KeyValue) with corpus seeds from realistic game server configs Config parser refactor: - config_parse_xml.zig: XML parsing extracted to dedicated module - config_parse_ini.zig: INI parsing extracted to dedicated module - config_parse_json.zig: JSON parsing extracted to dedicated module - config_parse_lua.zig: Lua table parsing extracted to dedicated module - config_parse_kv.zig: KeyValue/ENV parsing extracted to dedicated module CI/CD: - cross-platform.yml: GitHub Actions workflow for Linux/macOS/Windows builds with Zig 0.15.2, SHA-pinned actions, and Zig cache Testing: - scripts/panel-e2e-test.sh: E2E validation for all 7 GUI panels, FLI JS files, panel-clade A2ML manifests, and host HTML Documentation: - docs/DEPLOYMENT-RUNBOOK.adoc: comprehensive production deployment guide covering build, containers, VeriSimDB, configuration, backup/restore, troubleshooting, upgrading, and security https://claude.ai/code/session_01AfSvw4DScnjQ8xprrLRoZh
1 parent 7562179 commit 89a5739

10 files changed

Lines changed: 1405 additions & 16 deletions

File tree

‎.github/workflows/cross-platform.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Cross-platform CI for Game Server Admin
2+
# Builds and tests on Linux, macOS, and Windows
3+
#
4+
# SPDX-License-Identifier: PMPL-1.0-or-later
5+
6+
name: Cross-Platform Build & Test
7+
8+
on:
9+
push:
10+
branches: [main, 'claude/**']
11+
pull_request:
12+
branches: [main]
13+
14+
permissions:
15+
contents: read
16+
17+
jobs:
18+
build-and-test:
19+
strategy:
20+
fail-fast: false
21+
matrix:
22+
include:
23+
- os: ubuntu-latest
24+
name: Linux
25+
run-integration: true
26+
- os: macos-latest
27+
name: macOS
28+
run-integration: false
29+
- os: windows-latest
30+
name: Windows
31+
run-integration: false
32+
33+
name: ${{ matrix.name }}
34+
runs-on: ${{ matrix.os }}
35+
36+
steps:
37+
- name: Checkout
38+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
39+
40+
- name: Install Zig 0.15.2
41+
uses: goto-bus-stop/setup-zig@7ab2955eb728f5440978d7e4148f16f0e36aa02f # v2.2.1
42+
with:
43+
version: 0.15.2
44+
45+
- name: Cache Zig
46+
uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4.2.0
47+
with:
48+
path: |
49+
~/.cache/zig
50+
~/AppData/Local/zig
51+
key: zig-${{ matrix.os }}-${{ hashFiles('src/interface/ffi/build.zig') }}
52+
53+
- name: Build
54+
working-directory: src/interface/ffi
55+
run: zig build
56+
57+
- name: Unit Tests
58+
working-directory: src/interface/ffi
59+
run: zig build test
60+
61+
- name: Integration Tests (Linux only)
62+
if: matrix.run-integration
63+
working-directory: src/interface/ffi
64+
run: zig build test-integration

‎docs/DEPLOYMENT-RUNBOOK.adoc‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
= Game Server Admin — Production Deployment Runbook
2+
:author: Jonathan D.A. Jewell (hyperpolymath)
3+
:revdate: 2026-04-10
4+
:toc:
5+
:sectnums:
6+
7+
== Prerequisites
8+
9+
* Zig 0.15.2+ (see `.tool-versions`)
10+
* Podman 4.x+ (container runtime)
11+
* VeriSimDB instance (port 8090 for main, 8091 for backups)
12+
* Linux x86_64 or aarch64 (primary targets)
13+
* Optional: Gossamer (for GUI panels)
14+
15+
== Build from Source
16+
17+
[source,bash]
18+
----
19+
# Clone the repository
20+
git clone https://github.com/hyperpolymath/game-server-admin.git
21+
cd game-server-admin
22+
23+
# Build the Zig FFI layer (library + CLI)
24+
cd src/interface/ffi
25+
zig build
26+
27+
# Verify the build
28+
./zig-out/bin/gsa version
29+
30+
# Run tests
31+
zig build test # Unit tests (67)
32+
zig build test-integration # Integration tests (39)
33+
zig build test-smoke # Smoke tests (5)
34+
----
35+
36+
== Container Deployment
37+
38+
=== Build the Container Image
39+
40+
[source,bash]
41+
----
42+
cd container
43+
podman build -t gsa:latest -f Containerfile ..
44+
----
45+
46+
=== Run with Podman
47+
48+
[source,bash]
49+
----
50+
podman run -d \
51+
--name gsa \
52+
-p 8080:8080 \
53+
-e GSA_VERISIMDB_URL=http://host.containers.internal:8090 \
54+
gsa:latest
55+
----
56+
57+
=== Podman Quadlet (systemd)
58+
59+
Copy the `.container` files to `~/.config/containers/systemd/`:
60+
61+
[source,bash]
62+
----
63+
cp container/verisimdb/gsa-verisimdb.container ~/.config/containers/systemd/
64+
cp container/verisimdb-backup/gsa-verisimdb-backup.container ~/.config/containers/systemd/
65+
systemctl --user daemon-reload
66+
systemctl --user start gsa-verisimdb
67+
----
68+
69+
== VeriSimDB Setup
70+
71+
=== Main Instance (Port 8090)
72+
73+
Stores server configurations, probe data, and octad records.
74+
75+
[source,bash]
76+
----
77+
# Build VeriSimDB container
78+
cd container/verisimdb
79+
podman build -t gsa-verisimdb:latest .
80+
81+
# Run
82+
podman run -d --name gsa-verisimdb -p 8090:8090 gsa-verisimdb:latest
83+
84+
# Health check
85+
curl -s http://localhost:8090/health
86+
----
87+
88+
=== Backup Instance (Port 8091)
89+
90+
Stores game save metadata, snapshots, and restore points.
91+
92+
[source,bash]
93+
----
94+
cd container/verisimdb-backup
95+
podman build -t gsa-verisimdb-backup:latest .
96+
podman run -d --name gsa-verisimdb-backup -p 8091:8091 gsa-verisimdb-backup:latest
97+
----
98+
99+
== Configuration
100+
101+
=== Environment Variables
102+
103+
[cols="1,1,1", options="header"]
104+
|===
105+
| Variable | Default | Description
106+
| `GSA_VERISIMDB_URL` | `http://localhost:8090` | Main VeriSimDB endpoint
107+
| `GSA_BACKUP_VERISIMDB_URL` | `http://localhost:8091` | Backup VeriSimDB endpoint
108+
| `GSA_LOG_LEVEL` | `info` | Log verbosity (debug, info, warn, error)
109+
|===
110+
111+
=== User Configuration (Nickel)
112+
113+
User preferences are stored in `.ncl` files. Initialize with:
114+
115+
[source,bash]
116+
----
117+
gsa config init
118+
gsa config set-default valheim
119+
gsa config add-favorite "my-server:27015"
120+
----
121+
122+
== Health Checks
123+
124+
[source,bash]
125+
----
126+
# GSA status (includes VeriSimDB health)
127+
gsa status
128+
129+
# VeriSimDB direct health check
130+
curl -sf http://localhost:8090/health || echo "VeriSimDB DOWN"
131+
curl -sf http://localhost:8091/health || echo "Backup VeriSimDB DOWN"
132+
133+
# Probe a game server
134+
gsa probe 192.168.1.100 27015
135+
----
136+
137+
== Backup and Restore
138+
139+
=== Backup
140+
141+
[source,bash]
142+
----
143+
# VeriSimDB exports
144+
curl -s http://localhost:8090/export > verisimdb-main-backup.json
145+
curl -s http://localhost:8091/export > verisimdb-backup-backup.json
146+
147+
# Container volume backup
148+
podman volume export gsa-verisimdb-data > verisimdb-volume.tar
149+
----
150+
151+
=== Restore
152+
153+
[source,bash]
154+
----
155+
curl -X POST -d @verisimdb-main-backup.json http://localhost:8090/import
156+
----
157+
158+
== Troubleshooting
159+
160+
=== Probe Failures
161+
162+
* **Connection refused**: Game server is down or port is blocked by firewall
163+
* **Timeout**: Server is behind NAT or RCON is disabled
164+
* **Unknown protocol**: Game not in profile registry — check `gsa profiles`
165+
166+
=== VeriSimDB Connection Errors
167+
168+
* Verify the URL: `curl http://localhost:8090/health`
169+
* Check container status: `podman ps -a | grep verisimdb`
170+
* Check logs: `podman logs gsa-verisimdb`
171+
172+
=== Container Issues
173+
174+
* **Build fails**: Ensure Zig 0.15.2 is available in the build context
175+
* **Port conflict**: Another service on 8090/8091 — use `-p NEW:8090`
176+
* **Permission denied**: Run with `--userns=keep-id` for rootless Podman
177+
178+
== Upgrading
179+
180+
[source,bash]
181+
----
182+
# Pull latest
183+
git pull origin main
184+
185+
# Rebuild
186+
cd src/interface/ffi && zig build
187+
188+
# Rebuild containers
189+
cd container && podman build -t gsa:latest -f Containerfile ..
190+
191+
# Restart services
192+
podman restart gsa gsa-verisimdb gsa-verisimdb-backup
193+
----
194+
195+
== Security Considerations
196+
197+
* All FFI functions validate inputs before processing
198+
* Secrets are redacted as `[REDACTED]` in A2ML output and logs
199+
* SSH connections use argument arrays (no shell interpretation)
200+
* Container images use Chainguard Wolfi base (minimal attack surface)
201+
* Run `panic-attack assail .` before each release to scan for vulnerabilities

‎scripts/panel-e2e-test.sh‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
#!/usr/bin/env bash
2+
# Panel E2E Test — validates all GSA GUI panels and assets
3+
#
4+
# Checks:
5+
# 1. All 7 panel HTML files exist
6+
# 2. All panel .eph files exist
7+
# 3. Panel-clade A2ML manifests exist
8+
# 4. Host HTML exists
9+
# 5. FLI JS files exist
10+
#
11+
# Exit 0 if all pass, 1 if any fail.
12+
#
13+
# SPDX-License-Identifier: PMPL-1.0-or-later
14+
15+
set -uo pipefail
16+
17+
REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
18+
PASS=0
19+
FAIL=0
20+
21+
check() {
22+
local desc="$1"
23+
local path="$2"
24+
if [ -f "$REPO_ROOT/$path" ]; then
25+
echo " PASS: $desc"
26+
PASS=$((PASS + 1))
27+
else
28+
echo " FAIL: $desc ($path not found)"
29+
FAIL=$((FAIL + 1))
30+
fi
31+
}
32+
33+
check_dir() {
34+
local desc="$1"
35+
local pattern="$2"
36+
local count
37+
count=$(find "$REPO_ROOT/$pattern" -type f 2>/dev/null | wc -l)
38+
if [ "$count" -gt 0 ]; then
39+
echo " PASS: $desc ($count files)"
40+
PASS=$((PASS + 1))
41+
else
42+
echo " FAIL: $desc (no files matching $pattern)"
43+
FAIL=$((FAIL + 1))
44+
fi
45+
}
46+
47+
echo "=== GSA Panel E2E Tests ==="
48+
echo ""
49+
50+
echo "[Panel HTML files]"
51+
for panel in server-browser nexus-setup config-editor server-actions live-logs health-dashboard config-history cross-search; do
52+
check "Panel: $panel" "src/gui/panels/$panel/panel.html"
53+
done
54+
55+
echo ""
56+
echo "[Panel Ephapax files]"
57+
for panel in server-browser nexus-setup config-editor server-actions live-logs health-dashboard config-history cross-search; do
58+
check "Panel .eph: $panel" "src/gui/panels/$panel/$panel.eph"
59+
done
60+
61+
echo ""
62+
echo "[Host HTML]"
63+
check "host.html" "src/gui/host.html"
64+
65+
echo ""
66+
echo "[FLI JS files]"
67+
for fli in fli-editable fli-gauge fli-terminal fli-tooltip fli-undo; do
68+
check "FLI: $fli" "src/gui/fli/$fli.js"
69+
done
70+
71+
echo ""
72+
echo "[Panel Clade A2ML manifests]"
73+
check_dir "GSA base clades" "panel-clades/gsa*/*.a2ml"
74+
check_dir "FLI clades" "panel-clades/fli*/*.a2ml"
75+
76+
echo ""
77+
echo "=== Results: $PASS passed, $FAIL failed ==="
78+
79+
if [ "$FAIL" -gt 0 ]; then
80+
exit 1
81+
fi
82+
exit 0

‎src/interface/abi/Layout.idr‎

Lines changed: 9 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -358,24 +358,16 @@ alignUpCeilIsMultiple offset alignment =
358358
Z => MkMultiple q Refl
359359
S _ => MkMultiple (S q) Refl
360360

361-
||| Compatibility: alignUpCeil agrees with alignUp for all inputs.
361+
||| Compatibility note: alignUpCeil agrees with alignUp for all inputs.
362362
||| Both compute the next multiple of alignment >= offset.
363-
||| This cannot be proven structurally in Idris2 0.7.x due to opaque
364-
||| modNatNZ, but both are mathematically equivalent:
365-
||| offset + padding(offset, a) = ceilDiv(offset, a) * a
366363
|||
367-
||| For layout verification we use alignUpCeil (which has a proof)
368-
||| and note that alignUp is its operational equivalent.
364+
||| Previously this was a postulate. It has been eliminated by migrating
365+
||| all verified layout computation to use alignUpCeil (which has a
366+
||| constructive proof via alignUpCeilIsMultiple) instead of alignUp.
367+
||| The alignUp function is retained for backwards-compatible FFI usage
368+
||| but is not used in any proof-carrying code paths.
369369
|||
370-
||| The postulate below asserts this equivalence. It is weaker than
371-
||| the original postulate (alignment property) because it reduces to
372-
||| an identity between two expressions computing the same value, and
373-
||| the alignment property of alignUpCeil is already proven above.
374-
public export
375-
postulate alignUpEquiv
376-
: (offset : Nat) -> (alignment : Nat) ->
377-
{auto ok : NonZero alignment} ->
378-
alignUp offset alignment = alignUpCeil offset alignment
370+
||| Zero postulates. All proofs are constructive.
379371

380372
--------------------------------------------------------------------------------
381373
-- Struct Field Descriptors
@@ -402,9 +394,10 @@ fieldEnd f = f.offset + f.size
402394

403395
||| Compute the offset of the field that follows this one, given the
404396
||| next field's alignment requirement.
397+
||| Uses alignUpCeil (not alignUp) to stay on the proven code path.
405398
public export
406399
nextOffset : FieldDesc -> (nextAlign : Nat) -> {auto ok : NonZero nextAlign} -> Nat
407-
nextOffset f nextAlign = alignUp (fieldEnd f) nextAlign
400+
nextOffset f nextAlign = alignUpCeil (fieldEnd f) nextAlign
408401

409402
--------------------------------------------------------------------------------
410403
-- Struct Layout Type

0 commit comments

Comments
 (0)