v0.4

.cursorrules

@@ -0,0 +1,94 @@
+# Cursor rules for this Go project
+
+These rules define how code should be written, reviewed, and changed in this repository.
+
+## Go toolchain + formatting (non-negotiable)
+
+- **Always run `gofmt`** on changed Go files.
+- **Use `goimports`** (or `gofmt` + manual imports) so imports are grouped and unused imports removed.
+- **Prefer standard library** over new dependencies unless there’s a clear reason.
+- **Keep `go.mod` tidy**: don’t add deps casually; when you do, keep versions minimal and coherent.
+
+## Code style + structure
+
+- **Small, focused diffs**: change the minimum surface area necessary.
+- **Package boundaries**: prefer adding code to an existing relevant package over creating new packages.
+- **Avoid cyclic dependencies**; keep `internal/...` layering clean.
+- **Public API discipline**:
+  - Export only what must be used outside the package.
+  - Keep exported types/functions well-documented (GoDoc comment starting with the symbol name).
+- **Naming**:
+  - Use Go conventions (short receiver names, no `GetX()` unless needed).
+  - Prefer clear domain names over generic ones (e.g., `RoomService` not `Service`).
+
+## Error handling (industry patterns)
+
+- **Return errors, don’t panic** in normal control flow.
+- **Wrap errors with context** using `%w`:
+  - `return fmt.Errorf("doing X: %w", err)`
+- **Use sentinel errors sparingly**; prefer typed errors only when callers must branch on type.
+- **Don’t log and return the same error** unless you have a strong reason (avoid double logging).
+- **Use `errors.Is` / `errors.As`** for comparisons.
+
+## Context, cancellation, timeouts
+
+- **Plumb `context.Context`** through call chains for IO, network, and long-running operations.
+- **Never store `context.Context`** inside structs.
+- **Always set timeouts** for network calls unless the caller explicitly controls it.
+- **Select on `ctx.Done()`** in loops that can block or run indefinitely.
+
+## Concurrency hygiene
+
+- **Avoid goroutine leaks**:
+  - Always ensure goroutines can exit (ctx cancellation, closed channels, done signals).
+  - Prefer `errgroup.Group` for fan-out work with cancellation.
+- **Prefer channels for ownership transfer**, not for shared mutable state.
+- **Protect shared state** with `sync.Mutex`/`sync.RWMutex` or confine it to one goroutine.
+- **Avoid data races**: design for correctness first; use `-race` when running tests.
+
+## Logging & observability
+
+- Use the project’s logging conventions (currently `slog`).
+- Log **actionable** fields:
+  - request/connection identifiers where available
+  - addresses, user IDs, session IDs (avoid PII where possible)
+- **Don’t log secrets** (passwords, tokens, private keys).
+- Metrics:
+  - Prefer incrementing existing Prometheus metrics where appropriate instead of inventing new ones.
+
+## Networking & protocol code
+
+- Be strict on input validation at boundaries (HTTP params, websocket payloads, TCP packets).
+- For protocol evolution:
+  - Add backwards-compatible fields where possible.
+  - Keep parsing resilient; fail fast with clear errors on malformed inputs.
+- Avoid allocating in tight loops; reuse buffers when it materially improves hot paths.
+
+## Tests (expected behavior)
+
+- For new behavior, add or update tests close to the code:
+  - `*_test.go` in the same package unless black-box testing is required.
+- Prefer table-driven tests for multiple cases.
+- Verify error cases explicitly (invalid inputs, timeouts, empty states).
+- Keep tests deterministic; avoid sleeps when possible.
+
+## Security expectations
+
+- Treat all external input as untrusted (HTTP, WS, TCP, DB).
+- Never commit real credentials; use env vars/config where secrets are needed.
+- Prefer constant-time comparisons for secrets if relevant.
+- Validate/normalize user-controlled network addresses to avoid SSRF-like patterns.
+
+## Documentation when changing behavior
+
+- If you modify user-facing behavior (CLI flags, endpoints, defaults), update docs in `docs/`.
+- Keep “incomplete/WIP” notes accurate—don’t over-promise.
+
+## How to work in this repository (practical)
+
+- Before large refactors, look for existing patterns in `internal/...` and follow them.
+- When you touch the backend protocol handlers (`internal/backend/command_*.go`), prioritize:
+  - correctness
+  - compatibility with existing clients
+  - clear logging around handshake/session boundaries
+

.editorconfig

@@ -1,6 +1,6 @@
 root = true
 
-[ansible/**]
+[scripts/ansible/**]
 charset = utf-8
 end_of_line = lf
 indent_size = 2

.github/workflows/ci.yml

@@ -22,14 +22,34 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.24"
+          go-version: "1.26"
           cache: 'true'
 
       - name: Compile binary
         run: go build -v ./
 
       - name: Run Tests
-        run: go test -v -cover -race ./...
+        run: go test -v -timeout 600s -cover -race ./...
+
+      - name: Run E2E Tests
+        run: go test -v -tags=e2e -timeout 1200s ./internal/acceptance/...
+
+  integration:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    needs:
+      - test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.26"
+
+      - name: Run multi-docker integration tests
+        # Docker is pre-installed on GitHub-hosted runners.
+        run: go test -tags=integration -run 'TestSpike|TestLANGameExchange' -v -timeout 300s -count=1 ./internal/integration/...
 
   build:
     runs-on: ubuntu-latest
@@ -44,7 +64,7 @@ jobs:
         id: setup-go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.24"
+          go-version: "1.26"
 
       - name: Get build data
         run: |
@@ -74,7 +94,7 @@ jobs:
             -ldflags="main.version=${BUILD_VERSION}" \
             -ldflags="main.commit=${BUILD_REVISION}" \
             -ldflags="main.date=${BUILD_TIME}" \
-            -env="GOTOOLCHAIN=go1.24.4" \
+            -env="GOTOOLCHAIN=go1.26" \
             -tags=gui
 
       - name: Extract packaged app
@@ -89,7 +109,7 @@ jobs:
         with:
           name: windows-build
           path: |
-            dist/Gladiator.exe 
+            dist/Gladiator.exe
 
       - name: Release
         uses: softprops/action-gh-release@v2
@@ -115,7 +135,7 @@ jobs:
         id: setup-go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.24"
+          go-version: "1.26"
 
       - name: Get build data
         run: |

.github/workflows/container.yml

@@ -18,7 +18,7 @@ jobs:
         id: setup-go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.24"
+          go-version: "1.26"
 
       - name: Get build data
         run: |
@@ -52,4 +52,4 @@ jobs:
             --build-arg GIT_COMMIT=$BUILD_REVISION \
             -t $IMAGE_NAME .
         env:
-          IMAGE_NAME: "ghcr.io/${{ github.repository_owner }}/gladiator:latest"
+          IMAGE_NAME: "ghcr.io/${{ github.repository_owner }}/gladiator:latest"

.gitignore

@@ -36,3 +36,7 @@ go.work
 
 # Releases
 *.zip
+
+# deepwork state (git-local)
+.slim/deepwork/
+.dwp/

DEPLOY.md

@@ -0,0 +1,72 @@
+# Deploy
+
+## Prerequisites
+
+- **Ansible** installed locally (`brew install ansible` or `pip install ansible`)
+- **SSH key** with root (or sudo-capable user) access to the target server
+- A **domain name** pointing to the server's public IP
+
+## Quick start
+
+```bash
+HOST=1.2.3.4 \
+DOMAIN=gladiator.example.com \
+EMAIL=admin@example.com \
+./scripts/deploy.sh
+```
+
+That's it. The script will:
+
+1. Install the required Ansible collection (`community.general`)
+2. Run the playbook against the server
+
+You can also go through the Makefile:
+
+```bash
+make deploy HOST=1.2.3.4 DOMAIN=gladiator.example.com EMAIL=admin@example.com
+```
+
+### Optional variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `SSH_USER` | `root` | SSH user on the target |
+| `SSH_KEY` | *(none)* | Path to your SSH private key |
+| `ANSIBLE_EXTRA_VARS` | *(none)* | Additional vars forwarded to Ansible (`k=v k=v`) |
+
+## What gets installed
+
+| Role | What it does |
+|---|---|
+| **podman** | Installs Podman, enables auto-update timer |
+| **security** | Hardens SSH (key-only), enables UFW (ports 22/80/443/9999), installs fail2ban & unattended-upgrades |
+| **appuser** | Creates unprivileged `appuser`, enables systemd lingering, sets file limits |
+| **gladiator** | Deploys the container as a Quadlet systemd service via Podman |
+| **nginx** | Installs nginx + certbot, provisions a Let's Encrypt certificate, configures reverse proxy |
+
+## Building the container image locally
+
+```bash
+make docker-build
+# or
+docker compose build
+```
+
+This compiles the Go binary inside a multi-stage Docker build and produces the `gladiator` image. Run it locally:
+
+```bash
+docker compose up -d
+```
+
+## SSH reference
+
+```bash
+make ssh HOST=1.2.3.4 SSH_KEY=~/.ssh/id_ed25519
+```
+
+## Per-server notes
+
+- The container runs rootless under `appuser` via Quadlet (Podman's systemd integration)
+- Container auto-updates: `podman-auto-update.timer` checks for new images on a system timer
+- The SQLite database persists in `/var/lib/gladiator/` on the host
+- UDP port 9999 is the game relay; TCP 2137 is the HTTP console (proxied through nginx on 443)

Dockerfile

@@ -1,6 +1,15 @@
+# syntax=docker/dockerfile:1
+# Build stage
+FROM golang:1-alpine AS builder
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -o /gladiator .
+
+# Runtime stage
 FROM gcr.io/distroless/static-debian12
 
-# Add build-time metadata
 ARG BUILD_DATE
 ARG VERSION
 ARG GIT_COMMIT
@@ -9,14 +18,10 @@ LABEL org.opencontainers.image.created="${BUILD_DATE}" \
       org.opencontainers.image.version="${VERSION}" \
       org.opencontainers.image.revision="${GIT_COMMIT}"
 
-# Copy the compiled binary
-COPY ./gladiator /gladiator
+COPY --from=builder /gladiator /gladiator
 
-# Name the directory for the volume
 VOLUME /data
 
-# Document the ports that will be exposed
-EXPOSE 2137
-EXPOSE 9999
+EXPOSE 2137 9999
 
-ENTRYPOINT ["/gladiator"]
+ENTRYPOINT ["/gladiator"]

Dockerfile.integration

@@ -0,0 +1,21 @@
+# syntax=docker/dockerfile:1
+# Integration test image: gladiator server + mock game client.
+# Used by testcontainers (FromDockerfile) for the multi-docker integration suite.
+FROM golang:1-alpine AS builder
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -o /gladiator ./
+RUN CGO_ENABLED=0 go build -o /mockclient ./cmd/integration-client
+
+# Runtime: distroless static (no shell needed; one process per container).
+FROM gcr.io/distroless/static-debian12
+
+COPY --from=builder /gladiator /gladiator
+COPY --from=builder /mockclient /mockclient
+
+VOLUME /data
+EXPOSE 2137 9999 6112
+
+ENTRYPOINT ["/gladiator"]

Makefile

@@ -10,13 +10,34 @@ join_id ?= 2
 build:
 	go build -race -v -o /dev/null ./
 
+docker-build:
+	docker compose build
+
+deploy:
+	./scripts/deploy.sh
+
 serve:
 	 go run -v ./ serve --backend-addr=127.0.0.1:6112 --console-addr=127.0.0.1:2137
 	#go run ./ serve --backend-addr=0.0.0.0:6112 --console-addr=0.0.0.0:2137
 	#(go build -v); (.\gladiator.exe serve --backend-addr=0.0.0.0:6112 --console-addr=0.0.0.0:2137)
 
 test:
-	go test -v --race ./...
+	go test -v --race -timeout 600s ./...
+
+test-e2e:
+	go test -v -tags=e2e -timeout 1200s ./internal/acceptance/...
+
+test-integration-lan:
+	go test -tags=integration -run 'TestSpike|TestLANGameExchange' -v -timeout 300s -count=1 ./internal/integration/...
+
+test-integration-relay:
+	go test -tags integration -run TestRelayGameExchange -v -timeout 300s -count=1 ./internal/integration/...
+
+test-integration-lifecycle:
+	go test -tags integration -run 'TestRelayFullLifecycleWithMigration' -v -timeout 600s -count=1 ./internal/integration/...
+
+lint:
+	go tool golangci-lint run ./...
 
 console: clear
 	go run -v ./ console --console-addr=127.0.0.1:2137