refactor(game): lock-free storage, remove /command, flatten engine wrapper #73

2026-05-30T11:39:46Z

developer commented

2026-05-30 11:39:46 +00:00

Refactor of the game-engine plumbing (game logic untouched), in three stages reviewed with the owner.

Stage 1 — lock-free persistence + admin serialisation. Removed the file lock from repo/fs (the .lock file, the Read/Write-vs-*Safe duality, the dead ReadSafe polling); Write is now a single atomic rename so concurrent reads are torn-free without a lock. The state-mutating admin writers (init/turn/banish) are serialised by one shared router LimitMiddleware, rewritten to block on the request context instead of a racy shared 100 ms timer.

Stage 2 — removed the obsolete immediate-command path end to end. Players submit through PUT /api/v1/order; the legacy PUT /api/v1/command path is deleted across game (route, handler, 24 command factories, Ctrl), backend (Commands handler/route, engineclient.ExecuteCommands), gateway (dispatch + executeUserGamesCommand + routing entry), the FlatBuffers/model contract (UserGamesCommand[Response]) and transcoder, plus every affected OpenAPI/README/FUNCTIONAL/ARCHITECTURE doc. The integration proxy test is converted to the order path.

Stage 3 — flattened the REST→engine wrapper. Replaced the executor adapter, the controller.* package functions and RepoController with one concrete controller.Service; dropped the single-implementation Repo and Storage interfaces (repo.Repo / fs.FS are now concrete). Handlers depend on a thin handler.Engine seam and own the domain→REST projection; storage is resolved once at startup instead of per request.

Net diff: +682 / −2805 across 65 files. All Go modules build and unit-test green locally; the integration suite runs here.

Refactor of the game-engine plumbing (game logic untouched), in three stages reviewed with the owner. **Stage 1 — lock-free persistence + admin serialisation.** Removed the file lock from `repo/fs` (the `.lock` file, the `Read`/`Write`-vs-`*Safe` duality, the dead `ReadSafe` polling); `Write` is now a single atomic rename so concurrent reads are torn-free without a lock. The state-mutating admin writers (`init`/`turn`/`banish`) are serialised by one shared router `LimitMiddleware`, rewritten to block on the request context instead of a racy shared 100 ms timer. **Stage 2 — removed the obsolete immediate-command path end to end.** Players submit through `PUT /api/v1/order`; the legacy `PUT /api/v1/command` path is deleted across game (route, handler, 24 command factories, `Ctrl`), backend (`Commands` handler/route, `engineclient.ExecuteCommands`), gateway (dispatch + `executeUserGamesCommand` + routing entry), the FlatBuffers/model contract (`UserGamesCommand[Response]`) and transcoder, plus every affected OpenAPI/README/FUNCTIONAL/ARCHITECTURE doc. The integration proxy test is converted to the order path. **Stage 3 — flattened the REST→engine wrapper.** Replaced the executor adapter, the `controller.*` package functions and `RepoController` with one concrete `controller.Service`; dropped the single-implementation `Repo` and `Storage` interfaces (`repo.Repo` / `fs.FS` are now concrete). Handlers depend on a thin `handler.Engine` seam and own the domain→REST projection; storage is resolved once at startup instead of per request. Net diff: **+682 / −2805** across 65 files. All Go modules build and unit-test green locally; the integration suite runs here.

developer added 1 commit 2026-05-30 11:39:46 +00:00

refactor(game): lock-free storage, remove /command, flatten engine wrapper

Tests · Go / test (push) Successful in 2m27s

Details

Tests · UI / test (push) Waiting to run

Details

Tests · Integration / integration (pull_request) Successful in 1m45s

Details

Tests · Go / test (pull_request) Successful in 3m13s

Details

Tests · UI / test (pull_request) Successful in 3m8s

Details

601970b028

Three-stage refactor of the game-engine plumbing (game logic untouched):

Stage 1 — lock-free persistence + admin serialisation. Remove the file
lock from repo/fs (the .lock file, the Read/Write-vs-*Safe duality and the
dead ReadSafe polling) and replace the two-step rename with a single atomic
rename so concurrent reads are torn-free without a lock. Serialise the
state-mutating admin writers (init/turn/banish) with one shared router
LimitMiddleware, rewritten to block on the request context instead of a
racy shared 100ms timer.

Stage 2 — remove the obsolete immediate-command path end to end. Players
submit through PUT /api/v1/order; the legacy PUT /api/v1/command path is
deleted across game (route, handler, 24 command factories, Ctrl), backend
(Commands handler/route, engineclient.ExecuteCommands), gateway (dispatch +
executeUserGamesCommand + routing entry), the FlatBuffers/model contract
(UserGamesCommand[Response]) and transcoder, plus every affected
OpenAPI/README/FUNCTIONAL/ARCHITECTURE doc. The integration proxy test is
converted to the order path.

Stage 3 — flatten the REST->engine wrapper. Replace the executor adapter,
the controller package functions and RepoController with one concrete
controller.Service; drop the single-implementation Repo and Storage
interfaces (repo.Repo / fs.FS are now concrete). Handlers depend on a thin
handler.Engine seam and own the domain->REST projection; storage is
resolved once at startup instead of per request.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

owner approved these changes 2026-05-30 12:21:33 +00:00

developer merged commit 2f55fc4988 into development

2026-05-30 12:23:29 +00:00

developer deleted branch feature/game-engine-refactor

2026-05-30 12:23:29 +00:00

developer referenced this pull request

2026-05-30 12:46:18 +00:00

fix(backend): retry migrations on transient connection errors #74

developer referenced this pull request

2026-05-30 13:16:18 +00:00

chore(cleanup): purge /command residuals — fakeEngine, canon golden, openapi #75

developer referenced this issue from a commit