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

charmarr_lib/core/_arr/_recyclarr.py

@@ -0,0 +1,150 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Recyclarr integration for Trash Guides quality profile sync.
+
+This module provides utilities for running Recyclarr to sync quality profiles
+and custom formats from Trash Guides to Radarr, Sonarr, and Lidarr.
+
+See ADR: apps/adr-003-recyclarr-integration.md
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from charmarr_lib.core.enums import MediaManager
+
+if TYPE_CHECKING:
+    import ops
+
+import ops.pebble
+
+logger = logging.getLogger(__name__)
+
+_RECYCLARR_TIMEOUT = 120.0
+_RECYCLARR_BIN_PATH = "/app/recyclarr/recyclarr"
+_RECYCLARR_CONFIG_PATH = "/tmp/recyclarr.yml"
+
+
+class RecyclarrError(Exception):
+    """Raised when Recyclarr execution fails."""
+
+
+def _expand_template_to_includes(manager: MediaManager, template: str) -> list[str]:
+    """Expand user-friendly template name to actual Recyclarr include names.
+
+    Recyclarr templates (shown in `config list templates`) are NOT directly usable
+    in the `include:` directive. Each template maps to multiple includes:
+    - quality-definition (varies by media type: movie for radarr, series for sonarr)
+    - quality-profile-{template}
+    - custom-formats-{template}
+
+    Sonarr uses v4 prefix for quality-profiles and custom-formats.
+    See: https://github.com/recyclarr/config-templates/tree/master/sonarr/includes
+    """
+    prefix = manager.value
+    if manager == MediaManager.RADARR:
+        return [
+            f"{prefix}-quality-definition-movie",
+            f"{prefix}-quality-profile-{template}",
+            f"{prefix}-custom-formats-{template}",
+        ]
+    elif manager == MediaManager.SONARR:
+        return [
+            f"{prefix}-quality-definition-series",
+            f"{prefix}-v4-quality-profile-{template}",
+            f"{prefix}-v4-custom-formats-{template}",
+        ]
+    else:
+        raise RecyclarrError(f"Unsupported media manager for Recyclarr: {manager}")
+
+
+def _generate_config(
+    manager: MediaManager,
+    api_key: str,
+    templates: list[str],
+    port: int,
+    base_url: str | None,
+) -> str:
+    """Generate Recyclarr YAML config using TRaSH Guide templates."""
+    config_key = manager.value
+    url_base = base_url or ""
+
+    # Expand templates to actual include names and deduplicate
+    includes: list[str] = []
+    seen: set[str] = set()
+    for template in templates:
+        for include in _expand_template_to_includes(manager, template):
+            if include not in seen:
+                includes.append(include)
+                seen.add(include)
+
+    includes_yaml = "\n".join(f"      - template: {inc}" for inc in includes)
+
+    return f"""{config_key}:
+  {config_key}:
+    base_url: http://localhost:{port}{url_base}
+    api_key: {api_key}
+
+    include:
+{includes_yaml}
+"""
+
+
+def _run_recyclarr_in_container(
+    container: ops.Container,
+    config_content: str,
+) -> None:
+    """Run Recyclarr in a container with the official recyclarr image."""
+    container.push(_RECYCLARR_CONFIG_PATH, config_content, make_dirs=True)
+
+    process = container.exec(
+        [_RECYCLARR_BIN_PATH, "sync", "--config", _RECYCLARR_CONFIG_PATH],
+        timeout=_RECYCLARR_TIMEOUT,
+    )
+    try:
+        stdout, _ = process.wait_output()
+        logger.info("Recyclarr sync completed: %s", stdout)
+    except (ops.pebble.ExecError, ops.pebble.ChangeError) as e:
+        logger.error("Recyclarr sync failed: %s", e)
+        raise RecyclarrError(f"Recyclarr sync failed: {e}") from e
+
+
+def sync_trash_profiles(
+    container: ops.Container,
+    manager: MediaManager,
+    api_key: str,
+    profiles_config: str,
+    port: int,
+    base_url: str | None = None,
+) -> None:
+    """Sync Trash Guides profiles for the specified media manager.
+
+    Generates Recyclarr config and runs it in the provided container
+    to sync quality profiles from Trash Guides. Runs idempotently.
+
+    Args:
+        container: Pebble container running the recyclarr image
+        manager: The media manager type (RADARR, SONARR, etc.)
+        api_key: API key for the media manager
+        profiles_config: Comma-separated list of profile template names
+        port: WebUI port for the media manager
+        base_url: Optional URL base path (e.g., "/radarr")
+
+    Raises:
+        RecyclarrError: If Recyclarr execution fails
+    """
+    templates = [t.strip() for t in profiles_config.split(",") if t.strip()]
+    if not templates:
+        return
+
+    config = _generate_config(
+        manager=manager,
+        api_key=api_key,
+        templates=templates,
+        port=port,
+        base_url=base_url,
+    )
+    _run_recyclarr_in_container(container, config)

charmarr_lib/core/_juju/__init__.py

@@ -0,0 +1,27 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Juju-specific utilities for Charmarr charms."""
+
+from charmarr_lib.core._juju._pebble import ensure_pebble_user, get_config_hash
+from charmarr_lib.core._juju._reconciler import (
+    all_events,
+    observe_events,
+    reconcilable_events_k8s,
+    reconcilable_events_k8s_workloadless,
+)
+from charmarr_lib.core._juju._secrets import (
+    get_secret_rotation_policy,
+    sync_secret_rotation_policy,
+)
+
+__all__ = [
+    "all_events",
+    "ensure_pebble_user",
+    "get_config_hash",
+    "get_secret_rotation_policy",
+    "observe_events",
+    "reconcilable_events_k8s",
+    "reconcilable_events_k8s_workloadless",
+    "sync_secret_rotation_policy",
+]

charmarr_lib/core/_juju/_pebble.py

@@ -0,0 +1,102 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Pebble utilities for Juju charms.
+
+Provides utilities for:
+- User creation for LinuxServer.io images (PUID/PGID handling)
+- Config file change detection via content hashing
+
+LinuxServer.io images use s6-overlay which dynamically creates users based on
+PUID/PGID environment variables. When bypassing s6 to run applications directly
+via Pebble's user-id/group-id options, users must exist in /etc/passwd and
+/etc/group beforehand.
+"""
+
+import hashlib
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ops import Container
+
+
+def ensure_pebble_user(
+    container: "Container",
+    puid: int,
+    pgid: int,
+    username: str = "app",
+    home_dir: str = "/config",
+) -> bool:
+    """Ensure user and group entries exist for Pebble's user-id/group-id.
+
+    LinuxServer.io images don't have users for arbitrary UIDs. This function
+    adds entries to /etc/passwd and /etc/group so Pebble can run the workload
+    with the specified user-id and group-id.
+
+    Args:
+        container: The ops.Container to modify.
+        puid: User ID for the workload process.
+        pgid: Group ID for the workload process.
+        username: Username for the passwd/group entries.
+        home_dir: Home directory for the user.
+
+    Returns:
+        True if any changes were made, False if entries already existed.
+
+    Side Effects:
+        Modifies /etc/passwd and /etc/group in the container if the specified
+        UID/GID entries do not already exist.
+    """
+    changed = False
+
+    group_file = container.pull("/etc/group").read()
+    if f":{pgid}:" not in group_file:
+        group_file += f"{username}:x:{pgid}:\n"
+        container.push("/etc/group", group_file)
+        changed = True
+
+    passwd_file = container.pull("/etc/passwd").read()
+    if f":{puid}:" not in passwd_file:
+        passwd_file += f"{username}:x:{puid}:{pgid}::{home_dir}:/bin/false\n"
+        container.push("/etc/passwd", passwd_file)
+        changed = True
+
+    return changed
+
+
+def get_config_hash(container: "Container", config_path: str) -> str:
+    """Get a short hash of a config file for change detection.
+
+    This hash can be included in a Pebble layer's environment variables
+    to trigger automatic service restarts when the config file changes. (Thanks Mike Thamm!)
+    Pebble's replan() detects layer changes and restarts affected services.
+
+    Example usage in a charm::
+
+        def _build_pebble_layer(self) -> ops.pebble.LayerDict:
+            return {
+                "services": {
+                    "myservice": {
+                        "command": "/app/run",
+                        "environment": {
+                            # Pebble restarts service when this changes
+                            "__CONFIG_HASH": get_config_hash(
+                                self._container, "/config/app.ini"
+                            ),
+                        },
+                    }
+                }
+            }
+
+    Args:
+        container: The ops.Container to read from.
+        config_path: Path to the config file in the container.
+
+    Returns:
+        A 16-character hex hash of the file content, or empty string
+        if the file doesn't exist.
+    """
+    if not container.exists(config_path):
+        return ""
+    content = container.pull(config_path).read()
+    return hashlib.sha256(content.encode()).hexdigest()[:16]

charmarr_lib/core/_juju/_reconciler.py

@@ -0,0 +1,137 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Reconciler utilities for Juju charm event observation.
+
+This module provides utilities for implementing the reconciler pattern in Juju charms.
+The key insight is that most charm logic can be expressed as a reconcile function that
+brings actual state in line with desired state, and this function should run on most
+events.
+
+Key components:
+- observe_events(): Register a handler for multiple event types at once
+- reconcilable_events_k8s: Default event set for K8s charms
+- reconcilable_events_k8s_workloadless: Event set for charms without containers
+
+Usage:
+    class MyCharm(ops.CharmBase):
+        def __init__(self, framework: ops.Framework):
+            super().__init__(framework)
+            observe_events(self, reconcilable_events_k8s, self._reconcile)
+
+        def _reconcile(self, event: ops.EventBase) -> None:
+            # Your reconciliation logic here
+            pass
+
+Based on: https://github.com/canonical/cos-lib/blob/main/src/cosl/reconciler.py
+"""
+
+import inspect
+import itertools
+from collections.abc import Callable, Iterable
+from typing import Any, Final, cast
+
+import ops
+
+_CTR = itertools.count()
+
+all_events: Final[set[type[ops.EventBase]]] = {
+    ops.charm.PebbleCheckRecoveredEvent,
+    ops.charm.PebbleCheckFailedEvent,
+    ops.charm.ConfigChangedEvent,
+    ops.charm.UpdateStatusEvent,
+    ops.charm.PreSeriesUpgradeEvent,
+    ops.charm.PostSeriesUpgradeEvent,
+    ops.charm.LeaderElectedEvent,
+    ops.charm.LeaderSettingsChangedEvent,
+    ops.charm.RelationCreatedEvent,
+    ops.charm.PebbleReadyEvent,
+    ops.charm.RelationJoinedEvent,
+    ops.charm.RelationChangedEvent,
+    ops.charm.RelationDepartedEvent,
+    ops.charm.RelationBrokenEvent,
+    ops.charm.StorageAttachedEvent,
+    ops.charm.StorageDetachingEvent,
+    ops.charm.SecretChangedEvent,
+    ops.charm.SecretRotateEvent,
+    ops.charm.SecretRemoveEvent,
+    ops.charm.SecretExpiredEvent,
+    ops.charm.InstallEvent,
+    ops.charm.StartEvent,
+    ops.charm.RemoveEvent,
+    ops.charm.StopEvent,
+    ops.charm.UpgradeCharmEvent,
+    ops.charm.PebbleCustomNoticeEvent,
+}
+
+reconcilable_events_k8s: Final[set[type[ops.EventBase]]] = all_events.difference(
+    {
+        # Custom notices often need specific handling
+        ops.charm.PebbleCustomNoticeEvent,
+        # Reconciling towards "up" state during removal is harmful
+        ops.charm.RemoveEvent,
+        # This is the only chance to detect upgrades and perform migration logic
+        ops.charm.UpgradeCharmEvent,
+    }
+)
+
+reconcilable_events_k8s_workloadless: Final[set[type[ops.EventBase]]] = (
+    reconcilable_events_k8s.difference(
+        {
+            # Workload-less charms don't have Pebble containers
+            ops.charm.PebbleCheckRecoveredEvent,
+            ops.charm.PebbleCheckFailedEvent,
+            ops.charm.PebbleReadyEvent,
+        }
+    )
+)
+
+
+def observe_events[EventT: type[ops.EventBase]](
+    charm: ops.CharmBase,
+    events: Iterable[EventT],
+    handler: Callable[[Any], None] | Callable[[], None],
+) -> None:
+    """Observe all events that are subtypes of a given list using the provided handler.
+
+    This function simplifies the common pattern of observing many event types with
+    the same handler (reconcile function).
+
+    Args:
+        charm: The charm instance.
+        events: Event types to observe (e.g., reconcilable_events_k8s).
+        handler: The handler function. Can be either:
+            - A method of an ops.Object that takes an event parameter
+            - A zero-argument callable (a proxy will be created)
+
+    Examples:
+        # Observe all reconcilable events with a method
+        observe_events(self, reconcilable_events_k8s, self._reconcile)
+
+        # Observe specific events
+        observe_events(self, {ops.StartEvent, ops.ConfigChangedEvent}, self._on_config_event)
+
+        # For workload-less charms (no Pebble events)
+        observe_events(self, reconcilable_events_k8s_workloadless, self._reconcile)
+    """
+    evthandler: Callable[[Any], None]
+
+    if not inspect.signature(handler).parameters:
+
+        class _Observer(ops.Object):
+            _key = f"_observer_proxy_{next(_CTR)}"
+
+            def __init__(self) -> None:
+                super().__init__(charm, key=self._key)
+                setattr(charm.framework, self._key, self)
+
+            def evt_handler(self, _: ops.EventBase) -> None:
+                handler()  # type: ignore[call-arg]
+
+        evthandler = _Observer().evt_handler
+    else:
+        evthandler = cast(Callable[[Any], None], handler)
+
+    for bound_evt in charm.on.events().values():
+        if any(issubclass(bound_evt.event_type, include_type) for include_type in events):
+            charm.framework.observe(bound_evt, evthandler)

charmarr_lib/core/_juju/_secrets.py

@@ -0,0 +1,44 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Juju Secrets utilities for Charmarr charms."""
+
+from __future__ import annotations
+
+import ops
+
+_ROTATION_POLICIES: dict[str, ops.SecretRotate | None] = {
+    "disabled": None,
+    "daily": ops.SecretRotate.DAILY,
+    "monthly": ops.SecretRotate.MONTHLY,
+    "yearly": ops.SecretRotate.YEARLY,
+}
+
+
+def get_secret_rotation_policy(config_value: str) -> ops.SecretRotate | None:
+    """Convert config string to SecretRotate enum.
+
+    Args:
+        config_value: One of 'disabled', 'daily', 'monthly', 'yearly'
+
+    Returns:
+        SecretRotate enum value or None if disabled
+    """
+    return _ROTATION_POLICIES.get(config_value.lower())
+
+
+def sync_secret_rotation_policy(secret: ops.Secret, config_value: str) -> None:
+    """Sync secret rotation policy with config value.
+
+    Updates the secret's rotation policy if it differs from the configured value.
+    This should be called during reconciliation to ensure config changes take effect.
+
+    Args:
+        secret: The Juju secret to update
+        config_value: One of 'disabled', 'daily', 'monthly', 'yearly'
+    """
+    desired_policy = get_secret_rotation_policy(config_value)
+    current_info = secret.get_info()
+
+    if current_info.rotation != desired_policy and desired_policy is not None:
+        secret.set_info(rotate=desired_policy)

charmarr_lib/core/_k8s/__init__.py

@@ -0,0 +1,43 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Kubernetes utilities for resource management and patching.
+
+This package provides utilities for interacting with Kubernetes resources
+via lightkube, with a focus on patching StatefulSets managed by Juju.
+
+Key components:
+- K8sResourceManager: Generic K8s resource operations with retry logic (from charmarr-lib-krm)
+- reconcile_storage_volume: Mount shared PVCs in StatefulSets
+- reconcile_hardware_transcoding: Mount hardware devices for GPU transcoding
+- check_storage_permissions: Verify puid/pgid can write to mounted storage
+"""
+
+from charmarr_lib.core._k8s._hardware import (
+    is_hardware_device_mounted,
+    reconcile_hardware_transcoding,
+)
+from charmarr_lib.core._k8s._permission_check import (
+    PermissionCheckResult,
+    PermissionCheckStatus,
+    check_storage_permissions,
+    delete_permission_check_job,
+)
+from charmarr_lib.core._k8s._storage import (
+    is_storage_mounted,
+    reconcile_storage_volume,
+)
+from charmarr_lib.krm import K8sResourceManager, ReconcileResult
+
+__all__ = [
+    "K8sResourceManager",
+    "PermissionCheckResult",
+    "PermissionCheckStatus",
+    "ReconcileResult",
+    "check_storage_permissions",
+    "delete_permission_check_job",
+    "is_hardware_device_mounted",
+    "is_storage_mounted",
+    "reconcile_hardware_transcoding",
+    "reconcile_storage_volume",
+]

charmarr_lib/core/_k8s/_hardware.py

@@ -0,0 +1,191 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""StatefulSet patching utilities for hardware device access.
+
+This module provides functions to mount host devices (like /dev/dri for
+Intel QuickSync) into a StatefulSet managed by Juju. Used by charms that
+need hardware transcoding capabilities (Plex, Jellyfin).
+
+Key concepts:
+- HostPath volume: Mounts a path from the host node into the pod
+- Device access: /dev/dri provides GPU access for hardware transcoding
+
+See ADR: apps/adr-009-plex.md (hardware transcoding section)
+"""
+
+from lightkube.models.core_v1 import (
+    Container,
+    HostPathVolumeSource,
+    Volume,
+    VolumeMount,
+)
+from lightkube.resources.apps_v1 import StatefulSet
+
+from charmarr_lib.krm import K8sResourceManager, ReconcileResult
+
+_DRI_VOLUME_NAME = "dev-dri"
+_DRI_HOST_PATH = "/dev/dri"
+_DRI_MOUNT_PATH = "/dev/dri"
+
+
+def _has_volume(sts: StatefulSet, volume_name: str) -> bool:
+    """Check if a StatefulSet has a volume with the given name."""
+    if sts.spec is None or sts.spec.template.spec is None:
+        return False
+    volumes = sts.spec.template.spec.volumes or []
+    return any(v.name == volume_name for v in volumes)
+
+
+def _has_volume_mount(sts: StatefulSet, container_name: str, mount_name: str) -> bool:
+    """Check if a container has a volume mount with the given name."""
+    if sts.spec is None or sts.spec.template.spec is None:
+        return False
+    containers = sts.spec.template.spec.containers or []
+    for container in containers:
+        if container.name == container_name:
+            mounts = container.volumeMounts or []
+            return any(m.name == mount_name for m in mounts)
+    return False
+
+
+def is_hardware_device_mounted(
+    sts: StatefulSet,
+    container_name: str,
+    volume_name: str = _DRI_VOLUME_NAME,
+) -> bool:
+    """Check if hardware device is already mounted in a StatefulSet.
+
+    Args:
+        sts: The StatefulSet to check.
+        container_name: Name of the container (from charmcraft.yaml).
+        volume_name: Name of the volume.
+
+    Returns:
+        True if both the volume and its mount exist, False otherwise.
+    """
+    return _has_volume(sts, volume_name) and _has_volume_mount(sts, container_name, volume_name)
+
+
+def _build_hardware_device_patch(
+    container_name: str,
+    host_path: str,
+    mount_path: str,
+    volume_name: str,
+) -> dict:
+    """Build a strategic merge patch for adding hardware device volume."""
+    volume = Volume(
+        name=volume_name,
+        hostPath=HostPathVolumeSource(path=host_path, type="Directory"),
+    )
+    mount = VolumeMount(name=volume_name, mountPath=mount_path)
+    container = Container(name=container_name, volumeMounts=[mount])
+
+    return {
+        "spec": {
+            "template": {
+                "spec": {
+                    "volumes": [volume.to_dict()],
+                    "containers": [container.to_dict()],
+                }
+            }
+        }
+    }
+
+
+def _find_volume_index(volumes: list[Volume], name: str) -> int | None:
+    """Find the index of a volume by name."""
+    for i, vol in enumerate(volumes):
+        if vol.name == name:
+            return i
+    return None
+
+
+def _find_mount_index(mounts: list[VolumeMount], name: str) -> int | None:
+    """Find the index of a volume mount by name."""
+    for i, mount in enumerate(mounts):
+        if mount.name == name:
+            return i
+    return None
+
+
+def _build_remove_hardware_device_json_patch(
+    sts: StatefulSet,
+    container_name: str,
+    volume_name: str,
+) -> list[dict]:
+    """Build JSON patch operations to remove a hardware device volume and mount."""
+    if sts.spec is None or sts.spec.template.spec is None:
+        return []
+
+    pod_spec = sts.spec.template.spec
+    operations: list[dict] = []
+
+    volumes = pod_spec.volumes or []
+    volume_idx = _find_volume_index(volumes, volume_name)
+    if volume_idx is not None:
+        operations.append({"op": "remove", "path": f"/spec/template/spec/volumes/{volume_idx}"})
+
+    containers = pod_spec.containers or []
+    for ci, container in enumerate(containers):
+        if container.name == container_name:
+            mounts = container.volumeMounts or []
+            mount_idx = _find_mount_index(mounts, volume_name)
+            if mount_idx is not None:
+                operations.append(
+                    {
+                        "op": "remove",
+                        "path": f"/spec/template/spec/containers/{ci}/volumeMounts/{mount_idx}",
+                    }
+                )
+            break
+
+    return operations
+
+
+def reconcile_hardware_transcoding(
+    manager: K8sResourceManager,
+    statefulset_name: str,
+    namespace: str,
+    container_name: str,
+    enabled: bool,
+    host_path: str = _DRI_HOST_PATH,
+    mount_path: str = _DRI_MOUNT_PATH,
+    volume_name: str = _DRI_VOLUME_NAME,
+) -> ReconcileResult:
+    """Reconcile hardware device (e.g., /dev/dri) mount on a StatefulSet.
+
+    This function ensures a hardware device is mounted (or unmounted) in a
+    Juju-managed StatefulSet for GPU-accelerated transcoding.
+
+    Args:
+        manager: K8sResourceManager instance.
+        statefulset_name: Name of the StatefulSet (usually self.app.name).
+        namespace: Kubernetes namespace (usually self.model.name).
+        container_name: Container name from charmcraft.yaml (NOT self.app.name!).
+        enabled: Whether hardware transcoding should be enabled.
+        host_path: Path on the host to mount (default: /dev/dri).
+        mount_path: Path inside the container (default: /dev/dri).
+        volume_name: Name for the volume definition.
+
+    Returns:
+        ReconcileResult indicating if changes were made.
+    """
+    from lightkube.types import PatchType
+
+    sts = manager.get(StatefulSet, statefulset_name, namespace)
+
+    if not enabled:
+        if not is_hardware_device_mounted(sts, container_name, volume_name):
+            return ReconcileResult(changed=False, message="Hardware device not mounted")
+        patch_ops = _build_remove_hardware_device_json_patch(sts, container_name, volume_name)
+        if patch_ops:
+            manager.patch(StatefulSet, statefulset_name, patch_ops, namespace, PatchType.JSON)
+        return ReconcileResult(changed=True, message=f"Removed hardware device {volume_name}")
+
+    if is_hardware_device_mounted(sts, container_name, volume_name):
+        return ReconcileResult(changed=False, message="Hardware device already mounted")
+
+    patch = _build_hardware_device_patch(container_name, host_path, mount_path, volume_name)
+    manager.patch(StatefulSet, statefulset_name, patch, namespace)
+    return ReconcileResult(changed=True, message=f"Hardware device mounted at {mount_path}")