docs: WS auth per message, and how to test beyond SQLite

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Fabian @ Blax Software 2026-10-29 02:04:51 +01:00
parent 987a91fc81
commit b824d4fc70
2 changed files with 3 additions and 0 deletions

View File

@ -20,6 +20,8 @@ Read [docs/architecture.md](docs/architecture.md) before you change game logic,
Every formula in `app/Game/` gets a Pest unit test. Every action gets a feature test that moves time with `Carbon::setTestNow()`. A milestone is done when its tests are green. Every formula in `app/Game/` gets a Pest unit test. Every action gets a feature test that moves time with `Carbon::setTestNow()`. A milestone is done when its tests are green.
Tests run on SQLite; production is MySQL. After a deploy, `scripts/e2e-edgerealm.sh` runs the WS API end to end (join, show, build with its push, map) in a throwaway container on edgerealm with its own database, so production data stays untouched. Never register test accounts on the live backend. A check against live data runs inside a transaction that is rolled back.
## WebSocket API ## WebSocket API
The API is WS-first, the same as learn-atc. It uses native controllers in `app/Websocket/Controllers/` (blax-software/laravel-websockets). Load the `blax-websockets` skill before you write a controller or a push. HTTP is used only to log in, register (issues the Sanctum bearer token), and serve health checks. After the engine processes an event, it pushes the change to the owner's sockets with `ws_whisper`. The API is WS-first, the same as learn-atc. It uses native controllers in `app/Websocket/Controllers/` (blax-software/laravel-websockets). Load the `blax-websockets` skill before you write a controller or a push. HTTP is used only to log in, register (issues the Sanctum bearer token), and serve health checks. After the engine processes an event, it pushes the change to the owner's sockets with `ws_whisper`.

View File

@ -16,6 +16,7 @@ The frontend builds with `ssr: false` for every target. It is a game behind a lo
- Accounts are email + password, with no verification for now. Steam login comes later as a second provider. - Accounts are email + password, with no verification for now. Steam login comes later as a second provider.
- HTTP `POST /api/auth/register|login` returns a Sanctum bearer token. The client stores it and passes it as `getAuthToken` to the WS client. The same flow works inside a Steam wrapper, where cookies across origins would not. - HTTP `POST /api/auth/register|login` returns a Sanctum bearer token. The client stores it and passes it as `getAuthToken` to the WS client. The same flow works inside a Steam wrapper, where cookies across origins would not.
- Everything else runs over WS through native controllers (`<prefix>.<method>`), for example `village.show`, `village.build`, `village.demolish`, `village.cancel`, and `village.staff`. - Everything else runs over WS through native controllers (`<prefix>.<method>`), for example `village.show`, `village.build`, `village.demolish`, `village.cancel`, and `village.staff`.
- blax laravel-websockets authenticates a message only by its own `data.authtoken`, so the client adds the token to every `ws.send`. `App\Websocket\GameController::booted()` then caches the user as `socket_<id>` and calls `WebsocketService::setUserAuthed`, so the socket's later messages and the `game:events` pushes find the user. A frame without a token is refused.
- Push goes to the owner's sockets with `ws_whisper('village:updated', …)` after the engine processes an event. The client then refetches or patches its state. - Push goes to the owner's sockets with `ws_whisper('village:updated', …)` after the engine processes an event. The client then refetches or patches its state.
## Backend layers ## Backend layers