[PR-7] add emote feature

Author: bnbong

backend/app/config.py

@@ -56,6 +56,18 @@ class Settings(BaseSettings):
     DEFAULT_MMR: int = 1000
     MMR_K_FACTOR: int = 32
 
+    # Emote system (PR-07).
+    # EMOTE_COOLDOWN_SECONDS: minimum gap between any two emotes from one
+    #   connection.  Attempts within this window are rejected with RATE_LIMITED.
+    # EMOTE_BURST_CAP: maximum emotes allowed within EMOTE_BURST_WINDOW_SECONDS.
+    # EMOTE_BURST_WINDOW_SECONDS: sliding window size for burst-cap enforcement.
+    # EMOTE_SAME_REPEAT_CAP: max consecutive sends of the identical emote_id
+    #   before a soft block kicks in (same-emote spam prevention).
+    EMOTE_COOLDOWN_SECONDS: float = 1.5
+    EMOTE_BURST_CAP: int = 3
+    EMOTE_BURST_WINDOW_SECONDS: int = 10
+    EMOTE_SAME_REPEAT_CAP: int = 2
+
     model_config = SettingsConfigDict(
         env_file=".env",
         env_file_encoding="utf-8",

backend/app/services/emote_service.py

@@ -0,0 +1,180 @@
+"""
+Emote broadcast service (PR-07).
+
+Responsibilities
+----------------
+* Validate that an emote_id belongs to the fixed permitted catalog.
+* Enforce per-connection rate limits (all values from settings):
+    - Cooldown: EMOTE_COOLDOWN_SECONDS (1.5 s) between any two emotes.
+    - Burst cap: at most EMOTE_BURST_CAP (3) emotes within
+      EMOTE_BURST_WINDOW_SECONDS (10 s) sliding window.
+    - Same-emote soft block: more than EMOTE_SAME_REPEAT_CAP (2) consecutive
+      sends of the identical slug are denied until a different emote is sent.
+* Provide reset() for test isolation.
+
+No broadcast or session logic lives here — the WS handler is responsible
+for fanout and mute filtering.
+
+Emote catalog
+-------------
+Emotes are identified by a short ASCII slug.  The client maps these to
+emoji / images.  The server only validates the slug — it never stores or
+renders it.
+
+Permitted slugs:
+  thumbsup   👍   좋아요
+  thumbsdown 👎   별로
+  smile      😄   웃음
+  sweat      😅   땀
+  thinking   🤔   생각
+  fire       🔥   열정
+  cry        😭   눈물
+  clap       👏   박수
+"""
+
+from __future__ import annotations
+
+import time
+
+from app.config import settings
+
+# ---------------------------------------------------------------------------
+# Catalog
+# ---------------------------------------------------------------------------
+
+VALID_EMOTE_IDS: frozenset[str] = frozenset(
+    {
+        "thumbsup",
+        "thumbsdown",
+        "smile",
+        "sweat",
+        "thinking",
+        "fire",
+        "cry",
+        "clap",
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Service
+# ---------------------------------------------------------------------------
+
+
+class EmoteService:
+    """
+    Stateful rate-limit tracker for emote broadcasts.
+
+    One instance is shared for the entire server process.  All state is
+    keyed by connection_id so there is no per-user persistence.
+    State is cleared between tests via reset().
+    """
+
+    def __init__(self) -> None:
+        # connection_id -> timestamp of the most recent allowed emote
+        self._last_sent: dict[str, float] = {}
+        # connection_id -> list of timestamps within the current burst window
+        self._window_history: dict[str, list[float]] = {}
+        # connection_id -> (last_emote_id, consecutive_count)
+        # Tracks same-emote repetitions for soft-block enforcement.
+        self._same_emote: dict[str, tuple[str, int]] = {}
+        # connection_id -> reason string for the most recent denial
+        # One of: "cooldown", "burst", "same_emote"
+        self._last_deny_reason: dict[str, str] = {}
+
+    # ------------------------------------------------------------------
+    # Validation
+    # ------------------------------------------------------------------
+
+    def is_valid_emote(self, emote_id: str) -> bool:
+        """Return True if emote_id is in the permitted catalog."""
+        return emote_id in VALID_EMOTE_IDS
+
+    # ------------------------------------------------------------------
+    # Rate limiting
+    # ------------------------------------------------------------------
+
+    def check_and_record(self, conn_id: str, emote_id: str) -> bool:
+        """
+        Check whether conn_id may send *emote_id* right now.
+
+        Returns True and records the emission if allowed.
+        Returns False (without recording) if any limit would be violated.
+
+        Rules applied in order:
+          1. Cooldown: now − last_sent < EMOTE_COOLDOWN_SECONDS → deny.
+          2. Burst cap: entries_in_window >= EMOTE_BURST_CAP → deny.
+          3. Same-emote soft block: consecutive_same > EMOTE_SAME_REPEAT_CAP
+             → deny until a different emote is used.
+        """
+        now = time.time()
+
+        # 1. Cooldown check
+        last = self._last_sent.get(conn_id, 0.0)
+        if now - last < settings.EMOTE_COOLDOWN_SECONDS:
+            self._last_deny_reason[conn_id] = "cooldown"
+            return False
+
+        # 2. Burst window — prune expired entries then count
+        window = self._window_history.get(conn_id, [])
+        window = [t for t in window if now - t < settings.EMOTE_BURST_WINDOW_SECONDS]
+        if len(window) >= settings.EMOTE_BURST_CAP:
+            self._last_deny_reason[conn_id] = "burst"
+            return False
+
+        # 3. Same-emote soft block
+        prev_id, streak = self._same_emote.get(conn_id, ("", 0))
+        if emote_id == prev_id and streak >= settings.EMOTE_SAME_REPEAT_CAP:
+            self._last_deny_reason[conn_id] = "same_emote"
+            return False
+
+        # Allowed — record
+        window.append(now)
+        self._last_sent[conn_id] = now
+        self._window_history[conn_id] = window
+
+        # Update same-emote streak counter
+        if emote_id == prev_id:
+            self._same_emote[conn_id] = (emote_id, streak + 1)
+        else:
+            self._same_emote[conn_id] = (emote_id, 1)
+
+        return True
+
+    def last_deny_reason(self, conn_id: str) -> str:
+        """
+        Return the reason for the most recent rate-limit denial for conn_id.
+
+        Returns one of: ``"cooldown"``, ``"burst"``, ``"same_emote"``.
+        Returns ``""`` if conn_id has never been denied.
+        """
+        return self._last_deny_reason.get(conn_id, "")
+
+    def remaining_cooldown(self, conn_id: str) -> float:
+        """
+        Return seconds until the cooldown expires for conn_id.
+
+        Returns 0.0 if the connection is not rate-limited.
+        Useful for generating informative error messages.
+        """
+        last = self._last_sent.get(conn_id, 0.0)
+        remaining = settings.EMOTE_COOLDOWN_SECONDS - (time.time() - last)
+        return max(0.0, remaining)
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def reset(self) -> None:
+        """Clear all rate-limit state.  Called between tests."""
+        self._last_sent.clear()
+        self._window_history.clear()
+        self._same_emote.clear()
+        self._last_deny_reason.clear()
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton
+# ---------------------------------------------------------------------------
+
+emote_service = EmoteService()

backend/app/ws/connection_manager.py

@@ -47,6 +47,10 @@ def join_room(self, conn_id: str, room_code: str) -> None:
             self._room_members[room_code] = set()
         self._room_members[room_code].add(conn_id)
 
+    def get_room_members(self, room_code: str) -> list[str]:
+        """Return a snapshot of connection IDs currently in room_code."""
+        return list(self._room_members.get(room_code, set()))
+
     def leave_room(self, conn_id: str, room_code: str) -> None:
         self._room_members.get(room_code, set()).discard(conn_id)
 

backend/app/ws/handler.py

@@ -91,6 +91,10 @@ async def handle_message(
         )
     elif msg_type == "QUICK_MATCH_LEAVE":
         await _quick_match_leave(ws, session, matchmaking_service)
+    elif msg_type == "EMOTE_SEND":
+        await _emote_send(ws, session, data, manager)
+    elif msg_type == "EMOTE_MUTE":
+        await _emote_mute(ws, session, data)
     elif msg_type == "PING":
         await ws.send_json({"type": "PONG", "data": {}})
     elif msg_type == "PONG":
@@ -1002,3 +1006,96 @@ async def _on_ready(rc: str, m) -> None:
             room_code=room.room_code,
             on_turn_ready=_on_ready,
         )
+
+
+# ---------------------------------------------------------------------------
+# Emote handlers (PR-07)
+# ---------------------------------------------------------------------------
+
+
+async def _emote_send(
+    ws: WebSocket,
+    session: WsSession,
+    data: dict,
+    manager: ConnectionManager,
+) -> None:
+    """
+    Relay an emote from one player to all room participants.
+
+    Validation:
+      - Session must be authenticated and in a room.
+      - emote_id must be in the permitted catalog.
+      - Per-connection rate limits (cooldown + burst cap) must not be exceeded.
+
+    On success: broadcasts EMOTE_BROADCAST to every room member whose
+    session does not have emotes_muted=True.
+    The sender always receives the broadcast (they see their own emote).
+    """
+    from app.services.emote_service import emote_service
+
+    if not session.is_authenticated:
+        await _error(ws, "NOT_AUTHENTICATED", "Authenticate before sending emotes")
+        return
+
+    if not session.in_room:
+        await _error(ws, "NOT_IN_ROOM", "Join a room before sending emotes")
+        return
+
+    emote_id = data.get("emote_id", "")
+    if not emote_service.is_valid_emote(emote_id):
+        await _error(ws, "INVALID_EMOTE", f"Unknown emote: {emote_id!r}")
+        return
+
+    if not emote_service.check_and_record(session.connection_id, emote_id):
+        reason = emote_service.last_deny_reason(session.connection_id)
+        if reason == "cooldown":
+            cooldown = emote_service.remaining_cooldown(session.connection_id)
+            msg = f"Sending emotes too fast — wait {cooldown:.1f}s"
+        elif reason == "burst":
+            msg = "Emote burst cap reached — slow down"
+        else:  # same_emote
+            msg = "Send a different emote before repeating"
+        await ws.send_json(
+            {
+                "type": "ERROR",
+                "data": {
+                    "code": "EMOTE_RATE_LIMITED",
+                    "reason": reason,
+                    "message": msg,
+                },
+            }
+        )
+        return
+
+    payload = {
+        "type": "EMOTE_BROADCAST",
+        "data": {
+            "seat_index": session.seat_index,
+            "emote_id": emote_id,
+        },
+    }
+
+    # Fan out to every room member, skipping connections with mutes.
+    for conn_id in manager.get_room_members(session.room_code):
+        target_session = manager.get_session(conn_id)
+        if target_session is not None and target_session.emotes_muted:
+            continue
+        await manager.send_to(conn_id, payload)
+
+
+async def _emote_mute(
+    ws: WebSocket,
+    session: WsSession,
+    data: dict,
+) -> None:
+    """
+    Toggle emote broadcast reception for this connection.
+
+    The client sends {"type": "EMOTE_MUTE", "data": {"muted": true|false}}.
+    The server acknowledges with EMOTE_MUTE_ACK carrying the new state.
+    When muted=True, this connection will no longer receive EMOTE_BROADCAST
+    messages until it explicitly unmutes.
+    """
+    muted = bool(data.get("muted", True))
+    session.emotes_muted = muted
+    await ws.send_json({"type": "EMOTE_MUTE_ACK", "data": {"muted": session.emotes_muted}})

backend/app/ws/session.py

@@ -28,6 +28,10 @@ class WsSession:
     # Cleared when a match is formed or the player leaves the queue manually.
     in_queue: bool = False
 
+    # True when this connection has opted out of receiving emote broadcasts
+    # (PR-07).  Emotes sent by others are silently dropped for this session.
+    emotes_muted: bool = False
+
     @property
     def is_authenticated(self) -> bool:
         return self.display_name is not None

backend/tests/conftest.py

@@ -72,6 +72,16 @@ def reset_matchmaking_service():
     matchmaking_service.reset()
 
 
+@pytest.fixture(autouse=True)
+def reset_emote_service():
+    """Clear per-connection rate-limit state between tests."""
+    from app.services.emote_service import emote_service
+
+    emote_service.reset()
+    yield
+    emote_service.reset()
+
+
 @pytest.fixture()
 def db_engine():
     """Fresh in-memory SQLite engine for one test."""