collapsarr 0.1.3__py3-none-any.whl

collapsarr/__init__.py

@@ -0,0 +1,15 @@
+"""Collapsarr — an *arr-family companion app.
+
+Detects monitored media files that are missing a lower-channel-count audio
+track and adds one via FFmpeg, without ever touching the original track.
+
+This package hosts the FastAPI backend. The public entry points are
+:func:`collapsarr.main.create_app` (the application factory) and the
+module-level ``app`` instance it builds.
+"""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

collapsarr/__main__.py

@@ -0,0 +1,25 @@
+"""Console entry point: ``python -m collapsarr`` (and the ``collapsarr`` script).
+
+Starts the ASGI server bound to the configured host/port.
+"""
+
+from __future__ import annotations
+
+from .config import get_settings
+
+
+def main() -> None:
+    """Run the Collapsarr API server using the configured host and port."""
+    import uvicorn
+
+    settings = get_settings()
+    uvicorn.run(
+        "collapsarr.main:app",
+        host=settings.host,
+        port=settings.port,
+        log_level=settings.log_level.lower(),
+    )
+
+
+if __name__ == "__main__":
+    main()

collapsarr/arr/__init__.py

@@ -0,0 +1,76 @@
+"""Sonarr/Radarr instance connection management (COL-11, COL-12, COL-13, COL-14).
+
+Home for arr-integration concerns per ``docs/TRACKER.md``: instance config
+model, connectivity/version checks, the monitored-file-list client, remote
+path mapping, and the inbound import/upgrade webhook handler.
+
+This module is imported for its side effect of registering
+:class:`~collapsarr.arr.models.ArrInstance` with
+:data:`collapsarr.database.Base.metadata` — see
+:func:`collapsarr.database.init_db`.
+"""
+
+from __future__ import annotations
+
+from .client import ConnectivityResult, check_connectivity
+from .files import AudioInfo, MonitoredFile, fetch_monitored_files
+from .models import ArrInstance, ConnectivityStatus, InstanceType, RemotePathMapping, resolve_path
+from .service import (
+    InstanceNotFoundError,
+    PathMappingNotFoundError,
+    create_instance,
+    create_path_mapping,
+    delete_instance,
+    delete_path_mapping,
+    get_instance,
+    get_path_mapping,
+    list_instances,
+    list_path_mappings,
+    update_instance,
+    update_path_mapping,
+)
+from .webhooks import (
+    OnFileReadyHook,
+    ResolvedWebhookFile,
+    WebhookFile,
+    WebhookValidationError,
+    default_on_file_ready_hook,
+    parse_radarr_webhook,
+    parse_sonarr_webhook,
+    parse_webhook_payload,
+    resolve_webhook_file,
+)
+
+__all__ = [
+    "ArrInstance",
+    "AudioInfo",
+    "ConnectivityResult",
+    "ConnectivityStatus",
+    "InstanceNotFoundError",
+    "InstanceType",
+    "MonitoredFile",
+    "OnFileReadyHook",
+    "PathMappingNotFoundError",
+    "RemotePathMapping",
+    "ResolvedWebhookFile",
+    "WebhookFile",
+    "WebhookValidationError",
+    "check_connectivity",
+    "create_instance",
+    "create_path_mapping",
+    "default_on_file_ready_hook",
+    "delete_instance",
+    "delete_path_mapping",
+    "fetch_monitored_files",
+    "get_instance",
+    "get_path_mapping",
+    "list_instances",
+    "list_path_mappings",
+    "parse_radarr_webhook",
+    "parse_sonarr_webhook",
+    "parse_webhook_payload",
+    "resolve_path",
+    "resolve_webhook_file",
+    "update_instance",
+    "update_path_mapping",
+]

collapsarr/arr/client.py

@@ -0,0 +1,71 @@
+"""HTTP client for validating connectivity to a Sonarr/Radarr instance.
+
+Sonarr and Radarr expose an identical ``/api/v3/system/status`` endpoint
+(authenticated via the ``X-Api-Key`` header) that returns instance metadata
+including its running version. :func:`check_connectivity` calls it and
+reports success/failure without ever raising, so callers can persist the
+result unconditionally.
+
+Tests inject a ``transport`` (``httpx.MockTransport``) built from recorded
+fixture responses instead of making real network calls.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+_STATUS_PATH = "/api/v3/system/status"
+_DEFAULT_TIMEOUT = 10.0
+_ERROR_BODY_LIMIT = 500
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectivityResult:
+    """Outcome of a connectivity/version check against an Arr instance."""
+
+    ok: bool
+    version: str | None = None
+    error: str | None = None
+
+
+def check_connectivity(
+    base_url: str,
+    api_key: str,
+    *,
+    timeout: float = _DEFAULT_TIMEOUT,
+    transport: httpx.BaseTransport | None = None,
+) -> ConnectivityResult:
+    """Call the instance's system/status endpoint and report the result.
+
+    Never raises: network errors, timeouts, non-2xx responses, and malformed
+    payloads are all captured as a failed :class:`ConnectivityResult` so the
+    service layer can persist success/failure state without a try/except.
+    """
+    url = f"{base_url.rstrip('/')}{_STATUS_PATH}"
+    if transport is not None:
+        client = httpx.Client(timeout=timeout, transport=transport)
+    else:
+        client = httpx.Client(timeout=timeout)
+
+    try:
+        with client:
+            response = client.get(url, headers={"X-Api-Key": api_key})
+        response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        detail = f"HTTP {exc.response.status_code}: {exc.response.text}"[:_ERROR_BODY_LIMIT]
+        return ConnectivityResult(ok=False, error=detail)
+    except httpx.HTTPError as exc:
+        return ConnectivityResult(ok=False, error=str(exc))
+
+    try:
+        payload = response.json()
+    except ValueError:
+        return ConnectivityResult(ok=False, error="Invalid JSON in status response")
+
+    version = payload.get("version") if isinstance(payload, dict) else None
+    if not isinstance(version, str) or not version:
+        return ConnectivityResult(ok=False, error="Status response missing 'version' field")
+
+    return ConnectivityResult(ok=True, version=version)

collapsarr/arr/files.py

@@ -0,0 +1,211 @@
+"""Pull the monitored media-file list from a configured Sonarr/Radarr instance.
+
+Per the PRD, Collapsarr discovers work by pulling *monitored* file lists from
+the Arr APIs rather than scanning arbitrary folders itself. Sonarr and Radarr
+expose that information differently:
+
+- Sonarr has no single "all monitored episode files" endpoint. Series are
+  fetched via ``GET /api/v3/series`` (each with a ``monitored`` flag), and for
+  every *monitored* series its files are fetched via
+  ``GET /api/v3/episodefile?seriesId=<id>``.
+- Radarr's ``GET /api/v3/movie`` returns every movie in one call, each with
+  ``monitored``/``hasFile`` flags and (when present) an embedded
+  ``movieFile`` object — no second request needed.
+
+Both variants are normalized to the same :class:`MonitoredFile` shape and
+reached through the single :func:`fetch_monitored_files` entry point, which
+dispatches on :attr:`~collapsarr.arr.models.ArrInstance.type` so callers don't
+need to special-case Sonarr vs. Radarr.
+
+Audio metadata is taken from the Arr APIs' ``mediaInfo`` block, which reports
+*aggregate* fields (codec, total channel count, language list, stream count)
+rather than a per-stream breakdown — that is the granularity normalized into
+:class:`AudioInfo`. A per-stream probe (e.g. via ffprobe) is out of scope here.
+
+Unlike :func:`collapsarr.arr.client.check_connectivity`, which never raises so
+a connectivity outcome can always be persisted, this module lets
+``httpx.HTTPError`` propagate: a failed fetch has no sensible default (an
+empty list would be indistinguishable from "no monitored files"), so callers
+decide how to handle it.
+
+Tests inject a ``transport`` (``httpx.MockTransport``) built from recorded
+fixture responses instead of making real network calls.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+from .models import ArrInstance, InstanceType
+
+_SERIES_PATH = "/api/v3/series"
+_EPISODE_FILE_PATH = "/api/v3/episodefile"
+_MOVIE_PATH = "/api/v3/movie"
+_DEFAULT_TIMEOUT = 10.0
+
+
+@dataclass(frozen=True, slots=True)
+class AudioInfo:
+    """Aggregate audio-stream metadata as exposed by an Arr API's ``mediaInfo``.
+
+    All fields are ``None`` when the underlying file has no ``mediaInfo``
+    block, or when a given sub-field wasn't present/wasn't of the expected
+    type.
+    """
+
+    codec: str | None = None
+    channels: float | None = None
+    languages: str | None = None
+    stream_count: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class MonitoredFile:
+    """A single monitored media file, normalized across Sonarr and Radarr."""
+
+    instance_id: int
+    media_title: str
+    file_path: str
+    source_file_id: int | None = None
+    audio: AudioInfo | None = None
+
+
+def fetch_monitored_files(
+    instance: ArrInstance,
+    *,
+    timeout: float = _DEFAULT_TIMEOUT,
+    transport: httpx.BaseTransport | None = None,
+) -> list[MonitoredFile]:
+    """Fetch the normalized monitored-file list for a configured instance.
+
+    Dispatches to the Sonarr or Radarr variant based on ``instance.type`` —
+    both return the same :class:`MonitoredFile` shape.
+
+    Raises:
+        httpx.HTTPError: on a network failure or a non-2xx response from the
+            instance. This function does not swallow errors the way
+            :func:`collapsarr.arr.client.check_connectivity` does.
+    """
+    if instance.type is InstanceType.SONARR:
+        return _fetch_sonarr_files(instance, timeout=timeout, transport=transport)
+    if instance.type is InstanceType.RADARR:
+        return _fetch_radarr_files(instance, timeout=timeout, transport=transport)
+    raise ValueError(f"Unsupported instance type: {instance.type!r}")  # pragma: no cover
+
+
+def _build_client(timeout: float, transport: httpx.BaseTransport | None) -> httpx.Client:
+    if transport is not None:
+        return httpx.Client(timeout=timeout, transport=transport)
+    return httpx.Client(timeout=timeout)
+
+
+def _extract_audio_info(media_info: object) -> AudioInfo | None:
+    """Normalize an Arr ``mediaInfo`` block into :class:`AudioInfo`, or ``None``."""
+    if not isinstance(media_info, dict):
+        return None
+
+    codec = media_info.get("audioCodec")
+    channels = media_info.get("audioChannels")
+    languages = media_info.get("audioLanguages")
+    stream_count = media_info.get("audioStreamCount")
+
+    return AudioInfo(
+        codec=codec if isinstance(codec, str) else None,
+        channels=float(channels) if isinstance(channels, int | float) else None,
+        languages=languages if isinstance(languages, str) else None,
+        stream_count=stream_count if isinstance(stream_count, int) else None,
+    )
+
+
+def _fetch_sonarr_files(
+    instance: ArrInstance, *, timeout: float, transport: httpx.BaseTransport | None
+) -> list[MonitoredFile]:
+    base_url = instance.base_url.rstrip("/")
+    headers = {"X-Api-Key": instance.api_key}
+    results: list[MonitoredFile] = []
+
+    with _build_client(timeout, transport) as client:
+        series_response = client.get(f"{base_url}{_SERIES_PATH}", headers=headers)
+        series_response.raise_for_status()
+        series_list = series_response.json()
+        if not isinstance(series_list, list):
+            return results
+
+        for series in series_list:
+            if not isinstance(series, dict) or not series.get("monitored"):
+                continue
+            series_id = series.get("id")
+            series_title = series.get("title")
+            if series_id is None or not isinstance(series_title, str):
+                continue
+
+            files_response = client.get(
+                f"{base_url}{_EPISODE_FILE_PATH}",
+                params={"seriesId": series_id},
+                headers=headers,
+            )
+            files_response.raise_for_status()
+            episode_files = files_response.json()
+            if not isinstance(episode_files, list):
+                continue
+
+            for episode_file in episode_files:
+                if not isinstance(episode_file, dict):
+                    continue
+                path = episode_file.get("path")
+                if not isinstance(path, str) or not path:
+                    continue
+                file_id = episode_file.get("id")
+                results.append(
+                    MonitoredFile(
+                        instance_id=instance.id,
+                        media_title=series_title,
+                        file_path=path,
+                        source_file_id=file_id if isinstance(file_id, int) else None,
+                        audio=_extract_audio_info(episode_file.get("mediaInfo")),
+                    )
+                )
+
+    return results
+
+
+def _fetch_radarr_files(
+    instance: ArrInstance, *, timeout: float, transport: httpx.BaseTransport | None
+) -> list[MonitoredFile]:
+    base_url = instance.base_url.rstrip("/")
+    headers = {"X-Api-Key": instance.api_key}
+    results: list[MonitoredFile] = []
+
+    with _build_client(timeout, transport) as client:
+        response = client.get(f"{base_url}{_MOVIE_PATH}", headers=headers)
+        response.raise_for_status()
+        movies = response.json()
+        if not isinstance(movies, list):
+            return results
+
+        for movie in movies:
+            if not isinstance(movie, dict):
+                continue
+            if not movie.get("monitored") or not movie.get("hasFile"):
+                continue
+            movie_file = movie.get("movieFile")
+            if not isinstance(movie_file, dict):
+                continue
+            path = movie_file.get("path")
+            title = movie.get("title")
+            if not isinstance(path, str) or not path or not isinstance(title, str):
+                continue
+            file_id = movie_file.get("id")
+            results.append(
+                MonitoredFile(
+                    instance_id=instance.id,
+                    media_title=title,
+                    file_path=path,
+                    source_file_id=file_id if isinstance(file_id, int) else None,
+                    audio=_extract_audio_info(movie_file.get("mediaInfo")),
+                )
+            )
+
+    return results

collapsarr/arr/models.py

@@ -0,0 +1,147 @@
+"""ORM model for a configured Sonarr/Radarr instance connection.
+
+Each :class:`ArrInstance` row is a single Sonarr or Radarr connection: a name,
+its type, where to reach it, and the API key to authenticate with. Instances
+of either type coexist independently — nothing here assumes at most one
+Sonarr or one Radarr.
+
+Connectivity is not verified at the model layer; :mod:`collapsarr.arr.service`
+calls :mod:`collapsarr.arr.client` on save and stores the outcome in the
+``status``/``status_error``/``version``/``status_checked_at`` columns.
+"""
+
+from __future__ import annotations
+
+import enum
+from datetime import UTC, datetime
+
+from sqlalchemy import Enum as SAEnum
+from sqlalchemy import ForeignKey, Integer, String, Text, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+
+from collapsarr.database import Base
+
+
+class InstanceType(enum.StrEnum):
+    """The two supported *arr backends."""
+
+    SONARR = "sonarr"
+    RADARR = "radarr"
+
+
+class ConnectivityStatus(enum.StrEnum):
+    """Outcome of the most recent connectivity/version check for an instance."""
+
+    UNKNOWN = "unknown"
+    OK = "ok"
+    ERROR = "error"
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class ArrInstance(Base):
+    """A configured Sonarr or Radarr connection.
+
+    ``base_url`` and ``api_key`` are the only fields required to talk to the
+    remote instance; the ``status*``/``version`` columns cache the result of
+    the last connectivity check performed by the service layer on save.
+    """
+
+    __tablename__ = "arr_instances"
+    __table_args__ = (UniqueConstraint("name", name="uq_arr_instances_name"),)
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(100), nullable=False, index=True)
+    type: Mapped[InstanceType] = mapped_column(
+        SAEnum(
+            InstanceType,
+            values_callable=lambda enum_cls: [member.value for member in enum_cls],
+        ),
+        nullable=False,
+        index=True,
+    )
+    base_url: Mapped[str] = mapped_column(String(500), nullable=False)
+    api_key: Mapped[str] = mapped_column(String(255), nullable=False)
+
+    status: Mapped[ConnectivityStatus] = mapped_column(
+        SAEnum(
+            ConnectivityStatus,
+            values_callable=lambda enum_cls: [member.value for member in enum_cls],
+        ),
+        nullable=False,
+        default=ConnectivityStatus.UNKNOWN,
+    )
+    status_error: Mapped[str | None] = mapped_column(Text, nullable=True, default=None)
+    status_checked_at: Mapped[datetime | None] = mapped_column(nullable=True, default=None)
+    version: Mapped[str | None] = mapped_column(String(50), nullable=True, default=None)
+
+    created_at: Mapped[datetime] = mapped_column(default=_utcnow)
+    updated_at: Mapped[datetime] = mapped_column(default=_utcnow, onupdate=_utcnow)
+
+    def __repr__(self) -> str:
+        return f"ArrInstance(id={self.id!r}, name={self.name!r}, type={self.type!r})"
+
+
+class RemotePathMapping(Base):
+    """A remote-to-local path prefix mapping for an ArrInstance.
+
+    Ordered mappings allow Collapsarr to translate container-relative paths
+    (e.g., ``/tv/Show/Season 01/file.mkv`` reported by a Sonarr/Radarr API
+    running in Docker) into host-local paths (e.g., ``/mnt/media/...``) that
+    Collapsarr can actually read/write on disk.
+
+    Mappings are applied in order; the first matching remote_prefix wins.
+    Unmapped paths pass through unchanged.
+    """
+
+    __tablename__ = "remote_path_mappings"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    instance_id: Mapped[int] = mapped_column(
+        ForeignKey("arr_instances.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    remote_prefix: Mapped[str] = mapped_column(String(500), nullable=False)
+    local_prefix: Mapped[str] = mapped_column(String(500), nullable=False)
+    order: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
+    created_at: Mapped[datetime] = mapped_column(default=_utcnow)
+    updated_at: Mapped[datetime] = mapped_column(default=_utcnow, onupdate=_utcnow)
+
+    def __repr__(self) -> str:
+        return (
+            f"RemotePathMapping(id={self.id!r}, instance_id={self.instance_id!r}, "
+            f"remote_prefix={self.remote_prefix!r}, local_prefix={self.local_prefix!r})"
+        )
+
+
+def resolve_path(
+    file_path: str, mappings: list[RemotePathMapping] | None = None
+) -> str:
+    """Resolve a remote file path to a local path using configured mappings.
+
+    Applies the ordered list of path mappings to transform a file path as
+    reported by a Sonarr/Radarr API (e.g., a container-relative path) into
+    the local file path Collapsarr can actually read/write on disk.
+
+    The first mapping whose ``remote_prefix`` matches the start of
+    ``file_path`` is applied; subsequent mappings are ignored. If no mapping
+    matches, the original ``file_path`` is returned unchanged.
+
+    Args:
+        file_path: The path to resolve (typically as reported by Arr API).
+        mappings: Ordered list of RemotePathMapping objects. When ``None`` or
+            empty, ``file_path`` is returned unchanged.
+
+    Returns:
+        The resolved local path, or ``file_path`` if no mapping applies.
+    """
+    if not mappings:
+        return file_path
+
+    for mapping in mappings:
+        if file_path.startswith(mapping.remote_prefix):
+            return file_path.replace(mapping.remote_prefix, mapping.local_prefix, 1)
+
+    return file_path