collapsarr 0.1.3__py3-none-any.whl

collapsarr/arr/routes.py

@@ -0,0 +1,290 @@
+"""HTTP REST endpoints for arr instance config & path mappings (COL-27).
+
+Thin CRUD layer wrapping :mod:`collapsarr.arr.service`, exposed as a FastAPI
+:class:`~fastapi.APIRouter` mounted under ``/api`` by
+:func:`collapsarr.main.create_app`. Because everything under ``/api`` is gated
+by the API-key middleware (COL-26), every route here inherits key-based auth --
+no per-route auth wiring is needed.
+
+Resource shape follows Sonarr/Radarr conventions: an instance is a named
+Sonarr/Radarr connection (``/api/instances``), and remote path mappings are
+managed per instance as a nested sub-resource
+(``/api/instances/{instance_id}/path-mappings``), mirroring how the mappings
+belong to a single instance in the data model. Request/response bodies use the
+same field names as the ORM models so the surface round-trips cleanly.
+
+Service-layer ``LookupError`` subclasses (:class:`~collapsarr.arr.service.
+InstanceNotFoundError`, :class:`~collapsarr.arr.service.PathMappingNotFoundError`)
+are translated to ``404`` responses; creation against a missing instance is
+likewise a ``404``.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, ConfigDict
+from sqlalchemy.orm import Session
+
+from ..database import get_session
+from .models import ConnectivityStatus, InstanceType
+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,
+)
+
+router = APIRouter(prefix="/api", tags=["arr"])
+
+
+# --- schemas -----------------------------------------------------------------
+
+
+class InstanceCreate(BaseModel):
+    """Request body to create an arr instance."""
+
+    name: str
+    type: InstanceType
+    base_url: str
+    api_key: str
+
+
+class InstanceUpdate(BaseModel):
+    """Request body to update an arr instance; omitted fields are left unchanged.
+
+    ``type`` is not updatable -- switching a configured connection between
+    Sonarr and Radarr is a delete-and-recreate, matching the service layer.
+    """
+
+    name: str | None = None
+    base_url: str | None = None
+    api_key: str | None = None
+
+
+class InstanceRead(BaseModel):
+    """Response shape for an arr instance, including cached connectivity state."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    name: str
+    type: InstanceType
+    base_url: str
+    api_key: str
+    status: ConnectivityStatus
+    status_error: str | None
+    status_checked_at: datetime | None
+    version: str | None
+    created_at: datetime
+    updated_at: datetime
+
+
+class PathMappingCreate(BaseModel):
+    """Request body to create a remote path mapping."""
+
+    remote_prefix: str
+    local_prefix: str
+    order: int = 0
+
+
+class PathMappingUpdate(BaseModel):
+    """Request body to update a path mapping; omitted fields are left unchanged."""
+
+    remote_prefix: str | None = None
+    local_prefix: str | None = None
+    order: int | None = None
+
+
+class PathMappingRead(BaseModel):
+    """Response shape for a remote path mapping."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    instance_id: int
+    remote_prefix: str
+    local_prefix: str
+    order: int
+    created_at: datetime
+    updated_at: datetime
+
+
+# --- instance endpoints ------------------------------------------------------
+
+
+@router.get("/instances", response_model=list[InstanceRead])
+def list_instances_endpoint(session: Session = Depends(get_session)) -> list[object]:
+    """List all configured Sonarr/Radarr instances, ordered by id."""
+    return list(list_instances(session))
+
+
+@router.post("/instances", response_model=InstanceRead, status_code=201)
+def create_instance_endpoint(
+    body: InstanceCreate, session: Session = Depends(get_session)
+) -> object:
+    """Create an instance; connectivity is validated and cached on save."""
+    return create_instance(
+        session,
+        name=body.name,
+        instance_type=body.type,
+        base_url=body.base_url,
+        api_key=body.api_key,
+    )
+
+
+@router.get("/instances/{instance_id}", response_model=InstanceRead)
+def get_instance_endpoint(
+    instance_id: int, session: Session = Depends(get_session)
+) -> object:
+    """Fetch a single instance, or ``404`` if it does not exist."""
+    instance = get_instance(session, instance_id)
+    if instance is None:
+        raise HTTPException(status_code=404, detail=f"No arr instance with id={instance_id}")
+    return instance
+
+
+@router.put("/instances/{instance_id}", response_model=InstanceRead)
+def update_instance_endpoint(
+    instance_id: int,
+    body: InstanceUpdate,
+    session: Session = Depends(get_session),
+) -> object:
+    """Update an instance's fields and re-validate connectivity."""
+    try:
+        return update_instance(
+            session,
+            instance_id,
+            name=body.name,
+            base_url=body.base_url,
+            api_key=body.api_key,
+        )
+    except InstanceNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+
+@router.delete("/instances/{instance_id}", status_code=204)
+def delete_instance_endpoint(
+    instance_id: int, session: Session = Depends(get_session)
+) -> None:
+    """Delete an instance (cascades to its path mappings)."""
+    try:
+        delete_instance(session, instance_id)
+    except InstanceNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+
+# --- path-mapping endpoints --------------------------------------------------
+
+
+def _require_instance(session: Session, instance_id: int) -> None:
+    if get_instance(session, instance_id) is None:
+        raise HTTPException(status_code=404, detail=f"No arr instance with id={instance_id}")
+
+
+@router.get(
+    "/instances/{instance_id}/path-mappings",
+    response_model=list[PathMappingRead],
+)
+def list_path_mappings_endpoint(
+    instance_id: int, session: Session = Depends(get_session)
+) -> list[object]:
+    """List an instance's path mappings in application order."""
+    _require_instance(session, instance_id)
+    return list(list_path_mappings(session, instance_id))
+
+
+@router.post(
+    "/instances/{instance_id}/path-mappings",
+    response_model=PathMappingRead,
+    status_code=201,
+)
+def create_path_mapping_endpoint(
+    instance_id: int,
+    body: PathMappingCreate,
+    session: Session = Depends(get_session),
+) -> object:
+    """Create a path mapping under an instance, or ``404`` if it is missing."""
+    try:
+        return create_path_mapping(
+            session,
+            instance_id,
+            remote_prefix=body.remote_prefix,
+            local_prefix=body.local_prefix,
+            order=body.order,
+        )
+    except InstanceNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+
+def _load_mapping(session: Session, instance_id: int, mapping_id: int) -> object:
+    mapping = get_path_mapping(session, mapping_id)
+    if mapping is None or mapping.instance_id != instance_id:
+        raise HTTPException(
+            status_code=404,
+            detail=f"No path mapping with id={mapping_id} for instance id={instance_id}",
+        )
+    return mapping
+
+
+@router.get(
+    "/instances/{instance_id}/path-mappings/{mapping_id}",
+    response_model=PathMappingRead,
+)
+def get_path_mapping_endpoint(
+    instance_id: int,
+    mapping_id: int,
+    session: Session = Depends(get_session),
+) -> object:
+    """Fetch one path mapping, scoped to its instance."""
+    return _load_mapping(session, instance_id, mapping_id)
+
+
+@router.put(
+    "/instances/{instance_id}/path-mappings/{mapping_id}",
+    response_model=PathMappingRead,
+)
+def update_path_mapping_endpoint(
+    instance_id: int,
+    mapping_id: int,
+    body: PathMappingUpdate,
+    session: Session = Depends(get_session),
+) -> object:
+    """Update a path mapping's fields, scoped to its instance."""
+    _load_mapping(session, instance_id, mapping_id)
+    try:
+        return update_path_mapping(
+            session,
+            mapping_id,
+            remote_prefix=body.remote_prefix,
+            local_prefix=body.local_prefix,
+            order=body.order,
+        )
+    except PathMappingNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+
+@router.delete(
+    "/instances/{instance_id}/path-mappings/{mapping_id}",
+    status_code=204,
+)
+def delete_path_mapping_endpoint(
+    instance_id: int,
+    mapping_id: int,
+    session: Session = Depends(get_session),
+) -> None:
+    """Delete a path mapping, scoped to its instance."""
+    _load_mapping(session, instance_id, mapping_id)
+    try:
+        delete_path_mapping(session, mapping_id)
+    except PathMappingNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc

collapsarr/arr/service.py

@@ -0,0 +1,222 @@
+"""Service-layer CRUD for :class:`~collapsarr.arr.models.ArrInstance`.
+
+HTTP exposure is a separate (API) epic's concern — this module is the whole
+surface: plain functions taking a SQLAlchemy :class:`~sqlalchemy.orm.Session`
+and returning/mutating ORM objects. Creating or updating an instance always
+re-validates connectivity via :func:`collapsarr.arr.client.check_connectivity`
+and persists the outcome, per COL-11's acceptance criteria.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+import httpx
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from .client import check_connectivity
+from .models import ArrInstance, ConnectivityStatus, InstanceType, RemotePathMapping
+
+
+class InstanceNotFoundError(LookupError):
+    """Raised when an operation targets an instance id that does not exist."""
+
+
+class PathMappingNotFoundError(LookupError):
+    """Raised when an operation targets a path-mapping id that does not exist."""
+
+
+def _apply_connectivity_check(
+    instance: ArrInstance, *, transport: httpx.BaseTransport | None
+) -> None:
+    """Run the connectivity/version check and stamp its outcome onto ``instance``."""
+    result = check_connectivity(instance.base_url, instance.api_key, transport=transport)
+    instance.status = ConnectivityStatus.OK if result.ok else ConnectivityStatus.ERROR
+    instance.status_error = result.error
+    instance.version = result.version
+    instance.status_checked_at = datetime.now(UTC)
+
+
+def create_instance(
+    session: Session,
+    *,
+    name: str,
+    instance_type: InstanceType,
+    base_url: str,
+    api_key: str,
+    transport: httpx.BaseTransport | None = None,
+) -> ArrInstance:
+    """Create a new instance config and validate connectivity before returning it.
+
+    The row is persisted regardless of whether the connectivity check
+    succeeds — ``status``/``status_error`` record the outcome so failed
+    instances remain visible (and editable) rather than being silently
+    dropped.
+    """
+    instance = ArrInstance(
+        name=name,
+        type=instance_type,
+        base_url=base_url.rstrip("/"),
+        api_key=api_key,
+    )
+    _apply_connectivity_check(instance, transport=transport)
+    session.add(instance)
+    session.commit()
+    session.refresh(instance)
+    return instance
+
+
+def list_instances(session: Session) -> list[ArrInstance]:
+    """Return all configured instances, both types, ordered by id."""
+    return list(session.scalars(select(ArrInstance).order_by(ArrInstance.id)))
+
+
+def get_instance(session: Session, instance_id: int) -> ArrInstance | None:
+    """Return the instance with ``instance_id``, or ``None`` if it doesn't exist."""
+    return session.get(ArrInstance, instance_id)
+
+
+def update_instance(
+    session: Session,
+    instance_id: int,
+    *,
+    name: str | None = None,
+    base_url: str | None = None,
+    api_key: str | None = None,
+    transport: httpx.BaseTransport | None = None,
+) -> ArrInstance:
+    """Update the given fields on an instance and re-validate connectivity.
+
+    Only fields passed explicitly (non-``None``) are changed. Connectivity is
+    re-checked on every save, matching :func:`create_instance`, so a fixed API
+    key or corrected URL is reflected in ``status`` immediately.
+
+    Raises:
+        InstanceNotFoundError: if ``instance_id`` does not exist.
+    """
+    instance = get_instance(session, instance_id)
+    if instance is None:
+        raise InstanceNotFoundError(f"No arr instance with id={instance_id}")
+
+    if name is not None:
+        instance.name = name
+    if base_url is not None:
+        instance.base_url = base_url.rstrip("/")
+    if api_key is not None:
+        instance.api_key = api_key
+
+    _apply_connectivity_check(instance, transport=transport)
+    session.commit()
+    session.refresh(instance)
+    return instance
+
+
+def delete_instance(session: Session, instance_id: int) -> None:
+    """Delete an instance config.
+
+    Raises:
+        InstanceNotFoundError: if ``instance_id`` does not exist.
+    """
+    instance = get_instance(session, instance_id)
+    if instance is None:
+        raise InstanceNotFoundError(f"No arr instance with id={instance_id}")
+    session.delete(instance)
+    session.commit()
+
+
+def list_path_mappings(session: Session, instance_id: int) -> list[RemotePathMapping]:
+    """Return an instance's path mappings in their configured application order.
+
+    Used by the webhook handler (COL-14) to resolve a webhook-reported remote
+    path to a local one via :func:`collapsarr.arr.models.resolve_path`. Does
+    not raise for an unknown ``instance_id`` -- it simply returns an empty
+    list, matching :func:`resolve_path`'s "no mappings" pass-through.
+    """
+    return list(
+        session.scalars(
+            select(RemotePathMapping)
+            .where(RemotePathMapping.instance_id == instance_id)
+            .order_by(RemotePathMapping.order)
+        )
+    )
+
+
+def get_path_mapping(session: Session, mapping_id: int) -> RemotePathMapping | None:
+    """Return the path mapping with ``mapping_id``, or ``None`` if it doesn't exist."""
+    return session.get(RemotePathMapping, mapping_id)
+
+
+def create_path_mapping(
+    session: Session,
+    instance_id: int,
+    *,
+    remote_prefix: str,
+    local_prefix: str,
+    order: int = 0,
+) -> RemotePathMapping:
+    """Create a path mapping for an instance and return it.
+
+    Raises:
+        InstanceNotFoundError: if ``instance_id`` does not exist. Mappings are
+            meaningless without their instance, so creation is rejected rather
+            than leaving a dangling row.
+    """
+    if get_instance(session, instance_id) is None:
+        raise InstanceNotFoundError(f"No arr instance with id={instance_id}")
+
+    mapping = RemotePathMapping(
+        instance_id=instance_id,
+        remote_prefix=remote_prefix,
+        local_prefix=local_prefix,
+        order=order,
+    )
+    session.add(mapping)
+    session.commit()
+    session.refresh(mapping)
+    return mapping
+
+
+def update_path_mapping(
+    session: Session,
+    mapping_id: int,
+    *,
+    remote_prefix: str | None = None,
+    local_prefix: str | None = None,
+    order: int | None = None,
+) -> RemotePathMapping:
+    """Update the given fields on a path mapping and return it.
+
+    Only fields passed explicitly (non-``None``) are changed, matching
+    :func:`update_instance`.
+
+    Raises:
+        PathMappingNotFoundError: if ``mapping_id`` does not exist.
+    """
+    mapping = get_path_mapping(session, mapping_id)
+    if mapping is None:
+        raise PathMappingNotFoundError(f"No path mapping with id={mapping_id}")
+
+    if remote_prefix is not None:
+        mapping.remote_prefix = remote_prefix
+    if local_prefix is not None:
+        mapping.local_prefix = local_prefix
+    if order is not None:
+        mapping.order = order
+
+    session.commit()
+    session.refresh(mapping)
+    return mapping
+
+
+def delete_path_mapping(session: Session, mapping_id: int) -> None:
+    """Delete a path mapping.
+
+    Raises:
+        PathMappingNotFoundError: if ``mapping_id`` does not exist.
+    """
+    mapping = get_path_mapping(session, mapping_id)
+    if mapping is None:
+        raise PathMappingNotFoundError(f"No path mapping with id={mapping_id}")
+    session.delete(mapping)
+    session.commit()