collapsarr 0.1.3__py3-none-any.whl

collapsarr/arr/webhooks.py

@@ -0,0 +1,200 @@
+"""Inbound Sonarr/Radarr "on import"/"on upgrade" webhook handling (COL-14).
+
+Sonarr and Radarr both fire the same webhook event -- ``eventType: "Download"``
+-- for both a fresh import and a quality upgrade, distinguished only by the
+``isUpgrade`` flag on the payload. Other eventTypes (``Test``, ``Grab``,
+``Rename``, ``Health``, ...) are accepted and acknowledged with 200 but not
+otherwise acted on -- that matches Sonarr/Radarr's own webhook UI, whose
+"Test" button expects a 2xx response for any configured event, not just
+Download.
+
+Neither Sonarr's nor Radarr's webhook payload carries an instance identifier
+of its own, so :mod:`collapsarr.main` routes webhooks per configured instance
+(``POST /api/webhook/arr/{instance_id}``) and this module dispatches parsing
+on that instance's ``type`` rather than trying to sniff the payload shape.
+
+Path resolution reuses :func:`collapsarr.arr.models.resolve_path` -- the same
+instance + path-mapping logic used elsewhere -- so a webhook-reported
+container path arrives at the "file ready" hook already translated to a
+host-local path.
+
+The "file ready" hook itself is intentionally pluggable: this module ships a
+stub/log implementation (:func:`default_on_file_ready_hook`), and the Job
+Queue & Scheduler epic (COL-22) wires the real one --
+:meth:`collapsarr.jobs.scheduler.JobScheduler.on_file_ready`, which enqueues a
+downmix job -- in via ``create_app(enable_scheduler=True)``.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .models import ArrInstance, InstanceType, RemotePathMapping, resolve_path
+
+logger = logging.getLogger(__name__)
+
+# The eventType Sonarr/Radarr fire on both a fresh import and an upgrade;
+# distinguished only by the payload's `isUpgrade` flag.
+_DOWNLOAD_EVENT = "Download"
+
+
+class WebhookValidationError(ValueError):
+    """Raised when a webhook payload is malformed for its declared event type."""
+
+
+@dataclass(frozen=True, slots=True)
+class WebhookFile:
+    """File info extracted from a webhook payload, before path resolution."""
+
+    media_title: str
+    file_path: str
+    is_upgrade: bool
+    source_file_id: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedWebhookFile:
+    """A webhook-reported file after instance + path-mapping resolution.
+
+    Normalized the same way :class:`collapsarr.arr.files.MonitoredFile` is,
+    so downstream consumers (e.g. the future Job Queue) see one consistent
+    shape regardless of whether a file was discovered via polling or a
+    webhook.
+    """
+
+    instance_id: int
+    instance_name: str
+    media_title: str
+    file_path: str
+    is_upgrade: bool
+    source_file_id: int | None = None
+
+
+OnFileReadyHook = Callable[[ResolvedWebhookFile], None]
+
+
+def default_on_file_ready_hook(file: ResolvedWebhookFile) -> None:
+    """Stub "file ready" hook: logs the resolved file.
+
+    The default fallback when no scheduler is wired. In production the real
+    hook (:meth:`collapsarr.jobs.scheduler.JobScheduler.on_file_ready`, which
+    enqueues a downmix job) is wired in via ``create_app(enable_scheduler=True)``.
+    """
+    action = "upgraded" if file.is_upgrade else "imported"
+    logger.info(
+        "arr webhook: %s ready (%s) from instance %r (id=%s): %s",
+        action,
+        file.media_title,
+        file.instance_name,
+        file.instance_id,
+        file.file_path,
+    )
+
+
+def _require_dict(value: object, field: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise WebhookValidationError(f"Missing or invalid '{field}' object in webhook payload")
+    return value
+
+
+def _require_str(container: dict[str, Any], field: str) -> str:
+    value = container.get(field)
+    if not isinstance(value, str) or not value:
+        raise WebhookValidationError(f"Missing or invalid '{field}' field in webhook payload")
+    return value
+
+
+def _optional_int(container: dict[str, Any], field: str) -> int | None:
+    value = container.get(field)
+    return value if isinstance(value, int) else None
+
+
+def parse_sonarr_webhook(payload: dict[str, Any]) -> WebhookFile | None:
+    """Parse a Sonarr webhook payload into a :class:`WebhookFile`.
+
+    Returns ``None`` for a valid payload whose ``eventType`` is not
+    ``"Download"`` (import/upgrade) -- those are acknowledged but not acted
+    on. Raises :class:`WebhookValidationError` if a ``Download`` event is
+    missing the ``series``/``episodeFile`` data needed to resolve a file.
+    """
+    event_type = payload.get("eventType")
+    if not isinstance(event_type, str) or not event_type:
+        raise WebhookValidationError("Missing or invalid 'eventType' field in webhook payload")
+    if event_type != _DOWNLOAD_EVENT:
+        return None
+
+    series = _require_dict(payload.get("series"), "series")
+    media_title = _require_str(series, "title")
+
+    episode_file = _require_dict(payload.get("episodeFile"), "episodeFile")
+    file_path = _require_str(episode_file, "path")
+
+    return WebhookFile(
+        media_title=media_title,
+        file_path=file_path,
+        is_upgrade=bool(payload.get("isUpgrade", False)),
+        source_file_id=_optional_int(episode_file, "id"),
+    )
+
+
+def parse_radarr_webhook(payload: dict[str, Any]) -> WebhookFile | None:
+    """Parse a Radarr webhook payload into a :class:`WebhookFile`.
+
+    Mirror of :func:`parse_sonarr_webhook` for Radarr's ``movie``/``movieFile``
+    shape.
+    """
+    event_type = payload.get("eventType")
+    if not isinstance(event_type, str) or not event_type:
+        raise WebhookValidationError("Missing or invalid 'eventType' field in webhook payload")
+    if event_type != _DOWNLOAD_EVENT:
+        return None
+
+    movie = _require_dict(payload.get("movie"), "movie")
+    media_title = _require_str(movie, "title")
+
+    movie_file = _require_dict(payload.get("movieFile"), "movieFile")
+    file_path = _require_str(movie_file, "path")
+
+    return WebhookFile(
+        media_title=media_title,
+        file_path=file_path,
+        is_upgrade=bool(payload.get("isUpgrade", False)),
+        source_file_id=_optional_int(movie_file, "id"),
+    )
+
+
+def parse_webhook_payload(
+    instance_type: InstanceType, payload: dict[str, Any]
+) -> WebhookFile | None:
+    """Dispatch webhook parsing based on the target instance's configured type.
+
+    The payload itself carries no instance identifier or explicit
+    "this is Sonarr/Radarr" marker, so which parser to use is decided by
+    which :class:`~collapsarr.arr.models.ArrInstance` the webhook URL names
+    (looked up by id), not by sniffing the payload shape.
+    """
+    if instance_type is InstanceType.SONARR:
+        return parse_sonarr_webhook(payload)
+    if instance_type is InstanceType.RADARR:
+        return parse_radarr_webhook(payload)
+    msg = f"Unsupported instance type: {instance_type!r}"
+    raise WebhookValidationError(msg)  # pragma: no cover
+
+
+def resolve_webhook_file(
+    instance: ArrInstance,
+    file: WebhookFile,
+    mappings: list[RemotePathMapping] | None = None,
+) -> ResolvedWebhookFile:
+    """Apply instance + path-mapping resolution to a parsed webhook file."""
+    return ResolvedWebhookFile(
+        instance_id=instance.id,
+        instance_name=instance.name,
+        media_title=file.media_title,
+        file_path=resolve_path(file.file_path, mappings),
+        is_upgrade=file.is_upgrade,
+        source_file_id=file.source_file_id,
+    )

collapsarr/auth.py

@@ -0,0 +1,83 @@
+"""API-key authentication for the HTTP API (COL-26).
+
+Every request under the ``/api`` prefix must present the instance's
+auto-generated API key, matching the Sonarr/Radarr convention: the
+``X-Api-Key`` request header (or, as a fallback for callers that can only set a
+query string -- e.g. a Sonarr/Radarr webhook URL -- an ``apikey`` query
+parameter). The key itself lives on the persisted
+:class:`~collapsarr.settings.models.GlobalSettings` row and is minted on first
+run (see :func:`collapsarr.settings.models.generate_api_key`), so it is
+retrievable and rotatable through the same Settings surface as every other
+setting.
+
+Non-``/api`` routes (the ``/health`` liveness probe and the interactive API
+docs) are intentionally left open -- ``/health`` is an unauthenticated probe by
+the same convention Sonarr/Radarr's ``/ping`` follows.
+
+The check is wired as HTTP middleware by
+:func:`collapsarr.main.create_app`; it reads the expected key from the
+request-scoped session factory on ``app.state`` and compares it in constant
+time.
+"""
+
+from __future__ import annotations
+
+import secrets
+from collections.abc import Awaitable, Callable
+
+from fastapi import Request, Response
+from fastapi.responses import JSONResponse
+from sqlalchemy.orm import Session, sessionmaker
+
+from .settings.service import get_global_settings
+
+API_KEY_HEADER = "X-Api-Key"
+"""Request header carrying the API key (Sonarr/Radarr convention)."""
+
+API_KEY_QUERY = "apikey"
+"""Query-parameter fallback for callers that cannot set a custom header."""
+
+PROTECTED_PREFIX = "/api"
+"""Only routes under this path prefix require the API key."""
+
+
+def _extract_key(request: Request) -> str | None:
+    """Return the presented API key from the header, then query string, if any."""
+    header = request.headers.get(API_KEY_HEADER)
+    if header:
+        return header
+    return request.query_params.get(API_KEY_QUERY) or None
+
+
+def _requires_api_key(path: str) -> bool:
+    """Whether ``path`` is a protected API route (i.e. under ``/api``)."""
+    return path.startswith(PROTECTED_PREFIX)
+
+
+async def api_key_middleware(
+    request: Request,
+    call_next: Callable[[Request], Awaitable[Response]],
+) -> Response:
+    """Reject ``/api`` requests lacking a valid API key with ``401``.
+
+    Non-API routes pass straight through. For API routes the expected key is
+    read from the singleton settings row (created on demand, so the very first
+    request already has a key to check against) and compared to the presented
+    one in constant time; a missing or mismatched key yields a ``401`` before
+    the route handler ever runs.
+    """
+    if not _requires_api_key(request.url.path):
+        return await call_next(request)
+
+    session_factory: sessionmaker[Session] = request.app.state.session_factory
+    with session_factory() as session:
+        expected: str = get_global_settings(session).api_key
+
+    provided = _extract_key(request)
+    if provided is None or not secrets.compare_digest(provided, expected):
+        return JSONResponse(
+            status_code=401,
+            content={"detail": "Invalid or missing API key."},
+        )
+
+    return await call_next(request)

collapsarr/config.py

@@ -0,0 +1,95 @@
+"""Application configuration.
+
+All settings load from environment variables (prefix ``COLLAPSARR_``) with the
+documented defaults below, so a bare ``docker run`` or ``pip install`` works
+without any configuration. An optional ``.env`` file in the working directory is
+also read (see ``.env.example``).
+
+Documented environment variables and their defaults:
+
+===============================  ==========================  ==================================
+Environment variable             Default                     Description
+===============================  ==========================  ==================================
+``COLLAPSARR_DATABASE_PATH``     ``/config/collapsarr.db``   Filesystem path to the SQLite DB.
+``COLLAPSARR_DATABASE_URL``      *(derived from path)*       Full SQLAlchemy URL override.
+``COLLAPSARR_HOST``              ``0.0.0.0``                 Bind address for the API server.
+``COLLAPSARR_PORT``              ``8282``                    Bind port for the API server.
+``COLLAPSARR_LOG_LEVEL``         ``INFO``                    Log level (passed to uvicorn).
+``COLLAPSARR_JOB_MAX_CONCURRENCY`` ``1``                      Max downmix jobs run concurrently.
+``COLLAPSARR_SCAN_INTERVAL_HOURS`` ``6.0``                    Hours between periodic library scans.
+===============================  ==========================  ==================================
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Runtime configuration sourced from the environment.
+
+    Values are read once at process start. Use :func:`get_settings` to obtain
+    the cached singleton; construct :class:`Settings` directly (e.g. in tests)
+    when you need an isolated, overridden configuration.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="COLLAPSARR_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    database_path: str = Field(
+        default="/config/collapsarr.db",
+        description="Filesystem path to the SQLite database file.",
+    )
+    database_url: str | None = Field(
+        default=None,
+        description="Full SQLAlchemy database URL. Overrides database_path when set.",
+    )
+
+    host: str = Field(default="0.0.0.0", description="API server bind address.")
+    port: int = Field(default=8282, description="API server bind port.")
+    log_level: str = Field(default="INFO", description="Log level for the server.")
+    job_max_concurrency: int = Field(
+        default=1,
+        ge=1,
+        description=(
+            "Maximum number of downmix jobs the job queue (collapsarr.jobs) runs "
+            "concurrently. Read by JobQueue.from_settings()."
+        ),
+    )
+    scan_interval_hours: float = Field(
+        default=6.0,
+        gt=0,
+        description=(
+            "Interval, in hours, between periodic full-library scans that enqueue "
+            "downmix jobs for monitored files with qualifying targets. Read by the "
+            "background scheduler (collapsarr.jobs.scheduler.JobScheduler), which "
+            "also uses it as the de-duplication window: a file whose most recent job "
+            "reached a terminal state within this window is not re-enqueued, so a "
+            "webhook and a scheduled scan overlapping within one cycle can't "
+            "double-enqueue it."
+        ),
+    )
+
+    @property
+    def sqlalchemy_url(self) -> str:
+        """Resolve the effective SQLAlchemy database URL.
+
+        Uses ``database_url`` verbatim when provided, otherwise builds a SQLite
+        URL from ``database_path``.
+        """
+        if self.database_url:
+            return self.database_url
+        return f"sqlite:///{self.database_path}"
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """Return the process-wide cached :class:`Settings` instance."""
+    return Settings()

collapsarr/database.py

@@ -0,0 +1,82 @@
+"""Database engine, session factory, and ORM base.
+
+SQLAlchemy 2.0 style. The engine and session factory are built from
+:class:`~collapsarr.config.Settings` so tests can point them at a throwaway
+SQLite path. Both are attached to ``app.state`` in the application factory and
+consumed by request handlers via the :func:`get_session` dependency.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+
+from fastapi import Request
+from sqlalchemy import Engine, create_engine
+from sqlalchemy.orm import DeclarativeBase, Session, sessionmaker
+
+from .config import Settings
+
+
+class Base(DeclarativeBase):
+    """Declarative base class shared by all Collapsarr ORM models.
+
+    Feature tickets (instances, tracked media, job queue, settings) define their
+    tables against this base so a single ``Base.metadata`` drives schema
+    creation.
+    """
+
+
+def create_engine_from_settings(settings: Settings) -> Engine:
+    """Create a SQLAlchemy :class:`Engine` from application settings.
+
+    For file-based SQLite URLs the parent directory is created if missing (the
+    ``/config`` volume in the Docker image), and ``check_same_thread`` is
+    disabled so the connection can be shared across FastAPI's worker threads.
+    """
+    url = settings.sqlalchemy_url
+    connect_args: dict[str, object] = {}
+
+    if url.startswith("sqlite"):
+        connect_args["check_same_thread"] = False
+        # Ensure the directory for a file-based SQLite DB exists.
+        if settings.database_url is None and settings.database_path != ":memory:":
+            db_path = Path(settings.database_path).expanduser()
+            db_path.parent.mkdir(parents=True, exist_ok=True)
+
+    return create_engine(url, connect_args=connect_args, future=True)
+
+
+def create_session_factory(engine: Engine) -> sessionmaker[Session]:
+    """Build a configured :class:`sessionmaker` bound to ``engine``."""
+    return sessionmaker(
+        bind=engine,
+        autoflush=False,
+        autocommit=False,
+        expire_on_commit=False,
+    )
+
+
+def init_db(engine: Engine) -> None:
+    """Create any tables registered on :class:`Base` that do not yet exist.
+
+    Feature packages (e.g. :mod:`collapsarr.arr`) are imported here, not at
+    module scope, so their models register with ``Base.metadata`` before
+    ``create_all`` runs without introducing an import-time cycle back to this
+    module (they import :class:`Base` from here).
+    """
+    from . import arr, jobs, media, notify, settings  # noqa: F401
+
+    Base.metadata.create_all(bind=engine)
+
+
+def get_session(request: Request) -> Iterator[Session]:
+    """FastAPI dependency yielding a request-scoped :class:`Session`.
+
+    The session factory is read from ``app.state`` (set up in the application
+    factory's lifespan), so each request gets a fresh session that is closed
+    when the request finishes.
+    """
+    session_factory: sessionmaker[Session] = request.app.state.session_factory
+    with session_factory() as session:
+        yield session

collapsarr/downmix/__init__.py

@@ -0,0 +1,54 @@
+"""Downmix engine: channel-layout detection, target selection, FFmpeg remux (COL-15+).
+
+Home for downmix-engine concerns per ``docs/TRACKER.md``: FFprobe-based
+audio-stream inspection, no-upmix target detection, the FFmpeg remux itself,
+and validate + atomic swap.
+"""
+
+from __future__ import annotations
+
+from .apply import (
+    DEFAULT_DURATION_TOLERANCE_SECONDS,
+    ApplyFailureReason,
+    ApplyResult,
+    apply_remux_result,
+)
+from .pipeline import PipelineOutcome, PipelineResult, run_downmix_pipeline
+from .probe import (
+    AudioStreamInfo,
+    FfprobeError,
+    FfprobeNotFoundError,
+    MediaSummary,
+    probe_audio_streams,
+    probe_media_summary,
+)
+from .remux import RemuxResult, build_remux_command, run_remux
+from .targets import (
+    DownmixSettings,
+    DownmixTarget,
+    QualifyingTarget,
+    detect_qualifying_targets,
+)
+
+__all__ = [
+    "DEFAULT_DURATION_TOLERANCE_SECONDS",
+    "ApplyFailureReason",
+    "ApplyResult",
+    "AudioStreamInfo",
+    "DownmixSettings",
+    "DownmixTarget",
+    "FfprobeError",
+    "FfprobeNotFoundError",
+    "MediaSummary",
+    "PipelineOutcome",
+    "PipelineResult",
+    "QualifyingTarget",
+    "RemuxResult",
+    "apply_remux_result",
+    "build_remux_command",
+    "detect_qualifying_targets",
+    "probe_audio_streams",
+    "probe_media_summary",
+    "run_downmix_pipeline",
+    "run_remux",
+]