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)
-}

game/internal/repo/fs/fs_test.go

@@ -1,9 +1,11 @@
 package fs_test
 
 import (
+	"bytes"
 	"os"
 	"path/filepath"
 	"slices"
+	"sync"
 	"testing"
 
 	"galaxy/game/internal/repo/fs"
@@ -12,10 +14,6 @@ import (
 	"github.com/stretchr/testify/assert"
 )
 
-const (
-	lockFile = ".lock"
-)
-
 type sampleData struct {
 	data []byte
 }
@@ -36,20 +34,6 @@ func TestNewFileStorageSuccess(t *testing.T) {
 	assert.NoError(t, err)
 }
 
-func TestLock(t *testing.T) {
-	root, cleanup := util.CreateWorkDir(t)
-	defer cleanup()
-	fs, err := fs.NewFileStorage(root)
-	assert.NoError(t, err, "create file storage")
-	unlock, err := fs.Lock()
-	assert.NoError(t, err, "acquire lock")
-	lockPath := filepath.Join(root, lockFile)
-	assert.FileExists(t, lockPath, "lock file should be created")
-	err = unlock()
-	assert.NoError(t, err, "unlocking existing lock")
-	assert.NoFileExists(t, lockPath, "lock file must be removed")
-}
-
 func TestExist(t *testing.T) {
 	root, cleanup := util.CreateWorkDir(t)
 	defer cleanup()
@@ -78,9 +62,6 @@ func TestWrite(t *testing.T) {
 	fs, err := fs.NewFileStorage(root)
 	assert.NoError(t, err, "create file storage: %s", err)
 
-	unlock, err := fs.Lock()
-	assert.NoError(t, err, "acquire lock: %s", err)
-
 	dirName := "some-dir"
 	if err := os.Mkdir(filepath.Join(root, dirName), os.ModePerm); err != nil {
 		t.Fatal(err)
@@ -93,9 +74,8 @@ func TestWrite(t *testing.T) {
 		{path: "file-1.ext"},
 		{path: "/dir/file-2.ext"},
 		{path: "dir/subdir/file-3.ext"},
-		{path: lockFile, err: "write to the lock file"},
-		{path: dirName, err: "wrong type"},
-		{path: "/" + dirName, err: "wrong type"},
+		{path: dirName, err: "file exists"},
+		{path: "/" + dirName, err: "file exists"},
 	} {
 		t.Run(tc.path, func(t *testing.T) {
 			sd := &sampleData{[]byte{0, 1, 2, 3}}
@@ -103,13 +83,26 @@ func TestWrite(t *testing.T) {
 			if tc.err == "" {
 				assert.NoError(t, err)
 				assert.FileExists(t, filepath.Join(root, tc.path), "the written file should exist")
-			} else if tc.err != "" {
+			} else {
 				assert.ErrorContains(t, err, tc.err)
 			}
 		})
 	}
+}
 
-	assert.NoError(t, unlock(), "unlocking existing lock")
+func TestWriteLeavesNoTempLeftovers(t *testing.T) {
+	root, cleanup := util.CreateWorkDir(t)
+	defer cleanup()
+
+	s, err := fs.NewFileStorage(root)
+	assert.NoError(t, err)
+
+	assert.NoError(t, s.Write("state.bin", &sampleData{[]byte{1, 2, 3}}))
+
+	entries, err := os.ReadDir(root)
+	assert.NoError(t, err)
+	assert.Len(t, entries, 1, "a successful write must leave only the target file, no temporaries")
+	assert.Equal(t, "state.bin", entries[0].Name())
 }
 
 func TestRead(t *testing.T) {
@@ -121,11 +114,6 @@ func TestRead(t *testing.T) {
 	fs, err := fs.NewFileStorage(root)
 	assert.NoError(t, err, "create file storage: %s", err)
 
-	assert.EqualError(t, fs.Read("some.file", sd), "lock must be acquired before read")
-
-	unlock, err := fs.Lock()
-	assert.NoError(t, err, "acquire lock: %s", err)
-
 	dirName := "some-dir"
 	if err := os.Mkdir(filepath.Join(root, dirName), os.ModePerm); err != nil {
 		t.Fatal(err)
@@ -142,33 +130,82 @@ func TestRead(t *testing.T) {
 	}{
 		{path: fileName},
 		{path: "/" + fileName},
-		{path: lockFile, err: "read from the lock file"},
 		{path: "dir/subdir/file-3.ext", err: "no such file"},
-		{path: lockFile, err: "read from the lock file"},
 		{path: dirName, err: "is a directory"},
 	} {
 		t.Run(tc.path, func(t *testing.T) {
 			err = fs.Read(tc.path, sd)
 			if tc.err == "" {
 				assert.NoError(t, err)
-				assert.FileExists(t, filepath.Join(root, tc.path), "the written file should exist")
-			} else if tc.err != "" {
+			} else {
 				assert.ErrorContains(t, err, tc.err)
 			}
 		})
 	}
-	assert.NoError(t, unlock(), "unlocking existing lock")
 }
 
-func TestWriteErrorWithoutLock(t *testing.T) {
+// TestReadAtomicUnderConcurrentWrites is the regression that guards the
+// lock-free contract: with Write swapping files in via a single rename, a
+// concurrent Read must always observe one previously written payload in full —
+// never a torn mix and never a missing file. The two payloads differ in length
+// so any partial read is detectable.
+func TestReadAtomicUnderConcurrentWrites(t *testing.T) {
 	root, cleanup := util.CreateWorkDir(t)
 	defer cleanup()
-	fs, err := fs.NewFileStorage(root)
-	assert.NoError(t, err, "create file storage")
-	sd := &sampleData{[]byte{0, 1, 2, 3}}
-	err = fs.Write("some/path", sd)
-	assert.Error(t, err, "should return error when no lock acquired")
-	assert.EqualError(t, err, "lock must be acquired before write")
+
+	s, err := fs.NewFileStorage(root)
+	assert.NoError(t, err)
+
+	const path = "state.bin"
+	payloads := [][]byte{
+		bytes.Repeat([]byte{0xAA}, 4096),
+		bytes.Repeat([]byte{0xBB}, 8192),
+	}
+	assert.NoError(t, s.Write(path, &sampleData{slices.Clone(payloads[0])}))
+
+	stop := make(chan struct{})
+	var writers sync.WaitGroup
+	for w := range 4 {
+		writers.Go(func() {
+			for {
+				select {
+				case <-stop:
+					return
+				default:
+					_ = s.Write(path, &sampleData{slices.Clone(payloads[w%len(payloads)])})
+				}
+			}
+		})
+	}
+
+	var readers sync.WaitGroup
+	for range 8 {
+		readers.Go(func() {
+			for range 1000 {
+				sd := new(sampleData)
+				if err := s.Read(path, sd); err != nil {
+					t.Errorf("read during concurrent write failed: %v", err)
+					return
+				}
+				if !knownPayload(sd.data, payloads) {
+					t.Errorf("read observed a torn payload (len=%d)", len(sd.data))
+					return
+				}
+			}
+		})
+	}
+	readers.Wait()
+	close(stop)
+	writers.Wait()
+}
+
+func knownPayload(got []byte, want [][]byte) bool {
+	for _, w := range want {
+		if bytes.Equal(got, w) {
+			return true
+		}
+	}
+	return false
 }
 
 func TestNewFileStorageErrorNotExists(t *testing.T) {

game/internal/repo/game.go

@@ -19,6 +19,7 @@ import (
 	"galaxy/model/report"
 
 	"galaxy/game/internal/model/game"
+	"galaxy/game/internal/repo/fs"
 
 	"github.com/google/uuid"
 )
@@ -42,11 +43,11 @@ func (o *storedOrder) UnmarshalBinary(data []byte) error {
 	return json.Unmarshal(data, o)
 }
 
-func (r *repo) SaveNewTurn(t uint, g *game.Game) error {
+func (r *Repo) SaveNewTurn(t uint, g *game.Game) error {
 	return saveNewTurn(r.s, t, g)
 }
 
-func saveNewTurn(s Storage, t uint, g *game.Game) error {
+func saveNewTurn(s *fs.FS, t uint, g *game.Game) error {
 	path := fmt.Sprintf("%s/state.json", TurnDir(t))
 	exist, err := s.Exists(path)
 	if err != nil {
@@ -61,27 +62,23 @@ func saveNewTurn(s Storage, t uint, g *game.Game) error {
 	return saveLastState(s, g)
 }
 
-func (r *repo) SaveLastState(g *game.Game) error {
+func (r *Repo) SaveLastState(g *game.Game) error {
 	return saveLastState(r.s, g)
 }
 
-func saveLastState(s Storage, g *game.Game) error {
+func saveLastState(s *fs.FS, g *game.Game) error {
 	if err := s.Write(statePath, g); err != nil {
 		return NewStorageError(err)
 	}
 	return nil
 }
 
-func (r *repo) LoadState() (*game.Game, error) {
-	return loadState(r.s, true)
+func (r *Repo) LoadState() (*game.Game, error) {
+	return loadState(r.s)
 }
 
-func (r *repo) LoadStateSafe() (*game.Game, error) {
-	return loadState(r.s, false)
-}
-
-func loadState(s Storage, locked bool) (*game.Game, error) {
-	var result *game.Game = new(game.Game)
+func loadState(s *fs.FS) (*game.Game, error) {
+	result := new(game.Game)
 	path := statePath
 	exist, err := s.Exists(path)
 	if err != nil {
@@ -90,19 +87,13 @@ func loadState(s Storage, locked bool) (*game.Game, error) {
 	if !exist {
 		return nil, NewGameNotInitializedError()
 	}
-	if locked {
-		if err := s.Read(path, result); err != nil {
-			return nil, NewStorageError(err)
-		}
-	} else {
-		if err := s.ReadSafe(path, result); err != nil {
-			return nil, NewStorageError(err)
-		}
+	if err := s.Read(path, result); err != nil {
+		return nil, NewStorageError(err)
 	}
 	return result, nil
 }
 
-func loadMeta(s Storage) (*game.GameMeta, error) {
+func loadMeta(s *fs.FS) (*game.GameMeta, error) {
 	var result *game.GameMeta = new(game.GameMeta)
 	path := metaPath
 	exist, err := s.Exists(path)
@@ -112,13 +103,13 @@ func loadMeta(s Storage) (*game.GameMeta, error) {
 	if !exist {
 		return result, nil
 	}
-	if err := s.ReadSafe(path, result); err != nil {
+	if err := s.Read(path, result); err != nil {
 		return nil, NewStorageError(err)
 	}
 	return result, nil
 }
 
-func loadTurnMeta(s Storage, turn uint) (*game.GameMeta, error) {
+func loadTurnMeta(s *fs.FS, turn uint) (*game.GameMeta, error) {
 	var result *game.GameMeta = new(game.GameMeta)
 	path := fmt.Sprintf("%s/%s", TurnDir(turn), metaPath)
 	exist, err := s.Exists(path)
@@ -128,13 +119,13 @@ func loadTurnMeta(s Storage, turn uint) (*game.GameMeta, error) {
 	if !exist {
 		return result, nil
 	}
-	if err := s.ReadSafe(path, result); err != nil {
+	if err := s.Read(path, result); err != nil {
 		return nil, NewStorageError(err)
 	}
 	return result, nil
 }
 
-func saveMeta(s Storage, turn uint, gm *game.GameMeta) error {
+func saveMeta(s *fs.FS, turn uint, gm *game.GameMeta) error {
 	// save turn's meta
 	path := fmt.Sprintf("%s/%s", TurnDir(turn), metaPath)
 	if err := s.Write(path, gm); err != nil {
@@ -148,7 +139,7 @@ func saveMeta(s Storage, turn uint, gm *game.GameMeta) error {
 	return nil
 }
 
-func (r *repo) LoadBattle(turn uint, id uuid.UUID) (*report.BattleReport, bool, error) {
+func (r *Repo) LoadBattle(turn uint, id uuid.UUID) (*report.BattleReport, bool, error) {
 	meta, err := loadTurnMeta(r.s, turn)
 	if err != nil {
 		return nil, false, err
@@ -164,7 +155,7 @@ func (r *repo) LoadBattle(turn uint, id uuid.UUID) (*report.BattleReport, bool,
 	return result, true, nil
 }
 
-func (r *repo) SaveBattle(turn uint, b *report.BattleReport, m *game.BattleMeta) error {
+func (r *Repo) SaveBattle(turn uint, b *report.BattleReport, m *game.BattleMeta) error {
 	meta, err := loadMeta(r.s)
 	if err != nil {
 		return err
@@ -177,7 +168,7 @@ func (r *repo) SaveBattle(turn uint, b *report.BattleReport, m *game.BattleMeta)
 	return saveMeta(r.s, turn, meta)
 }
 
-func saveBattle(s Storage, turn uint, b *report.BattleReport) error {
+func saveBattle(s *fs.FS, turn uint, b *report.BattleReport) error {
 	path := fmt.Sprintf("%s/battle/%s.json", TurnDir(turn), b.ID.String())
 	exist, err := s.Exists(path)
 	if err != nil {
@@ -192,7 +183,7 @@ func saveBattle(s Storage, turn uint, b *report.BattleReport) error {
 	return nil
 }
 
-func loadBattle(s Storage, turn uint, id uuid.UUID) (*report.BattleReport, error) {
+func loadBattle(s *fs.FS, turn uint, id uuid.UUID) (*report.BattleReport, error) {
 	path := fmt.Sprintf("%s/battle/%s.json", TurnDir(turn), id.String())
 	exist, err := s.Exists(path)
 	if err != nil {
@@ -202,13 +193,13 @@ func loadBattle(s Storage, turn uint, id uuid.UUID) (*report.BattleReport, error
 		return nil, NewStateError(fmt.Sprintf("battle %v for turn %d never was saved", id, turn))
 	}
 	result := new(report.BattleReport)
-	if err := s.ReadSafe(path, result); err != nil {
+	if err := s.Read(path, result); err != nil {
 		return nil, NewStorageError(err)
 	}
 	return result, nil
 }
 
-func (r *repo) SaveBombings(turn uint, b []*game.Bombing) error {
+func (r *Repo) SaveBombings(turn uint, b []*game.Bombing) error {
 	meta, err := loadMeta(r.s)
 	if err != nil {
 		return err
@@ -219,11 +210,11 @@ func (r *repo) SaveBombings(turn uint, b []*game.Bombing) error {
 	return saveMeta(r.s, turn, meta)
 }
 
-func (r *repo) SaveReport(turn uint, rep *report.Report) error {
+func (r *Repo) SaveReport(turn uint, rep *report.Report) error {
 	return saveReport(r.s, turn, rep)
 }
 
-func saveReport(s Storage, t uint, v *report.Report) error {
+func saveReport(s *fs.FS, t uint, v *report.Report) error {
 	path := ReportDir(t, v.RaceID)
 	if err := s.Write(path, v); err != nil {
 		return NewStorageError(err)
@@ -231,11 +222,11 @@ func saveReport(s Storage, t uint, v *report.Report) error {
 	return nil
 }
 
-func (r *repo) LoadReport(turn uint, id uuid.UUID) (*report.Report, error) {
+func (r *Repo) LoadReport(turn uint, id uuid.UUID) (*report.Report, error) {
 	return loadReport(r.s, turn, id)
 }
 
-func loadReport(s Storage, turn uint, id uuid.UUID) (*report.Report, error) {
+func loadReport(s *fs.FS, turn uint, id uuid.UUID) (*report.Report, error) {
 	path := ReportDir(turn, id)
 	result := new(report.Report)
 	exist, err := s.Exists(path)
@@ -245,29 +236,29 @@ func loadReport(s Storage, turn uint, id uuid.UUID) (*report.Report, error) {
 	if !exist {
 		return nil, NewReportNotFoundError()
 	}
-	if err := s.ReadSafe(path, result); err != nil {
+	if err := s.Read(path, result); err != nil {
 		return nil, NewStorageError(err)
 	}
 	return result, nil
 }
 
-func (r *repo) SaveOrder(t uint, id uuid.UUID, o *order.UserGamesOrder) error {
+func (r *Repo) SaveOrder(t uint, id uuid.UUID, o *order.UserGamesOrder) error {
 	return saveOrder(r.s, t, id, o)
 }
 
-func saveOrder(s Storage, t uint, id uuid.UUID, o *order.UserGamesOrder) error {
+func saveOrder(s *fs.FS, t uint, id uuid.UUID, o *order.UserGamesOrder) error {
 	path := OrderDir(t, id)
-	if err := s.WriteSafe(path, o); err != nil {
+	if err := s.Write(path, o); err != nil {
 		return NewStorageError(err)
 	}
 	return nil
 }
 
-func (r *repo) LoadOrder(t uint, id uuid.UUID) (*order.UserGamesOrder, bool, error) {
+func (r *Repo) LoadOrder(t uint, id uuid.UUID) (*order.UserGamesOrder, bool, error) {
 	return loadOrder(r.s, t, id)
 }
 
-func loadOrder(s Storage, t uint, id uuid.UUID) (*order.UserGamesOrder, bool, error) {
+func loadOrder(s *fs.FS, t uint, id uuid.UUID) (*order.UserGamesOrder, bool, error) {
 	path := OrderDir(t, id)
 
 	exist, err := s.Exists(path)
@@ -279,7 +270,7 @@ func loadOrder(s Storage, t uint, id uuid.UUID) (*order.UserGamesOrder, bool, er
 	}
 
 	stored := new(storedOrder)
-	if err := s.ReadSafe(path, stored); err != nil {
+	if err := s.Read(path, stored); err != nil {
 		return nil, false, NewStorageError(err)
 	}
 	// An empty stored batch is a valid state — the player either

game/internal/repo/repo.go

@@ -1,9 +1,6 @@
 package repo
 
 import (
-	"encoding"
-	"errors"
-
 	e "galaxy/error"
 
 	"galaxy/game/internal/repo/fs"
@@ -25,66 +22,23 @@ func NewStateError(msg string) error {
 	return e.NewGameStateError(msg)
 }
 
-type Storage interface {
-	Lock() (func() error, error)
-	Exists(string) (bool, error)
-	Write(string, encoding.BinaryMarshaler) error
-	WriteSafe(string, encoding.BinaryMarshaler) error
-	Read(string, encoding.BinaryUnmarshaler) error
-	ReadSafe(string, encoding.BinaryUnmarshaler) error
+// Repo persists game state through a file-backed FS. Reads and writes are
+// atomic and lock-free: Write swaps a fully written file into place with
+// rename, so Read never observes a partial file. Serialising concurrent
+// writers to the same state file is the caller's concern (the engine does it
+// at the router, see LimitMiddleware).
+type Repo struct {
+	s *fs.FS
 }
 
-type repo struct {
-	s       Storage
-	release func() error
+func NewRepo(s *fs.FS) (*Repo, error) {
+	return &Repo{s: s}, nil
 }
 
-func NewRepo(s Storage) (*repo, error) {
-	r := &repo{
-		s: s,
-	}
-	return r, nil
-}
-
-func NewFileRepo(path string) (*repo, error) {
+func NewFileRepo(path string) (*Repo, error) {
 	s, err := fs.NewFileStorage(path)
 	if err != nil {
 		return nil, err
 	}
 	return NewRepo(s)
 }
-
-func (r *repo) Lock() (err error) {
-	if r.s == nil {
-		return errors.New("storage is closed")
-	}
-	if r.release != nil {
-		return errors.New("storage already locked")
-	}
-	r.release, err = r.s.Lock()
-	if err != nil {
-		r.close()
-		return
-	}
-	return nil
-}
-
-func (r *repo) Release() (err error) {
-	if r.s == nil {
-		return errors.New("storage is closed")
-	}
-	if r.release == nil {
-		return errors.New("storage was never locked")
-	}
-	err = r.release()
-	if err != nil {
-		return
-	}
-	r.close()
-	return nil
-}
-
-func (r *repo) close() {
-	r.release = nil
-	r.s = nil
-}

game/internal/repo/repo_export_test.go

@@ -3,13 +3,15 @@ package repo
 import (
 	"galaxy/model/order"
 
+	"galaxy/game/internal/repo/fs"
+
 	"github.com/google/uuid"
 )
 
-func LoadOrder_T(s Storage, t uint, id uuid.UUID) (*order.UserGamesOrder, bool, error) {
+func LoadOrder_T(s *fs.FS, t uint, id uuid.UUID) (*order.UserGamesOrder, bool, error) {
 	return loadOrder(s, t, id)
 }
 
-func SaveOrder_T(s Storage, t uint, id uuid.UUID, o *order.UserGamesOrder) error {
+func SaveOrder_T(s *fs.FS, t uint, id uuid.UUID, o *order.UserGamesOrder) error {
 	return saveOrder(s, t, id, o)
 }

game/internal/repo/repo_test.go

@@ -92,7 +92,7 @@ func TestSaveOrder(t *testing.T) {
 	LoadOrderTest(t, s, root, turn, id, o)
 }
 
-func LoadOrderTest(t *testing.T, s repo.Storage, root string, turn uint, id uuid.UUID, expected *order.UserGamesOrder) {
+func LoadOrderTest(t *testing.T, s *fs.FS, root string, turn uint, id uuid.UUID, expected *order.UserGamesOrder) {
 	o, ok, err := repo.LoadOrder_T(s, turn, id)
 	assert.NoError(t, err)
 	assert.True(t, ok)