feat: add logs feature with internationalization support

- Introduced a new logs view for admin users, allowing real-time monitoring of backend logs.
- Implemented a log entry streaming mechanism using Socket.IO.
- Added filtering and searching capabilities for log entries.
- Created localized log messages in Spanish, French, Hungarian, Italian, Japanese, Korean, Polish, Portuguese, Romanian, Russian, Simplified Chinese, and Traditional Chinese.
- Updated router and sidebar components to include the new logs route.
- Enhanced user interface with tooltips and buttons for copying and downloading logs.

Author: zurdi15

backend/endpoints/logs.py

@@ -0,0 +1,33 @@
+from fastapi import Request
+
+from decorators.auth import protected_route
+from endpoints.responses.log import LogEntrySchema
+from endpoints.sockets.logs import get_recent_logs
+from handler.auth.constants import Scope
+from utils.router import APIRouter
+
+router = APIRouter(
+    prefix="/logs",
+    tags=["logs"],
+)
+
+# Largest backfill the buffer holds (mirrors LOG_BUFFER_SIZE).
+MAX_LOG_LIMIT = 1000
+
+
+@protected_route(router.get, "", [Scope.USERS_WRITE])
+async def get_logs(
+    request: Request, limit: int = MAX_LOG_LIMIT
+) -> list[LogEntrySchema]:
+    """Return the most recent backend log lines for backfill (admin only).
+
+    Args:
+        request (Request): FastAPI Request object.
+        limit (int): Maximum number of recent lines to return.
+
+    Returns:
+        list[LogEntrySchema]: Recent log lines, oldest-first.
+    """
+    bounded = max(1, min(limit, MAX_LOG_LIMIT))
+    entries = await get_recent_logs(bounded)
+    return [LogEntrySchema(**entry) for entry in entries]

backend/endpoints/responses/log.py

@@ -0,0 +1,10 @@
+from endpoints.responses.base import BaseModel
+
+
+class LogEntrySchema(BaseModel):
+    """A single backend log line streamed to the admin log viewer."""
+
+    ts: int  # epoch milliseconds
+    level: str
+    module: str
+    message: str

backend/endpoints/sockets/logs.py

@@ -0,0 +1,180 @@
+"""Real-time backend log streaming over Socket.IO (admin only).
+
+Pieces:
+- ``connect`` handler on the main socket server: resolves the session user and,
+  if they are an admin, joins them to the ``admin`` room. It never rejects a
+  connection, so the existing scan/sync sockets keep working for everyone.
+- ``start_log_forwarder``: a single background task (Redis-lock guarded) that
+  subscribes to the ``romm:logs`` pub/sub channel — fed by ``LogStreamHandler``
+  in every backend process — and relays each line to the ``admin`` room.
+- ``get_recent_logs``: reads the capped ring buffer for backfill on view open.
+"""
+
+import asyncio
+import uuid
+from http.cookies import SimpleCookie
+from typing import Any, Final
+
+import socketio  # type: ignore
+
+from config import REDIS_URL
+from handler.database import db_user_handler
+from handler.redis_handler import async_cache
+from handler.socket_handler import socket_handler
+from logger.log_stream_handler import LOG_BUFFER_KEY, LOG_CHANNEL
+from logger.logger import log
+from models.user import Role
+from utils import json_module
+
+ADMIN_ROOM: Final = "admin"
+FORWARDER_LOCK_KEY: Final = "romm:logs:forwarder"
+FORWARDER_LOCK_TTL: Final = 30  # seconds
+# Session cookie name configured on RedisSessionMiddleware in main.py.
+SESSION_COOKIE_NAME: Final = "romm_session"
+
+
+async def _session_from_environ(environ: dict[str, Any]) -> dict[str, Any]:
+    """Resolve the auth session for a socket handshake.
+
+    Tries the session the middleware attached to the ASGI scope first; if it's
+    absent (scope not propagated to the mounted socket app), falls back to
+    parsing the session cookie and reading the session straight from Redis —
+    the same lookup RedisSessionMiddleware performs.
+    """
+    scope = environ.get("asgi.scope", {})
+    session = scope.get("session")
+    if session:
+        return session
+
+    raw_cookie = environ.get("HTTP_COOKIE", "")
+    if not raw_cookie:
+        return {}
+
+    cookie: SimpleCookie = SimpleCookie()
+    cookie.load(raw_cookie)
+    morsel = cookie.get(SESSION_COOKIE_NAME)
+    if morsel is None:
+        return {}
+
+    session_data = await async_cache.get(f"session:{morsel.value}")
+    if not session_data:
+        return {}
+    try:
+        return json_module.loads(session_data)
+    except Exception:  # noqa: BLE001 - malformed session is "no session"
+        return {}
+
+
+@socket_handler.socket_server.on("connect")  # type: ignore
+async def connect(sid: str, environ: dict[str, Any], auth: Any = None) -> None:
+    """Join admin users to the log-streaming room on socket connect.
+
+    Always returns ``None`` (accepts the connection) — only the room membership
+    is gated, so the existing scan/sync sockets keep working for everyone.
+    """
+    try:
+        session = await _session_from_environ(environ)
+        if session.get("iss") != "romm:auth":
+            return
+
+        username = session.get("sub")
+        if not username:
+            return
+
+        user = db_user_handler.get_user_by_username(username)
+        if user and user.enabled and user.role == Role.ADMIN:
+            await socket_handler.socket_server.enter_room(sid, ADMIN_ROOM)
+    except Exception:  # noqa: BLE001 - never let auth resolution refuse a socket
+        log.exception("Failed to resolve admin for log stream connect")
+
+
+async def get_recent_logs(limit: int) -> list[dict[str, Any]]:
+    """Return the most recent buffered log lines in chronological order."""
+    raw = await async_cache.lrange(LOG_BUFFER_KEY, 0, max(0, limit - 1))
+    entries: list[dict[str, Any]] = []
+    for item in raw:
+        try:
+            entries.append(json_module.loads(item))
+        except Exception:  # noqa: BLE001 - skip any malformed buffer entry
+            continue
+    # The buffer is newest-first (LPUSH); callers want oldest-first.
+    entries.reverse()
+    return entries
+
+
+async def start_log_forwarder() -> None:
+    """Relay log lines from Redis pub/sub to admin Socket.IO clients.
+
+    Guarded by a Redis lock so that, when more than one web worker is running
+    (WEB_SERVER_CONCURRENCY > 1), exactly one forwards and clients don't receive
+    duplicate lines.
+    """
+    lock_id = str(uuid.uuid4())
+    pubsub = None
+    # Write-only manager for emitting — the same proven path scan/sync use. It
+    # publishes the room emit to Redis; the main socket server's read-side
+    # manager resolves `admin` room membership and delivers. Created inside the
+    # running loop (like sync.py) rather than at import time.
+    socket_manager = socketio.AsyncRedisManager(REDIS_URL, write_only=True)
+    try:
+        while True:
+            got_lock = await async_cache.set(
+                FORWARDER_LOCK_KEY, lock_id, nx=True, ex=FORWARDER_LOCK_TTL
+            )
+            if not got_lock:
+                # Another worker owns the forwarder; check back periodically in
+                # case it dies and the lock expires.
+                await asyncio.sleep(FORWARDER_LOCK_TTL / 2)
+                continue
+
+            pubsub = async_cache.pubsub()
+            await pubsub.subscribe(LOG_CHANNEL)
+            log.info("Log stream forwarder started")
+            try:
+                while True:
+                    # Heartbeat the lock so a healthy forwarder keeps ownership.
+                    await async_cache.set(
+                        FORWARDER_LOCK_KEY, lock_id, xx=True, ex=FORWARDER_LOCK_TTL
+                    )
+                    message = await pubsub.get_message(
+                        ignore_subscribe_messages=True,
+                        timeout=FORWARDER_LOCK_TTL / 3,
+                    )
+                    if not message:
+                        continue
+                    data = message.get("data")
+                    if not data:
+                        continue
+                    # One bad message or emit must not kill the forwarder —
+                    # swallow per-line and keep relaying.
+                    try:
+                        payload = json_module.loads(data)
+                        await socket_manager.emit(
+                            "logs:entry", payload, room=ADMIN_ROOM
+                        )
+                    except Exception:  # noqa: BLE001 - skip; keep forwarding
+                        continue
+            finally:
+                await pubsub.unsubscribe(LOG_CHANNEL)
+                await pubsub.aclose()  # type: ignore[attr-defined]
+                pubsub = None
+    except asyncio.CancelledError:
+        if pubsub is not None:
+            await pubsub.aclose()  # type: ignore[attr-defined]
+        # Release the lock on shutdown so a restart (e.g. uvicorn --reload)
+        # resumes forwarding immediately instead of waiting out the TTL.
+        await _release_lock(lock_id)
+        raise
+    except Exception:  # noqa: BLE001 - never let the forwarder kill the app
+        log.exception("Log forwarder crashed")
+        await _release_lock(lock_id)
+
+
+async def _release_lock(lock_id: str) -> None:
+    """Delete the forwarder lock only if we still own it."""
+    try:
+        current = await async_cache.get(FORWARDER_LOCK_KEY)
+        if current == lock_id:
+            await async_cache.delete(FORWARDER_LOCK_KEY)
+    except Exception:  # noqa: BLE001 - best-effort cleanup
+        pass

backend/logger/log_stream_handler.py

@@ -0,0 +1,76 @@
+import logging
+import re
+from typing import Final
+
+# Redis keys shared between the logging handler (producer, runs in every
+# process), the forwarder (relays pub/sub to Socket.IO) and the REST backfill
+# endpoint.
+LOG_CHANNEL: Final = "romm:logs"
+LOG_BUFFER_KEY: Final = "romm:logs:buffer"
+LOG_BUFFER_SIZE: Final = 1000
+
+# Strips ANSI SGR escapes (colors) that the `highlight()` helper embeds in log
+# messages — they render as colors on a terminal but as garbage in a browser.
+_ANSI_RE: Final = re.compile(r"\x1b\[[0-9;]*m")
+
+
+class LogStreamHandler(logging.Handler):
+    """Logging handler that mirrors records to Redis for real-time streaming.
+
+    Each record is serialized to a small JSON payload, appended to a capped
+    Redis ring buffer (for backfill on view open) and published to a pub/sub
+    channel that a single forwarder in the main app relays to admin Socket.IO
+    clients.
+
+    The handler is attached to the ``romm`` logger, so it runs in every process
+    that imports it (main app, RQ workers, scheduler, watchers) and the stream
+    covers the whole backend.
+
+    Failures are swallowed **silently** — stdout is the source-of-truth log, so
+    a Redis hiccup (or the metadata package not being importable yet during the
+    first few boot lines) must neither raise into the app nor spam tracebacks
+    via ``handleError``.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        # The redaction regex lives in handler.metadata.base_handler, which
+        # pulls a heavy import chain (and, during early boot, a partially
+        # initialized handler.redis_handler). Resolve it lazily and cache it
+        # once available; until then, skip redaction — exactly like the
+        # Formatter does for the first few boot lines.
+        self._redactor: re.Pattern[str] | None = None
+
+    def _redact(self, message: str) -> str:
+        if self._redactor is None:
+            try:
+                from handler.metadata.base_handler import SENSITIVE_KEYS_REGEX
+
+                self._redactor = SENSITIVE_KEYS_REGEX
+            except Exception:  # noqa: BLE001 - not importable yet during boot
+                return message
+        return self._redactor.sub(r"\1=***", message)
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            from handler.redis_handler import redis_client
+            from utils import json_module
+
+            module = getattr(record, "module_name", record.module)
+            payload = json_module.dumps(
+                {
+                    "ts": int(record.created * 1000),
+                    "level": record.levelname,
+                    "module": str(module).lower(),
+                    "message": self._redact(_ANSI_RE.sub("", record.getMessage())),
+                }
+            )
+
+            # A single pipeline keeps buffer write + publish to one round-trip.
+            pipe = redis_client.pipeline()
+            pipe.lpush(LOG_BUFFER_KEY, payload)
+            pipe.ltrim(LOG_BUFFER_KEY, 0, LOG_BUFFER_SIZE - 1)
+            pipe.publish(LOG_CHANNEL, payload)
+            pipe.execute()
+        except Exception:  # noqa: BLE001 - best-effort mirror; never raise/spam
+            pass

backend/logger/logger.py

@@ -1,8 +1,9 @@
 import logging
 import sys
 
-from config import LOGLEVEL
+from config import IS_PYTEST_RUN, LOGLEVEL
 from logger.formatter import Formatter
+from logger.log_stream_handler import LogStreamHandler
 
 # Set up logger
 log = logging.getLogger("romm")
@@ -14,6 +15,13 @@
 stdout_handler.setFormatter(Formatter())
 log.addHandler(stdout_handler)
 
+# Mirror records to Redis for the real-time admin log viewer. Skipped under
+# pytest, where there is no live Redis to stream to.
+if not IS_PYTEST_RUN:
+    stream_handler = LogStreamHandler()
+    stream_handler.setLevel(LOGLEVEL)
+    log.addHandler(stream_handler)
+
 # Hush passlib warnings
 logging.getLogger("passlib").setLevel(logging.ERROR)
 

backend/main.py

@@ -13,6 +13,7 @@
 from starlette.middleware.authentication import AuthenticationMiddleware
 from startup import main
 
+import endpoints.sockets.logs  # noqa
 import endpoints.sockets.netplay  # noqa
 import endpoints.sockets.scan  # noqa
 import endpoints.sockets.sync  # noqa
@@ -34,6 +35,7 @@
 from endpoints.feeds import router as feeds_router
 from endpoints.firmware import router as firmware_router
 from endpoints.heartbeat import router as heartbeat_router
+from endpoints.logs import router as logs_router
 from endpoints.netplay import router as netplay_router
 from endpoints.platform import router as platform_router
 from endpoints.play_sessions import router as play_sessions_router
@@ -68,7 +70,19 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None]:
     async with initialize_context():
         app.state.aiohttp_session = ctx_aiohttp_session.get()
         app.state.httpx_client = ctx_httpx_client.get()
-        yield
+
+        # Relay backend log lines to admin Socket.IO clients in real time.
+        log_forwarder_task: asyncio.Task[None] | None = None
+        if not IS_PYTEST_RUN:
+            from endpoints.sockets.logs import start_log_forwarder
+
+            log_forwarder_task = asyncio.create_task(start_log_forwarder())
+
+        try:
+            yield
+        finally:
+            if log_forwarder_task is not None:
+                log_forwarder_task.cancel()
 
 
 sentry_sdk.init(
@@ -140,6 +154,7 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None]:
 app.include_router(feeds_router, prefix="/api")
 app.include_router(configs_router, prefix="/api")
 app.include_router(stats_router, prefix="/api")
+app.include_router(logs_router, prefix="/api")
 app.include_router(raw_router, prefix="/api")
 app.include_router(screenshots_router, prefix="/api")
 app.include_router(firmware_router, prefix="/api")

frontend/src/locales/bg_BG/common.json

@@ -152,5 +152,6 @@
   "changelog-view-all": "Вижте всички издания в GitHub",
   "visibility": "Видимост",
   "server-offline-retrying": "Server connection lost · retrying…",
-  "server-reconnected": "Reconnected to the server"
+  "server-reconnected": "Reconnected to the server",
+  "logs": "Logs"
 }

frontend/src/locales/bg_BG/logs.json

@@ -0,0 +1,18 @@
+{
+  "level-all": "All levels",
+  "level-filter": "Filter by level",
+  "search-placeholder": "Search logs",
+  "pause": "Pause",
+  "resume": "Resume",
+  "copy": "Copy to clipboard",
+  "download": "Download",
+  "clear": "Clear",
+  "empty": "No logs yet",
+  "no-matches": "No logs match your filters",
+  "jump-to-latest": "Jump to latest",
+  "load-error": "Failed to load logs",
+  "copied": "Logs copied to clipboard",
+  "copy-error": "Failed to copy logs",
+  "click-to-copy": "Click to copy to clipboard",
+  "line-copied": "Line copied to clipboard"
+}