docs: update PLAN, CODEBASE, README with env vars, stubs, tests, atomic state

PLAN.md:
- Add SERVER_BINARY, SERVER_PARAMS, STEAMCMD_PATH to env vars table
- Add testdata/ to project structure
- Add testing section (backend tests, stubs, frontend tests, make targets)
- Update process start flow with env var overrides

CODEBASE.md:
- Add testdata/ stubs to directory map
- Replace zustand with vitest/testing-library/jsdom in frontend deps
- Update CI to include test steps
- Update Makefile targets description
- Add atomic state machine to ProcessManager description
- Add env overrides and atomic state to design decisions
- Update data flow with env var overrides

README.md:
- Add SERVER_BINARY, SERVER_PARAMS, STEAMCMD_PATH to env vars table
- Remove FRONTEND_DIR (embedded frontend)
- Update Development section with make targets
This commit is contained in:
MrFastwind
2026-07-23 22:29:22 +02:00
parent 930b6cbca6
commit 41c1390972
3 changed files with 93 additions and 16 deletions
+59 -2
View File
@@ -51,7 +51,10 @@ arma3-web-server/
│ │ ├── server_process.go # Process lifecycle, arg builder, mod path resolver
│ │ ├── steamcmd.go # SteamCMD manager (UpdateGame, DownloadMod, DownloadMods)
│ │ ├── scheduler.go # Cron-based scheduled updates
│ │ ── log_streamer.go # Pub/sub fan-out for stdout/stderr via channels
│ │ ── log_streamer.go # Pub/sub fan-out for stdout/stderr via channels
│ │ └── testdata/ # Stub binaries for testing
│ │ ├── arma3server_x64 # Server stub: logs args, heartbeat, -t N exit, RPT writes
│ │ └── steamcmd # SteamCMD stub: fake downloads, creates mod dirs
│ ├── go.mod
│ └── go.sum
├── frontend/
@@ -91,7 +94,7 @@ arma3-web-server/
├── Dockerfile # Multi-stage: Go build -> npm build -> alpine runtime + SteamCMD
├── Dockerfile.goreleaser # Single-stage for GoReleaser (pre-built artifacts injected)
├── .goreleaser.yaml # GoReleaser v2 config (Gitea release target)
└── Makefile # Convenience targets: backend, frontend, build, run, dev, clean
└── Makefile # Convenience targets: backend, frontend, build, run, dev, clean, test
```
---
@@ -106,6 +109,9 @@ arma3-web-server/
| `PROFILES_DIR` | Server profile/save/log path | `$SERVERFILE_DIR/profiles` |
| `DATA_DIR` | Internal data (settings.json, modlists/) | `./data` |
| `LISTEN` | HTTP listen address | `:8080` |
| `SERVER_BINARY` | Server binary filename (overrides platform default) | `arma3server_x64` (`.exe` on Windows) |
| `SERVER_PARAMS` | Override server launch parameters (overrides settings.json) | `-server -world=empty -loadMissionToMemory -noPause` |
| `STEAMCMD_PATH` | Path to steamcmd binary | `steamcmd` |
> Note: `FRONTEND_DIR` was removed — the frontend is now embedded into the Go binary via `//go:embed`.
@@ -237,6 +243,8 @@ GET /ws/server/rpt # tail latest .rpt crash dump (250ms pollin
User clicks Start
→ Settings loaded from data/settings.json
→ WasRunning set to true, saved to disk
→ SERVER_PARAMS env overrides ServerParameters if set
→ SERVER_BINARY env overrides platform default binary name if set
→ If ServerParameters contains %command%:
→ Replace %command% with binary path (enables Wine wrappers)
→ Split into command + args
@@ -286,3 +294,52 @@ A cron expression in the `scheduled_update` field runs game + mod updates on a s
10. **Crash recovery**`WasRunning` flag persists across restarts. If `auto_start_on_startup` is enabled, the server restarts automatically.
11. **SteamCMD async with live streaming** — All steamcmd operations run in background goroutines, output broadcast to `"steamcmd"` key via LogStreamer pub/sub.
12. **Health endpoint**`/api/server/health` checks binary existence, directory writability, disk usage, mod counts, SteamCMD status, and frontend serving.
---
## Testing
### Backend tests
Run with `make test-backend` or `cd backend && go test ./...`.
Test files in `backend/internal/services/`:
- `settings_test.go` — SettingsManager load/save/defaults
- `config_manager_test.go` — ConfigManager CRUD + path traversal protection
- `modlist_manager_test.go` — ModlistManager CRUD + duplicate
- `modlist_parser_test.go` — HTML preset parser + renderer
- `log_streamer_test.go` — Pub/sub subscribe/unsubscribe/broadcast/stream
- `server_process_test.go` — Process lifecycle, arg building, mod path resolution, env var overrides, stub-based integration tests
- `steamcmd_test.go` — SteamCMD state machine, CheckWorkshopMod, stub-based download tests
### Test stubs
Stub binaries in `backend/internal/services/testdata/` replace real server/steamcmd during tests:
**`arma3server_x64` stub:**
- Logs binary path and all arguments to stdout
- Prints heartbeat every 5 seconds
- Accepts `-t N` to exit after N seconds (for auto-exit and timeout tests)
- Parses `-profiles=<dir>` and writes RPT log entries to `profilesDir/arma3server_x64_*.rpt`
**`steamcmd` stub:**
- Parses `+force_install_dir` and `+workshop_download_item` args
- Creates fake mod directories at the expected workshop content path
- Prints fake download progress and success logs
### Frontend tests
Run with `make test-frontend` or `cd frontend && npm test`.
Uses Vitest + React Testing Library + jsdom:
- `utils/format.test.ts` — fmtSize utility
- `components/Layout.test.tsx` — Sidebar navigation
- `pages/Mods.test.tsx` — Mods page with mods present
### Makefile test targets
| Target | Description |
|--------|-------------|
| `make test` | Run both backend and frontend tests |
| `make test-backend` | Run `go test ./...` in backend |
| `make test-frontend` | Run `vitest run` in frontend |