simple-module-background-tasks 0.0.1__py3-none-any.whl

background_tasks/__init__.py

@@ -0,0 +1 @@
+"""BackgroundTasks module — Celery + Redis task queue with admin UI."""

background_tasks/_signal_support.py

@@ -0,0 +1,105 @@
+"""Signal-handler helpers shared across :mod:`background_tasks.signals`.
+
+Kept in a separate module so :mod:`.signals` stays under the 300-line cap.
+These helpers are intentionally side-effect-free except for the DB write in
+``upsert_by_celery_id`` — signal handlers compose them.
+"""
+
+from __future__ import annotations
+
+import traceback as tb_mod
+from datetime import UTC, datetime
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from background_tasks.models import TaskExecution
+
+
+def now_utc() -> datetime:
+    return datetime.now(UTC)
+
+
+def coerce_args_kwargs(args: Any, kwargs: Any) -> tuple[list[Any], dict[str, Any]]:
+    """Normalise Celery args/kwargs payloads to JSON-ready shapes.
+
+    Celery sometimes hands us tuples/frozensets that our JSON column can't
+    store; also tolerates ``None`` so a partial payload won't wedge the row.
+    """
+    safe_args: list[Any] = list(args) if args else []
+    safe_kwargs: dict[str, Any] = dict(kwargs) if kwargs else {}
+    return safe_args, safe_kwargs
+
+
+def upsert_by_celery_id(
+    session: Session,
+    *,
+    celery_task_id: str | None,
+    defaults: dict[str, Any],
+) -> TaskExecution:
+    """Fetch the row for ``celery_task_id``, or create it from ``defaults``.
+
+    ``defaults`` must include ``task_name`` (it's NOT NULL on the table).
+    Handlers never race on the same row within a worker process — Celery
+    serialises per-task signals — so this is upsert-by-read, no advisory
+    locks needed.
+    """
+    row: TaskExecution | None = None
+    if celery_task_id:
+        stmt = select(TaskExecution).where(TaskExecution.celery_task_id == celery_task_id)
+        row = session.execute(stmt).scalar_one_or_none()
+    if row is None:
+        row = TaskExecution(celery_task_id=celery_task_id, **defaults)
+        session.add(row)
+    else:
+        for key, value in defaults.items():
+            setattr(row, key, value)
+    return row
+
+
+def task_name_of(sender: Any, task: Any = None) -> str:
+    """Best-effort resolution of a task's registered name from signal args."""
+    return (
+        (isinstance(sender, str) and sender)
+        or getattr(task, "name", None)
+        or getattr(sender, "name", None)
+        or "unknown"
+    )
+
+
+def task_id_from(sender: Any = None, request: Any = None) -> str | None:
+    """Pull the Celery task UUID out of whichever signal-arg carries it.
+
+    Celery's signals pass the task id via three different shapes depending
+    on the signal: ``task_id=`` kwarg, ``request.id``, or ``sender.request.id``.
+    Centralising the probe keeps the per-handler code boring.
+    """
+    if request is not None:
+        tid = getattr(request, "id", None)
+        if tid:
+            return tid
+    sender_request = getattr(sender, "request", None)
+    return getattr(sender_request, "id", None) if sender_request is not None else None
+
+
+def jsonable_result(result: Any) -> dict[str, Any] | None:
+    """Wrap arbitrary task results in a JSON-storable shape."""
+    if result is None:
+        return None
+    if isinstance(result, dict):
+        return result
+    try:
+        return {"value": result}
+    except Exception:
+        return {"value": repr(result)}
+
+
+def render_traceback(einfo: Any, exception: BaseException | None) -> str | None:
+    """Prefer Celery's pre-formatted traceback; fall back to the live exception."""
+    tb = getattr(einfo, "traceback", None)
+    if tb:
+        return str(tb)
+    if exception is not None:
+        return "".join(tb_mod.format_exception(type(exception), exception, exception.__traceback__))
+    return None

background_tasks/celery_app.py

@@ -0,0 +1,95 @@
+"""Build and configure the Celery application.
+
+Invoked from two places:
+
+- :meth:`BackgroundTasksModule.on_startup` in the web process, so the API
+  can enqueue tasks via ``app.state.background_tasks.celery.send_task(...)``.
+- ``scripts/run_worker.py`` at worker boot, so the worker process uses an
+  identical config (broker URL, signal handlers, autodiscovered tasks).
+
+Task discovery uses :py:meth:`celery.Celery.autodiscover_tasks` with the
+top-level package name of every installed module (enumerated via the
+``simple_module`` entry-point group). Any module that ships a ``tasks.py``
+is picked up automatically — no framework hook, no per-module registration.
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib.metadata import entry_points
+
+from celery import Celery
+from celery.schedules import schedule
+from simple_module_core.discovery import ENTRY_POINT_GROUP
+
+from background_tasks.constants import (
+    INTERNAL_TASK_PURGE_OLD,
+    INTERNAL_TASK_SWEEP_STUCK,
+    MODULE_NAME,
+)
+from background_tasks.settings import BackgroundTasksSettings
+
+logger = logging.getLogger(__name__)
+
+
+def _discover_task_packages() -> list[str]:
+    """Return the top-level package name of every installed simple_module.
+
+    Celery's ``autodiscover_tasks`` imports ``<package>.tasks`` for each name
+    returned here, so any module that ships a ``tasks.py`` registers its
+    tasks without a per-module hook.
+    """
+    packages: set[str] = set()
+    for ep in entry_points(group=ENTRY_POINT_GROUP):
+        module_path = ep.value.split(":", 1)[0]
+        top_level = module_path.split(".", 1)[0]
+        packages.add(top_level)
+    return sorted(packages)
+
+
+def build_celery(settings: BackgroundTasksSettings) -> Celery:
+    """Construct a Celery app wired to the project's Redis broker."""
+    celery = Celery(MODULE_NAME)
+
+    celery.conf.update(
+        broker_url=settings.broker_url,
+        result_backend=settings.result_backend,
+        task_default_queue=settings.task_default_queue,
+        # ``task_track_started`` gives us the ``STARTED`` state so
+        # ``task_prerun`` can flip our row to ``running``.
+        task_track_started=True,
+        # ``task_acks_late`` + ``worker_prefetch_multiplier=1`` gives us
+        # at-least-once semantics, which matches how the admin UI asks users
+        # to think about retries — duplicates beat lost work.
+        task_acks_late=True,
+        worker_prefetch_multiplier=1,
+        task_serializer="json",
+        result_serializer="json",
+        accept_content=["json"],
+        timezone="UTC",
+        enable_utc=True,
+        broker_connection_retry_on_startup=True,
+        beat_schedule={
+            "background-tasks-sweep-stuck": {
+                "task": INTERNAL_TASK_SWEEP_STUCK,
+                "schedule": schedule(settings.stuck_sweep_interval_seconds),
+            },
+            "background-tasks-purge-old": {
+                "task": INTERNAL_TASK_PURGE_OLD,
+                "schedule": schedule(settings.purge_interval_seconds),
+            },
+        },
+        beat_scheduler="celery.beat:PersistentScheduler",
+    )
+
+    # Autodiscover across every installed simple_module — a module just ships
+    # a `tasks.py` and the worker picks it up.
+    packages = _discover_task_packages()
+    logger.info("Celery autodiscover_tasks across: %s", packages)
+    celery.autodiscover_tasks(packages, related_name="tasks", force=True)
+
+    # Side-effect import: connects signal handlers to this Celery instance's
+    # ``celery.signals.*`` globals. Safe to import repeatedly.
+    from background_tasks import signals  # noqa: F401
+
+    return celery

background_tasks/constants.py

@@ -0,0 +1,75 @@
+"""Single source of truth for background_tasks module string literals.
+
+Anything that would otherwise become a magic string — table names, env-var
+prefixes, permission codes, route segments, page identifiers, task-status
+values — lives here so models, signals, services, endpoints, tests, and
+the frontend all agree on one spelling.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+# ── Module identity ─────────────────────────────────────────────
+MODULE_NAME = "background_tasks"
+MODULE_DISPLAY_NAME = "BackgroundTasks"
+TABLE_PREFIX = "background_tasks_"
+TABLE_TASK_EXECUTION = f"{TABLE_PREFIX}task_execution"
+
+# ── Env / settings ──────────────────────────────────────────────
+ENV_PREFIX = "SM_BG_TASKS_"
+
+# ── Permissions ─────────────────────────────────────────────────
+PERM_GROUP = "Background Tasks"
+PERM_VIEW = "background_tasks.view"
+PERM_MANAGE = "background_tasks.manage"
+
+# ── Routes ──────────────────────────────────────────────────────
+API_PREFIX = "/api/background_tasks"
+VIEW_PREFIX = "/admin/background-tasks"
+ADMIN_ROUTER_PREFIX = "/admin"
+
+# ── Menu ────────────────────────────────────────────────────────
+MENU_LABEL = "Background Tasks"
+MENU_ICON = "activity"
+MENU_ORDER = 80
+
+# ── Page identifiers ────────────────────────────────────────────
+# Kept as literals at the call site (see endpoints/views.py) so
+# ``make doctor``'s SM003/SM004 static analysis can match pages to renders.
+
+
+# ── Task statuses ───────────────────────────────────────────────
+class TaskStatus(StrEnum):
+    """Lifecycle state of a single task execution row."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCESS = "success"
+    FAILED = "failed"
+    STUCK = "stuck"
+    REVOKED = "revoked"
+    RETRYING = "retrying"
+
+
+RETRYABLE_STATUSES: frozenset[TaskStatus] = frozenset({TaskStatus.FAILED, TaskStatus.STUCK})
+TERMINAL_STATUSES: frozenset[TaskStatus] = frozenset(
+    {TaskStatus.SUCCESS, TaskStatus.FAILED, TaskStatus.STUCK, TaskStatus.REVOKED}
+)
+
+# ── Defaults ────────────────────────────────────────────────────
+DEFAULT_QUEUE = "default"
+DEFAULT_BROKER_URL = "redis://localhost:6379/0"
+DEFAULT_RESULT_BACKEND = "redis://localhost:6379/1"
+DEFAULT_STUCK_AFTER_SECONDS = 300
+DEFAULT_STUCK_SWEEP_INTERVAL_SECONDS = 60
+DEFAULT_PURGE_INTERVAL_SECONDS = 60 * 60 * 24
+DEFAULT_RETENTION_DAYS = 14
+DEFAULT_MAX_RETRIES = 3
+
+# ── Internal task names ─────────────────────────────────────────
+INTERNAL_TASK_SWEEP_STUCK = "background_tasks.sweep_stuck_tasks"
+INTERNAL_TASK_PURGE_OLD = "background_tasks.purge_old_executions"
+# Harmless round-trip task; only wired into CI smoke tests and local dev —
+# not scheduled, not invoked by other modules.
+DEMO_ECHO_TASK = "background_tasks.demo_echo"

background_tasks/contracts/__init__.py

@@ -0,0 +1 @@
+"""Public contracts for the BackgroundTasks module."""

background_tasks/contracts/events.py

@@ -0,0 +1,26 @@
+"""Public events emitted by the BackgroundTasks module."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+
+from simple_module_core.events import Event
+
+
+@dataclass
+class TaskFailed(Event):
+    """A task transitioned to ``failed`` — subscribers may alert/log."""
+
+    task_execution_id: uuid.UUID
+    task_name: str
+    exception_type: str | None
+
+
+@dataclass
+class TaskRetried(Event):
+    """A failed/stuck task was manually retried via the admin UI."""
+
+    original_id: uuid.UUID
+    new_id: uuid.UUID
+    task_name: str

background_tasks/contracts/schemas.py

@@ -0,0 +1,66 @@
+"""DTOs returned by the BackgroundTasks admin API / views."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Any
+
+from pydantic import ConfigDict
+from sqlmodel import SQLModel
+
+from background_tasks.constants import TaskStatus
+
+
+class TaskExecutionListItem(SQLModel):
+    """Compact row for the admin listing table."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    celery_task_id: str | None = None
+    task_name: str
+    status: TaskStatus
+    queue: str
+    retries: int
+    worker: str | None = None
+    queued_at: datetime | None = None
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+    exception_type: str | None = None
+    retried_from_id: uuid.UUID | None = None
+
+
+class TaskExecutionDetail(SQLModel):
+    """Full row for the detail page (adds args/kwargs/result/traceback)."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    celery_task_id: str | None = None
+    task_name: str
+    status: TaskStatus
+    queue: str
+    args: list[Any] = []
+    kwargs: dict[str, Any] = {}
+    result: dict[str, Any] | None = None
+    traceback: str | None = None
+    exception_type: str | None = None
+    worker: str | None = None
+    retries: int = 0
+    retried_from_id: uuid.UUID | None = None
+    queued_at: datetime | None = None
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+    heartbeat_at: datetime | None = None
+
+
+class TaskExecutionListResponse(SQLModel):
+    """Paginated response shape used by both the API and Inertia views."""
+
+    items: list[TaskExecutionListItem]
+    total: int
+    page: int
+    per_page: int
+    status: TaskStatus | None = None
+    task_name: str | None = None

background_tasks/deps.py

@@ -0,0 +1,19 @@
+"""FastAPI dependencies for the BackgroundTasks module."""
+
+from __future__ import annotations
+
+from fastapi import Depends, Request
+from simple_module_core.events import EventBus
+from simple_module_db.deps import get_db
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from background_tasks.service import BackgroundTaskService
+
+
+async def get_background_task_service(
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+) -> BackgroundTaskService:
+    services = request.app.state.background_tasks
+    bus: EventBus = request.app.state.sm.event_bus
+    return BackgroundTaskService(db=db, celery=services.celery, event_bus=bus)

background_tasks/endpoints/api_admin.py

@@ -0,0 +1,62 @@
+"""Admin REST endpoints for BackgroundTasks."""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from simple_module_hosting.permissions import RequiresPermission
+
+from background_tasks.constants import (
+    ADMIN_ROUTER_PREFIX,
+    MODULE_NAME,
+    PERM_MANAGE,
+    PERM_VIEW,
+    TaskStatus,
+)
+from background_tasks.contracts.schemas import (
+    TaskExecutionDetail,
+    TaskExecutionListResponse,
+)
+from background_tasks.deps import get_background_task_service
+from background_tasks.service import BackgroundTaskService
+
+router = APIRouter(
+    prefix=ADMIN_ROUTER_PREFIX,
+    dependencies=[Depends(RequiresPermission(PERM_VIEW))],
+    tags=[f"{MODULE_NAME}-admin"],
+)
+
+
+@router.get("/executions", response_model=TaskExecutionListResponse)
+async def list_executions(
+    status: TaskStatus | None = Query(default=None),
+    task_name: str | None = Query(default=None),
+    page: int = Query(default=1, ge=1),
+    per_page: int = Query(default=20, ge=1, le=200),
+    service: BackgroundTaskService = Depends(get_background_task_service),
+) -> TaskExecutionListResponse:
+    return await service.list(status=status, task_name=task_name, page=page, per_page=per_page)
+
+
+@router.get("/executions/{execution_id}", response_model=TaskExecutionDetail)
+async def get_execution(
+    execution_id: uuid.UUID,
+    service: BackgroundTaskService = Depends(get_background_task_service),
+) -> TaskExecutionDetail:
+    detail = await service.get(execution_id)
+    if detail is None:
+        raise HTTPException(status_code=404, detail="Task execution not found")
+    return detail
+
+
+@router.post(
+    "/executions/{execution_id}/retry",
+    response_model=TaskExecutionDetail,
+    dependencies=[Depends(RequiresPermission(PERM_MANAGE))],
+)
+async def retry_execution(
+    execution_id: uuid.UUID,
+    service: BackgroundTaskService = Depends(get_background_task_service),
+) -> TaskExecutionDetail:
+    return await service.retry(execution_id)

background_tasks/endpoints/views.py

@@ -0,0 +1,71 @@
+"""Inertia view endpoints for the BackgroundTasks admin UI."""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from inertia import InertiaResponse
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_hosting.permissions import RequiresPermission
+
+from background_tasks.constants import (
+    PERM_VIEW,
+    TaskStatus,
+)
+from background_tasks.deps import get_background_task_service
+from background_tasks.service import BackgroundTaskService
+
+router = APIRouter(dependencies=[Depends(RequiresPermission(PERM_VIEW))])
+
+PER_PAGE = 20
+
+
+@router.get("/", response_model=None)
+async def index(
+    inertia: InertiaDep,
+    status: TaskStatus | None = Query(default=None),
+    task_name: str = Query(default="", alias="q"),
+    page: int = Query(default=1, ge=1),
+    service: BackgroundTaskService = Depends(get_background_task_service),
+) -> InertiaResponse:
+    response = await service.list(
+        status=status,
+        task_name=task_name or None,
+        page=page,
+        per_page=PER_PAGE,
+    )
+    return await inertia.render(
+        "BackgroundTasks/Index",
+        {
+            "executions": [i.model_dump(mode="json") for i in response.items],
+            "pagination": {
+                "page": response.page,
+                "per_page": response.per_page,
+                "total": response.total,
+            },
+            "filters": {
+                "status": status.value if status else "",
+                "task_name": task_name,
+            },
+        },
+    )
+
+
+@router.get("/{execution_id}", response_model=None)
+async def detail(
+    execution_id: str,
+    inertia: InertiaDep,
+    service: BackgroundTaskService = Depends(get_background_task_service),
+) -> InertiaResponse:
+    try:
+        eid = uuid.UUID(execution_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=404) from exc
+    row = await service.get(eid)
+    if row is None:
+        raise HTTPException(status_code=404)
+    return await inertia.render(
+        "BackgroundTasks/Detail",
+        {"execution": row.model_dump(mode="json")},
+    )

background_tasks/locales/en.json

@@ -0,0 +1,57 @@
+{
+  "index": {
+    "title": "Background Tasks",
+    "description": "Monitor task executions and retry failed or stuck jobs.",
+    "search_placeholder": "Search by task name…",
+    "count_one": "{count} task",
+    "count_other": "{count} tasks",
+    "empty_title": "No task executions yet",
+    "empty_description": "Tasks appear here as soon as modules enqueue work.",
+    "no_match": "No tasks match \"{query}\""
+  },
+  "filters": {
+    "status_label": "Status",
+    "status_all": "All statuses"
+  },
+  "status": {
+    "pending": "Pending",
+    "running": "Running",
+    "success": "Success",
+    "failed": "Failed",
+    "stuck": "Stuck",
+    "revoked": "Revoked",
+    "retrying": "Retrying"
+  },
+  "table": {
+    "task": "Task",
+    "status": "Status",
+    "queue": "Queue",
+    "queued_at": "Queued",
+    "duration": "Duration",
+    "worker": "Worker",
+    "actions": "Actions",
+    "view": "View",
+    "retry": "Retry"
+  },
+  "detail": {
+    "title": "Task execution",
+    "back_button": "Back to tasks",
+    "args": "Arguments",
+    "kwargs": "Keyword arguments",
+    "result": "Result",
+    "traceback": "Traceback",
+    "meta": "Details",
+    "retried_from": "Retried from",
+    "no_traceback": "No traceback recorded."
+  },
+  "retry_dialog": {
+    "title": "Retry this task?",
+    "description": "A new task execution will be enqueued with the same arguments. The original row is kept for history.",
+    "cancel": "Cancel",
+    "confirm": "Retry task"
+  },
+  "toasts": {
+    "retried": "Task \"{name}\" re-enqueued",
+    "retry_failed": "Failed to retry task"
+  }
+}

background_tasks/models.py

@@ -0,0 +1,86 @@
+"""SQLModel tables for the BackgroundTasks module."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Any
+
+from simple_module_db.base import create_module_base
+from simple_module_db.mixins import AuditMixin
+from sqlalchemy import JSON, Column, Index, String
+from sqlmodel import Field
+
+from background_tasks.constants import (
+    DEFAULT_QUEUE,
+    MODULE_NAME,
+    TABLE_TASK_EXECUTION,
+    TaskStatus,
+)
+
+# Provider is auto-detected from SM_DATABASE_URL (falls back to SQLite).
+# On PostgreSQL this gives the module its own `background_tasks` schema; on
+# SQLite all modules share one schema, so __tablename__ is prefixed for
+# isolation.
+Base = create_module_base(MODULE_NAME)
+
+
+class TaskExecution(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """Persistent record of a single Celery task execution.
+
+    We keep our own row (separate from Celery's volatile result backend)
+    because the admin UI needs stable history, retried-from chains, and a
+    "stuck since" timestamp that Celery's state machine doesn't model.
+    """
+
+    __tablename__ = TABLE_TASK_EXECUTION
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+
+    # Celery's own UUID for the running task. Nullable because we create the
+    # row *before* enqueue in the retry flow, then stamp it on send.
+    celery_task_id: str | None = Field(default=None, index=True, max_length=64)
+
+    task_name: str = Field(index=True, max_length=255)
+    # Stored as a plain string (the enum's ``value``) rather than a native
+    # SQL ENUM so autogenerate produces a VARCHAR column and Postgres
+    # doesn't own a ``taskstatus`` type that we'd need a separate migration
+    # to evolve.
+    status: TaskStatus = Field(
+        default=TaskStatus.PENDING,
+        sa_column=Column(String(20), index=True, nullable=False, default=TaskStatus.PENDING.value),
+    )
+    queue: str = Field(default=DEFAULT_QUEUE, max_length=64)
+
+    args: list[Any] = Field(default_factory=list, sa_column=Column(JSON))
+    kwargs: dict[str, Any] = Field(default_factory=dict, sa_column=Column(JSON))
+    result: dict[str, Any] | None = Field(default=None, sa_column=Column(JSON))
+
+    traceback: str | None = None
+    exception_type: str | None = Field(default=None, max_length=255)
+
+    worker: str | None = Field(default=None, max_length=255)
+    retries: int = 0
+
+    # Self-reference so the UI can show "retried from <original>" chains.
+    retried_from_id: uuid.UUID | None = Field(
+        default=None,
+        foreign_key=f"{TABLE_TASK_EXECUTION}.id",
+        index=True,
+    )
+
+    queued_at: datetime | None = None
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+    # Heartbeat is refreshed on every signal that touches a running task.
+    # `stuck_after_seconds` older than ``now`` ⇒ `sweep_stuck_tasks` flips
+    # the row to `stuck`.
+    heartbeat_at: datetime | None = None
+
+    __table_args__ = (
+        Index(
+            "ix_background_tasks_task_execution_status_queued",
+            "status",
+            "queued_at",
+        ),
+    )