charmarr-lib-core 0.12.2__py3-none-any.whl

charmarr_lib/core/_arr/_config_builders.py

@@ -0,0 +1,214 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Config builders for transforming relation data into API payloads."""
+
+from collections.abc import Callable
+from urllib.parse import urlparse
+
+from charmarr_lib.core.constants import MEDIA_MANAGER_IMPLEMENTATIONS
+from charmarr_lib.core.enums import DownloadClient, MediaManager
+from charmarr_lib.core.interfaces import (
+    DownloadClientProviderData,
+    MediaIndexerRequirerData,
+)
+
+# Type alias for secret retrieval callback.
+# Takes secret_id, returns dict with secret content (e.g., {"username": "...", "password": "..."})
+SecretGetter = Callable[[str], dict[str, str]]
+
+# Maps media manager types to the category field name in download client API payloads.
+# Each *arr application uses a different field name for the download category.
+_MEDIA_MANAGER_CATEGORY_FIELDS: dict[MediaManager, str] = {
+    MediaManager.RADARR: "movieCategory",
+    MediaManager.SONARR: "tvCategory",
+    MediaManager.LIDARR: "musicCategory",
+    MediaManager.READARR: "bookCategory",
+    MediaManager.WHISPARR: "movieCategory",  # Uses same as Radarr
+}
+
+# Maps media manager types to Prowlarr sync category IDs (NewzNab standard).
+# These are the default categories from Prowlarr's application schema.
+# https://wiki.servarr.com/en/prowlarr/settings#categories
+#
+# NewzNab category ID ranges by media type:
+#   2000-2090: Movies (2000=Movies, 2010=Foreign, 2020=Other, 2030=SD, 2040=HD,
+#              2045=UHD, 2050=BluRay, 2060=3D, 2070=DVD, 2080=WEB-DL, 2090=x265)
+#   3000-3060: Audio (3000=Audio, 3010=MP3, 3020=Video, 3030=Audiobook,
+#              3040=Lossless, 3050=Podcast, 3060=Foreign)
+#   5000-5090: TV (5000=TV, 5010=WEB-DL, 5020=Foreign, 5030=SD, 5040=HD,
+#              5045=UHD, 5050=Other, 5060=Sport, 5070=Anime, 5080=Documentary, 5090=x265)
+#   6000-6090: XXX (same structure as Movies)
+#   7000-7060: Books (7000=Books, 7010=Mags, 7020=EBook, 7030=Comics,
+#              7040=Technical, 7050=Foreign, 7060=Undefined)
+_MEDIA_MANAGER_SYNC_CATEGORIES: dict[MediaManager, list[int]] = {
+    MediaManager.RADARR: [2000, 2010, 2020, 2030, 2040, 2045, 2050, 2060, 2070, 2080, 2090],
+    MediaManager.SONARR: [5000, 5010, 5020, 5030, 5040, 5045, 5050, 5060, 5070, 5080, 5090],
+    MediaManager.LIDARR: [3000, 3010, 3020, 3030, 3040, 3050, 3060],
+    MediaManager.READARR: [7000, 7010, 7020, 7030, 7040, 7050, 7060],
+    MediaManager.WHISPARR: [6000, 6010, 6020, 6030, 6040, 6045, 6050, 6060, 6070, 6080, 6090],
+}
+
+
+class DownloadClientConfigBuilder:
+    """Build download client API payloads from relation data.
+
+    Transforms DownloadClientProviderData into *arr API payloads
+    for configuring download clients (qBittorrent, SABnzbd).
+    """
+
+    @staticmethod
+    def build(
+        provider: DownloadClientProviderData,
+        category: str,
+        media_manager: MediaManager,
+        get_secret: SecretGetter,
+    ) -> dict:
+        """Transform relation data into *arr API payload.
+
+        Args:
+            provider: Download client relation data
+            category: Category name for downloads (e.g., "radarr", "sonarr")
+            media_manager: The type of media manager calling this builder
+            get_secret: Callback to retrieve secret content by ID
+
+        Returns:
+            API payload dict ready for add_download_client()
+
+        Raises:
+            ValueError: If client type is not supported
+            KeyError: If media_manager is not in category fields mapping
+        """
+        category_field = _MEDIA_MANAGER_CATEGORY_FIELDS[media_manager]
+
+        if provider.client == DownloadClient.QBITTORRENT:
+            return DownloadClientConfigBuilder._build_qbittorrent(
+                provider, category, category_field, get_secret
+            )
+        elif provider.client == DownloadClient.SABNZBD:
+            return DownloadClientConfigBuilder._build_sabnzbd(
+                provider, category, category_field, get_secret
+            )
+        else:
+            raise ValueError(f"Unsupported download client: {provider.client}")
+
+    @staticmethod
+    def _build_qbittorrent(
+        provider: DownloadClientProviderData,
+        category: str,
+        category_field: str,
+        get_secret: SecretGetter,
+    ) -> dict:
+        """Build qBittorrent download client config."""
+        if provider.credentials_secret_id is None:
+            raise ValueError("qBittorrent requires credentials_secret_id")
+        credentials = get_secret(provider.credentials_secret_id)
+
+        parsed = urlparse(provider.api_url)
+
+        return {
+            "enable": True,
+            "protocol": "torrent",
+            "priority": 1,
+            "name": provider.instance_name,
+            "implementation": "QBittorrent",
+            "configContract": "QBittorrentSettings",
+            "fields": [
+                {"name": "host", "value": parsed.hostname},
+                {"name": "port", "value": parsed.port or 8080},
+                {"name": "useSsl", "value": parsed.scheme == "https"},
+                {"name": "urlBase", "value": provider.base_path or ""},
+                {"name": "username", "value": credentials["username"]},
+                {"name": "password", "value": credentials["password"]},
+                {"name": category_field, "value": category},
+            ],
+            "tags": [],
+        }
+
+    @staticmethod
+    def _build_sabnzbd(
+        provider: DownloadClientProviderData,
+        category: str,
+        category_field: str,
+        get_secret: SecretGetter,
+    ) -> dict:
+        """Build SABnzbd download client config."""
+        if provider.api_key_secret_id is None:
+            raise ValueError("SABnzbd requires api_key_secret_id")
+        secret = get_secret(provider.api_key_secret_id)
+        api_key = secret["api-key"]
+
+        parsed = urlparse(provider.api_url)
+
+        return {
+            "enable": True,
+            "protocol": "usenet",
+            "priority": 1,
+            "name": provider.instance_name,
+            "implementation": "Sabnzbd",
+            "configContract": "SabnzbdSettings",
+            "fields": [
+                {"name": "host", "value": parsed.hostname},
+                {"name": "port", "value": parsed.port or 8080},
+                {"name": "useSsl", "value": parsed.scheme == "https"},
+                {"name": "urlBase", "value": provider.base_path or ""},
+                {"name": "apiKey", "value": api_key},
+                {"name": category_field, "value": category},
+            ],
+            "tags": [],
+        }
+
+
+class ApplicationConfigBuilder:
+    """Build media indexer application API payloads from relation data.
+
+    Transforms MediaIndexerRequirerData into application payloads
+    for configuring connections to media managers (Radarr, Sonarr, etc.).
+
+    Note: Currently builds Prowlarr-compatible payloads. The field names
+    like "prowlarrUrl" are Prowlarr-specific API requirements.
+    """
+
+    @staticmethod
+    def build(
+        requirer: MediaIndexerRequirerData,
+        indexer_url: str,
+        get_secret: SecretGetter,
+    ) -> dict:
+        """Transform relation data into application payload.
+
+        Args:
+            requirer: Media indexer requirer relation data
+            indexer_url: URL of the indexer instance
+            get_secret: Callback to retrieve secret content by ID
+
+        Returns:
+            API payload dict ready for add_application()
+
+        Raises:
+            KeyError: If manager type is not in MEDIA_MANAGER_IMPLEMENTATIONS
+        """
+        implementation, config_contract = MEDIA_MANAGER_IMPLEMENTATIONS[requirer.manager]
+
+        secret = get_secret(requirer.api_key_secret_id)
+        api_key = secret["api-key"]
+
+        base_url = requirer.api_url.rstrip("/")
+        if requirer.base_path:
+            base_url = base_url + requirer.base_path
+
+        sync_categories = _MEDIA_MANAGER_SYNC_CATEGORIES.get(requirer.manager, [])
+
+        return {
+            "name": requirer.instance_name,
+            "syncLevel": "fullSync",
+            "implementation": implementation,
+            "configContract": config_contract,
+            "fields": [
+                {"name": "prowlarrUrl", "value": indexer_url},
+                {"name": "baseUrl", "value": base_url},
+                {"name": "apiKey", "value": api_key},
+                {"name": "syncCategories", "value": sync_categories},
+            ],
+            "tags": [],
+        }

charmarr_lib/core/_arr/_config_xml.py

@@ -0,0 +1,121 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Configuration XML utilities for *ARR applications.
+
+All arr applications (Prowlarr, Radarr, Sonarr, Lidarr) store their
+configuration in /config/config.xml including the auto-generated API key.
+"""
+
+import re
+import secrets
+import string
+
+
+def read_api_key(config_content: str) -> str | None:
+    """Extract API key from arr config.xml content.
+
+    Args:
+        config_content: The XML content of config.xml
+
+    Returns:
+        The API key string, or None if not found
+    """
+    match = re.search(r"<ApiKey>([^<]+)</ApiKey>", config_content)
+    return match.group(1) if match else None
+
+
+def config_has_api_key(config_content: str, api_key: str) -> bool:
+    """Check if config.xml contains the expected API key.
+
+    Args:
+        config_content: The XML content of config.xml
+        api_key: The expected API key
+
+    Returns:
+        True if config has this exact API key, False otherwise
+    """
+    return read_api_key(config_content) == api_key
+
+
+def generate_api_key() -> str:
+    """Generate a secure API key for arr applications.
+
+    Returns:
+        A 32-character lowercase alphanumeric string suitable for arr API keys
+    """
+    alphabet = string.ascii_lowercase + string.digits
+    return "".join(secrets.choice(alphabet) for _ in range(32))
+
+
+def update_api_key(config_content: str, new_api_key: str) -> str:
+    """Update API key in config.xml content.
+
+    Args:
+        config_content: The XML content of config.xml
+        new_api_key: The new API key to set
+
+    Returns:
+        Updated config.xml content
+    """
+    return re.sub(
+        r"<ApiKey>[^<]*</ApiKey>",
+        f"<ApiKey>{new_api_key}</ApiKey>",
+        config_content,
+    )
+
+
+def _set_element(content: str, element: str, value: str | int) -> str:
+    """Add or update an XML element."""
+    pattern = rf"<{element}>[^<]*</{element}>"
+    replacement = f"<{element}>{value}</{element}>"
+    if re.search(pattern, content):
+        return re.sub(pattern, replacement, content)
+    return re.sub(r"(</Config>)", f"  {replacement}\n\\1", content)
+
+
+def _remove_element(content: str, element: str) -> str:
+    """Remove an XML element if it exists."""
+    return re.sub(rf"\s*<{element}>[^<]*</{element}>\s*", "", content)
+
+
+def reconcile_config_xml(
+    content: str | None,
+    *,
+    api_key: str | None = None,
+    url_base: str | None = None,
+    port: int | None = None,
+    bind_address: str | None = None,
+) -> str:
+    """Reconcile config.xml content idempotently.
+
+    Creates, updates, or removes config elements based on provided values.
+    Preserves all other settings (authentication, user preferences, etc.).
+
+    Args:
+        content: Existing config.xml content, or None to create fresh
+        api_key: API key value, or None to remove
+        url_base: URL base path, or None to remove
+        port: Port number, or None to remove
+        bind_address: Bind address, or None to remove
+
+    Returns:
+        Updated config.xml content
+    """
+    if content is None:
+        content = '<?xml version="1.0" encoding="utf-8"?>\n<Config>\n</Config>\n'
+
+    elements = {
+        "ApiKey": api_key,
+        "UrlBase": url_base,
+        "Port": port,
+        "BindAddress": bind_address,
+    }
+
+    for element, value in elements.items():
+        if value is not None:
+            content = _set_element(content, element, value)
+        else:
+            content = _remove_element(content, element)
+
+    return content

charmarr_lib/core/_arr/_protocols.py

@@ -0,0 +1,54 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Protocols for *arr API clients.
+
+These protocols define the contracts that API clients must follow
+to be used with the generic reconcilers. Implementations typically
+extend BaseArrApiClient for HTTP mechanics.
+"""
+
+from typing import Any, Protocol
+
+from pydantic import BaseModel
+
+
+class MediaManagerConnection(BaseModel):
+    """A media manager connection registered in an indexer.
+
+    Represents a connection from an indexer (e.g., Prowlarr) to a
+    media manager (e.g., Radarr, Sonarr). The indexer syncs indexers
+    to these connected applications.
+    """
+
+    id: int
+    name: str
+
+
+class MediaIndexerClient(Protocol):
+    """Protocol for media indexer API clients (e.g., Prowlarr).
+
+    Any client implementing this protocol can be used with
+    reconcile_media_manager_connections. Implementations typically
+    extend BaseArrApiClient and add these methods.
+    """
+
+    def get_applications(self) -> list[MediaManagerConnection]:
+        """Get all configured media manager connections."""
+        ...
+
+    def get_application(self, app_id: int) -> dict[str, Any]:
+        """Get a single application by ID as raw dict."""
+        ...
+
+    def add_application(self, config: dict[str, Any]) -> Any:
+        """Add a new media manager connection."""
+        ...
+
+    def update_application(self, app_id: int, config: dict[str, Any]) -> Any:
+        """Update an existing media manager connection."""
+        ...
+
+    def delete_application(self, app_id: int) -> None:
+        """Delete a media manager connection."""
+        ...

charmarr_lib/core/_arr/_reconcilers.py

@@ -0,0 +1,269 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Reconcilers for synchronizing *arr application state with Juju relations."""
+
+import logging
+from typing import Any, Protocol
+
+from pydantic import ValidationError
+
+from charmarr_lib.core._arr._arr_client import ArrApiClient
+from charmarr_lib.core._arr._base_client import ArrApiError, BaseArrApiClient
+from charmarr_lib.core._arr._config_builders import (
+    ApplicationConfigBuilder,
+    DownloadClientConfigBuilder,
+    SecretGetter,
+)
+from charmarr_lib.core._arr._protocols import MediaIndexerClient
+from charmarr_lib.core.enums import MediaManager
+from charmarr_lib.core.interfaces import (
+    DownloadClientProviderData,
+    MediaIndexerRequirerData,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class NamedItem(Protocol):
+    """Protocol for items with id and name attributes."""
+
+    @property
+    def id(self) -> int: ...
+
+    @property
+    def name(self) -> str: ...
+
+
+class ReconcileOperations[T: NamedItem](Protocol):
+    """Protocol defining operations needed for generic reconciliation."""
+
+    def get_current(self) -> list[T]: ...
+    def get_full(self, item_id: int) -> dict[str, Any]: ...
+    def delete(self, item_id: int) -> None: ...
+    def add(self, config: dict[str, Any]) -> Any: ...
+    def update(self, item_id: int, config: dict[str, Any]) -> Any: ...
+
+
+def _extract_field_value(fields: list[dict[str, Any]], field_name: str) -> Any:
+    """Extract a field value from *arr API fields array."""
+    for field in fields:
+        if field.get("name") == field_name:
+            return field.get("value")
+    return None
+
+
+def _needs_config_update(
+    existing: dict[str, Any],
+    desired: dict[str, Any],
+    top_level_keys: list[str],
+) -> bool:
+    """Check if *arr config needs to be updated by comparing top-level keys and fields."""
+    for key in top_level_keys:
+        if existing.get(key) != desired.get(key):
+            return True
+
+    existing_fields = existing.get("fields", [])
+    desired_fields = desired.get("fields", [])
+    desired_field_values = {f["name"]: f.get("value") for f in desired_fields}
+
+    for field_name, desired_value in desired_field_values.items():
+        existing_value = _extract_field_value(existing_fields, field_name)
+        if existing_value != desired_value:
+            return True
+
+    return False
+
+
+_DOWNLOAD_CLIENT_KEYS = ["enable", "protocol", "implementation", "configContract"]
+_APPLICATION_KEYS = ["syncLevel", "implementation", "configContract"]
+
+
+def _reconcile_items[T: NamedItem](
+    ops: ReconcileOperations[T],
+    desired_configs: dict[str, dict[str, Any]],
+    comparison_keys: list[str],
+    item_type_name: str,
+) -> None:
+    """Generic reconciliation of *arr API items.
+
+    Args:
+        ops: Operations for interacting with the API
+        desired_configs: Mapping of item name to desired configuration
+        comparison_keys: Top-level keys to compare for update detection
+        item_type_name: Human-readable name for logging (e.g., "download client")
+    """
+    current = ops.get_current()
+    current_by_name = {item.name: item for item in current}
+
+    for name, current_item in current_by_name.items():
+        if name not in desired_configs:
+            logger.info("Removing %s: %s", item_type_name, name)
+            ops.delete(current_item.id)
+
+    for name, desired_config in desired_configs.items():
+        try:
+            existing = current_by_name.get(name)
+            if existing:
+                existing_full = ops.get_full(existing.id)
+                if _needs_config_update(existing_full, desired_config, comparison_keys):
+                    logger.info("Updating %s: %s", item_type_name, name)
+                    ops.update(existing.id, desired_config)
+            else:
+                logger.info("Adding %s: %s", item_type_name, name)
+                ops.add(desired_config)
+        except (ArrApiError, ValidationError) as e:
+            logger.warning("Failed to reconcile %s %s: %s", item_type_name, name, e)
+
+
+class _DownloadClientOps:
+    """Operations adapter for download client reconciliation."""
+
+    def __init__(self, client: ArrApiClient) -> None:
+        self._client = client
+
+    def get_current(self):
+        return self._client.get_download_clients()
+
+    def get_full(self, item_id: int) -> dict[str, Any]:
+        return self._client.get_download_client(item_id)
+
+    def delete(self, item_id: int) -> None:
+        self._client.delete_download_client(item_id)
+
+    def add(self, config: dict[str, Any]):
+        return self._client.add_download_client(config)
+
+    def update(self, item_id: int, config: dict[str, Any]):
+        return self._client.update_download_client(item_id, config)
+
+
+class _ApplicationOps:
+    """Operations adapter for media manager application reconciliation."""
+
+    def __init__(self, client: MediaIndexerClient) -> None:
+        self._client = client
+
+    def get_current(self):
+        return self._client.get_applications()
+
+    def get_full(self, item_id: int) -> dict[str, Any]:
+        return self._client.get_application(item_id)
+
+    def delete(self, item_id: int) -> None:
+        self._client.delete_application(item_id)
+
+    def add(self, config: dict[str, Any]):
+        return self._client.add_application(config)
+
+    def update(self, item_id: int, config: dict[str, Any]):
+        return self._client.update_application(item_id, config)
+
+
+def reconcile_download_clients(
+    api_client: ArrApiClient,
+    desired_clients: list[DownloadClientProviderData],
+    category: str,
+    media_manager: MediaManager,
+    get_secret: SecretGetter,
+) -> None:
+    """Reconcile download clients in Radarr/Sonarr/Lidarr.
+
+    Syncs download client configuration (qBittorrent, SABnzbd) to match
+    the desired state from Juju relations. Clients not in desired_clients
+    will be deleted.
+
+    Args:
+        api_client: API client for Radarr/Sonarr/Lidarr
+        desired_clients: Download client data from relations
+        category: Category name for downloads (e.g., "radarr", "sonarr")
+        media_manager: The type of media manager (determines category field name)
+        get_secret: Callback to retrieve secret content by ID
+    """
+    desired_configs: dict[str, dict[str, Any]] = {}
+    for provider in desired_clients:
+        config = DownloadClientConfigBuilder.build(
+            provider=provider,
+            category=category,
+            media_manager=media_manager,
+            get_secret=get_secret,
+        )
+        desired_configs[provider.instance_name] = config
+
+    _reconcile_items(
+        _DownloadClientOps(api_client),
+        desired_configs,
+        _DOWNLOAD_CLIENT_KEYS,
+        "download client",
+    )
+
+
+def reconcile_media_manager_connections(
+    api_client: MediaIndexerClient,
+    desired_managers: list[MediaIndexerRequirerData],
+    indexer_url: str,
+    get_secret: SecretGetter,
+) -> None:
+    """Reconcile media manager connections in an indexer application.
+
+    Syncs application configuration (connections to Radarr/Sonarr/Lidarr)
+    to match the desired state from Juju relations. Connections not in
+    desired_managers will be deleted.
+
+    Args:
+        api_client: API client implementing MediaIndexerClient protocol
+        desired_managers: Media manager data from media-indexer relations
+        indexer_url: URL of the indexer instance (e.g., Prowlarr)
+        get_secret: Callback to retrieve secret content by ID
+    """
+    desired_configs: dict[str, dict[str, Any]] = {}
+    for requirer in desired_managers:
+        config = ApplicationConfigBuilder.build(
+            requirer=requirer,
+            indexer_url=indexer_url,
+            get_secret=get_secret,
+        )
+        desired_configs[requirer.instance_name] = config
+
+    _reconcile_items(
+        _ApplicationOps(api_client),
+        desired_configs,
+        _APPLICATION_KEYS,
+        "media manager connection",
+    )
+
+
+def reconcile_root_folder(
+    api_client: ArrApiClient,
+    path: str,
+) -> None:
+    """Ensure root folder exists in Radarr/Sonarr/Lidarr. Additive only.
+
+    Args:
+        api_client: API client for Radarr/Sonarr/Lidarr
+        path: Filesystem path that should exist as a root folder
+    """
+    existing = api_client.get_root_folders()
+    existing_paths = {rf.path for rf in existing}
+
+    if path not in existing_paths:
+        logger.info("Adding root folder: %s", path)
+        api_client.add_root_folder(path)
+
+
+def reconcile_external_url(
+    api_client: BaseArrApiClient,
+    external_url: str,
+) -> None:
+    """Configure external URL in any *arr application host config.
+
+    Args:
+        api_client: Any *arr API client (extends BaseArrApiClient)
+        external_url: External URL for the application
+    """
+    current_full = api_client.get_host_config_raw()
+    current_external_url = current_full.get("applicationUrl", "")
+
+    if current_external_url != external_url:
+        logger.info("Updating external URL to: %s", external_url)
+        api_client.update_host_config({"applicationUrl": external_url})