⚡️(backend) refactor lobby storage to bound key lookups per room

The previous lobby lookup keyed off a scan over the whole cache, so
its cost was O(db_size) rather than O(room_size). Combined with the
recent switch to cursor-based `SCAN` at an inappropriate page size,
this caused a lot of Redis round-trips and noticeably slowed down
the backend pods under load.

Refactor the lobby storage to keep a per-room set of all its lobby
keys. Lookups now iterate that set instead of scanning the whole
database:

* Membership in the set acts as a memory of who is supposedly in
  the lobby for a given room.
* Individual keys are then read to check who is actually still
  waiting or accepted.

Complexity is now bounded by room size, not database size, which
should restore the backend performance to its previous levels while
keeping the lobby behavior unchanged.

CHANGELOG.md

@@ -28,6 +28,7 @@ and this project adheres to
 - 🐛(frontend) keep feedback buttons on one line for fr/es/en
 - ⚡️(frontend) increase lobby polling interval on both sides
 - ⚡️(frontend) add trailing slash on the /me endpoint call
+- ⚡️(backend) refactor lobby storage to bound key lookups per room
 
 ## [1.30.0] - 2026-09-01
 

src/backend/core/services/lobby.py

@@ -4,7 +4,7 @@ import logging
 import uuid
 from dataclasses import dataclass
 from enum import Enum
-from typing import Dict, List, Optional, Tuple
+from typing import Dict, FrozenSet, Optional, Sequence, Tuple
 from uuid import UUID
 
 from django.conf import settings
@@ -86,6 +86,47 @@ class LobbyService:
         """Generate cache key for participant(s) data."""
         return f"{settings.LOBBY_KEY_PREFIX}_{room_id!s}_{participant_id}"
 
+    @staticmethod
+    def _get_index_key(room_id: UUID) -> str:
+        """Raw Redis key of the per-room participant index (a native SET)."""
+        return cache.client.make_key(f"{settings.LOBBY_KEY_PREFIX}-index_{room_id!s}")
+
+    @staticmethod
+    def _redis(write: bool = True):
+        """Raw redis-py client.
+
+        SADD/SREM/SMEMBERS are not exposed by the Django cache API; this is
+        the documented django-redis escape hatch.
+        """
+        return cache.client.get_client(write=write)
+
+    def _index_add(self, room_id: UUID, participant_id: str) -> None:
+        """Record a participant id in the room index."""
+        index_key = self._get_index_key(room_id)
+        pipe = self._redis().pipeline(transaction=False)
+        pipe.sadd(index_key, participant_id)
+        pipe.expire(index_key, settings.LOBBY_ACCEPTED_TIMEOUT)
+        pipe.execute()
+
+    def _index_members(self, room_id: UUID) -> FrozenSet[str]:
+        """All participant ids currently indexed for the room."""
+        members = self._redis(write=False).smembers(self._get_index_key(room_id))
+        return frozenset(
+            member.decode() if isinstance(member, bytes) else member
+            for member in members
+        )
+
+    def _index_touch(self, room_id: UUID) -> None:
+        """Re-arm the room index backstop TTL."""
+        self._redis().expire(
+            self._get_index_key(room_id), settings.LOBBY_ACCEPTED_TIMEOUT
+        )
+
+    def _index_remove(self, room_id: UUID, *participant_ids: str) -> None:
+        """Drop participant ids from the room index."""
+        if participant_ids:
+            self._redis().srem(self._get_index_key(room_id), *participant_ids)
+
     @staticmethod
     def _get_or_create_participant_id(request) -> str:
         """Extract unique participant identifier from the request."""
@@ -209,15 +250,12 @@ class LobbyService:
         cache.touch(
             self._get_cache_key(room_id, participant_id), settings.LOBBY_WAITING_TIMEOUT
         )
+        self._index_touch(room_id)
 
     def enter(
         self, room_id: UUID, participant_id: str, username: str
     ) -> LobbyParticipant:
-        """Add participant to waiting lobby.
-
-        Create a new participant entry in waiting status and notify room
-        participants of the new entry request.
-        """
+        """Add participant to waiting lobby."""
 
         color = utils.generate_color(participant_id)
 
@@ -245,6 +283,7 @@ class LobbyService:
             participant.to_dict(),
             timeout=settings.LOBBY_WAITING_TIMEOUT,
         )
+        self._index_add(room_id, participant_id)
 
         return participant
 
@@ -266,28 +305,40 @@ class LobbyService:
             cache.delete(cache_key)
             return None
 
-    def list_waiting_participants(self, room_id: UUID) -> List[dict]:
+    def list_waiting_participants(self, room_id: UUID) -> Sequence[dict]:
         """List all waiting participants for a room."""
 
-        pattern = self._get_cache_key(room_id, "*")
-        keys = list(cache.iter_keys(pattern, itersize=utils.CACHE_SCAN_ITERSIZE))
+        member_ids = self._index_members(room_id)
 
-        if not keys:
-            return []
+        if not member_ids:
+            return ()
 
-        data = cache.get_many(keys)
+        keys_by_id = {
+            participant_id: self._get_cache_key(room_id, participant_id)
+            for participant_id in member_ids
+        }
+        data = cache.get_many(list(keys_by_id.values()))
 
+        dead_ids = []
         waiting_participants = []
-        for cache_key, raw_participant in data.items():
+
+        for participant_id, cache_key in keys_by_id.items():
+            raw_participant = data.get(cache_key)
+            if raw_participant is None:
+                dead_ids.append(participant_id)
+                continue
             try:
                 participant = LobbyParticipant.from_dict(raw_participant)
             except LobbyParticipantParsingError:
                 cache.delete(cache_key)
+                dead_ids.append(participant_id)
                 continue
             if participant.status == LobbyParticipantStatus.WAITING:
                 waiting_participants.append(participant.to_dict())
 
-        return waiting_participants
+        self._index_remove(room_id, *dead_ids)
+
+        return tuple(waiting_participants)
 
     def handle_participant_entry(
         self,
@@ -341,16 +392,24 @@ class LobbyService:
 
         participant.status = status
         cache.set(cache_key, participant.to_dict(), timeout=timeout)
+        self._index_touch(room_id)
 
     def clear_room_cache(self, room_id: UUID) -> None:
         """Clear all participant entries from the cache for a specific room."""
 
-        cache.delete_pattern(
-            self._get_cache_key(room_id, "*"), itersize=utils.CACHE_SCAN_ITERSIZE
-        )
+        member_ids = self._index_members(room_id)
+        if member_ids:
+            cache.delete_many(
+                [
+                    self._get_cache_key(room_id, participant_id)
+                    for participant_id in member_ids
+                ]
+            )
+        self._redis().delete(self._get_index_key(room_id))
 
     def clear_participant_cache(self, room_id: UUID, participant_id: str) -> None:
         """Clear a given participant entry from the cache for a specific room."""
 
         cache_key = self._get_cache_key(room_id, participant_id)
         cache.delete(cache_key)
+        self._index_remove(room_id, participant_id)

src/backend/core/tests/rooms/test_api_rooms_lobby.py

@@ -589,6 +589,9 @@ def test_list_waiting_participants_success(settings):
             "color": "#654321",
         },
     )
+    lobby_service = LobbyService()
+    lobby_service._index_add(room.id, "2f7f162f-e7d1-421b-90e7-02bfbfbf8def")
+    lobby_service._index_add(room.id, "f4ca3ab8a6c04ad88097b8da33f60f10")
 
     response = client.get(f"/api/v1.0/rooms/{room.id}/waiting-participants/")
 

src/backend/core/tests/services/test_lobby.py

@@ -2,7 +2,7 @@
 Test lobby service.
 """
 
-# pylint: disable=W0621,W0613, W0212, R0913
+# pylint: disable=W0621,W0613, W0212, R0913, C0302
 # ruff: noqa: PLR0913, PLR0917
 
 import uuid
@@ -24,7 +24,6 @@ from core.services.lobby import (
     LobbyParticipantStatus,
     LobbyService,
 )
-from core.services.presence import CACHE_SCAN_ITERSIZE
 from core.utils import NotificationError
 
 pytestmark = pytest.mark.django_db
@@ -466,18 +465,22 @@ def test_request_entry_participant_with_role(
 def test_refresh_waiting_status(mock_cache, lobby_service, participant_id):
     """Test refreshing waiting status for a participant."""
     lobby_service._get_cache_key = mock.Mock(return_value="mocked_cache_key")
+    lobby_service._index_touch = mock.Mock()
     room = RoomFactory(access_level=RoomAccessLevel.RESTRICTED)
     lobby_service.refresh_waiting_status(room.id, participant_id)
     mock_cache.touch.assert_called_once_with(
         "mocked_cache_key", settings.LOBBY_WAITING_TIMEOUT
     )
+    lobby_service._index_touch.assert_called_once_with(room.id)
 
 
 # pylint: disable=R0917
 @mock.patch("core.services.lobby.cache")
 @mock.patch("core.utils.generate_color")
 @mock.patch("core.utils.notify_participants")
+@mock.patch("core.services.lobby.LobbyService._index_add")
 def test_enter_success(
+    mock_index_add,
     mock_notify,
     mock_generate_color,
     mock_cache,
@@ -508,13 +511,16 @@ def test_enter_success(
     mock_notify.assert_called_once_with(
         room_name=str(room.pk), notification_data={"type": "participantWaiting"}
     )
+    mock_index_add.assert_called_once_with(room.id, participant_id)
 
 
 # pylint: disable=R0917
 @mock.patch("core.services.lobby.cache")
 @mock.patch("core.utils.generate_color")
 @mock.patch("core.utils.notify_participants")
+@mock.patch("core.services.lobby.LobbyService._index_add")
 def test_enter_with_notification_error(
+    mock_index_add,
     mock_notify,
     mock_generate_color,
     mock_cache,
@@ -541,6 +547,7 @@ def test_enter_with_notification_error(
         participant.to_dict(),
         timeout=settings.LOBBY_WAITING_TIMEOUT,
     )
+    mock_index_add.assert_called_once_with(room.id, participant_id)
 
 
 @mock.patch("core.services.lobby.cache")
@@ -579,14 +586,15 @@ def test_get_participant_parsing_error(
 @mock.patch("core.services.lobby.cache")
 def test_list_waiting_participants_empty(mock_cache, lobby_service):
     """Test listing waiting participants when none exist."""
-    mock_cache.iter_keys.return_value = []
-
     room = RoomFactory(access_level=RoomAccessLevel.RESTRICTED)
+    lobby_service._index_members = mock.Mock(return_value=[])
+    lobby_service._index_remove = mock.Mock()
+
     result = lobby_service.list_waiting_participants(room.id)
 
-    assert result == []
-    pattern = f"{settings.LOBBY_KEY_PREFIX}_{room.id!s}_*"
-    mock_cache.iter_keys.assert_called_once_with(pattern, itersize=CACHE_SCAN_ITERSIZE)
+    assert result == ()
+    lobby_service._index_members.assert_called_once_with(room.id)
+    lobby_service._index_remove.assert_not_called()
     mock_cache.get_many.assert_not_called()
 
 
@@ -595,7 +603,8 @@ def test_list_waiting_participants(mock_cache, lobby_service, participant_dict):
     """Test listing waiting participants with valid data."""
     room = RoomFactory(access_level=RoomAccessLevel.RESTRICTED)
     cache_key = f"{settings.LOBBY_KEY_PREFIX}_{room.id!s}_participant1"
-    mock_cache.iter_keys.return_value = [cache_key]
+    lobby_service._index_members = mock.Mock(return_value=["participant1"])
+    lobby_service._index_remove = mock.Mock()
     mock_cache.get_many.return_value = {cache_key: participant_dict}
 
     result = lobby_service.list_waiting_participants(room.id)
@@ -603,8 +612,8 @@ def test_list_waiting_participants(mock_cache, lobby_service, participant_dict):
     assert len(result) == 1
     assert result[0]["status"] == "waiting"
     assert result[0]["username"] == "test-username"
-    pattern = f"{settings.LOBBY_KEY_PREFIX}_{room.id!s}_*"
-    mock_cache.iter_keys.assert_called_once_with(pattern, itersize=CACHE_SCAN_ITERSIZE)
+    lobby_service._index_members.assert_called_once_with(room.id)
+    lobby_service._index_remove.assert_called_once_with(room.id)
     mock_cache.get_many.assert_called_once_with([cache_key])
 
 
@@ -629,7 +638,10 @@ def test_list_waiting_participants_multiple(mock_cache, lobby_service):
         "color": "#654321",
     }
 
-    mock_cache.iter_keys.return_value = [cache_key1, cache_key2]
+    lobby_service._index_members = mock.Mock(
+        return_value=["participant1", "participant2"]
+    )
+    lobby_service._index_remove = mock.Mock()
     mock_cache.get_many.return_value = {
         cache_key1: participant1,
         cache_key2: participant2,
@@ -646,8 +658,7 @@ def test_list_waiting_participants_multiple(mock_cache, lobby_service):
     # Verify all participants have waiting status
     assert all(p["status"] == "waiting" for p in result)
 
-    pattern = f"{settings.LOBBY_KEY_PREFIX}_{room.id!s}_*"
-    mock_cache.iter_keys.assert_called_once_with(pattern, itersize=CACHE_SCAN_ITERSIZE)
+    lobby_service._index_members.assert_called_once_with(room.id)
     mock_cache.get_many.assert_called_once_with([cache_key1, cache_key2])
 
 
@@ -656,12 +667,13 @@ def test_list_waiting_participants_corrupted_data(mock_cache, lobby_service):
     """Test listing waiting participants with corrupted data."""
     room = RoomFactory(access_level=RoomAccessLevel.RESTRICTED)
     cache_key = f"{settings.LOBBY_KEY_PREFIX}_{room.id!s}_participant1"
-    mock_cache.iter_keys.return_value = [cache_key]
+    lobby_service._index_members = mock.Mock(return_value=["participant1"])
+    lobby_service._index_remove = mock.Mock()
     mock_cache.get_many.return_value = {cache_key: {"invalid": "data"}}
 
     result = lobby_service.list_waiting_participants(room.id)
 
-    assert result == []
+    assert result == ()
     mock_cache.delete.assert_called_once_with(cache_key)
 
 
@@ -681,7 +693,10 @@ def test_list_waiting_participants_partially_corrupted(mock_cache, lobby_service
 
     corrupted_participant = {"invalid": "data"}
 
-    mock_cache.iter_keys.return_value = [cache_key1, cache_key2]
+    lobby_service._index_members = mock.Mock(
+        return_value=["participant1", "participant2"]
+    )
+    lobby_service._index_remove = mock.Mock()
     mock_cache.get_many.return_value = {
         cache_key1: corrupted_participant,
         cache_key2: valid_participant,
@@ -699,8 +714,6 @@ def test_list_waiting_participants_partially_corrupted(mock_cache, lobby_service
     mock_cache.delete.assert_called_once_with(cache_key1)
 
     # Verify both cache keys were queried
-    pattern = f"{settings.LOBBY_KEY_PREFIX}_{room.id!s}_*"
-    mock_cache.iter_keys.assert_called_once_with(pattern, itersize=CACHE_SCAN_ITERSIZE)
     mock_cache.get_many.assert_called_once_with([cache_key1, cache_key2])
 
 
@@ -724,7 +737,10 @@ def test_list_waiting_participants_non_waiting(mock_cache, lobby_service):
         "color": "#654321",
     }
 
-    mock_cache.iter_keys.return_value = [cache_key1, cache_key2]
+    lobby_service._index_members = mock.Mock(
+        return_value=["participant1", "participant2"]
+    )
+    lobby_service._index_remove = mock.Mock()
     mock_cache.get_many.return_value = {
         cache_key1: participant1,
         cache_key2: participant2,
@@ -820,6 +836,7 @@ def test_update_participant_status_success(mock_cache, lobby_service, participan
 
     mock_cache.get.return_value = participant_dict
     lobby_service._get_cache_key = mock.Mock(return_value="mocked_cache_key")
+    lobby_service._index_touch = mock.Mock()
 
     lobby_service._update_participant_status(
         room.id,
@@ -837,6 +854,7 @@ def test_update_participant_status_success(mock_cache, lobby_service, participan
     mock_cache.set.assert_called_once_with(
         "mocked_cache_key", expected_data, timeout=60
     )
+    lobby_service._index_touch.assert_called_once_with(room.id)
     lobby_service._get_cache_key.assert_called_once_with(room.id, participant_id)
 
 
@@ -881,9 +899,13 @@ def test_clear_room_cache(settings, lobby_service):
         timeout=settings.LOBBY_DENIED_TIMEOUT,
     )
 
+    for participant_id in ("participant1", "participant2", "participant3"):
+        lobby_service._index_add(room_id, participant_id)
+
     lobby_service.clear_room_cache(room_id)
 
     assert cache.keys(f"test-lobby_{room_id!s}_*") == []
+    assert lobby_service._index_members(room_id) == frozenset()
 
 
 def test_clear_room_empty(settings, lobby_service):
@@ -910,10 +932,13 @@ def test_clear_participant_cache(lobby_service):
         "color": "#123456",
     }
     cache.set(cache_key, participant_data, timeout=settings.LOBBY_WAITING_TIMEOUT)
+    lobby_service._index_add(room_id, participant_id)
     assert cache.get(cache_key) is not None
+    assert participant_id in lobby_service._index_members(room_id)
 
     lobby_service.clear_participant_cache(room_id, participant_id)
     assert cache.get(cache_key) is None
+    assert participant_id not in lobby_service._index_members(room_id)
 
 
 def test_clear_participant_cache_nonexistent(lobby_service):
@@ -927,3 +952,84 @@ def test_clear_participant_cache_nonexistent(lobby_service):
     lobby_service.clear_participant_cache(room_id, participant_id)
 
     assert cache.get(cache_key) is None
+
+
+def test_index_add_members_remove_roundtrip(lobby_service):
+    """The room index records, lists and forgets participant ids."""
+    room_id = uuid.uuid4()
+
+    assert lobby_service._index_members(room_id) == frozenset()
+
+    lobby_service._index_add(room_id, "participant1")
+    lobby_service._index_add(room_id, "participant2")
+
+    assert sorted(lobby_service._index_members(room_id)) == [
+        "participant1",
+        "participant2",
+    ]
+
+    # The index carries a backstop TTL so abandoned rooms cannot leak it.
+    ttl = lobby_service._redis().ttl(lobby_service._get_index_key(room_id))
+    assert 0 < ttl <= settings.LOBBY_ACCEPTED_TIMEOUT
+
+    lobby_service._index_remove(room_id, "participant1")
+    assert lobby_service._index_members(room_id) == frozenset(["participant2"])
+
+
+@mock.patch("core.utils.notify_participants")
+def test_enter_registers_participant_in_room_index(
+    mock_notify, lobby_service, participant_id, username
+):
+    """Entering the lobby must index the participant id for the room."""
+    room_id = uuid.uuid4()
+
+    lobby_service.enter(room_id, participant_id, username)
+
+    assert lobby_service._index_members(room_id) == frozenset([participant_id])
+
+
+def test_list_waiting_participants_prunes_stale_index_ids(settings, lobby_service):
+    """Indexed ids whose cache entry expired are pruned and not listed."""
+    settings.LOBBY_KEY_PREFIX = "test-lobby-prune"
+    room_id = uuid.uuid4()
+
+    cache.set(
+        f"test-lobby-prune_{room_id!s}_participant1",
+        {
+            "id": "participant1",
+            "username": "user1",
+            "status": "waiting",
+            "color": "#123456",
+        },
+        timeout=100,
+    )
+    lobby_service._index_add(room_id, "participant1")
+    # participant2 is indexed but its cache entry has expired.
+    lobby_service._index_add(room_id, "participant2")
+
+    result = lobby_service.list_waiting_participants(room_id)
+
+    assert [participant["id"] for participant in result] == ["participant1"]
+    assert lobby_service._index_members(room_id) == frozenset(["participant1"])
+
+
+def test_refresh_waiting_status_rearms_room_index_ttl(lobby_service, participant_id):
+    """A lone waiter's polling must keep the room index alive.
+
+    Regression test: the index backstop TTL is only armed at enter() time,
+    so a participant whose rolling WAITING refreshes outlast it would keep
+    their entry alive while silently vanishing from the moderator list.
+    Refreshing the waiting status must therefore re-arm the index TTL.
+    """
+    room_id = uuid.uuid4()
+    lobby_service._index_add(room_id, participant_id)
+
+    index_key = lobby_service._get_index_key(room_id)
+    redis_client = lobby_service._redis()
+    redis_client.expire(index_key, 10)
+    assert redis_client.ttl(index_key) <= 10
+
+    lobby_service.refresh_waiting_status(room_id, participant_id)
+
+    assert redis_client.ttl(index_key) > 10
+    assert lobby_service._index_members(room_id) == frozenset([participant_id])