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

charmarr_lib/core/_k8s/_permission_check.py

@@ -0,0 +1,310 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Permission checking utilities for shared storage volumes.
+
+This module provides functions to verify that a given puid/pgid can write
+to a mounted PVC. Uses a short-lived Kubernetes Job to test permissions.
+
+Use case:
+    The charmarr-storage charm needs to detect permission mismatches early,
+    rather than having consumer charms fail silently. This module creates
+    a Job that attempts to write a test file as the configured user/group.
+"""
+
+import logging
+from dataclasses import dataclass
+from enum import Enum
+
+from lightkube import ApiError
+from lightkube.models.batch_v1 import JobSpec
+from lightkube.models.core_v1 import (
+    Container,
+    PersistentVolumeClaimVolumeSource,
+    PodSpec,
+    PodTemplateSpec,
+    SecurityContext,
+    Volume,
+    VolumeMount,
+)
+from lightkube.models.meta_v1 import ObjectMeta
+from lightkube.resources.batch_v1 import Job
+from tenacity import retry, retry_if_result, stop_after_delay, wait_fixed
+
+from charmarr_lib.krm import K8sResourceManager
+
+logger = logging.getLogger(__name__)
+
+_JOB_NAME_PREFIX = "charmarr-permission-check"
+_TEST_FILE = ".charmarr-permission-test"
+_LABEL_PUID = "charmarr.io/puid"
+_LABEL_PGID = "charmarr.io/pgid"
+
+
+class PermissionCheckStatus(str, Enum):
+    """Status of a permission check."""
+
+    PASSED = "passed"
+    FAILED = "failed"
+    PENDING = "pending"
+    NOT_RUN = "not_run"
+
+
+@dataclass
+class PermissionCheckResult:
+    """Result of a storage permission check."""
+
+    status: PermissionCheckStatus
+    message: str
+
+
+def _get_job_name(pvc_name: str) -> str:
+    """Generate Job name from PVC name."""
+    return f"{_JOB_NAME_PREFIX}-{pvc_name[:20]}"
+
+
+def _build_permission_check_job(
+    job_name: str,
+    namespace: str,
+    pvc_name: str,
+    puid: int,
+    pgid: int,
+    mount_path: str,
+) -> Job:
+    """Build a Job that tests write permissions on the PVC."""
+    test_path = f"{mount_path}/{_TEST_FILE}"
+    command = [
+        "sh",
+        "-c",
+        f"touch {test_path} && rm {test_path} && echo 'Permission check passed'",
+    ]
+
+    container = Container(
+        name="permission-check",
+        image="busybox:latest",
+        command=command,
+        securityContext=SecurityContext(
+            runAsUser=puid,
+            runAsGroup=pgid,
+        ),
+        volumeMounts=[
+            VolumeMount(name="test-volume", mountPath=mount_path),
+        ],
+    )
+
+    volume = Volume(
+        name="test-volume",
+        persistentVolumeClaim=PersistentVolumeClaimVolumeSource(claimName=pvc_name),
+    )
+
+    return Job(
+        metadata=ObjectMeta(
+            name=job_name,
+            namespace=namespace,
+            labels={
+                "app.kubernetes.io/managed-by": "charmarr-storage",
+                _LABEL_PUID: str(puid),
+                _LABEL_PGID: str(pgid),
+            },
+        ),
+        spec=JobSpec(
+            ttlSecondsAfterFinished=300,
+            backoffLimit=0,
+            template=PodTemplateSpec(
+                spec=PodSpec(
+                    restartPolicy="Never",
+                    containers=[container],
+                    volumes=[volume],
+                ),
+            ),
+        ),
+    )
+
+
+def _get_job_status(job: Job) -> PermissionCheckStatus:
+    """Determine permission check status from Job state."""
+    if job.status is None:
+        return PermissionCheckStatus.PENDING
+
+    if job.status.succeeded and job.status.succeeded > 0:
+        return PermissionCheckStatus.PASSED
+
+    if job.status.failed and job.status.failed > 0:
+        return PermissionCheckStatus.FAILED
+
+    return PermissionCheckStatus.PENDING
+
+
+def _job_config_matches(job: Job, puid: int, pgid: int) -> bool:
+    """Check if existing Job was created with the same puid/pgid."""
+    if job.metadata is None or job.metadata.labels is None:
+        return False
+
+    labels = job.metadata.labels
+    job_puid = labels.get(_LABEL_PUID)
+    job_pgid = labels.get(_LABEL_PGID)
+
+    return job_puid == str(puid) and job_pgid == str(pgid)
+
+
+def _is_pending(result: PermissionCheckResult) -> bool:
+    """Check if result is still pending (used for retry condition)."""
+    return result.status == PermissionCheckStatus.PENDING
+
+
+def _make_poll_job_status(
+    manager: "K8sResourceManager",
+    job_name: str,
+    namespace: str,
+    puid: int,
+    pgid: int,
+):
+    """Create a polling function for Job status with tenacity retry."""
+
+    @retry(
+        stop=stop_after_delay(30),
+        wait=wait_fixed(2),
+        retry=retry_if_result(_is_pending),
+    )
+    def poll() -> PermissionCheckResult:
+        job = manager.get(Job, job_name, namespace)
+        status = _get_job_status(job)
+
+        if status == PermissionCheckStatus.PASSED:
+            return PermissionCheckResult(
+                status=PermissionCheckStatus.PASSED,
+                message="Storage permissions OK",
+            )
+        if status == PermissionCheckStatus.FAILED:
+            return PermissionCheckResult(
+                status=PermissionCheckStatus.FAILED,
+                message=f"Storage permission denied for puid={puid} pgid={pgid}. "
+                "Check ownership on storage backend.",
+            )
+        return PermissionCheckResult(
+            status=PermissionCheckStatus.PENDING,
+            message="Permission check in progress",
+        )
+
+    return poll
+
+
+def check_storage_permissions(
+    manager: K8sResourceManager,
+    namespace: str,
+    pvc_name: str,
+    puid: int,
+    pgid: int,
+    mount_path: str = "/data",
+) -> PermissionCheckResult:
+    """Check if puid/pgid can write to the mounted PVC.
+
+    Creates a short-lived Kubernetes Job that attempts to create and delete
+    a test file on the mounted storage as the specified user/group.
+
+    The Job is created if it doesn't exist, and its status is checked on
+    subsequent calls. Jobs are automatically cleaned up after 5 minutes
+    via ttlSecondsAfterFinished.
+
+    Args:
+        manager: K8sResourceManager instance.
+        namespace: Kubernetes namespace.
+        pvc_name: Name of the PVC to test.
+        puid: User ID to test write permissions as.
+        pgid: Group ID to test write permissions as.
+        mount_path: Path where the PVC is mounted.
+
+    Returns:
+        PermissionCheckResult with status and message.
+
+    Example:
+        result = check_storage_permissions(
+            manager=self.k8s,
+            namespace=self.model.name,
+            pvc_name="charmarr-shared-media",
+            puid=1000,
+            pgid=1000,
+        )
+        if result.status == PermissionCheckStatus.FAILED:
+            # Block charm with permission error message
+    """
+    job_name = _get_job_name(pvc_name)
+
+    try:
+        job = manager.get(Job, job_name, namespace)
+    except ApiError as e:
+        if e.status.code != 404:
+            raise
+        job = None
+
+    # If Job exists but config changed, delete it so we can create a new one
+    if job is not None and not _job_config_matches(job, puid, pgid):
+        logger.info(
+            "Permission check Job %s config changed, recreating with puid=%d pgid=%d",
+            job_name,
+            puid,
+            pgid,
+        )
+        manager.delete(Job, job_name, namespace)
+        job = None
+
+    if job is None:
+        job = _build_permission_check_job(
+            job_name=job_name,
+            namespace=namespace,
+            pvc_name=pvc_name,
+            puid=puid,
+            pgid=pgid,
+            mount_path=mount_path,
+        )
+        logger.info("Creating permission check Job %s for PVC %s", job_name, pvc_name)
+        manager.apply(job)
+
+    status = _get_job_status(job)
+
+    if status == PermissionCheckStatus.PASSED:
+        return PermissionCheckResult(
+            status=PermissionCheckStatus.PASSED,
+            message="Storage permissions OK",
+        )
+
+    if status == PermissionCheckStatus.FAILED:
+        return PermissionCheckResult(
+            status=PermissionCheckStatus.FAILED,
+            message=f"Storage permission denied for puid={puid} pgid={pgid}. "
+            "Check ownership on storage backend.",
+        )
+
+    # Job is PENDING - poll until it completes or times out
+    logger.info("Waiting for permission check Job %s to complete", job_name)
+    poll = _make_poll_job_status(manager, job_name, namespace, puid, pgid)
+    return poll()
+
+
+def delete_permission_check_job(
+    manager: K8sResourceManager,
+    namespace: str,
+    pvc_name: str,
+) -> bool:
+    """Delete the permission check Job if it exists.
+
+    Useful for forcing a re-check when puid/pgid config changes.
+
+    Args:
+        manager: K8sResourceManager instance.
+        namespace: Kubernetes namespace.
+        pvc_name: Name of the PVC the Job was created for.
+
+    Returns:
+        True if Job was deleted, False if it didn't exist.
+    """
+    job_name = _get_job_name(pvc_name)
+
+    try:
+        manager.delete(Job, job_name, namespace)
+        logger.info("Deleted permission check Job %s", job_name)
+        return True
+    except ApiError as e:
+        if e.status.code == 404:
+            return False
+        raise

charmarr_lib/core/_k8s/_storage.py

@@ -0,0 +1,253 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""StatefulSet patching utilities for shared storage volumes.
+
+This module provides functions to mount a shared PVC into a StatefulSet
+managed by Juju. Used by charms that need to access the shared media
+storage PVC created by the charmarr-storage charm.
+
+Key concepts:
+- Volume: A pod-level definition that references a PVC
+- VolumeMount: A container-level mount point for a volume
+- SecurityContext: Pod-level fsGroup for volume permissions
+
+Critical gotcha:
+    The container_name parameter MUST match the container name in
+    charmcraft.yaml, NOT the Juju application name (self.app.name).
+
+    Example:
+        # In charmcraft.yaml:
+        containers:
+          radarr:  # <- This is the container name
+            resource: oci-image
+
+        # In charm code:
+        reconcile_storage_volume(
+            manager,
+            statefulset_name=self.app.name,  # Could be "radarr-4k"
+            namespace=self.model.name,
+            container_name="radarr",  # MUST match charmcraft.yaml, not app.name!
+            pvc_name=storage_data.pvc_name,
+            mount_path=storage_data.mount_path,
+            pgid=storage_data.pgid,
+        )
+
+See ADR: storage/adr-003-pvc-patching-in-arr-charms.md
+"""
+
+from lightkube.models.core_v1 import (
+    Container,
+    PersistentVolumeClaimVolumeSource,
+    PodSecurityContext,
+    Volume,
+    VolumeMount,
+)
+from lightkube.resources.apps_v1 import StatefulSet
+from lightkube.types import PatchType
+
+from charmarr_lib.krm import K8sResourceManager, ReconcileResult
+
+_DEFAULT_VOLUME_NAME = "charmarr-shared-data"
+_DEFAULT_MOUNT_PATH = "/data"
+
+
+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_storage_mounted(
+    sts: StatefulSet,
+    container_name: str,
+    volume_name: str = _DEFAULT_VOLUME_NAME,
+) -> bool:
+    """Check if shared storage 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_storage_patch(
+    container_name: str,
+    pvc_name: str,
+    mount_path: str,
+    volume_name: str,
+    pgid: int | None = None,
+) -> dict:
+    """Build a strategic merge patch for adding storage volume.
+
+    The patch adds:
+    1. A volume referencing the PVC
+    2. A volumeMount in the specified container
+    3. Optionally, a securityContext with fsGroup for volume permissions
+
+    Strategic merge patch merges arrays by the 'name' field,
+    so existing volumes and containers are preserved.
+    """
+    volume = Volume(
+        name=volume_name,
+        persistentVolumeClaim=PersistentVolumeClaimVolumeSource(claimName=pvc_name),
+    )
+    mount = VolumeMount(name=volume_name, mountPath=mount_path)
+    container = Container(name=container_name, volumeMounts=[mount])
+
+    pod_spec: dict = {
+        "volumes": [volume.to_dict()],
+        "containers": [container.to_dict()],
+    }
+
+    if pgid is not None:
+        security_context = PodSecurityContext(fsGroup=pgid)
+        pod_spec["securityContext"] = security_context.to_dict()
+
+    return {
+        "spec": {
+            "template": {
+                "spec": pod_spec,
+            }
+        }
+    }
+
+
+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_storage_json_patch(
+    sts: StatefulSet,
+    container_name: str,
+    volume_name: str,
+) -> list[dict]:
+    """Build JSON patch operations to remove a storage volume, mount, and securityContext.
+
+    Returns a list of JSON patch operations that remove:
+    1. The volume from spec.template.spec.volumes
+    2. The volumeMount from the target container
+    3. The securityContext from the pod spec (if present)
+    """
+    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
+
+    if pod_spec.securityContext is not None:
+        operations.append({"op": "remove", "path": "/spec/template/spec/securityContext"})
+
+    return operations
+
+
+def reconcile_storage_volume(
+    manager: K8sResourceManager,
+    statefulset_name: str,
+    namespace: str,
+    container_name: str,
+    pvc_name: str | None,
+    mount_path: str = _DEFAULT_MOUNT_PATH,
+    volume_name: str = _DEFAULT_VOLUME_NAME,
+    pgid: int | None = None,
+) -> ReconcileResult:
+    """Reconcile shared storage PVC volume and mount on a StatefulSet.
+
+    This function ensures a shared PVC is mounted (or unmounted) in a
+    Juju-managed StatefulSet. Uses strategic merge patch which is idempotent.
+
+    If pvc_name is None, the volume is removed. If pvc_name is provided,
+    the volume is mounted.
+
+    When pgid is provided, the pod's SecurityContext is set with fsGroup.
+    This ensures files on the shared storage have the correct group ownership.
+
+    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!).
+        pvc_name: Name of the PVC to mount, or None to unmount.
+        mount_path: Path where the volume should be mounted.
+        volume_name: Name for the volume definition.
+        pgid: Group ID for fsGroup (from storage relation).
+
+    Returns:
+        ReconcileResult indicating if changes were made.
+
+    Raises:
+        ApiError: If the StatefulSet doesn't exist or patch fails.
+
+    Example:
+        result = reconcile_storage_volume(
+            manager,
+            statefulset_name=self.app.name,
+            namespace=self.model.name,
+            container_name="radarr",
+            pvc_name=storage_data.pvc_name if storage_data else None,
+            mount_path=storage_data.mount_path,
+            pgid=storage_data.pgid,
+        )
+    """
+    if pvc_name is None:
+        sts = manager.get(StatefulSet, statefulset_name, namespace)
+        if not is_storage_mounted(sts, container_name, volume_name):
+            return ReconcileResult(changed=False, message="Storage not mounted")
+        patch_ops = _build_remove_storage_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 volume {volume_name}")
+
+    patch = _build_storage_patch(container_name, pvc_name, mount_path, volume_name, pgid)
+    manager.patch(StatefulSet, statefulset_name, patch, namespace)
+    return ReconcileResult(changed=True, message=f"Storage configured at {mount_path}")

charmarr_lib/core/_variant.py

@@ -0,0 +1,37 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Content variant utilities for media managers."""
+
+from charmarr_lib.core.enums import ContentVariant, MediaManager
+
+_ROOT_FOLDERS: dict[tuple[ContentVariant, MediaManager], str] = {
+    (ContentVariant.STANDARD, MediaManager.RADARR): "/data/media/movies",
+    (ContentVariant.UHD, MediaManager.RADARR): "/data/media/movies-uhd",
+    (ContentVariant.ANIME, MediaManager.RADARR): "/data/media/anime/movies",
+    (ContentVariant.STANDARD, MediaManager.SONARR): "/data/media/tv",
+    (ContentVariant.UHD, MediaManager.SONARR): "/data/media/tv-uhd",
+    (ContentVariant.ANIME, MediaManager.SONARR): "/data/media/anime/tv",
+}
+
+_DEFAULT_TRASH_PROFILES: dict[ContentVariant, str] = {
+    ContentVariant.STANDARD: "",
+    ContentVariant.UHD: "uhd-bluray-web",
+    ContentVariant.ANIME: "anime",
+}
+
+
+def get_root_folder(variant: ContentVariant, manager: MediaManager) -> str:
+    """Get root folder path for a content variant and media manager."""
+    return _ROOT_FOLDERS[(variant, manager)]
+
+
+def get_default_trash_profiles(variant: ContentVariant) -> str:
+    """Get default trash profiles for a content variant.
+
+    Returns:
+        - standard: empty (no default profiles)
+        - 4k: uhd-bluray-web
+        - anime: anime
+    """
+    return _DEFAULT_TRASH_PROFILES[variant]

charmarr_lib/core/_version.py

@@ -0,0 +1,3 @@
+"""Version for charmarr-core package."""
+
+__version__ = "0.12.2"  # x-release-please-version

charmarr_lib/core/constants.py

@@ -0,0 +1,29 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Shared constants for Charmarr interfaces and API clients."""
+
+from charmarr_lib.core.enums import MediaManager
+
+# Maps media manager types to their download folder names.
+# Used by:
+# - Download client charms (qBittorrent, SABnzbd) to create categories with correct save paths
+# - Arr charms to know where downloads will land (for import path configuration)
+MEDIA_TYPE_DOWNLOAD_PATHS: dict[MediaManager, str] = {
+    MediaManager.RADARR: "movies",
+    MediaManager.SONARR: "tv",
+    MediaManager.LIDARR: "music",
+    MediaManager.READARR: "books",
+    MediaManager.WHISPARR: "xxx",
+}
+
+# Maps media managers to their Prowlarr application implementation details.
+# Tuple format: (implementation_name, config_contract_name)
+# Used by ApplicationConfigBuilder to transform relation data into Prowlarr application payloads.
+MEDIA_MANAGER_IMPLEMENTATIONS: dict[MediaManager, tuple[str, str]] = {
+    MediaManager.RADARR: ("Radarr", "RadarrSettings"),
+    MediaManager.SONARR: ("Sonarr", "SonarrSettings"),
+    MediaManager.LIDARR: ("Lidarr", "LidarrSettings"),
+    MediaManager.READARR: ("Readarr", "ReadarrSettings"),
+    MediaManager.WHISPARR: ("Whisparr", "WhisparrSettings"),
+}

charmarr_lib/core/enums.py

@@ -0,0 +1,55 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Consolidated enums for Charmarr interfaces."""
+
+from enum import Enum
+
+
+class MediaIndexer(str, Enum):
+    """Media indexer applications."""
+
+    PROWLARR = "prowlarr"
+
+
+class MediaManager(str, Enum):
+    """Media manager applications."""
+
+    RADARR = "radarr"
+    SONARR = "sonarr"
+    LIDARR = "lidarr"
+    READARR = "readarr"
+    WHISPARR = "whisparr"
+
+
+class DownloadClient(str, Enum):
+    """Download client applications."""
+
+    QBITTORRENT = "qbittorrent"
+    SABNZBD = "sabnzbd"
+
+
+class DownloadClientType(str, Enum):
+    """Download protocol categories."""
+
+    TORRENT = "torrent"
+    USENET = "usenet"
+
+
+class RequestManager(str, Enum):
+    """Request management applications."""
+
+    OVERSEERR = "overseerr"
+    JELLYSEERR = "jellyseerr"
+
+
+class ContentVariant(str, Enum):
+    """Content variant for media manager instances.
+
+    STANDARD is the default catch-all for any content type.
+    UHD and ANIME are specialized variants with dedicated folders.
+    """
+
+    STANDARD = "standard"
+    UHD = "4k"
+    ANIME = "anime"