feat: improve storage for replays files

Author: Nihisil

backend/game/game-architecture.md

@@ -384,6 +384,7 @@ ronin/
 ├── Makefile
 └── backend/
     ├── shared/
+    │   ├── storage.py            # ReplayStorage protocol, LocalReplayStorage (gzip file persistence with two-level shard directories), replay_file_path helper
     │   ├── dal/
     │   │   ├── __init__.py           # Public API: PlayerRepository, GameRepository, PlayedGame
     │   │   ├── models.py             # PlayedGame persistence model

backend/game/replay/external/tenhou.py

@@ -587,7 +587,7 @@ def main() -> None:
             old_file.unlink()
     OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
 
-    replay_files = sorted(REPLAYS_DIR.glob("*.txt.gz"))
+    replay_files = sorted(REPLAYS_DIR.glob("??/??/*.txt.gz"))
     if not replay_files:
         logger.info("No replay files found in %s", REPLAYS_DIR)
         return

backend/lobby/lobby-architecture.md

@@ -18,7 +18,7 @@ Portal service for room management, authentication, and game client serving.
 
 ### Public (replay access)
 - `GET /play/history/{game_id}` - Game client HTML page for replay viewing (serves same play.html template, no auth required)
-- `GET /api/replays/{game_id}` - Replay API endpoint returning gzip-compressed NDJSON replay content (`Content-Encoding: gzip`, `Cache-Control: immutable`). Returns 404 for invalid/nonexistent game IDs. Rate-limited via Traefik in production
+- `GET /api/replays/{game_id}` - Replay API endpoint returning gzip-compressed NDJSON replay content (`Content-Encoding: gzip`, `Cache-Control: immutable`). Requires game_id to be at least 4 characters; returns 404 for invalid/nonexistent game IDs. Rate-limited via Traefik in production
 
 ### Protected (session cookie or API key required)
 - `GET /` - Lobby HTML page (server-rendered, lists rooms from local room manager)
@@ -174,7 +174,7 @@ These practices are mandatory for all lobby code. Violations must be caught in c
 - **Views** (`views/`) - Jinja2 templates and view handlers split by domain:
   - `handlers.py` — Lobby, room, and matchmaking page handlers (`lobby_page`, `room_page`, `matchmaking_page`, `create_room_and_redirect`, `join_room_and_redirect`)
   - `history_handlers.py` — History page handler and game data transformation (`history_page`, `_format_duration`, `_prepare_history_for_display`)
-  - `replay_handlers.py` — Replay API handler (`replay_content`); reads gzip-compressed replay files with path traversal protection and file size limits
+  - `replay_handlers.py` — Replay API handler (`replay_content`); resolves sharded replay file paths via `shared.storage.replay_file_path`, enforces minimum game ID length, path traversal protection, and file size limits
   - `game_handlers.py` — Game client and dev page handlers (`play_page`, `styleguide_page`)
   - `assets.py` — Vite manifest utilities and Jinja2 template factory (`create_templates`, `load_vite_manifest`, `resolve_vite_asset_urls`)
   - `auth_handlers.py` — Auth handlers (login, register, logout, bot_auth, bot_create_room, bot_matchmaking_auth)
@@ -190,6 +190,7 @@ Dependencies on `shared/`:
 - `shared.validators` - String list parsing (CORS origins, allowed hosts) and custom env settings source
 - `shared.auth` - `AuthService`, `AuthSessionStore`, `PlayerRepository` for player management; `create_signed_ticket` and `sign_game_ticket` for HMAC-signed game tickets
 - `shared.db` - `Database`, `SqlitePlayerRepository` for SQLite-backed player storage, `SqliteGameRepository` for played game queries
+- `shared.storage` - `replay_file_path` for resolving sharded replay file paths, `_MIN_GAME_ID_LEN` for game ID validation
 
 ## Project Structure
 
@@ -306,7 +307,7 @@ Lobby settings (prefixed with `LOBBY_`):
 - `LOBBY_GAME_CLIENT_URL` - Game client URL for room creation redirects and join links (default: `/play`)
 - `LOBBY_WS_ALLOWED_ORIGIN` - Allowed origin for WebSocket connections (CSRF protection). Default: `http://localhost:8710`. Set to `None` to allow all origins
 - `LOBBY_GAME_ASSETS_DIR` - Directory containing built game client assets and `.vite/manifest.json` (default: `frontend/dist`)
-- `LOBBY_REPLAY_DIR` - Directory containing gzip-compressed replay files (default: `backend/data/replays`)
+- `LOBBY_REPLAY_DIR` - Root directory for gzip-compressed replay files distributed across a two-level shard structure `{id[0:2]}/{id[2:4]}/{game_id}.txt.gz` (default: `backend/data/replays`)
 - `LOBBY_VITE_DEV_URL` - Vite dev server URL for HMR in development (default: empty; set to `http://localhost:5173` when running Vite dev server)
 
 Auth settings (prefixed with `AUTH_`):

backend/lobby/tests/unit/test_replay_handlers.py

@@ -9,6 +9,7 @@
 from lobby.server.settings import LobbyServerSettings
 from lobby.views.replay_handlers import _load_replay
 from shared.auth.settings import AuthSettings
+from shared.storage import replay_file_path
 
 
 def _make_client(tmp_path):
@@ -37,9 +38,11 @@ def _make_client(tmp_path):
 
 
 def _write_gzip_replay(replay_dir, game_id, content):
-    """Write a gzip-compressed replay file."""
+    """Write a gzip-compressed replay file at the sharded path."""
+    target = replay_file_path(replay_dir, game_id)
+    target.parent.mkdir(parents=True, exist_ok=True)
     compressed = gzip.compress(content.encode("utf-8"))
-    (replay_dir / f"{game_id}.txt.gz").write_bytes(compressed)
+    target.write_bytes(compressed)
 
 
 class TestReplayContent:
@@ -107,6 +110,11 @@ def test_game_id_too_long_returns_404(self, setup):
         response = client.get(f"/api/replays/{'a' * 51}")
         assert response.status_code == 404
 
+    def test_game_id_too_short_returns_404(self, setup):
+        client, _replay_dir = setup
+        response = client.get("/api/replays/abc")
+        assert response.status_code == 404
+
     def test_game_id_at_max_length_is_accepted(self, setup):
         """A 50-char game_id should be accepted (if file exists)."""
         client, replay_dir = setup
@@ -126,33 +134,40 @@ def test_game_id_with_url_encoded_traversal_returns_404(self, setup):
     def test_oversized_file_returns_404(self, setup):
         """Files exceeding 1 MB on disk are rejected."""
         client, replay_dir = setup
+        game_id = "big-game"
+        target = replay_file_path(replay_dir, game_id)
+        target.parent.mkdir(parents=True, exist_ok=True)
         # Write raw bytes > 1 MB (not valid gzip, but size check happens first)
-        (replay_dir / "big-game.txt.gz").write_bytes(b"\x00" * (1_048_576 + 1))
+        target.write_bytes(b"\x00" * (1_048_576 + 1))
 
-        response = client.get("/api/replays/big-game")
+        response = client.get(f"/api/replays/{game_id}")
         assert response.status_code == 404
 
     def test_unreadable_file_returns_404(self, setup):
         """Files that exist but can't be read return 404."""
         client, replay_dir = setup
-        target = replay_dir / "broken.txt.gz"
-        target.mkdir()  # directory, not a file — read_bytes will fail
+        game_id = "broken_file"
+        target = replay_file_path(replay_dir, game_id)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.mkdir()  # directory, not a file — read will fail
 
-        response = client.get("/api/replays/broken")
+        response = client.get(f"/api/replays/{game_id}")
         assert response.status_code == 404
 
     def test_path_traversal_via_symlink_returns_404(self, setup, tmp_path):
         """A game_id whose resolved path escapes the replay dir is rejected."""
         _client, replay_dir = setup
+        game_id = "escape_link"
         # Create a file outside the replay dir
         outside = tmp_path / "secret.txt.gz"
         outside.write_bytes(gzip.compress(b"secret"))
-        # Create a symlink inside the replay dir pointing outside
-        link = replay_dir / "escape.txt.gz"
-        link.symlink_to(outside)
+        # Create a symlink at the sharded path pointing outside
+        target = replay_file_path(replay_dir, game_id)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.symlink_to(outside)
 
         # Call the sync helper directly — the symlink resolves outside replay_dir
-        result = _load_replay(str(replay_dir), "escape")
+        result = _load_replay(str(replay_dir), game_id)
         assert result is None
 
     def test_replay_page_route_serves_play_page(self, setup):

backend/lobby/views/replay_handlers.py

@@ -9,6 +9,8 @@
 
 from starlette.responses import Response
 
+from shared.storage import _MIN_GAME_ID_LEN, replay_file_path
+
 if TYPE_CHECKING:
     from starlette.requests import Request
 
@@ -25,11 +27,11 @@
 def _load_replay(replay_dir_str: str, game_id: str) -> bytes | None:
     """Resolve paths and read a gzip-compressed replay file.
 
-    Returns the raw gzip bytes, or None if the file is missing, too large,
+    Return the raw gzip bytes, or None if the file is missing, too large,
     or the game_id resolves outside the replay directory.
     """
     replay_dir = Path(replay_dir_str).resolve()
-    target = (replay_dir / f"{game_id}.txt.gz").resolve()
+    target = replay_file_path(replay_dir, game_id).resolve()
 
     if not target.is_relative_to(replay_dir):
         return None
@@ -50,7 +52,12 @@ async def replay_content(request: Request) -> Response:
     """GET /api/replays/{game_id} — serve a gzip-compressed replay file."""
     game_id = request.path_params["game_id"]
 
-    if not game_id or len(game_id) > _GAME_ID_MAX_LEN or not _GAME_ID_RE.match(game_id):
+    if (
+        not game_id
+        or len(game_id) < _MIN_GAME_ID_LEN
+        or len(game_id) > _GAME_ID_MAX_LEN
+        or not _GAME_ID_RE.match(game_id)
+    ):
         return _NOT_FOUND
 
     replay_dir_str: str = request.app.state.settings.replay_dir

backend/shared/storage.py

@@ -2,8 +2,12 @@
 
 Replay files are gzip-compressed NDJSON containing full game event logs.
 Replays are public and served to any user via the lobby replay API.
-Files are written with owner-only permissions (0o600) inside an
-owner-only directory (0o700) as a filesystem hygiene measure.
+Files are written with owner-only permissions (0o600) inside owner-only
+directories (0o700) as a filesystem hygiene measure.
+
+Replay files are distributed across a two-level directory structure using
+the first 4 characters of the game ID as shard prefixes:
+``{replay_dir}/{id[0:2]}/{id[2:4]}/{game_id}.txt.gz``
 """
 
 import contextlib
@@ -23,6 +27,23 @@
 # Owner-only file permissions for replay data files.
 _REPLAY_FILE_MODE = 0o600
 
+# Game IDs shorter than this cannot produce a two-level shard prefix.
+_MIN_GAME_ID_LEN = 4
+
+
+def replay_file_path(replay_dir: Path, game_id: str) -> Path:
+    """Build the sharded file path for a replay.
+
+    Use the first 4 characters of game_id as a two-level directory
+    prefix (2 chars each) to distribute files across subdirectories.
+    Require game_id to be at least 4 characters long.
+    """
+    if len(game_id) < _MIN_GAME_ID_LEN:
+        raise ValueError(f"game_id must be at least {_MIN_GAME_ID_LEN} characters, got {len(game_id)}")
+    prefix_a = game_id[:2]
+    prefix_b = game_id[2:4]
+    return replay_dir / prefix_a / prefix_b / f"{game_id}.txt.gz"
+
 
 class ReplayStorage(Protocol):
     """Protocol for persisting replay data."""
@@ -31,10 +52,11 @@ def save_replay(self, game_id: str, content: str) -> None: ...
 
 
 class LocalReplayStorage:
-    """Writes gzip-compressed replay files to the local filesystem.
+    """Write gzip-compressed replay files to the local filesystem.
 
-    Files are created with owner-only read/write (0o600) inside an
-    owner-only directory (0o700) as a filesystem hygiene measure.
+    Files are created with owner-only read/write (0o600) inside owner-only
+    directories (0o700) as a filesystem hygiene measure. Replay files are
+    distributed across a two-level shard directory structure.
     """
 
     def __init__(self, replay_dir: str) -> None:
@@ -43,21 +65,26 @@ def __init__(self, replay_dir: str) -> None:
     def save_replay(self, game_id: str, content: str) -> None:
         """Save gzip-compressed replay content under the configured directory.
 
-        Creates the directory lazily on first write with owner-only permissions
-        (0o700). Writes replay files atomically via temp-file-then-rename with
-        owner-only permissions (0o600). Rejects path traversal attempts that
-        would place the file outside the replay root.
+        Create shard directories lazily on first write with owner-only
+        permissions (0o700). Write replay files atomically via
+        temp-file-then-rename with owner-only permissions (0o600). Reject
+        path traversal attempts that would place the file outside the replay
+        root.
         """
-        target = (self._replay_dir / f"{game_id}.txt.gz").resolve()
+        target = replay_file_path(self._replay_dir, game_id).resolve()
         if not target.is_relative_to(self._replay_dir):
             raise ValueError(f"Path traversal rejected: '{game_id}' resolves outside replay directory")
 
-        self._replay_dir.mkdir(mode=_REPLAY_DIR_MODE, parents=True, exist_ok=True)
-        self._replay_dir.chmod(_REPLAY_DIR_MODE)
+        shard_dir = target.parent
+        shard_dir.mkdir(mode=_REPLAY_DIR_MODE, parents=True, exist_ok=True)
+        # Ensure owner-only permissions on all directory levels (mkdir
+        # parents=True applies mode only to the leaf; umask may weaken it).
+        for directory in (self._replay_dir, shard_dir.parent, shard_dir):
+            directory.chmod(_REPLAY_DIR_MODE)
 
         compressed = gzip.compress(content.encode("utf-8"))
 
-        fd, tmp_path = tempfile.mkstemp(dir=str(self._replay_dir), suffix=".tmp", prefix=".replay_")
+        fd, tmp_path = tempfile.mkstemp(dir=str(shard_dir), suffix=".tmp", prefix=".replay_")
         fd_owned = True
         try:
             with os.fdopen(fd, "wb") as f: