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

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>

game/internal/repo/fs/fs.go

@@ -5,26 +5,19 @@ import (
 	"errors"
 	"fmt"
 	"galaxy/util"
-	"math/big"
 	"os"
 	"path/filepath"
-	"time"
 )
 
-const (
-	defaultPerm   = 0o644
-	lockFile      = ".lock"
-	oldFileSuffix = ".old"
-	newFileSuffix = ".new"
-)
+const defaultPerm = 0o644
 
-type fs struct {
+// FS is the file-backed Storage implementation: atomic, lock-free reads and
+// writes rooted at a single per-game directory.
+type FS struct {
 	root string
-	lock *os.File
 }
 
-func NewFileStorage(path string) (*fs, error) {
-	filepath.Join("", "")
+func NewFileStorage(path string) (*FS, error) {
 	absPath, err := filepath.Abs(path)
 	if err != nil {
 		return nil, fmt.Errorf("path %s invalid: %s", path, err)
@@ -41,55 +34,26 @@ func NewFileStorage(path string) (*fs, error) {
 		return nil, errors.New("directory should have read-write access: " + absPath)
 	}
 
-	fs := &fs{
-		root: path,
-	}
-	return fs, nil
+	return &FS{root: path}, nil
 }
 
-func (f *fs) Lock() (func() error, error) {
-	lockPath := f.lockFilePath()
-	exists, err := util.FileExists(lockPath)
-	if err != nil {
-		return nil, fmt.Errorf("check lock file exists: %s", err)
-	}
-	if exists {
-		return nil, errors.New("lock file already exists")
-	}
-	fd, err := os.OpenFile(lockPath, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0o600)
-	if err != nil {
-		return nil, fmt.Errorf("create lock file: %s", err)
-	}
-	f.lock = fd
-	unlock := func() error {
-		if err := f.lock.Close(); err != nil {
-			return fmt.Errorf("close lock file: %s", err)
-		}
-		if err := os.Remove(f.lock.Name()); err != nil {
-			return fmt.Errorf("remove lock file: %s", err)
-		}
-		f.lock = nil
-		return nil
-	}
-	if _, err := f.lock.Write(big.NewInt(time.Now().UnixMilli()).Bytes()); err != nil {
-		return nil, errors.Join(fmt.Errorf("write lock file: %s", err), unlock())
-	}
-	return unlock, nil
-}
-
-func (f *fs) Exists(path string) (bool, error) {
+func (f *FS) Exists(path string) (bool, error) {
 	return util.FileExists(filepath.Join(f.root, path))
 }
 
-func (f *fs) WriteSafe(path string, v encoding.BinaryMarshaler) error {
+// Write atomically persists v at path: it stages the payload in a temporary
+// file and swaps it into place with a single rename. On POSIX rename replaces
+// the destination atomically, so a concurrent reader always observes either
+// the previous file or the new one in full — the target is never absent
+// mid-write and never half-written. This atomic replace is the only
+// protection against torn reads; the storage holds no lock, and concurrent
+// writers to the same state file are serialised one layer up, at the router.
+func (f *FS) Write(path string, v encoding.BinaryMarshaler) error {
 	if v == nil {
 		return errors.New("cant't marshal from nil object")
 	}
 
 	targetFilePath := filepath.Join(f.root, path)
-	if targetFilePath == f.lockFilePath() {
-		return errors.New("can't write to the lock file")
-	}
 
 	data, err := v.MarshalBinary()
 	if err != nil {
@@ -103,120 +67,53 @@ func (f *fs) WriteSafe(path string, v encoding.BinaryMarshaler) error {
 			return fmt.Errorf("check target dir exists: %s", err)
 		}
 		if !ok {
-			err := os.MkdirAll(targetDir, os.ModePerm)
-			if err != nil {
+			if err := os.MkdirAll(targetDir, os.ModePerm); err != nil {
 				return fmt.Errorf("create target dirs: %s", err)
 			}
 		}
 	}
-	oldFilePath := targetFilePath + oldFileSuffix
 
-	targetExists, err := util.FileExists(targetFilePath)
+	// Stage the payload in a uniquely named temporary file next to the target
+	// and swap it in with a single rename. A unique temp name means a crashed
+	// write leaves no fixed-name leftover that would block later writes, and a
+	// single rename is the atomic replace POSIX guarantees.
+	tmp, err := os.CreateTemp(targetDir, filepath.Base(targetFilePath)+".tmp-*")
 	if err != nil {
-		return fmt.Errorf("check target file exists: %s", err)
+		return fmt.Errorf("create temp file: %s", err)
 	}
-	if targetExists {
-		oldFileExists, err := util.FileExists(oldFilePath)
-		if err != nil {
-			return fmt.Errorf("check old file exists: %s", err)
-		}
-		if oldFileExists {
-			return fmt.Errorf("old file exists at: %s", oldFilePath)
-		}
+	tmpPath := tmp.Name()
+	if _, err := tmp.Write(data); err != nil {
+		tmp.Close()
+		os.Remove(tmpPath)
+		return fmt.Errorf("write temp file: %s", err)
 	}
-
-	newFilePath := targetFilePath + newFileSuffix
-	newFileExists, err := util.FileExists(newFilePath)
-	if err != nil {
-		return fmt.Errorf("check new file exists: %s", err)
+	if err := tmp.Close(); err != nil {
+		os.Remove(tmpPath)
+		return fmt.Errorf("close temp file: %s", err)
 	}
-	if newFileExists {
-		return fmt.Errorf("new file exists at: %s", oldFilePath)
+	if err := os.Chmod(tmpPath, defaultPerm); err != nil {
+		os.Remove(tmpPath)
+		return fmt.Errorf("chmod temp file: %s", err)
 	}
-
-	err = os.WriteFile(newFilePath, data, defaultPerm)
-	if err != nil {
-		return fmt.Errorf("write data to the new file: %s", err)
-	}
-
-	if targetExists {
-		if err := os.Rename(targetFilePath, oldFilePath); err != nil {
-			return fmt.Errorf("rename target file to the old file: %s", err)
-		}
-	}
-
-	if err := os.Rename(newFilePath, targetFilePath); err != nil {
-		return fmt.Errorf("rename new file to the target file: %s", err)
-	}
-
-	if targetExists {
-		err := os.Remove(oldFilePath)
-		if err != nil {
-			return fmt.Errorf("remove old file: %s", err)
-		}
+	if err := os.Rename(tmpPath, targetFilePath); err != nil {
+		os.Remove(tmpPath)
+		return fmt.Errorf("replace target file: %s", err)
 	}
 	return nil
 }
 
-func (f *fs) Write(path string, v encoding.BinaryMarshaler) error {
-	if f.lock == nil {
-		return errors.New("lock must be acquired before write")
-	}
-
-	return f.WriteSafe(path, v)
-}
-
-func (f *fs) Read(path string, v encoding.BinaryUnmarshaler) error {
-	if f.lock == nil {
-		return errors.New("lock must be acquired before read")
-	}
-
-	return f.readUnsafe(path, v)
-}
-
-func (f *fs) ReadSafe(path string, v encoding.BinaryUnmarshaler) error {
-	if f.lock != nil {
-		timeout := time.NewTimer(time.Millisecond * 100)
-		checker := time.NewTicker(time.Millisecond)
-	out:
-		for {
-			select {
-			case <-checker.C:
-				if f.lock == nil {
-					checker.Stop()
-					timeout.Stop()
-					break out
-				}
-			case <-timeout.C:
-				checker.Stop()
-				return errors.New("timeout waiting for lock release")
-			}
-		}
-	}
-
-	return f.readUnsafe(path, v)
-}
-
-// readUnsafe reads the file contents without locking mechanism in mind.
-// Using readUnsafe directly may cause errors if file being written at the moment.
-func (f *fs) readUnsafe(file string, v encoding.BinaryUnmarshaler) error {
+// Read loads path into v. Reads need no lock: because Write swaps files into
+// place atomically with rename, a reader always observes a complete file even
+// when a write is in flight.
+func (f *FS) Read(path string, v encoding.BinaryUnmarshaler) error {
 	if v == nil {
 		return errors.New("can't unmarshal to a nil object")
 	}
 
-	targetFilePath := filepath.Join(f.root, file)
-	if targetFilePath == f.lockFilePath() {
-		return errors.New("can't read from the lock file")
-	}
-
-	data, err := os.ReadFile(targetFilePath)
+	data, err := os.ReadFile(filepath.Join(f.root, path))
 	if err != nil {
 		return fmt.Errorf("reading data file: %s", err)
 	}
 
 	return v.UnmarshalBinary(data)
 }
-
-func (f *fs) lockFilePath() string {
-	return filepath.Join(f.root, lockFile)
-}