feat(server): add anime_service wrapper, unit tests, update docs

src/server/services/anime_service.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+from functools import lru_cache
+from typing import List, Optional
+
+import structlog
+
+from src.core.SeriesApp import SeriesApp
+
+logger = structlog.get_logger(__name__)
+
+
+class AnimeServiceError(Exception):
+    """Service-level exception for anime operations."""
+
+
+class AnimeService:
+    """Wraps the blocking SeriesApp for use in the FastAPI web layer.
+
+    - Runs blocking operations in a threadpool
+    - Exposes async methods
+    - Adds simple in-memory caching for read operations
+    """
+
+    def __init__(self, directory: str, max_workers: int = 4):
+        self._directory = directory
+        self._executor = ThreadPoolExecutor(max_workers=max_workers)
+        # SeriesApp is blocking; instantiate per-service
+        try:
+            self._app = SeriesApp(directory)
+        except Exception as e:
+            logger.exception("Failed to initialize SeriesApp")
+            raise AnimeServiceError("Initialization failed") from e
+
+    async def _run_in_executor(self, func, *args, **kwargs):
+        loop = asyncio.get_event_loop()
+        try:
+            return await loop.run_in_executor(self._executor, lambda: func(*args, **kwargs))
+        except Exception as e:
+            logger.exception("Executor task failed")
+            raise AnimeServiceError(str(e)) from e
+
+    @lru_cache(maxsize=128)
+    def _cached_list_missing(self) -> List[dict]:
+        # Synchronous cached call used by async wrapper
+        try:
+            series = self._app.series_list
+            # normalize to simple dicts
+            return [s.to_dict() if hasattr(s, "to_dict") else s for s in series]
+        except Exception as e:
+            logger.exception("Failed to get missing episodes list")
+            raise
+
+    async def list_missing(self) -> List[dict]:
+        """Return list of series with missing episodes."""
+        try:
+            return await self._run_in_executor(self._cached_list_missing)
+        except AnimeServiceError:
+            raise
+        except Exception as e:
+            logger.exception("list_missing failed")
+            raise AnimeServiceError("Failed to list missing series") from e
+
+    async def search(self, query: str) -> List[dict]:
+        """Search for series using underlying loader.Search."""
+        if not query:
+            return []
+        try:
+            result = await self._run_in_executor(self._app.search, query)
+            # result may already be list of dicts or objects
+            return result
+        except Exception as e:
+            logger.exception("search failed")
+            raise AnimeServiceError("Search failed") from e
+
+    async def rescan(self, callback=None) -> None:
+        """Trigger a re-scan. Accepts an optional callback function.
+
+        The callback is executed in the threadpool by SeriesApp.
+        """
+        try:
+            await self._run_in_executor(self._app.ReScan, callback)
+            # invalidate cache
+            try:
+                self._cached_list_missing.cache_clear()
+            except Exception:
+                pass
+        except Exception as e:
+            logger.exception("rescan failed")
+            raise AnimeServiceError("Rescan failed") from e
+
+    async def download(self, serie_folder: str, season: int, episode: int, key: str, callback=None) -> bool:
+        """Start a download via the underlying loader.
+
+        Returns True on success or raises AnimeServiceError on failure.
+        """
+        try:
+            result = await self._run_in_executor(self._app.download, serie_folder, season, episode, key, callback)
+            return bool(result)
+        except Exception as e:
+            logger.exception("download failed")
+            raise AnimeServiceError("Download failed") from e
+
+
+def get_anime_service(directory: str = "./") -> AnimeService:
+    """Factory used by FastAPI dependency injection."""
+    return AnimeService(directory)