refactor: comprehensive code review fixes across 31 files

Addresses all critical, high, medium, and low issues from full codebase
review. 494 tests pass, ruff clean, ty type-check clean.

Security:
- Add tool_error_handler context manager (exceptions.py) — standardised
  error handling, eliminates 11 bare except-reraise patterns
- Remove unused exception subclasses (ConfigurationError, UnraidAPIError,
  SubscriptionError, ValidationError, IdempotentOperationError)
- Harden GraphQL subscription query validator with allow-list and
  forbidden-keyword regex (diagnostics.py)
- Add input validation for rclone create_remote config_data: injection,
  path-traversal, and key-count limits (rclone.py)
- Validate notifications importance enum before GraphQL request (notifications.py)
- Sanitise HTTP/network/JSON error messages — no raw exception strings
  leaked to clients (client.py)
- Strip path/creds from displayed API URL via _safe_display_url (health.py)
- Enable Ruff S (bandit) rule category in pyproject.toml
- Harden container mutations to strict-only matching — no fuzzy/substring
  for destructive operations (docker.py)

Performance:
- Token-bucket rate limiter (90 tokens, 9 req/s) with 429 retry backoff (client.py)
- Lazy asyncio.Lock init via _get_client_lock() — fixes event-loop
  module-load crash (client.py)
- Double-checked locking in get_http_client() for fast-path (client.py)
- Short hex container ID fast-path skips list fetch (docker.py)
- Cap resource_data log content to 1 MB / 5,000 lines (manager.py)
- Reset reconnect counter after 30 s stable connection (manager.py)
- Move tail_lines validation to module level; enforce 10,000 line cap
  (storage.py, docker.py)
- force_terminal=True removed from logging RichHandler (logging.py)

Architecture:
- Register diagnostic tools in server startup (server.py)
- Move ALL_ACTIONS computation to module level in all tools
- Consolidate format_kb / format_bytes into shared core/utils.py
- Add _safe_get() helper in core/utils.py for nested dict traversal
- Extract _analyze_subscription_status() from health.py diagnose handler
- Validate required config at startup — fail fast with CRITICAL log (server.py)

Code quality:
- Remove ~90 lines of dead Rich formatting helpers from logging.py
- Remove dead self.websocket attribute from SubscriptionManager
- Remove dead setup_uvicorn_logging() wrapper
- Move _VALID_IMPORTANCE to module level (N806 fix)
- Add slots=True to all three dataclasses (SubscriptionData, SystemHealth, APIResponse)
- Fix None rendering as literal "None" string in info.py summaries
- Change fuzzy-match log messages from INFO to DEBUG (docker.py)
- UTC-aware datetimes throughout (manager.py, diagnostics.py)

Infrastructure:
- Upgrade base image python:3.11-slim → python:3.12-slim (Dockerfile)
- Add non-root appuser (UID/GID 1000) with HEALTHCHECK (Dockerfile)
- Add read_only, cap_drop: ALL, tmpfs /tmp to docker-compose.yml
- Single-source version via importlib.metadata (pyproject.toml → __init__.py)
- Add open_timeout to all websockets.connect() calls

Tests:
- Update error message matchers to match sanitised messages (test_client.py)
- Fix patch targets for UNRAID_API_URL → utils module (test_subscriptions.py)
- Fix importance="info" → importance="normal" (test_notifications.py, http_layer)
- Fix naive datetime fixtures → UTC-aware (test_subscriptions.py)

Co-authored-by: Claude <claude@anthropic.com>

unraid_mcp/tools/storage.py

@@ -4,17 +4,19 @@ Provides the `unraid_storage` tool with 6 actions for shares, physical disks,
 unassigned devices, log files, and log content retrieval.
 """
 
+import os
 from typing import Any, Literal
 
-import anyio
 from fastmcp import FastMCP
 
 from ..config.logging import logger
 from ..core.client import DISK_TIMEOUT, make_graphql_request
-from ..core.exceptions import ToolError
+from ..core.exceptions import ToolError, tool_error_handler
+from ..core.utils import format_bytes
 
 
 _ALLOWED_LOG_PREFIXES = ("/var/log/", "/boot/logs/", "/mnt/")
+_MAX_TAIL_LINES = 10_000
 
 QUERIES: dict[str, str] = {
     "shares": """
@@ -56,6 +58,8 @@ QUERIES: dict[str, str] = {
     """,
 }
 
+ALL_ACTIONS = set(QUERIES)
+
 STORAGE_ACTIONS = Literal[
     "shares",
     "disks",
@@ -66,21 +70,6 @@ STORAGE_ACTIONS = Literal[
 ]
 
 
-def format_bytes(bytes_value: int | None) -> str:
-    """Format byte values into human-readable sizes."""
-    if bytes_value is None:
-        return "N/A"
-    try:
-        value = float(int(bytes_value))
-    except (ValueError, TypeError):
-        return "N/A"
-    for unit in ["B", "KB", "MB", "GB", "TB", "PB"]:
-        if value < 1024.0:
-            return f"{value:.2f} {unit}"
-        value /= 1024.0
-    return f"{value:.2f} EB"
-
-
 def register_storage_tool(mcp: FastMCP) -> None:
     """Register the unraid_storage tool with the FastMCP instance."""
 
@@ -101,17 +90,22 @@ def register_storage_tool(mcp: FastMCP) -> None:
           log_files - List available log files
           logs - Retrieve log content (requires log_path, optional tail_lines)
         """
-        if action not in QUERIES:
-            raise ToolError(f"Invalid action '{action}'. Must be one of: {list(QUERIES.keys())}")
+        if action not in ALL_ACTIONS:
+            raise ToolError(f"Invalid action '{action}'. Must be one of: {sorted(ALL_ACTIONS)}")
 
         if action == "disk_details" and not disk_id:
             raise ToolError("disk_id is required for 'disk_details' action")
 
+        if tail_lines < 1 or tail_lines > _MAX_TAIL_LINES:
+            raise ToolError(f"tail_lines must be between 1 and {_MAX_TAIL_LINES}, got {tail_lines}")
+
         if action == "logs":
             if not log_path:
                 raise ToolError("log_path is required for 'logs' action")
-            # Resolve path to prevent traversal attacks (e.g. /var/log/../../etc/shadow)
-            normalized = str(await anyio.Path(log_path).resolve())
+            # Resolve path synchronously to prevent traversal attacks.
+            # Using os.path.realpath instead of anyio.Path.resolve() because the
+            # async variant blocks on NFS-mounted paths under /mnt/ (Perf-AI-1).
+            normalized = os.path.realpath(log_path)  # noqa: ASYNC240
             if not any(normalized.startswith(p) for p in _ALLOWED_LOG_PREFIXES):
                 raise ToolError(
                     f"log_path must start with one of: {', '.join(_ALLOWED_LOG_PREFIXES)}. "
@@ -128,17 +122,15 @@ def register_storage_tool(mcp: FastMCP) -> None:
         elif action == "logs":
             variables = {"path": log_path, "lines": tail_lines}
 
-        try:
+        with tool_error_handler("storage", action, logger):
             logger.info(f"Executing unraid_storage action={action}")
             data = await make_graphql_request(query, variables, custom_timeout=custom_timeout)
 
             if action == "shares":
-                shares = data.get("shares", [])
-                return {"shares": list(shares) if isinstance(shares, list) else []}
+                return {"shares": data.get("shares", [])}
 
             if action == "disks":
-                disks = data.get("disks", [])
-                return {"disks": list(disks) if isinstance(disks, list) else []}
+                return {"disks": data.get("disks", [])}
 
             if action == "disk_details":
                 raw = data.get("disk", {})
@@ -159,22 +151,14 @@ def register_storage_tool(mcp: FastMCP) -> None:
                 return {"summary": summary, "details": raw}
 
             if action == "unassigned":
-                devices = data.get("unassignedDevices", [])
-                return {"devices": list(devices) if isinstance(devices, list) else []}
+                return {"devices": data.get("unassignedDevices", [])}
 
             if action == "log_files":
-                files = data.get("logFiles", [])
-                return {"log_files": list(files) if isinstance(files, list) else []}
+                return {"log_files": data.get("logFiles", [])}
 
             if action == "logs":
                 return dict(data.get("logFile") or {})
 
             raise ToolError(f"Unhandled action '{action}' — this is a bug")
 
-        except ToolError:
-            raise
-        except Exception as e:
-            logger.error(f"Error in unraid_storage action={action}: {e}", exc_info=True)
-            raise ToolError(f"Failed to execute storage/{action}: {e!s}") from e
-
     logger.info("Storage tool registered successfully")