plain.jobs 0.33.0__py3-none-any.whl

plain/jobs/cli.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import datetime
+import logging
+import signal
+from typing import Any
+
+import click
+
+from plain.cli import register_cli
+from plain.runtime import settings
+from plain.utils import timezone
+
+from .models import JobProcess, JobRequest, JobResult
+from .registry import jobs_registry
+from .scheduling import load_schedule
+from .workers import Worker
+
+logger = logging.getLogger("plain.jobs")
+
+
+@register_cli("jobs")
+@click.group()
+def cli() -> None:
+    pass
+
+
+@cli.command()
+@click.option(
+    "queues",
+    "--queue",
+    default=["default"],
+    multiple=True,
+    type=str,
+    help="Queue to process",
+)
+@click.option(
+    "--max-processes",
+    "max_processes",
+    default=None,
+    type=int,
+    envvar="PLAIN_JOBS_WORKER_MAX_PROCESSES",
+)
+@click.option(
+    "--max-jobs-per-process",
+    "max_jobs_per_process",
+    default=None,
+    type=int,
+    envvar="PLAIN_JOBS_WORKER_MAX_JOBS_PER_PROCESS",
+)
+@click.option(
+    "--max-pending-per-process",
+    "max_pending_per_process",
+    default=10,
+    type=int,
+    envvar="PLAIN_JOBS_WORKER_MAX_PENDING_PER_PROCESS",
+)
+@click.option(
+    "--stats-every",
+    "stats_every",
+    default=60,
+    type=int,
+    envvar="PLAIN_JOBS_WORKER_STATS_EVERY",
+)
+def worker(
+    queues: tuple[str, ...],
+    max_processes: int | None,
+    max_jobs_per_process: int | None,
+    max_pending_per_process: int,
+    stats_every: int,
+) -> None:
+    """Run the job worker."""
+    jobs_schedule = load_schedule(settings.JOBS_SCHEDULE)
+
+    worker = Worker(
+        queues=list(queues),
+        jobs_schedule=jobs_schedule,
+        max_processes=max_processes,
+        max_jobs_per_process=max_jobs_per_process,
+        max_pending_per_process=max_pending_per_process,
+        stats_every=stats_every,
+    )
+
+    def _shutdown(signalnum: int, _: Any) -> None:
+        logger.info("Job worker shutdown signal received signalnum=%s", signalnum)
+        worker.shutdown()
+
+    # Allow the worker to be stopped gracefully on SIGTERM
+    signal.signal(signal.SIGTERM, _shutdown)
+    signal.signal(signal.SIGINT, _shutdown)
+
+    # Start processing jobs
+    worker.run()
+
+
+@cli.command()
+def clear() -> None:
+    """Clear all completed job results in all queues."""
+    cutoff = timezone.now() - datetime.timedelta(
+        seconds=settings.JOBS_RESULTS_RETENTION
+    )
+    click.echo(f"Clearing job results created before {cutoff}")
+    results = JobResult.query.filter(created_at__lt=cutoff).delete()
+    click.echo(f"Deleted {results[0]} jobs")
+
+
+@cli.command()
+def stats() -> None:
+    """Stats across all queues."""
+    pending = JobRequest.query.count()
+    processing = JobProcess.query.count()
+
+    successful = JobResult.query.successful().count()
+    errored = JobResult.query.errored().count()
+    lost = JobResult.query.lost().count()
+
+    click.secho(f"Pending: {pending}", bold=True)
+    click.secho(f"Processing: {processing}", bold=True)
+    click.secho(f"Successful: {successful}", bold=True, fg="green")
+    click.secho(f"Errored: {errored}", bold=True, fg="red")
+    click.secho(f"Lost: {lost}", bold=True, fg="yellow")
+
+
+@cli.command()
+def purge() -> None:
+    """Delete all running and pending jobs regardless of queue."""
+    if not click.confirm(
+        "Are you sure you want to clear all running and pending jobs? This will delete all current Jobs and JobRequests"
+    ):
+        return
+
+    deleted = JobRequest.query.all().delete()[0]
+    click.echo(f"Deleted {deleted} job requests")
+
+    deleted = JobProcess.query.all().delete()[0]
+    click.echo(f"Deleted {deleted} jobs")
+
+
+@cli.command()
+@click.argument("job_class_name", type=str)
+def run(job_class_name: str) -> None:
+    """Run a job class directly (and not using a worker)."""
+    job = jobs_registry.load_job(job_class_name, {"args": [], "kwargs": {}})
+    click.secho("Loaded job: ", bold=True, nl=False)
+    print(job)
+    job.run()
+
+
+@cli.command("list")
+def list_jobs() -> None:
+    """List all registered jobs."""
+    for name, job_class in jobs_registry.jobs.items():
+        click.echo(f"{click.style(name, fg='blue')}: {job_class}")

plain/jobs/config.py

@@ -0,0 +1,19 @@
+from importlib import import_module
+
+from plain.packages import PackageConfig, packages_registry, register_config
+
+from .registry import jobs_registry
+
+
+@register_config
+class Config(PackageConfig):
+    package_label = "plainjobs"
+
+    def ready(self) -> None:
+        # Trigger register calls to fire by importing the modules
+        packages_registry.autodiscover_modules("jobs", include_app=True)
+
+        # Also need to make sure out internal jobs are registered
+        import_module("plain.jobs.scheduling")
+
+        jobs_registry.ready = True

plain/jobs/default_settings.py

@@ -0,0 +1,6 @@
+JOBS_RESULTS_RETENTION: int = 60 * 60 * 24 * 7  # One week
+JOBS_TIMEOUT: int = 60 * 60 * 24  # One day
+JOBS_MIDDLEWARE: list[str] = [
+    "plain.jobs.middleware.AppLoggerMiddleware",
+]
+JOBS_SCHEDULE: list[tuple[str, str]] = []

plain/jobs/jobs.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import datetime
+import inspect
+import logging
+from typing import TYPE_CHECKING, Any
+
+from opentelemetry import trace
+from opentelemetry.semconv._incubating.attributes.code_attributes import (
+    CODE_FILEPATH,
+    CODE_LINENO,
+)
+from opentelemetry.semconv._incubating.attributes.messaging_attributes import (
+    MESSAGING_DESTINATION_NAME,
+    MESSAGING_MESSAGE_ID,
+    MESSAGING_OPERATION_NAME,
+    MESSAGING_OPERATION_TYPE,
+    MESSAGING_SYSTEM,
+    MessagingOperationTypeValues,
+)
+from opentelemetry.semconv.attributes.error_attributes import ERROR_TYPE
+from opentelemetry.trace import SpanKind, format_span_id, format_trace_id
+
+from plain.models import IntegrityError
+from plain.utils import timezone
+
+from .registry import JobParameters, jobs_registry
+
+if TYPE_CHECKING:
+    from .models import JobProcess, JobRequest
+
+logger = logging.getLogger(__name__)
+tracer = trace.get_tracer("plain.jobs")
+
+
+class JobType(type):
+    """
+    Metaclass allows us to capture the original args/kwargs
+    used to instantiate the job, so we can store them in the database
+    when we schedule the job.
+    """
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Job:
+        instance = super().__call__(*args, **kwargs)
+        instance._init_args = args
+        instance._init_kwargs = kwargs
+        return instance
+
+
+class Job(metaclass=JobType):
+    def run(self) -> None:
+        raise NotImplementedError
+
+    def run_in_worker(
+        self,
+        *,
+        queue: str | None = None,
+        delay: int | datetime.timedelta | datetime.datetime | None = None,
+        priority: int | None = None,
+        retries: int | None = None,
+        retry_attempt: int = 0,
+        unique_key: str | None = None,
+    ) -> JobRequest | list[JobRequest | JobProcess]:
+        from .models import JobRequest
+
+        job_class_name = jobs_registry.get_job_class_name(self.__class__)
+
+        if queue is None:
+            queue = self.get_queue()
+
+        with tracer.start_as_current_span(
+            f"run_in_worker {job_class_name}",
+            kind=SpanKind.PRODUCER,
+            attributes={
+                MESSAGING_SYSTEM: "plain.jobs",
+                MESSAGING_OPERATION_TYPE: MessagingOperationTypeValues.SEND.value,
+                MESSAGING_OPERATION_NAME: "run_in_worker",
+                MESSAGING_DESTINATION_NAME: queue,
+            },
+        ) as span:
+            try:
+                # Try to automatically annotate the source of the job
+                caller = inspect.stack()[1]
+                source = f"{caller.filename}:{caller.lineno}"
+                span.set_attributes(
+                    {
+                        CODE_FILEPATH: caller.filename,
+                        CODE_LINENO: caller.lineno,
+                    }
+                )
+            except (IndexError, AttributeError):
+                source = ""
+
+            parameters = JobParameters.to_json(self._init_args, self._init_kwargs)
+
+            if priority is None:
+                priority = self.get_priority()
+
+            if retries is None:
+                retries = self.get_retries()
+
+            if delay is None:
+                start_at = None
+            elif isinstance(delay, int):
+                start_at = timezone.now() + datetime.timedelta(seconds=delay)
+            elif isinstance(delay, datetime.timedelta):
+                start_at = timezone.now() + delay
+            elif isinstance(delay, datetime.datetime):
+                start_at = delay
+            else:
+                raise ValueError(f"Invalid delay: {delay}")
+
+            if unique_key is None:
+                unique_key = self.get_unique_key()
+
+            if unique_key:
+                # Only need to look at in progress jobs
+                # if we also have a unique key.
+                # Otherwise it's up to the user to use _in_progress()
+                if running := self._in_progress(unique_key):
+                    span.set_attribute(ERROR_TYPE, "DuplicateJob")
+                    return running
+
+            # Is recording is not enough here... because we also record for summaries!
+
+            # Capture current trace context
+            current_span = trace.get_current_span()
+            span_context = current_span.get_span_context()
+
+            # Only include trace context if the span is being recorded (sampled)
+            # This ensures jobs are only linked to traces that are actually being collected
+            if current_span.is_recording() and span_context.is_valid:
+                trace_id = f"0x{format_trace_id(span_context.trace_id)}"
+                span_id = f"0x{format_span_id(span_context.span_id)}"
+            else:
+                trace_id = None
+                span_id = None
+
+            try:
+                job_request = JobRequest(
+                    job_class=job_class_name,
+                    parameters=parameters,
+                    start_at=start_at,
+                    source=source,
+                    queue=queue,
+                    priority=priority,
+                    retries=retries,
+                    retry_attempt=retry_attempt,
+                    unique_key=unique_key,
+                    trace_id=trace_id,
+                    span_id=span_id,
+                )
+                job_request.save(
+                    clean_and_validate=False
+                )  # So IntegrityError is raised on unique instead of potentially confusing ValidationError...
+
+                span.set_attribute(
+                    MESSAGING_MESSAGE_ID,
+                    str(job_request.uuid),
+                )
+
+                # Add job UUID to current span for bidirectional linking
+                span.set_attribute("job.uuid", str(job_request.uuid))
+                span.set_status(trace.StatusCode.OK)
+
+                return job_request
+            except IntegrityError as e:
+                span.set_attribute(ERROR_TYPE, "IntegrityError")
+                span.set_status(trace.Status(trace.StatusCode.ERROR, "Duplicate job"))
+                logger.warning("Job already in progress: %s", e)
+                # Try to return the _in_progress list again
+                return self._in_progress(unique_key)
+
+    def _in_progress(self, unique_key: str) -> list[JobRequest | JobProcess]:
+        """Get all JobRequests and JobProcess that are currently in progress, regardless of queue."""
+        from .models import JobProcess, JobRequest
+
+        job_class_name = jobs_registry.get_job_class_name(self.__class__)
+
+        job_requests = JobRequest.query.filter(
+            job_class=job_class_name,
+            unique_key=unique_key,
+        )
+
+        jobs = JobProcess.query.filter(
+            job_class=job_class_name,
+            unique_key=unique_key,
+        )
+
+        return list(job_requests) + list(jobs)
+
+    def get_unique_key(self) -> str:
+        """
+        A unique key to prevent duplicate jobs from being queued.
+        Enabled by returning a non-empty string.
+
+        Note that this is not a "once and only once" guarantee, but rather
+        an "at least once" guarantee. Jobs should still be idempotent in case
+        multiple instances are queued in a race condition.
+        """
+        return ""
+
+    def get_queue(self) -> str:
+        return "default"
+
+    def get_priority(self) -> int:
+        """
+        Return the default priority for this job.
+
+        Higher numbers run first: 10 > 5 > 0 > -5 > -10
+        - Use positive numbers for high priority jobs
+        - Use negative numbers for low priority jobs
+        - Default is 0
+        """
+        return 0
+
+    def get_retries(self) -> int:
+        return 0
+
+    def get_retry_delay(self, attempt: int) -> int:
+        """
+        Calculate a delay in seconds before the next retry attempt.
+
+        On the first retry, attempt will be 1.
+        """
+        return 0

plain/jobs/middleware.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from plain.logs import app_logger
+
+if TYPE_CHECKING:
+    from .models import JobProcess, JobResult
+
+
+class AppLoggerMiddleware:
+    def __init__(self, run_job: Callable[[JobProcess], JobResult]) -> None:
+        self.run_job = run_job
+
+    def __call__(self, job: JobProcess) -> JobResult:
+        with app_logger.include_context(
+            job_request_uuid=str(job.job_request_uuid), job_process_uuid=str(job.uuid)
+        ):
+            return self.run_job(job)

plain/jobs/migrations/0001_initial.py

@@ -0,0 +1,246 @@
+# Generated by Plain 0.52.2 on 2025-07-08 01:17
+
+import uuid
+
+from plain import models
+from plain.models import migrations
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="Job",
+            fields=[
+                ("id", models.PrimaryKeyField()),
+                ("uuid", models.UUIDField(default=uuid.uuid4)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("started_at", models.DateTimeField(allow_null=True, required=False)),
+                ("job_request_uuid", models.UUIDField()),
+                ("job_class", models.CharField(max_length=255)),
+                ("parameters", models.JSONField(allow_null=True, required=False)),
+                ("priority", models.IntegerField(default=0)),
+                ("source", models.TextField(required=False)),
+                ("queue", models.CharField(default="default", max_length=255)),
+                ("retries", models.IntegerField(default=0)),
+                ("retry_attempt", models.IntegerField(default=0)),
+                ("unique_key", models.CharField(max_length=255, required=False)),
+            ],
+            options={
+                "ordering": ["-created_at"],
+            },
+        ),
+        migrations.CreateModel(
+            name="JobRequest",
+            fields=[
+                ("id", models.PrimaryKeyField()),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("uuid", models.UUIDField(default=uuid.uuid4)),
+                ("job_class", models.CharField(max_length=255)),
+                ("parameters", models.JSONField(allow_null=True, required=False)),
+                ("priority", models.IntegerField(default=0)),
+                ("source", models.TextField(required=False)),
+                ("queue", models.CharField(default="default", max_length=255)),
+                ("retries", models.IntegerField(default=0)),
+                ("retry_attempt", models.IntegerField(default=0)),
+                ("unique_key", models.CharField(max_length=255, required=False)),
+                ("start_at", models.DateTimeField(allow_null=True, required=False)),
+            ],
+            options={
+                "ordering": ["priority", "-created_at"],
+            },
+        ),
+        migrations.CreateModel(
+            name="JobResult",
+            fields=[
+                ("id", models.PrimaryKeyField()),
+                ("uuid", models.UUIDField(default=uuid.uuid4)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("job_uuid", models.UUIDField()),
+                ("started_at", models.DateTimeField(allow_null=True, required=False)),
+                ("ended_at", models.DateTimeField(allow_null=True, required=False)),
+                ("error", models.TextField(required=False)),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[
+                            ("SUCCESSFUL", "Successful"),
+                            ("ERRORED", "Errored"),
+                            ("CANCELLED", "Cancelled"),
+                            ("LOST", "Lost"),
+                        ],
+                        max_length=20,
+                    ),
+                ),
+                ("job_request_uuid", models.UUIDField()),
+                ("job_class", models.CharField(max_length=255)),
+                ("parameters", models.JSONField(allow_null=True, required=False)),
+                ("priority", models.IntegerField(default=0)),
+                ("source", models.TextField(required=False)),
+                ("queue", models.CharField(default="default", max_length=255)),
+                ("retries", models.IntegerField(default=0)),
+                ("retry_attempt", models.IntegerField(default=0)),
+                ("unique_key", models.CharField(max_length=255, required=False)),
+                (
+                    "retry_job_request_uuid",
+                    models.UUIDField(allow_null=True, required=False),
+                ),
+            ],
+            options={
+                "ordering": ["-created_at"],
+            },
+        ),
+        migrations.AddIndex(
+            model_name="job",
+            index=models.Index(
+                fields=["created_at"], name="plainworker_created_a02317_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="job",
+            index=models.Index(fields=["queue"], name="plainworker_queue_077806_idx"),
+        ),
+        migrations.AddIndex(
+            model_name="job",
+            index=models.Index(
+                fields=["unique_key"], name="plainworker_unique__04d87b_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="job",
+            index=models.Index(
+                fields=["started_at"], name="plainworker_started_143df5_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="job",
+            index=models.Index(
+                fields=["job_class"], name="plainworker_job_cla_884b46_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="job",
+            index=models.Index(
+                fields=["job_request_uuid"], name="plainworker_job_req_db2681_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="job",
+            index=models.Index(
+                fields=["job_class", "unique_key"], name="job_class_unique_key"
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="job",
+            constraint=models.UniqueConstraint(
+                fields=("uuid",), name="plainworker_job_unique_uuid"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="jobrequest",
+            index=models.Index(
+                fields=["priority"], name="plainworker_priorit_785e73_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="jobrequest",
+            index=models.Index(
+                fields=["created_at"], name="plainworker_created_c81fe5_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="jobrequest",
+            index=models.Index(fields=["queue"], name="plainworker_queue_2614aa_idx"),
+        ),
+        migrations.AddIndex(
+            model_name="jobrequest",
+            index=models.Index(
+                fields=["start_at"], name="plainworker_start_a_4d6020_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="jobrequest",
+            index=models.Index(
+                fields=["unique_key"], name="plainworker_unique__21a534_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="jobrequest",
+            index=models.Index(
+                fields=["job_class"], name="plainworker_job_cla_3e7dea_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="jobrequest",
+            index=models.Index(
+                fields=["job_class", "unique_key"], name="job_request_class_unique_key"
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="jobrequest",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(("retry_attempt", 0), ("unique_key__gt", "")),
+                fields=("job_class", "unique_key"),
+                name="plainworker_jobrequest_unique_job_class_key",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="jobrequest",
+            constraint=models.UniqueConstraint(
+                fields=("uuid",), name="plainworker_jobrequest_unique_uuid"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="jobresult",
+            index=models.Index(
+                fields=["created_at"], name="plainworker_created_6894c5_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="jobresult",
+            index=models.Index(
+                fields=["job_uuid"], name="plainworker_job_uui_8307d1_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="jobresult",
+            index=models.Index(
+                fields=["started_at"], name="plainworker_started_9bce76_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="jobresult",
+            index=models.Index(
+                fields=["ended_at"], name="plainworker_ended_a_63caaf_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="jobresult",
+            index=models.Index(fields=["status"], name="plainworker_status_a7ca35_idx"),
+        ),
+        migrations.AddIndex(
+            model_name="jobresult",
+            index=models.Index(
+                fields=["job_request_uuid"], name="plainworker_job_req_1e1bf2_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="jobresult",
+            index=models.Index(
+                fields=["job_class"], name="plainworker_job_cla_d138b5_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="jobresult",
+            index=models.Index(fields=["queue"], name="plainworker_queue_23d8fe_idx"),
+        ),
+        migrations.AddConstraint(
+            model_name="jobresult",
+            constraint=models.UniqueConstraint(
+                fields=("uuid",), name="plainworker_jobresult_unique_uuid"
+            ),
+        ),
+    ]