cpkit 0.1.0__py3-none-any.whl

cpkit/jobs/repository.py

@@ -0,0 +1,306 @@
+"""Repository helpers for the framework message queue."""
+
+from typing import Any
+
+from cpkit.db import execute_stmt, fetch_all, fetch_one
+
+from .maintenance import FAIL_ZOMBIE_JOBS_MESSAGE_TYPE
+from .types import IntID, Job, JobID, JobStatsResponse, LinkedResourceRef, Task
+
+QUEUE_TABLE = "cpkit.mq"
+JOBS_TABLE = "cpkit.jobs"
+TASKS_TABLE = "cpkit.tasks"
+
+
+class QueueRepositoryMixin:
+    """Repository mixin for enqueueing framework queue messages."""
+
+    def enqueue_message(
+        self,
+        msg_type: Any,
+        payload: Any | None,
+        created_by: str,
+        *,
+        start_after_seconds: int = 0,
+    ) -> None:
+        """Enqueue a message to be processed by the framework worker."""
+        execute_stmt(
+            f"""
+            INSERT INTO {QUEUE_TABLE}
+                (msg_type, msg_data, created_by, start_after)
+            VALUES
+                (%s, %s, %s, now() + (%s * INTERVAL '1s'))
+            """,
+            (
+                _message_type_value(msg_type),
+                _payload_value(payload),
+                created_by,
+                start_after_seconds,
+            ),
+            operation="jobs.enqueue_message",
+        )
+
+
+class QueueJobRepositoryMixin(QueueRepositoryMixin):
+    """Repository mixin for enqueueing queue messages backed by job records."""
+
+    def enqueue_command(
+        self,
+        command_type: Any,
+        payload: Any,
+        created_by: str,
+    ) -> JobID:
+        payload_value = _payload_value(payload)
+        playbook_version = payload_value.get("playbook_version")
+        job_description = {
+            key: value for key, value in payload_value.items() if key != "playbook_version"
+        }
+        command_type_value = _message_type_value(command_type)
+        return fetch_one(
+            f"""
+            WITH
+            create_new_job AS (
+                INSERT INTO {QUEUE_TABLE}
+                    (msg_type, msg_data, created_by)
+                VALUES
+                    (%s, %s, %s)
+                RETURNING msg_id
+            )
+            INSERT INTO {JOBS_TABLE}
+                (job_id, job_type, status, playbook_version, description, created_by)
+            VALUES
+                ((select msg_id from create_new_job), %s, %s, %s, %s, %s)
+            RETURNING job_id AS job_id
+            """,
+            (
+                command_type_value,
+                payload_value,
+                created_by,
+                command_type_value,
+                "QUEUED",
+                str(playbook_version) if playbook_version is not None else None,
+                job_description,
+                created_by,
+            ),
+            JobID,
+            operation="jobs.enqueue_command",
+        )
+
+
+class JobsRepositoryMixin:
+    """Repository mixin for framework job history, status, and task records."""
+
+    def get_job_stats(
+        self,
+        groups: list[str],
+        is_admin: bool = False,
+    ) -> JobStatsResponse:
+        if is_admin:
+            return (
+                fetch_one(
+                    f"""
+                    SELECT
+                        COUNT(*) AS total,
+                        COALESCE(SUM(CASE WHEN status = %s THEN 1 ELSE 0 END), 0) AS running,
+                        COALESCE(SUM(CASE WHEN status = %s THEN 1 ELSE 0 END), 0) AS queued,
+                        COALESCE(SUM(CASE WHEN status = %s THEN 1 ELSE 0 END), 0) AS failed
+                    FROM {JOBS_TABLE}
+                    """,
+                    ("RUNNING", "QUEUED", "FAILED"),
+                    JobStatsResponse,
+                )
+                or JobStatsResponse(total=0, running=0, queued=0, failed=0)
+            )
+
+        return (
+            fetch_one(
+                f"""
+                WITH
+                c AS (
+                    SELECT cluster_id
+                    FROM clusters
+                    WHERE grp = ANY (%s)
+                ),
+                cj AS (
+                    SELECT DISTINCT job_id
+                    FROM {self.job_cluster_map_table}
+                    WHERE cluster_id IN (SELECT * FROM c)
+                )
+                SELECT
+                    COUNT(*) AS total,
+                    COALESCE(SUM(CASE WHEN status = %s THEN 1 ELSE 0 END), 0) AS running,
+                    COALESCE(SUM(CASE WHEN status = %s THEN 1 ELSE 0 END), 0) AS queued,
+                    COALESCE(SUM(CASE WHEN status = %s THEN 1 ELSE 0 END), 0) AS failed
+                FROM {JOBS_TABLE}
+                WHERE job_id IN (SELECT * FROM cj)
+                """,
+                (groups, "RUNNING", "QUEUED", "FAILED"),
+                JobStatsResponse,
+            )
+            or JobStatsResponse(total=0, running=0, queued=0, failed=0)
+        )
+
+    def list_jobs(self, groups: list[str], is_admin: bool = False) -> list[Job]:
+        if is_admin:
+            return fetch_all(
+                f"""
+                SELECT *
+                FROM {JOBS_TABLE}
+                ORDER BY created_at DESC
+                """,
+                (),
+                Job,
+            )
+
+        return fetch_all(
+            f"""
+            WITH
+            c AS (
+                SELECT cluster_id
+                FROM clusters
+                WHERE grp = ANY (%s)
+            ),
+            cj AS (
+                SELECT job_id
+                FROM {self.job_cluster_map_table}
+                WHERE cluster_id IN (SELECT * FROM c)
+            )
+            SELECT *
+            FROM {JOBS_TABLE}
+            WHERE job_id IN (SELECT * FROM cj)
+            ORDER BY created_at DESC;
+            """,
+            (groups,),
+            Job,
+        )
+
+    def get_job(
+        self,
+        job_id: int,
+        groups: list[str],
+        is_admin: bool = False,
+    ) -> Job | None:
+        if is_admin:
+            return fetch_one(
+                f"""
+                SELECT *
+                FROM {JOBS_TABLE}
+                WHERE job_id = %s
+                """,
+                (job_id,),
+                Job,
+            )
+        return fetch_one(
+            f"""
+            WITH
+            c AS (
+                SELECT cluster_id
+                FROM clusters
+                WHERE grp = ANY (%s)
+            ),
+            cj AS (
+                SELECT job_id
+                FROM {self.job_cluster_map_table}
+                WHERE cluster_id IN (SELECT * FROM c)
+            )
+            SELECT *
+            FROM {JOBS_TABLE}
+            WHERE job_id IN (SELECT * FROM cj)
+                AND job_id = %s
+            """,
+            (groups, job_id),
+            Job,
+        )
+
+    def list_tasks(self, job_id: int) -> list[Task]:
+        return fetch_all(
+            f"""
+            SELECT job_id, task_id,
+                created_at, task_name, task_desc
+            FROM {TASKS_TABLE}
+            WHERE job_id = %s
+            ORDER BY task_id DESC
+            """,
+            (job_id,),
+            Task,
+        )
+
+    @property
+    def job_cluster_map_table(self) -> str:
+        raise NotImplementedError(
+            "Applications using group-scoped job visibility must provide "
+            "a job-cluster mapping table."
+        )
+
+    def list_linked_resources(self, job_id: int) -> list[LinkedResourceRef]:
+        return []
+
+    def update_job(self, job_id: int, status: str) -> None:
+        execute_stmt(
+            f"""
+            UPDATE {JOBS_TABLE}
+            SET status = %s
+            WHERE job_id = %s
+            """,
+            (_message_type_value(status), job_id),
+        )
+
+    def set_job_playbook_version(self, job_id: int, playbook_version: str) -> None:
+        execute_stmt(
+            f"""
+            UPDATE {JOBS_TABLE}
+            SET playbook_version = %s
+            WHERE job_id = %s
+            """,
+            (playbook_version, job_id),
+        )
+
+    def fail_zombie_jobs(self) -> list[IntID]:
+        return fetch_all(
+            f"""
+            WITH
+            fail_zombie_jobs AS (
+                INSERT INTO {QUEUE_TABLE} (msg_type, start_after)
+                VALUES (%s, now() + INTERVAL '300s' + (random()*10)::INTERVAL)
+                RETURNING 1
+            )
+            UPDATE {JOBS_TABLE}
+            SET status = %s
+            WHERE status in (%s, %s)
+                AND now() > updated_at + INTERVAL '300s'
+            RETURNING job_id AS id
+            """,
+            (FAIL_ZOMBIE_JOBS_MESSAGE_TYPE, "FAILED", "RUNNING", "QUEUED"),
+            IntID,
+        )
+
+    def create_task(
+        self,
+        job_id: int,
+        task_id: int,
+        created_at,
+        task_name: str,
+        task_desc,
+    ) -> None:
+        execute_stmt(
+            f"""
+            INSERT INTO {TASKS_TABLE}
+                (job_id, task_id, created_at, task_name, task_desc)
+            VALUES (%s, %s, %s, %s, %s)
+            """,
+            (job_id, task_id, created_at, task_name, task_desc),
+        )
+
+
+def _message_type_value(msg_type: Any) -> str:
+    return str(getattr(msg_type, "value", msg_type))
+
+
+def _payload_value(payload: Any | None) -> dict[str, Any]:
+    if payload is None:
+        return {}
+    if hasattr(payload, "model_dump"):
+        return payload.model_dump()
+    if isinstance(payload, dict):
+        return payload
+    raise TypeError("Queue message payload must be a mapping or Pydantic model.")

cpkit/jobs/router.py

@@ -0,0 +1,105 @@
+"""FastAPI routes for framework job management."""
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from .types import Job, JobDetailsResponse, JobRescheduleResponse, JobStatsResponse
+
+
+def create_jobs_router(
+    *,
+    get_service: Callable[..., Any],
+    get_access_scope: Callable[[dict], tuple[list[str], bool]],
+    get_audit_actor: Callable[..., Any],
+    require_readonly: Callable[..., Any],
+    require_user: Callable[..., Any],
+    handle_service_error: Callable[[Exception], None],
+    service_error_type: type[Exception] = Exception,
+) -> APIRouter:
+    router = APIRouter(prefix="/jobs", tags=["cpkit"])
+
+    @router.get("/")
+    async def list_jobs(
+        claims: dict = Depends(require_readonly),
+        service=Depends(get_service),
+    ) -> list[Job]:
+        groups, is_admin = get_access_scope(claims)
+        try:
+            return service.list_visible_jobs(groups, is_admin)
+        except service_error_type as err:
+            handle_service_error(err)
+
+    @router.get("/stats", response_model=JobStatsResponse)
+    async def get_job_stats(
+        claims: dict = Depends(require_readonly),
+        service=Depends(get_service),
+    ) -> JobStatsResponse:
+        groups, is_admin = get_access_scope(claims)
+        try:
+            return service.get_visible_job_stats(groups, is_admin)
+        except service_error_type as err:
+            handle_service_error(err)
+
+    @router.get("/{job_id}")
+    async def get_job(
+        job_id: int,
+        claims: dict = Depends(require_readonly),
+        service=Depends(get_service),
+    ) -> Job:
+        groups, is_admin = get_access_scope(claims)
+        try:
+            job = service.get_job_for_user(job_id, groups, is_admin)
+        except service_error_type as err:
+            handle_service_error(err)
+
+        if job is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Job '{job_id}' was not found.",
+            )
+
+        return job
+
+    @router.get("/{job_id}/details", response_model=JobDetailsResponse)
+    async def get_job_details(
+        job_id: int,
+        claims: dict = Depends(require_readonly),
+        service=Depends(get_service),
+    ) -> JobDetailsResponse:
+        groups, is_admin = get_access_scope(claims)
+        try:
+            details = service.get_job_details_for_user(job_id, groups, is_admin)
+        except service_error_type as err:
+            handle_service_error(err)
+
+        if details is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Job '{job_id}' was not found.",
+            )
+
+        return JobDetailsResponse(**details)
+
+    @router.post("/{job_id}/reschedule", response_model=JobRescheduleResponse)
+    async def reschedule_job(
+        job_id: int,
+        claims: dict = Depends(require_user),
+        actor_id: str = Depends(get_audit_actor),
+        service=Depends(get_service),
+    ) -> JobRescheduleResponse:
+        groups, is_admin = get_access_scope(claims)
+        try:
+            new_job_id = service.enqueue_job_reschedule(
+                job_id,
+                groups,
+                is_admin,
+                actor_id,
+            )
+        except service_error_type as err:
+            handle_service_error(err)
+
+        return JobRescheduleResponse(job_id=new_job_id)
+
+    return router

cpkit/jobs/service.py

@@ -0,0 +1,138 @@
+"""Service helpers for framework job history and rescheduling."""
+
+from collections.abc import Callable
+from typing import Any
+
+import yaml
+
+from cpkit.errors import RepositoryError, ServiceNotFoundError, from_repository_error
+
+from .types import Job, JobID, JobStatsResponse
+
+PayloadParser = Callable[[Any, dict[str, Any]], Any]
+RescheduleTypeResolver = Callable[[str], Any]
+JobAuditHook = Callable[[Any, str, str, dict[str, Any]], None]
+
+
+class JobsService:
+    def __init__(
+        self,
+        repo,
+        *,
+        parse_payload: PayloadParser,
+        reschedule_type_resolver: RescheduleTypeResolver,
+        rescheduled_hook: JobAuditHook | None = None,
+    ) -> None:
+        self.repo = repo
+        self.parse_payload = parse_payload
+        self.reschedule_type_resolver = reschedule_type_resolver
+        self.rescheduled_hook = rescheduled_hook
+
+    def list_visible_jobs(self, groups: list[str], is_admin: bool) -> list[Job]:
+        try:
+            return self.repo.list_jobs(groups, is_admin)
+        except RepositoryError as err:
+            raise from_repository_error(
+                err,
+                unavailable_message="Jobs are temporarily unavailable.",
+                fallback_message="Unable to load jobs.",
+            ) from err
+
+    def get_visible_job_stats(
+        self,
+        groups: list[str],
+        is_admin: bool,
+    ) -> JobStatsResponse:
+        try:
+            return self.repo.get_job_stats(groups, is_admin)
+        except RepositoryError as err:
+            raise from_repository_error(
+                err,
+                unavailable_message="Job stats are temporarily unavailable.",
+                fallback_message="Unable to load job stats.",
+            ) from err
+
+    def get_job_for_user(
+        self,
+        job_id: int,
+        groups: list[str],
+        is_admin: bool,
+    ) -> Job | None:
+        try:
+            return self.repo.get_job(job_id, groups, is_admin)
+        except RepositoryError as err:
+            raise from_repository_error(
+                err,
+                unavailable_message="Job details are temporarily unavailable.",
+                fallback_message=f"Unable to load job '{job_id}'.",
+            ) from err
+
+    def get_job_details_for_user(
+        self,
+        job_id: int,
+        groups: list[str],
+        is_admin: bool,
+    ) -> dict[str, Any] | None:
+        selected_job = self.get_job_for_user(job_id, groups, is_admin)
+        if selected_job is None:
+            return None
+
+        try:
+            return {
+                "job": selected_job,
+                "description_yaml": yaml.dump(selected_job.description),
+                "tasks": self.repo.list_tasks(job_id),
+                "linked_resources": self.repo.list_linked_resources(job_id),
+            }
+        except RepositoryError as err:
+            raise from_repository_error(
+                err,
+                unavailable_message="Job details are temporarily unavailable.",
+                fallback_message=f"Unable to load tasks for job '{job_id}'.",
+            ) from err
+
+    def enqueue_job_reschedule(
+        self,
+        job_id: int,
+        groups: list[str],
+        is_admin: bool,
+        requested_by: str,
+    ) -> int:
+        selected_job = self.get_job_for_user(job_id, groups, is_admin)
+        if selected_job is None:
+            raise ServiceNotFoundError(f"Job '{job_id}' was not found.")
+
+        command_type = self.reschedule_type_resolver(selected_job.job_type)
+        payload = self.parse_payload(command_type, selected_job.description)
+
+        try:
+            msg_id: JobID = self.repo.enqueue_command(
+                command_type,
+                payload,
+                requested_by,
+            )
+            if self.rescheduled_hook is not None:
+                self.rescheduled_hook(
+                    self.repo,
+                    requested_by,
+                    "JOB_RESCHEDULE_REQUESTED",
+                    _payload_value(payload) | {"job_id": msg_id.job_id},
+                )
+            return msg_id.job_id
+        except RepositoryError as err:
+            raise from_repository_error(
+                err,
+                unavailable_message="Job rescheduling is temporarily unavailable.",
+                validation_message=(
+                    "The job could not be rescheduled with its current payload."
+                ),
+                fallback_message=f"Unable to reschedule job '{job_id}'.",
+            ) from err
+
+
+def _payload_value(payload: Any) -> dict[str, Any]:
+    if hasattr(payload, "model_dump"):
+        return payload.model_dump()
+    if isinstance(payload, dict):
+        return payload
+    return {"payload": payload}

cpkit/jobs/types.py

@@ -0,0 +1,67 @@
+"""Generic job queue data types."""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class QueueMessage(BaseModel):
+    """Message claimed from the framework queue."""
+
+    msg_id: int
+    start_after: datetime
+    msg_type: str
+    msg_data: dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime
+    created_by: str
+
+
+class JobID(BaseModel):
+    job_id: int
+
+
+class IntID(BaseModel):
+    id: int
+
+
+class LinkedResourceRef(BaseModel):
+    resource_type: str
+    resource_id: str
+
+
+class JobStatsResponse(BaseModel):
+    total: int
+    running: int
+    queued: int
+    failed: int
+
+
+class Job(BaseModel):
+    job_id: int
+    job_type: str
+    status: str | None = None
+    playbook_version: str | None = None
+    description: dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime
+    created_by: str | None = None
+    updated_at: datetime
+
+
+class Task(BaseModel):
+    job_id: int
+    task_id: int
+    created_at: datetime
+    task_name: str | None = None
+    task_desc: str | None = None
+
+
+class JobDetailsResponse(BaseModel):
+    job: Job
+    description_yaml: str
+    tasks: list[Task]
+    linked_resources: list[LinkedResourceRef]
+
+
+class JobRescheduleResponse(BaseModel):
+    job_id: int