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

charmarr_lib/core/interfaces/__init__.py

@@ -0,0 +1,78 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Juju relation interface implementations for Charmarr."""
+
+from charmarr_lib.core.interfaces._download_client import (
+    DownloadClientChangedEvent,
+    DownloadClientProvider,
+    DownloadClientProviderData,
+    DownloadClientRequirer,
+    DownloadClientRequirerData,
+)
+from charmarr_lib.core.interfaces._flaresolverr import (
+    FlareSolverrChangedEvent,
+    FlareSolverrProvider,
+    FlareSolverrProviderData,
+    FlareSolverrRequirer,
+)
+from charmarr_lib.core.interfaces._media_indexer import (
+    MediaIndexerChangedEvent,
+    MediaIndexerProvider,
+    MediaIndexerProviderData,
+    MediaIndexerRequirer,
+    MediaIndexerRequirerData,
+)
+from charmarr_lib.core.interfaces._media_manager import (
+    MediaManagerChangedEvent,
+    MediaManagerProvider,
+    MediaManagerProviderData,
+    MediaManagerRequirer,
+    MediaManagerRequirerData,
+    QualityProfile,
+)
+from charmarr_lib.core.interfaces._media_server import (
+    MediaServerChangedEvent,
+    MediaServerProvider,
+    MediaServerProviderData,
+    MediaServerRequirer,
+)
+from charmarr_lib.core.interfaces._media_storage import (
+    MediaStorageChangedEvent,
+    MediaStorageProvider,
+    MediaStorageProviderData,
+    MediaStorageRequirer,
+    MediaStorageRequirerData,
+)
+
+__all__ = [
+    "DownloadClientChangedEvent",
+    "DownloadClientProvider",
+    "DownloadClientProviderData",
+    "DownloadClientRequirer",
+    "DownloadClientRequirerData",
+    "FlareSolverrChangedEvent",
+    "FlareSolverrProvider",
+    "FlareSolverrProviderData",
+    "FlareSolverrRequirer",
+    "MediaIndexerChangedEvent",
+    "MediaIndexerProvider",
+    "MediaIndexerProviderData",
+    "MediaIndexerRequirer",
+    "MediaIndexerRequirerData",
+    "MediaManagerChangedEvent",
+    "MediaManagerProvider",
+    "MediaManagerProviderData",
+    "MediaManagerRequirer",
+    "MediaManagerRequirerData",
+    "MediaServerChangedEvent",
+    "MediaServerProvider",
+    "MediaServerProviderData",
+    "MediaServerRequirer",
+    "MediaStorageChangedEvent",
+    "MediaStorageProvider",
+    "MediaStorageProviderData",
+    "MediaStorageRequirer",
+    "MediaStorageRequirerData",
+    "QualityProfile",
+]

charmarr_lib/core/interfaces/_base.py

@@ -0,0 +1,103 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Base classes for Juju relation interfaces."""
+
+from abc import abstractmethod
+from typing import Any
+
+from ops import EventBase, Object
+from pydantic import BaseModel, ValidationError
+
+
+class RelationInterfaceBase[TData: BaseModel, TRemote: BaseModel](Object):
+    """Base class for relation interfaces with common patterns."""
+
+    def __init__(self, charm: Any, relation_name: str) -> None:
+        super().__init__(charm, relation_name)
+        self._charm = charm
+        self._relation_name = relation_name
+
+    def _publish_to_all_relations(self, data: TData) -> None:
+        """Publish data to all relations on this endpoint."""
+        if not self._charm.unit.is_leader():
+            return
+
+        for relation in self._charm.model.relations.get(self._relation_name, []):
+            relation.data[self._charm.app]["config"] = data.model_dump_json()
+
+    def _publish_to_single_relation(self, data: TData) -> None:
+        """Publish data to the single relation on this endpoint."""
+        if not self._charm.unit.is_leader():
+            return
+
+        relation = self._charm.model.get_relation(self._relation_name)
+        if relation:
+            relation.data[self._charm.app]["config"] = data.model_dump_json()
+
+    @abstractmethod
+    def _get_remote_data_model(self) -> type[TRemote]:
+        """Return the Pydantic model class for parsing remote data."""
+        ...
+
+    def _get_all_remote_app_data(self) -> list[TRemote]:
+        """Get parsed data from all remote applications on this endpoint."""
+        model_cls = self._get_remote_data_model()
+        results: list[TRemote] = []
+        for relation in self._charm.model.relations.get(self._relation_name, []):
+            try:
+                app_data = relation.data[relation.app]
+                if app_data and "config" in app_data:
+                    results.append(model_cls.model_validate_json(app_data["config"]))
+            except (ValidationError, KeyError):
+                continue
+        return results
+
+    def _get_all_provider_data(self) -> list[TRemote]:
+        """Get parsed data from all provider applications (for requirers with multiple relations)."""
+        model_cls = self._get_remote_data_model()
+        results: list[TRemote] = []
+        for relation in self._charm.model.relations.get(self._relation_name, []):
+            try:
+                provider_app = relation.app
+                if provider_app:
+                    app_data = relation.data[provider_app]
+                    if app_data and "config" in app_data:
+                        results.append(model_cls.model_validate_json(app_data["config"]))
+            except (ValidationError, KeyError):
+                continue
+        return results
+
+    def _get_single_provider_data(self) -> TRemote | None:
+        """Get parsed data from a single provider (for single-relation requirers)."""
+        model_cls = self._get_remote_data_model()
+        relation = self._charm.model.get_relation(self._relation_name)
+        if not relation:
+            return None
+
+        try:
+            provider_app = relation.app
+            if provider_app:
+                app_data = relation.data[provider_app]
+                if app_data and "config" in app_data:
+                    return model_cls.model_validate_json(app_data["config"])
+        except (ValidationError, KeyError):
+            pass
+        return None
+
+
+class EventObservingMixin:
+    """Mixin for interfaces that observe relation events and emit custom events."""
+
+    _charm: Any
+    _relation_name: str
+
+    def _setup_event_observation(self) -> None:
+        """Set up observation of relation_changed and relation_broken events."""
+        events = self._charm.on[self._relation_name]
+        self.framework.observe(events.relation_changed, self._emit_changed)  # type: ignore[attr-defined]
+        self.framework.observe(events.relation_broken, self._emit_changed)  # type: ignore[attr-defined]
+
+    def _emit_changed(self, event: EventBase) -> None:
+        """Emit the custom 'changed' event."""
+        self.on.changed.emit()  # type: ignore[attr-defined]

charmarr_lib/core/interfaces/_download_client.py

@@ -0,0 +1,125 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Download client interface for download client ↔ media manager integration."""
+
+from typing import Any
+
+from ops import EventBase, EventSource, ObjectEvents
+from pydantic import BaseModel, ValidationError, model_validator
+
+from charmarr_lib.core.enums import DownloadClient, DownloadClientType, MediaManager
+from charmarr_lib.core.interfaces._base import (
+    EventObservingMixin,
+    RelationInterfaceBase,
+)
+
+
+class DownloadClientProviderData(BaseModel):
+    """Data published by download clients.
+
+    Must have EITHER api_key_secret_id (SABnzbd) OR credentials_secret_id
+    (qBittorrent, Deluge, Transmission), but not both.
+    """
+
+    api_url: str
+    api_key_secret_id: str | None = None
+    credentials_secret_id: str | None = None
+    client: DownloadClient
+    client_type: DownloadClientType
+    instance_name: str
+    base_path: str | None = None
+
+    @model_validator(mode="after")
+    def validate_auth_fields(self) -> "DownloadClientProviderData":
+        """Validate that exactly one auth method is provided (XOR)."""
+        has_api_key = self.api_key_secret_id is not None
+        has_credentials = self.credentials_secret_id is not None
+
+        if not has_api_key and not has_credentials:
+            raise ValueError("Must provide either api_key_secret_id or credentials_secret_id")
+
+        if has_api_key and has_credentials:
+            raise ValueError("Cannot provide both api_key_secret_id and credentials_secret_id")
+
+        return self
+
+
+class DownloadClientRequirerData(BaseModel):
+    """Data published by media managers."""
+
+    manager: MediaManager
+    instance_name: str
+
+
+class DownloadClientChangedEvent(EventBase):
+    """Event emitted when download-client relation state changes."""
+
+    pass
+
+
+class DownloadClientProvider(
+    RelationInterfaceBase[DownloadClientProviderData, DownloadClientRequirerData]
+):
+    """Provider side of download-client interface."""
+
+    def __init__(self, charm: Any, relation_name: str = "download-client") -> None:
+        super().__init__(charm, relation_name)
+
+    def _get_remote_data_model(self) -> type[DownloadClientRequirerData]:
+        return DownloadClientRequirerData
+
+    def publish_data(self, data: DownloadClientProviderData) -> None:
+        """Publish provider data to all relations."""
+        self._publish_to_all_relations(data)
+
+    def get_requirers(self) -> list[DownloadClientRequirerData]:
+        """Get all connected requirers with valid data."""
+        return self._get_all_remote_app_data()
+
+
+class DownloadClientRequirerEvents(ObjectEvents):
+    """Events emitted by DownloadClientRequirer."""
+
+    changed = EventSource(DownloadClientChangedEvent)
+
+
+class DownloadClientRequirer(
+    EventObservingMixin,
+    RelationInterfaceBase[DownloadClientRequirerData, DownloadClientProviderData],
+):
+    """Requirer side of download-client interface."""
+
+    on = DownloadClientRequirerEvents()  # type: ignore[assignment]
+
+    def __init__(self, charm: Any, relation_name: str = "download-client") -> None:
+        super().__init__(charm, relation_name)
+        self._setup_event_observation()
+
+    def _get_remote_data_model(self) -> type[DownloadClientProviderData]:
+        return DownloadClientProviderData
+
+    def publish_data(self, data: DownloadClientRequirerData) -> None:
+        """Publish requirer data to all relations."""
+        self._publish_to_all_relations(data)
+
+    def get_providers(self) -> list[DownloadClientProviderData]:
+        """Get all connected download clients with valid data."""
+        return self._get_all_provider_data()
+
+    def is_ready(self) -> bool:
+        """Check if requirer has published data and has >=1 valid provider."""
+        relations = self._charm.model.relations.get(self._relation_name, [])
+        if not relations:
+            return False
+
+        try:
+            first_relation = relations[0]
+            published_data = first_relation.data[self._charm.app]
+            if not published_data or "config" not in published_data:
+                return False
+            DownloadClientRequirerData.model_validate_json(published_data["config"])
+        except (ValidationError, KeyError):
+            return False
+
+        return len(self.get_providers()) > 0

charmarr_lib/core/interfaces/_flaresolverr.py

@@ -0,0 +1,69 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""FlareSolverr interface for Cloudflare bypass proxy."""
+
+from typing import Any
+
+from ops import EventBase, EventSource, ObjectEvents
+from pydantic import BaseModel, Field
+
+from charmarr_lib.core.interfaces._base import (
+    EventObservingMixin,
+    RelationInterfaceBase,
+)
+
+
+class FlareSolverrProviderData(BaseModel):
+    """Data published by flaresolverr-k8s charm."""
+
+    url: str = Field(description="FlareSolverr API URL (e.g., http://host:8191)")
+
+
+class FlareSolverrChangedEvent(EventBase):
+    """Event emitted when flaresolverr relation state changes."""
+
+    pass
+
+
+class FlareSolverrProvider(RelationInterfaceBase[FlareSolverrProviderData, BaseModel]):
+    """Provider side of flaresolverr interface."""
+
+    def __init__(self, charm: Any, relation_name: str = "flaresolverr") -> None:
+        super().__init__(charm, relation_name)
+
+    def _get_remote_data_model(self) -> type[BaseModel]:
+        return BaseModel
+
+    def publish_data(self, data: FlareSolverrProviderData) -> None:
+        """Publish provider data to all relations."""
+        self._publish_to_all_relations(data)
+
+
+class FlareSolverrRequirerEvents(ObjectEvents):
+    """Events emitted by FlareSolverrRequirer."""
+
+    changed = EventSource(FlareSolverrChangedEvent)
+
+
+class FlareSolverrRequirer(
+    EventObservingMixin, RelationInterfaceBase[BaseModel, FlareSolverrProviderData]
+):
+    """Requirer side of flaresolverr interface."""
+
+    on = FlareSolverrRequirerEvents()  # type: ignore[assignment]
+
+    def __init__(self, charm: Any, relation_name: str = "flaresolverr") -> None:
+        super().__init__(charm, relation_name)
+        self._setup_event_observation()
+
+    def _get_remote_data_model(self) -> type[FlareSolverrProviderData]:
+        return FlareSolverrProviderData
+
+    def get_provider(self) -> FlareSolverrProviderData | None:
+        """Get FlareSolverr provider data if available."""
+        return self._get_single_provider_data()
+
+    def is_ready(self) -> bool:
+        """Check if FlareSolverr is available."""
+        return self.get_provider() is not None

charmarr_lib/core/interfaces/_media_indexer.py

@@ -0,0 +1,131 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Media indexer interface for indexer manager ↔ media manager integration."""
+
+from typing import Any
+
+from ops import EventBase, EventSource, ObjectEvents
+from pydantic import BaseModel, ValidationError
+
+from charmarr_lib.core.enums import MediaIndexer, MediaManager
+from charmarr_lib.core.interfaces._base import (
+    EventObservingMixin,
+    RelationInterfaceBase,
+)
+
+
+class MediaIndexerProviderData(BaseModel):
+    """Data published by the indexer manager."""
+
+    api_url: str
+    api_key_secret_id: str
+    indexer: MediaIndexer
+    base_path: str | None = None
+
+
+class MediaIndexerRequirerData(BaseModel):
+    """Data published by the media manager."""
+
+    api_url: str
+    api_key_secret_id: str
+    manager: MediaManager
+    instance_name: str
+    base_path: str | None = None
+
+
+class MediaIndexerChangedEvent(EventBase):
+    """Event emitted when media-indexer relation state changes."""
+
+    pass
+
+
+class MediaIndexerProviderEvents(ObjectEvents):
+    """Events emitted by MediaIndexerProvider."""
+
+    changed = EventSource(MediaIndexerChangedEvent)
+
+
+class MediaIndexerProvider(
+    EventObservingMixin, RelationInterfaceBase[MediaIndexerProviderData, MediaIndexerRequirerData]
+):
+    """Provider side of media-indexer interface."""
+
+    on = MediaIndexerProviderEvents()  # type: ignore[assignment]
+
+    def __init__(self, charm: Any, relation_name: str = "media-indexer") -> None:
+        super().__init__(charm, relation_name)
+        self._setup_event_observation()
+
+    def _get_remote_data_model(self) -> type[MediaIndexerRequirerData]:
+        return MediaIndexerRequirerData
+
+    def publish_data(self, data: MediaIndexerProviderData) -> None:
+        """Publish provider data to all relations."""
+        self._publish_to_all_relations(data)
+
+    def get_requirers(self) -> list[MediaIndexerRequirerData]:
+        """Get all connected requirers with valid data."""
+        return self._get_all_remote_app_data()
+
+    def is_ready(self) -> bool:
+        """Check if provider has published data and has >=1 valid requirer."""
+        relations = self._charm.model.relations.get(self._relation_name, [])
+        if not relations:
+            return False
+
+        try:
+            first_relation = relations[0]
+            published_data = first_relation.data[self._charm.app]
+            if not published_data or "config" not in published_data:
+                return False
+            MediaIndexerProviderData.model_validate_json(published_data["config"])
+        except (ValidationError, KeyError):
+            return False
+
+        return len(self.get_requirers()) > 0
+
+
+class MediaIndexerRequirerEvents(ObjectEvents):
+    """Events emitted by MediaIndexerRequirer."""
+
+    changed = EventSource(MediaIndexerChangedEvent)
+
+
+class MediaIndexerRequirer(
+    EventObservingMixin, RelationInterfaceBase[MediaIndexerRequirerData, MediaIndexerProviderData]
+):
+    """Requirer side of media-indexer interface."""
+
+    on = MediaIndexerRequirerEvents()  # type: ignore[assignment]
+
+    def __init__(self, charm: Any, relation_name: str = "media-indexer") -> None:
+        super().__init__(charm, relation_name)
+        self._setup_event_observation()
+
+    def _get_remote_data_model(self) -> type[MediaIndexerProviderData]:
+        return MediaIndexerProviderData
+
+    def publish_data(self, data: MediaIndexerRequirerData) -> None:
+        """Publish requirer data to relation."""
+        self._publish_to_single_relation(data)
+
+    def get_provider_data(self) -> MediaIndexerProviderData | None:
+        """Get provider data if available."""
+        return self._get_single_provider_data()
+
+    def is_ready(self) -> bool:
+        """Check if both requirer and provider have published valid data."""
+        relation = self._charm.model.get_relation(self._relation_name)
+        if not relation:
+            return False
+
+        try:
+            published_data = relation.data[self._charm.app]
+            if not published_data or "config" not in published_data:
+                return False
+            MediaIndexerRequirerData.model_validate_json(published_data["config"])
+        except (ValidationError, KeyError):
+            return False
+
+        return self.get_provider_data() is not None

charmarr_lib/core/interfaces/_media_manager.py

@@ -0,0 +1,111 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Media manager interface for connecting media managers to request managers."""
+
+from typing import Any
+
+from ops import EventBase, EventSource, ObjectEvents
+from pydantic import BaseModel, Field
+
+from charmarr_lib.core.enums import ContentVariant, MediaManager, RequestManager
+from charmarr_lib.core.interfaces._base import (
+    EventObservingMixin,
+    RelationInterfaceBase,
+)
+
+
+class QualityProfile(BaseModel):
+    """Quality profile from Radarr/Sonarr."""
+
+    id: int = Field(description="Quality profile ID from the media manager API")
+    name: str = Field(description="Quality profile name (e.g., HD-Bluray+WEB, UHD-Bluray+WEB)")
+
+
+class MediaManagerProviderData(BaseModel):
+    """Data published by media manager charms (Radarr, Sonarr, etc.)."""
+
+    # Connection details
+    api_url: str = Field(description="Full API URL (e.g., http://radarr:7878)")
+    api_key_secret_id: str = Field(description="Juju secret ID containing API key")
+
+    # Identity
+    manager: MediaManager = Field(description="Type of media manager")
+    instance_name: str = Field(description="Juju app name (e.g., radarr-4k)")
+    base_path: str | None = Field(default=None, description="URL base path if configured")
+
+    # Configuration (populated from media manager API after Recyclarr sync)
+    quality_profiles: list[QualityProfile] = Field(
+        description="Available quality profiles from the media manager"
+    )
+    root_folders: list[str] = Field(description="Available root folder paths")
+    variant: ContentVariant = Field(
+        default=ContentVariant.STANDARD,
+        description="Content variant: standard (catch-all), 4k, or anime",
+    )
+
+
+class MediaManagerRequirerData(BaseModel):
+    """Data published by request manager charms (Overseerr, Jellyseerr)."""
+
+    requester: RequestManager = Field(description="Type of request manager")
+    instance_name: str = Field(description="Juju application name")
+
+
+class MediaManagerChangedEvent(EventBase):
+    """Event emitted when media-manager relation state changes."""
+
+    pass
+
+
+class MediaManagerProvider(
+    RelationInterfaceBase[MediaManagerProviderData, MediaManagerRequirerData]
+):
+    """Provider side of media-manager interface (passive - no events)."""
+
+    def __init__(self, charm: Any, relation_name: str = "media-manager") -> None:
+        super().__init__(charm, relation_name)
+
+    def _get_remote_data_model(self) -> type[MediaManagerRequirerData]:
+        return MediaManagerRequirerData
+
+    def publish_data(self, data: MediaManagerProviderData) -> None:
+        """Publish provider data to all relations."""
+        self._publish_to_all_relations(data)
+
+    def get_requirers(self) -> list[MediaManagerRequirerData]:
+        """Get data from all connected requirer applications."""
+        return self._get_all_remote_app_data()
+
+
+class MediaManagerRequirerEvents(ObjectEvents):
+    """Events emitted by MediaManagerRequirer."""
+
+    changed = EventSource(MediaManagerChangedEvent)
+
+
+class MediaManagerRequirer(
+    EventObservingMixin, RelationInterfaceBase[MediaManagerRequirerData, MediaManagerProviderData]
+):
+    """Requirer side of media-manager interface."""
+
+    on = MediaManagerRequirerEvents()  # type: ignore[assignment]
+
+    def __init__(self, charm: Any, relation_name: str = "media-manager") -> None:
+        super().__init__(charm, relation_name)
+        self._setup_event_observation()
+
+    def _get_remote_data_model(self) -> type[MediaManagerProviderData]:
+        return MediaManagerProviderData
+
+    def publish_data(self, data: MediaManagerRequirerData) -> None:
+        """Publish requirer data to all relations."""
+        self._publish_to_all_relations(data)
+
+    def get_providers(self) -> list[MediaManagerProviderData]:
+        """Get data from all connected provider applications."""
+        return self._get_all_provider_data()
+
+    def is_ready(self) -> bool:
+        """Check if at least one media manager is connected and ready."""
+        return len(self.get_providers()) > 0

charmarr_lib/core/interfaces/_media_server.py

@@ -0,0 +1,74 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Media server interface for connecting media servers (Plex, Jellyfin) to request managers."""
+
+from typing import Any
+
+from ops import EventBase, EventSource, ObjectEvents
+from pydantic import BaseModel, Field
+
+from charmarr_lib.core.interfaces._base import (
+    EventObservingMixin,
+    RelationInterfaceBase,
+)
+
+
+class MediaServerProviderData(BaseModel):
+    """Data published by media server charms (Plex, Jellyfin)."""
+
+    name: str = Field(description="Server name (e.g., 'My Plex Server')")
+    api_url: str = Field(description="API URL (e.g., http://plex-k8s:32400)")
+    web_url: str | None = Field(
+        default=None,
+        description="Optional web UI URL for 'Open in Plex' links",
+    )
+
+
+class MediaServerChangedEvent(EventBase):
+    """Event emitted when media-server relation state changes."""
+
+    pass
+
+
+class MediaServerProvider(RelationInterfaceBase[MediaServerProviderData, BaseModel]):
+    """Provider side of media-server interface (Plex, Jellyfin)."""
+
+    def __init__(self, charm: Any, relation_name: str = "media-server") -> None:
+        super().__init__(charm, relation_name)
+
+    def _get_remote_data_model(self) -> type[BaseModel]:
+        return BaseModel
+
+    def publish_data(self, data: MediaServerProviderData) -> None:
+        """Publish provider data to all relations."""
+        self._publish_to_all_relations(data)
+
+
+class MediaServerRequirerEvents(ObjectEvents):
+    """Events emitted by MediaServerRequirer."""
+
+    changed = EventSource(MediaServerChangedEvent)
+
+
+class MediaServerRequirer(
+    EventObservingMixin, RelationInterfaceBase[BaseModel, MediaServerProviderData]
+):
+    """Requirer side of media-server interface (Overseerr, Jellyseerr)."""
+
+    on = MediaServerRequirerEvents()  # type: ignore[assignment]
+
+    def __init__(self, charm: Any, relation_name: str = "media-server") -> None:
+        super().__init__(charm, relation_name)
+        self._setup_event_observation()
+
+    def _get_remote_data_model(self) -> type[MediaServerProviderData]:
+        return MediaServerProviderData
+
+    def get_provider(self) -> MediaServerProviderData | None:
+        """Get media server provider data if available."""
+        return self._get_single_provider_data()
+
+    def is_ready(self) -> bool:
+        """Check if a media server is available."""
+        return self.get_provider() is not None