Add pre-emptive rate limiting to metadata API services

Wire the existing RateLimiter into the IGDB, ScreenScraper, MobyGames and
RetroAchievements services so requests are spaced under each provider's
documented req/s cap, instead of only reacting to HTTP 429 after the fact.

- IGDB: 4 req/s (documented hard limit)
- MobyGames: 1 req/s (free-tier burst cap)
- ScreenScraper: 1 req/s (free-tier throttle)
- RetroAchievements: 4 req/s (conservative; no published hard limit)

A slot is acquired before both the initial request and the timeout/429
retry. The reactive 2s 429 backoff is kept as a fallback. Tests neutralize
the shared limiters via an autouse fixture and assert acquire() is awaited.

https://claude.ai/code/session_01133QQuWvq8Zm25DZMP9PVr

Author: claude

backend/adapters/services/igdb.py

@@ -3,7 +3,7 @@
 import json
 from collections.abc import Sequence
 from functools import partial
-from typing import TYPE_CHECKING, TypedDict
+from typing import TYPE_CHECKING, Final, TypedDict
 
 import aiohttp
 import yarl
@@ -17,10 +17,15 @@
 from logger.logger import log
 from utils import get_version
 from utils.context import ctx_aiohttp_session
+from utils.rate_limiter import RateLimiter
 
 if TYPE_CHECKING:
     from handler.metadata.igdb_handler import TwitchAuth
 
+# IGDB caps clients at 4 requests per second (max 8 open requests).
+IGDB_MAX_REQUESTS_PER_SECOND: Final[float] = 4
+_rate_limiter = RateLimiter(IGDB_MAX_REQUESTS_PER_SECOND)
+
 
 class IGDBInvalidCredentialsException(Exception):
     """Exception raised when IGDB credentials are invalid."""
@@ -94,6 +99,7 @@ async def _request(
         )
 
         try:
+            await _rate_limiter.acquire()
             res = await aiohttp_session.post(
                 url,
                 data=content,
@@ -142,6 +148,7 @@ async def _request(
                 content,
                 request_timeout,
             )
+            await _rate_limiter.acquire()
             res = await aiohttp_session.post(
                 url,
                 data=content,

backend/adapters/services/mobygames.py

@@ -2,7 +2,7 @@
 import http
 import json
 from collections.abc import Collection
-from typing import Literal, overload
+from typing import Final, Literal, overload
 
 import aiohttp
 import yarl
@@ -14,6 +14,11 @@
 from logger.logger import log
 from utils import get_version
 from utils.context import ctx_aiohttp_session
+from utils.rate_limiter import RateLimiter
+
+# MobyGames caps the free/non-commercial tier at 1 request per second.
+MOBYGAMES_MAX_REQUESTS_PER_SECOND: Final[float] = 1
+_rate_limiter = RateLimiter(MOBYGAMES_MAX_REQUESTS_PER_SECOND)
 
 
 async def auth_middleware(
@@ -45,6 +50,7 @@ async def _request(self, url: str, request_timeout: int = 120) -> dict:
         )
 
         try:
+            await _rate_limiter.acquire()
             res = await aiohttp_session.get(
                 url,
                 headers={"user-agent": f"RomM/{get_version()}"},
@@ -85,6 +91,7 @@ async def _request(self, url: str, request_timeout: int = 120) -> dict:
                 url,
                 request_timeout,
             )
+            await _rate_limiter.acquire()
             res = await aiohttp_session.get(
                 url,
                 headers={"user-agent": f"RomM/{get_version()}"},

backend/adapters/services/retroachievements.py

@@ -2,7 +2,7 @@
 import http
 import json
 from collections.abc import AsyncIterator
-from typing import cast
+from typing import Final, cast
 
 import aiohttp
 import yarl
@@ -20,6 +20,12 @@
 from logger.logger import log
 from utils import get_version
 from utils.context import ctx_aiohttp_session
+from utils.rate_limiter import RateLimiter
+
+# RetroAchievements does not publish a fixed limit; stay conservative to keep
+# within the "fair burst" allowance the API documents.
+RA_MAX_REQUESTS_PER_SECOND: Final[float] = 4
+_rate_limiter = RateLimiter(RA_MAX_REQUESTS_PER_SECOND)
 
 
 async def auth_middleware(
@@ -53,6 +59,7 @@ async def _request(self, url: str, request_timeout: int = 120) -> dict:
             request_timeout,
         )
         try:
+            await _rate_limiter.acquire()
             res = await aiohttp_session.get(
                 url,
                 headers={"user-agent": f"RomM/{get_version()}"},
@@ -90,6 +97,7 @@ async def _request(self, url: str, request_timeout: int = 120) -> dict:
                 url,
                 request_timeout,
             )
+            await _rate_limiter.acquire()
             res = await aiohttp_session.get(
                 url,
                 headers={"user-agent": f"RomM/{get_version()}"},

backend/adapters/services/screenscraper.py

@@ -14,11 +14,16 @@
 from logger.logger import log
 from utils import get_version
 from utils.context import ctx_aiohttp_session
+from utils.rate_limiter import RateLimiter
 
 SS_DEV_ID: Final = base64.b64decode("enVyZGkxNQ==").decode()
 SS_DEV_PASSWORD: Final = base64.b64decode("eFRKd29PRmpPUUc=").decode()
 LOGIN_ERROR_CHECK: Final = "Erreur de login"
 
+# ScreenScraper throttles the free tier to roughly one request per second.
+SS_MAX_REQUESTS_PER_SECOND: Final[float] = 1
+_rate_limiter = RateLimiter(SS_MAX_REQUESTS_PER_SECOND)
+
 
 async def auth_middleware(
     req: aiohttp.ClientRequest, handler: aiohttp.ClientHandlerType
@@ -57,6 +62,7 @@ async def _request(self, url: str, request_timeout: int = 120) -> dict:
             request_timeout,
         )
         try:
+            await _rate_limiter.acquire()
             res = await aiohttp_session.get(
                 url,
                 headers={"user-agent": f"RomM/{get_version()}"},
@@ -125,6 +131,7 @@ async def _request(self, url: str, request_timeout: int = 120) -> dict:
                 url,
                 request_timeout,
             )
+            await _rate_limiter.acquire()
             res = await aiohttp_session.get(
                 url,
                 headers={"user-agent": f"RomM/{get_version()}"},

backend/tests/adapters/services/conftest.py

@@ -1,9 +1,29 @@
 from contextvars import ContextVar
+from unittest.mock import AsyncMock
 
 import aiohttp
+import pytest
 import pytest_asyncio
 
 
+@pytest.fixture(autouse=True)
+def _disable_metadata_rate_limiters(monkeypatch):
+    """Neutralize the pre-emptive rate limiters during tests.
+
+    Each metadata service spaces its requests via a module-level ``RateLimiter``
+    whose ``acquire`` sleeps to stay under the provider's req/s cap. Letting it
+    run would add real delays and inject extra ``asyncio.sleep`` calls that
+    interfere with retry assertions, so we replace ``acquire`` with a no-op.
+    """
+    for module in (
+        "adapters.services.igdb",
+        "adapters.services.mobygames",
+        "adapters.services.retroachievements",
+        "adapters.services.screenscraper",
+    ):
+        monkeypatch.setattr(f"{module}._rate_limiter.acquire", AsyncMock())
+
+
 @pytest_asyncio.fixture
 async def mock_ctx_aiohttp_session():
     """Create a real aiohttp session for integration tests."""

backend/tests/adapters/services/test_mobygames.py

@@ -104,6 +104,28 @@ async def test_request_success(self, service):
         mock_response.raise_for_status.assert_called_once()
         mock_response.json.assert_called_once()
 
+    @pytest.mark.asyncio
+    async def test_request_acquires_rate_limiter(self, service, monkeypatch):
+        """Test that the request reserves a rate-limiter slot before sending."""
+        acquire_mock = AsyncMock()
+        monkeypatch.setattr(
+            "adapters.services.mobygames._rate_limiter.acquire", acquire_mock
+        )
+
+        mock_session = AsyncMock()
+        mock_response = MagicMock()
+        mock_response.json = AsyncMock(return_value={"games": []})
+        mock_response.raise_for_status.return_value = None
+        mock_session.get.return_value = mock_response
+
+        mock_context = MagicMock()
+        mock_context.get.return_value = mock_session
+
+        with patch("adapters.services.mobygames.ctx_aiohttp_session", mock_context):
+            await service._request("https://api.mobygames.com/v1/games")
+
+        acquire_mock.assert_awaited_once()
+
     @pytest.mark.asyncio
     async def test_request_connection_error(self, service):
         """Test request with connection error."""

backend/tests/adapters/services/test_retroachivements.py

@@ -77,6 +77,30 @@ async def test_request_connection_error(self, service):
         assert exc_info.value.status_code == status.HTTP_503_SERVICE_UNAVAILABLE
         assert "Can't connect to RetroAchievements" in exc_info.value.detail
 
+    @pytest.mark.asyncio
+    async def test_request_acquires_rate_limiter(self, service, monkeypatch):
+        """Test that the request reserves a rate-limiter slot before sending."""
+        acquire_mock = AsyncMock()
+        monkeypatch.setattr(
+            "adapters.services.retroachievements._rate_limiter.acquire", acquire_mock
+        )
+
+        mock_session = AsyncMock()
+        mock_response = MagicMock()
+        mock_response.json = AsyncMock(return_value={})
+        mock_response.raise_for_status.return_value = None
+        mock_session.get.return_value = mock_response
+
+        mock_context = MagicMock()
+        mock_context.get.return_value = mock_session
+
+        with patch(
+            "adapters.services.retroachievements.ctx_aiohttp_session", mock_context
+        ):
+            await service._request("https://retroachievements.org/API")
+
+        acquire_mock.assert_awaited_once()
+
 
 class TestRetroAchievementsServiceIntegration:
     @pytest.fixture

backend/tests/adapters/services/test_screenscraper.py

@@ -148,6 +148,29 @@ async def test_request_success(self, service):
         mock_response.raise_for_status.assert_called_once()
         mock_response.json.assert_called_once()
 
+    @pytest.mark.asyncio
+    async def test_request_acquires_rate_limiter(self, service, monkeypatch):
+        """Test that the request reserves a rate-limiter slot before sending."""
+        acquire_mock = AsyncMock()
+        monkeypatch.setattr(
+            "adapters.services.screenscraper._rate_limiter.acquire", acquire_mock
+        )
+
+        mock_session = AsyncMock()
+        mock_response = MagicMock()
+        mock_response.json = AsyncMock(return_value={"response": {}})
+        mock_response.text = AsyncMock(return_value="{}")
+        mock_response.raise_for_status.return_value = None
+        mock_session.get.return_value = mock_response
+
+        mock_context = MagicMock()
+        mock_context.get.return_value = mock_session
+
+        with patch("adapters.services.screenscraper.ctx_aiohttp_session", mock_context):
+            await service._request("https://api.screenscraper.fr/api2/jeuInfos.php")
+
+        acquire_mock.assert_awaited_once()
+
     @pytest.mark.asyncio
     async def test_request_login_error(self, service):
         """Test request with login error in response text."""