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

background_tasks/module.py

@@ -0,0 +1,121 @@
+"""BackgroundTasks module definition."""
+
+from __future__ import annotations
+
+import importlib.resources
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter
+from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
+from simple_module_core.module import ModuleBase, ModuleMeta
+from simple_module_core.permissions import PermissionRegistry
+
+from background_tasks.constants import (
+    API_PREFIX,
+    MENU_ICON,
+    MENU_LABEL,
+    MENU_ORDER,
+    MODULE_DISPLAY_NAME,
+    MODULE_NAME,
+    PERM_GROUP,
+    PERM_MANAGE,
+    PERM_VIEW,
+    VIEW_PREFIX,
+)
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+
+logger = logging.getLogger(__name__)
+
+
+class BackgroundTasksModule(ModuleBase):
+    """Celery + Redis task queue with an admin UI for retrying failed/stuck tasks."""
+
+    meta = ModuleMeta(
+        name=MODULE_DISPLAY_NAME,
+        route_prefix=API_PREFIX,
+        view_prefix=VIEW_PREFIX,
+        depends_on=["Users"],
+    )
+
+    def register_settings(self, app: FastAPI) -> None:
+        import importlib
+
+        from background_tasks.services import BackgroundTasksServices
+        from background_tasks.settings import BackgroundTasksSettings
+
+        # SM009 is AST-based: a static `from settings.registration import ...`
+        # from a module helper is fine (plugin→plugin), but we resolve via
+        # importlib here to match the convention used framework-side and to
+        # keep the dependency direction one-way explicit.
+        register_module_settings = importlib.import_module(
+            "settings.registration"
+        ).register_module_settings
+
+        register_module_settings(
+            app,
+            "background_tasks",
+            BackgroundTasksSettings,
+            lambda s: BackgroundTasksServices(settings=s),
+        )
+
+    def register_permissions(self, registry: PermissionRegistry) -> None:
+        registry.add_group(PERM_GROUP, [PERM_VIEW, PERM_MANAGE])
+
+    def register_menu_items(self, registry: MenuRegistry) -> None:
+        registry.add(
+            MenuItem(
+                label=MENU_LABEL,
+                url=VIEW_PREFIX,
+                icon=MENU_ICON,
+                order=MENU_ORDER,
+                section=MenuSection.SIDEBAR,
+                roles=["admin"],
+            )
+        )
+
+    def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
+        from background_tasks.endpoints.api_admin import router as api_admin
+        from background_tasks.endpoints.views import router as views
+
+        api_router.include_router(api_admin)
+        view_router.include_router(views)
+
+    def locale_dirs(self) -> dict[str, Path]:
+        base = Path(str(importlib.resources.files(__package__) / "locales"))
+        return {MODULE_NAME: base}
+
+    async def on_startup(self, app: FastAPI) -> None:
+        """Build the Celery app, install signal handlers, hand-off to worker."""
+        import asyncio
+
+        from background_tasks.celery_app import build_celery
+        from background_tasks.signals import bind_event_bus
+
+        services = app.state.background_tasks
+        # build_celery imports `signals` for side effects and runs
+        # `autodiscover_tasks` across every installed module.
+        services.celery = build_celery(services.settings)
+        # Let signal handlers hop onto the API loop to publish events.
+        # In a standalone worker process this bind never runs, so signals
+        # stay a silent no-op — that's the documented cross-process limit.
+        bind_event_bus(app.state.sm.event_bus, asyncio.get_running_loop())
+        logger.info(
+            "BackgroundTasks: Celery app ready (broker=%s, queue=%s)",
+            services.settings.broker_url,
+            services.settings.task_default_queue,
+        )
+
+    async def on_shutdown(self, app: FastAPI) -> None:
+        from background_tasks.signals import unbind_event_bus
+        from background_tasks.sync_db import dispose_sync_engine
+
+        services = app.state.background_tasks
+        if services.celery is not None:
+            services.celery.close()
+        unbind_event_bus()
+        dispose_sync_engine()

background_tasks/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@simple-module-py/background-tasks",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Frontend assets for the BackgroundTasks module",
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@inertiajs/react": "^2.0.0",
+    "@simple-module-py/ui": "*"
+  },
+  "devDependencies": {
+    "@simple-module-py/tsconfig": "*"
+  },
+  "dependencies": {}
+}

background_tasks/pages/Detail.tsx

@@ -0,0 +1,180 @@
+import { Link, router, usePage } from '@inertiajs/react';
+import { PageShell } from '@simple-module-py/ui/components/PageShell';
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Card } from '@simple-module-py/ui/components/ui/card';
+import { usePermissions } from '@simple-module-py/ui/hooks/use-permissions';
+import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedLayout';
+import { ArrowLeft, RefreshCcw } from 'lucide-react';
+import type { ReactNode } from 'react';
+import { RetryConfirmDialog } from './components/RetryConfirmDialog';
+import { RETRYABLE_STATUSES, STATUS_BADGE_VARIANT, type TaskStatus, VIEW_BASE } from './constants';
+import { retryExecution } from './retry';
+
+interface Execution {
+  id: string;
+  celery_task_id: string | null;
+  task_name: string;
+  status: TaskStatus;
+  queue: string;
+  args: unknown[];
+  kwargs: Record<string, unknown>;
+  result: Record<string, unknown> | null;
+  traceback: string | null;
+  exception_type: string | null;
+  worker: string | null;
+  retries: number;
+  retried_from_id: string | null;
+  queued_at: string | null;
+  started_at: string | null;
+  finished_at: string | null;
+  heartbeat_at: string | null;
+}
+
+function statusLabel(status: TaskStatus): string {
+  return status[0].toUpperCase() + status.slice(1);
+}
+
+function pretty(value: unknown): string {
+  if (value === null || value === undefined) return '—';
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+function formatTs(ts: string | null): string {
+  return ts ? new Date(ts).toLocaleString() : '—';
+}
+
+function JsonCard({ title, children }: { title: string; children: ReactNode }) {
+  return (
+    <Card className="p-4">
+      <h3 className="font-semibold mb-2">{title}</h3>
+      {children}
+    </Card>
+  );
+}
+
+function JsonBlock({ value }: { value: unknown }) {
+  return (
+    <pre className="text-xs bg-muted rounded p-3 overflow-x-auto whitespace-pre-wrap">
+      {pretty(value)}
+    </pre>
+  );
+}
+
+function Row({ label, value, mono }: { label: string; value: string; mono?: boolean }) {
+  return (
+    <div className="flex justify-between gap-3">
+      <dt className="text-muted-foreground">{label}</dt>
+      <dd className={mono ? 'font-mono text-xs break-all text-right' : 'text-right'}>{value}</dd>
+    </div>
+  );
+}
+
+function Detail() {
+  const { execution } = usePage<{ props: { execution: Execution } }>().props as unknown as {
+    execution: Execution;
+  };
+  const { can } = usePermissions();
+  const retryable = RETRYABLE_STATUSES.has(execution.status) && can('background_tasks.manage');
+
+  async function handleRetry() {
+    const created = await retryExecution(execution);
+    if (created) router.visit(`${VIEW_BASE}/${created.id}`);
+  }
+
+  return (
+    <PageShell
+      title={execution.task_name}
+      description={`Task execution ${execution.id}`}
+      actions={
+        <div className="flex items-center gap-2">
+          <Button variant="outline" size="sm" asChild>
+            <Link href={VIEW_BASE}>
+              <ArrowLeft />
+              Back to tasks
+            </Link>
+          </Button>
+          {retryable && (
+            <RetryConfirmDialog
+              trigger={
+                <Button size="sm">
+                  <RefreshCcw />
+                  Retry task
+                </Button>
+              }
+              onConfirm={handleRetry}
+            />
+          )}
+        </div>
+      }
+    >
+      <div className="grid grid-cols-1 lg:grid-cols-3 gap-4">
+        <Card className="p-4 lg:col-span-1">
+          <h3 className="font-semibold mb-3">Details</h3>
+          <dl className="text-sm space-y-2">
+            <div className="flex justify-between gap-3">
+              <dt className="text-muted-foreground">Status</dt>
+              <dd>
+                <Badge variant={STATUS_BADGE_VARIANT[execution.status]}>
+                  {statusLabel(execution.status)}
+                </Badge>
+              </dd>
+            </div>
+            <Row label="Queue" value={execution.queue} />
+            <Row label="Retries" value={String(execution.retries)} />
+            <Row label="Worker" value={execution.worker || '—'} />
+            <Row label="Celery id" value={execution.celery_task_id || '—'} mono />
+            <Row label="Queued at" value={formatTs(execution.queued_at)} />
+            <Row label="Started at" value={formatTs(execution.started_at)} />
+            <Row label="Finished at" value={formatTs(execution.finished_at)} />
+            <Row label="Heartbeat" value={formatTs(execution.heartbeat_at)} />
+            <Row label="Exception" value={execution.exception_type || '—'} />
+            {execution.retried_from_id && (
+              <div className="flex justify-between gap-3">
+                <dt className="text-muted-foreground">Retried from</dt>
+                <dd>
+                  <Link
+                    href={`${VIEW_BASE}/${execution.retried_from_id}`}
+                    className="hover:underline"
+                  >
+                    {execution.retried_from_id.slice(0, 8)}…
+                  </Link>
+                </dd>
+              </div>
+            )}
+          </dl>
+        </Card>
+
+        <div className="lg:col-span-2 flex flex-col gap-4">
+          <JsonCard title="Arguments">
+            <JsonBlock value={execution.args} />
+          </JsonCard>
+          <JsonCard title="Keyword arguments">
+            <JsonBlock value={execution.kwargs} />
+          </JsonCard>
+          {execution.result !== null && (
+            <JsonCard title="Result">
+              <JsonBlock value={execution.result} />
+            </JsonCard>
+          )}
+          <JsonCard title="Traceback">
+            {execution.traceback ? (
+              <pre className="text-xs bg-muted rounded p-3 overflow-x-auto whitespace-pre-wrap">
+                {execution.traceback}
+              </pre>
+            ) : (
+              <p className="text-sm text-muted-foreground">No traceback recorded.</p>
+            )}
+          </JsonCard>
+        </div>
+      </div>
+    </PageShell>
+  );
+}
+
+Detail.layout = (page: React.ReactNode) => <AuthenticatedLayout>{page}</AuthenticatedLayout>;
+export default Detail;

background_tasks/pages/Index.tsx

@@ -0,0 +1,181 @@
+import { router, usePage } from '@inertiajs/react';
+import { PageShell } from '@simple-module-py/ui/components/PageShell';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Card } from '@simple-module-py/ui/components/ui/card';
+import { Input } from '@simple-module-py/ui/components/ui/input';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@simple-module-py/ui/components/ui/select';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@simple-module-py/ui/components/ui/table';
+import { usePermissions } from '@simple-module-py/ui/hooks/use-permissions';
+import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedLayout';
+import { Activity, Search } from 'lucide-react';
+import { useEffect, useState } from 'react';
+import { ExecutionRow, statusLabel } from './components/ExecutionRow';
+import { STATUS_ORDER, VIEW_BASE } from './constants';
+import { type Execution, retryExecution } from './retry';
+
+interface Pagination {
+  page: number;
+  per_page: number;
+  total: number;
+}
+
+interface Props {
+  executions: Execution[];
+  pagination: Pagination;
+  filters: { status: string; task_name: string };
+}
+
+const STATUS_ALL = '__all__';
+
+function pushFilters(filters: { status: string; task_name: string }, page: number): void {
+  const params: Record<string, string> = {};
+  if (filters.task_name) params.q = filters.task_name;
+  if (filters.status && filters.status !== STATUS_ALL) params.status = filters.status;
+  if (page > 1) params.page = String(page);
+  router.get(VIEW_BASE, params, { preserveState: true, preserveScroll: true });
+}
+
+function Index() {
+  const {
+    executions,
+    pagination,
+    filters: initialFilters,
+  } = usePage<{ props: Props }>().props as unknown as Props;
+
+  const { can } = usePermissions();
+  const canRetry = can('background_tasks.manage');
+
+  const [search, setSearch] = useState(initialFilters.task_name ?? '');
+  const totalPages = Math.ceil(pagination.total / pagination.per_page);
+  const statusValue = initialFilters.status || STATUS_ALL;
+
+  // Debounce search: any change from the server-provided value kicks off a
+  // page-1 navigation 300ms after the user stops typing.
+  useEffect(() => {
+    if (search === (initialFilters.task_name ?? '')) return;
+    const timeout = setTimeout(
+      () => pushFilters({ status: statusValue, task_name: search }, 1),
+      300,
+    );
+    return () => clearTimeout(timeout);
+  }, [search, initialFilters.task_name, statusValue]);
+
+  async function handleRetry(execution: Execution) {
+    const created = await retryExecution(execution);
+    if (created) router.reload({ only: ['executions', 'pagination'] });
+  }
+
+  return (
+    <PageShell
+      title="Background Tasks"
+      description="Monitor task executions and retry failed or stuck jobs."
+    >
+      <div className="mb-4 flex flex-col sm:flex-row items-stretch sm:items-center justify-between gap-3">
+        <div className="relative flex-1 max-w-sm">
+          <Search className="absolute left-3 top-1/2 -translate-y-1/2 size-4 text-muted-foreground" />
+          <Input
+            placeholder="Search by task name…"
+            value={search}
+            onChange={(e) => setSearch(e.target.value)}
+            className="pl-9"
+          />
+        </div>
+        <Select
+          value={statusValue}
+          onValueChange={(v) => pushFilters({ status: v, task_name: search }, 1)}
+        >
+          <SelectTrigger className="w-full sm:w-48">
+            <SelectValue placeholder="Status" />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value={STATUS_ALL}>All statuses</SelectItem>
+            {STATUS_ORDER.map((s) => (
+              <SelectItem key={s} value={s}>
+                {statusLabel(s)}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </div>
+
+      <Card>
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Task</TableHead>
+              <TableHead>Status</TableHead>
+              <TableHead className="hidden md:table-cell">Queue</TableHead>
+              <TableHead className="hidden lg:table-cell">Queued</TableHead>
+              <TableHead className="hidden sm:table-cell">Duration</TableHead>
+              <TableHead className="hidden xl:table-cell">Worker</TableHead>
+              <TableHead className="text-right">Actions</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {executions.map((e) => (
+              <ExecutionRow key={e.id} execution={e} canRetry={canRetry} onRetry={handleRetry} />
+            ))}
+            {executions.length === 0 && (
+              <TableRow>
+                <TableCell colSpan={7} className="h-32 text-center">
+                  <div className="flex flex-col items-center gap-2 text-muted-foreground">
+                    <Activity className="size-8" />
+                    <p>
+                      {search
+                        ? `No tasks match "${search}"`
+                        : 'No task executions yet. Tasks appear here as soon as modules enqueue work.'}
+                    </p>
+                  </div>
+                </TableCell>
+              </TableRow>
+            )}
+          </TableBody>
+        </Table>
+      </Card>
+
+      {totalPages > 1 && (
+        <div className="mt-4 flex items-center justify-center gap-2">
+          <Button
+            variant="outline"
+            size="sm"
+            disabled={pagination.page <= 1}
+            onClick={() =>
+              pushFilters({ status: statusValue, task_name: search }, pagination.page - 1)
+            }
+          >
+            Previous
+          </Button>
+          <span className="text-sm text-muted-foreground">
+            Page {pagination.page} of {totalPages}
+          </span>
+          <Button
+            variant="outline"
+            size="sm"
+            disabled={pagination.page >= totalPages}
+            onClick={() =>
+              pushFilters({ status: statusValue, task_name: search }, pagination.page + 1)
+            }
+          >
+            Next
+          </Button>
+        </div>
+      )}
+    </PageShell>
+  );
+}
+
+Index.layout = (page: React.ReactNode) => <AuthenticatedLayout>{page}</AuthenticatedLayout>;
+export default Index;

background_tasks/pages/components/ExecutionRow.tsx

@@ -0,0 +1,79 @@
+import { Link } from '@inertiajs/react';
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { TableCell, TableRow } from '@simple-module-py/ui/components/ui/table';
+import { RefreshCcw } from 'lucide-react';
+import { RETRYABLE_STATUSES, STATUS_BADGE_VARIANT, VIEW_BASE } from '../constants';
+import type { Execution } from '../retry';
+import { RetryConfirmDialog } from './RetryConfirmDialog';
+
+function statusLabel(status: string): string {
+  return status[0].toUpperCase() + status.slice(1);
+}
+
+function formatDuration(started: string | null, finished: string | null): string {
+  if (!started) return '—';
+  const end = finished ? new Date(finished) : new Date();
+  const ms = end.getTime() - new Date(started).getTime();
+  if (ms < 0) return '—';
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.floor(ms / 60_000)}m ${Math.floor((ms % 60_000) / 1000)}s`;
+}
+
+interface Props {
+  execution: Execution;
+  canRetry: boolean;
+  onRetry: (execution: Execution) => void;
+}
+
+export function ExecutionRow({ execution, canRetry, onRetry }: Props) {
+  const retryable = RETRYABLE_STATUSES.has(execution.status) && canRetry;
+  return (
+    <TableRow>
+      <TableCell>
+        <div className="flex flex-col">
+          <Link href={`${VIEW_BASE}/${execution.id}`} className="font-medium hover:underline">
+            {execution.task_name}
+          </Link>
+          {execution.exception_type && (
+            <span className="text-xs text-destructive">{execution.exception_type}</span>
+          )}
+        </div>
+      </TableCell>
+      <TableCell>
+        <Badge variant={STATUS_BADGE_VARIANT[execution.status]}>
+          {statusLabel(execution.status)}
+        </Badge>
+      </TableCell>
+      <TableCell className="hidden md:table-cell text-sm text-muted-foreground">
+        {execution.queue}
+      </TableCell>
+      <TableCell className="hidden lg:table-cell text-sm text-muted-foreground">
+        {execution.queued_at ? new Date(execution.queued_at).toLocaleString() : '—'}
+      </TableCell>
+      <TableCell className="hidden sm:table-cell text-sm tabular-nums">
+        {formatDuration(execution.started_at, execution.finished_at)}
+      </TableCell>
+      <TableCell className="hidden xl:table-cell text-sm text-muted-foreground">
+        {execution.worker || '—'}
+      </TableCell>
+      <TableCell className="text-right">
+        {retryable ? (
+          <RetryConfirmDialog
+            trigger={
+              <Button variant="ghost" size="icon-sm">
+                <RefreshCcw />
+              </Button>
+            }
+            onConfirm={() => onRetry(execution)}
+          />
+        ) : (
+          <span className="text-sm text-muted-foreground">—</span>
+        )}
+      </TableCell>
+    </TableRow>
+  );
+}
+
+export { statusLabel };

background_tasks/pages/components/RetryConfirmDialog.tsx

@@ -0,0 +1,38 @@
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@simple-module-py/ui/components/ui/alert-dialog';
+import type { ReactNode } from 'react';
+
+interface Props {
+  trigger: ReactNode;
+  onConfirm: () => void;
+}
+
+export function RetryConfirmDialog({ trigger, onConfirm }: Props) {
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>{trigger}</AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Retry this task?</AlertDialogTitle>
+          <AlertDialogDescription>
+            A new task execution will be enqueued with the same arguments. The original row is kept
+            for history.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <AlertDialogAction onClick={onConfirm}>Retry task</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}

background_tasks/pages/constants.ts

@@ -0,0 +1,49 @@
+// Frontend mirror of background_tasks/constants.py.
+// Kept small and hand-maintained — the backend file is the source of truth.
+
+export const API_BASE = '/api/background_tasks/admin';
+export const VIEW_BASE = '/admin/background-tasks';
+
+export const TASK_STATUS = {
+  PENDING: 'pending',
+  RUNNING: 'running',
+  SUCCESS: 'success',
+  FAILED: 'failed',
+  STUCK: 'stuck',
+  REVOKED: 'revoked',
+  RETRYING: 'retrying',
+} as const;
+
+export type TaskStatus = (typeof TASK_STATUS)[keyof typeof TASK_STATUS];
+
+export const RETRYABLE_STATUSES: ReadonlySet<TaskStatus> = new Set([
+  TASK_STATUS.FAILED,
+  TASK_STATUS.STUCK,
+]);
+
+export const TERMINAL_STATUSES: ReadonlySet<TaskStatus> = new Set([
+  TASK_STATUS.SUCCESS,
+  TASK_STATUS.FAILED,
+  TASK_STATUS.STUCK,
+  TASK_STATUS.REVOKED,
+]);
+
+export const STATUS_BADGE_VARIANT: Record<TaskStatus, 'secondary' | 'destructive' | 'outline'> = {
+  [TASK_STATUS.PENDING]: 'outline',
+  [TASK_STATUS.RUNNING]: 'secondary',
+  [TASK_STATUS.SUCCESS]: 'secondary',
+  [TASK_STATUS.FAILED]: 'destructive',
+  [TASK_STATUS.STUCK]: 'destructive',
+  [TASK_STATUS.REVOKED]: 'outline',
+  [TASK_STATUS.RETRYING]: 'outline',
+};
+
+export const STATUS_ORDER: TaskStatus[] = [
+  TASK_STATUS.PENDING,
+  TASK_STATUS.RUNNING,
+  TASK_STATUS.RETRYING,
+  TASK_STATUS.SUCCESS,
+  TASK_STATUS.FAILED,
+  TASK_STATUS.STUCK,
+  TASK_STATUS.REVOKED,
+];