supython 0.5.0__py3-none-any.whl

supython/jobs/__init__.py

@@ -0,0 +1,31 @@
+"""Jobs module — durable job queue with cron scheduling."""
+
+from .backends import get_backend
+from .context import JobCtx
+from .decorators import job
+from .registry import get_registry
+from .router import router
+from .schemas import EnqueueResult, JobResponse
+from .service import JobError, enqueue
+from .worker import Worker
+
+
+def get_worker() -> Worker:
+    from ..settings import get_settings
+
+    return Worker(get_settings())
+
+
+__all__ = [
+    "Worker",
+    "enqueue",
+    "get_backend",
+    "get_registry",
+    "get_worker",
+    "job",
+    "JobCtx",
+    "JobError",
+    "JobResponse",
+    "EnqueueResult",
+    "router",
+]

supython/jobs/backends.py

@@ -0,0 +1,97 @@
+"""Job backend protocol + default Postgres-queue implementation.
+
+Collapsed from a two-file ``backends/`` package into a single module during the
+v0.5 grooming pass: until a second backend actually lands (arq / dramatiq as
+optional extras), the package added no structure the Protocol does not already
+express. When an additional backend is introduced it should be promoted back
+to a package.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+from uuid import UUID
+
+from .. import db
+from ..settings import Settings, get_settings
+from .schemas import EnqueueResult, JobRecord
+from .service import cancel as svc_cancel
+from .service import enqueue as svc_enqueue
+from .service import get_job as svc_get_job
+from .service import list_jobs as svc_list_jobs
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .worker import Worker
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class JobBackend(Protocol):
+    async def enqueue(self, **kwargs) -> EnqueueResult: ...
+    async def run(self) -> None: ...
+    async def cancel(self, job_id: UUID) -> None: ...
+    async def retry(self, job_id: UUID) -> None: ...
+    async def list_jobs(self, **kwargs) -> list[JobRecord]: ...
+    async def get_job(self, job_id: UUID) -> JobRecord | None: ...
+    async def health_check(self) -> dict: ...
+
+
+class PgQueueBackend:
+    """Default backend — polls ``jobs.jobs`` with ``FOR UPDATE SKIP LOCKED``."""
+
+    def __init__(self, settings: Settings) -> None:
+        self._settings = settings
+        self._worker: Worker | None = None
+
+    async def enqueue(self, **kwargs) -> EnqueueResult:
+        async with db.as_service_role() as conn:
+            return await svc_enqueue(conn, **kwargs)
+
+    async def run(self) -> None:
+        from .worker import Worker
+
+        self._worker = Worker(self._settings)
+        await self._worker.start()
+
+    async def cancel(self, job_id: UUID) -> None:
+        async with db.as_service_role() as conn:
+            await svc_cancel(conn, job_id)
+
+    async def retry(self, job_id: UUID) -> None:
+        from .service import mark_failed_retry
+
+        async with db.as_service_role() as conn:
+            record = await svc_get_job(conn, job_id)
+            if record is None:
+                return
+            await mark_failed_retry(
+                conn,
+                job_id,
+                attempts=record.attempts,
+                backoff=record.backoff,
+                backoff_base_s=record.backoff_base_s,
+                backoff_max_s=record.backoff_max_s,
+            )
+
+    async def list_jobs(self, **kwargs) -> list[JobRecord]:
+        async with db.as_service_role() as conn:
+            return await svc_list_jobs(conn, **kwargs)
+
+    async def get_job(self, job_id: UUID) -> JobRecord | None:
+        async with db.as_service_role() as conn:
+            return await svc_get_job(conn, job_id)
+
+    async def health_check(self) -> dict:
+        try:
+            async with db.as_service_role() as conn:
+                await conn.fetchval("select 1 from jobs.jobs limit 1")
+            return {"backend": "pg", "healthy": True}
+        except Exception as exc:
+            return {"backend": "pg", "healthy": False, "detail": str(exc)}
+
+
+def get_backend(settings: Settings | None = None) -> JobBackend:
+    s = settings or get_settings()
+    return PgQueueBackend(s)

supython/jobs/context.py

@@ -0,0 +1,58 @@
+"""Job execution context — mirrors ``functions.context.Ctx`` for worker jobs.
+
+``HookCtx`` and ``build_hook_ctx`` used to live here; they moved to
+``supython.hooks`` so feature modules (auth, storage, ...) can fire hooks
+without importing the jobs package. This file now only owns the job-side
+context.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from uuid import UUID
+
+import asyncpg
+
+from ..functions.context import PostgrestClient, StorageClient, _make_send_email
+from ..mailer import EmailBackend, get_mailer
+from ..settings import Settings, get_settings
+from ..storage.backends import StorageBackend, get_backend
+
+
+@dataclass
+class JobCtx:
+    db: asyncpg.Connection
+    settings: Settings
+    send_email: Callable[..., Awaitable[None]]
+    storage: StorageClient
+    postgrest: PostgrestClient
+    logger: logging.Logger
+    job_id: UUID | None = None
+    attempt: int = 0
+    name: str = ""
+
+
+def build_job_ctx(
+    *,
+    conn: asyncpg.Connection,
+    job_id: UUID | None = None,
+    attempt: int = 0,
+    name: str = "",
+    backend: StorageBackend | None = None,
+    mailer: EmailBackend | None = None,
+    settings: Settings | None = None,
+) -> JobCtx:
+    s = settings or get_settings()
+    return JobCtx(
+        db=conn,
+        settings=s,
+        send_email=_make_send_email(mailer or get_mailer()),
+        storage=StorageClient(conn, backend or get_backend()),
+        postgrest=PostgrestClient(s.postgrest_url, None),
+        logger=logging.getLogger(f"supython.jobs.{name}"),
+        job_id=job_id,
+        attempt=attempt,
+        name=name,
+    )

supython/jobs/cron.py

@@ -0,0 +1,152 @@
+"""Cron scheduling — ``pg_cron`` synchronisation only.
+
+The in-process ``croniter`` fallback moved to :mod:`.cron_inproc` so that
+the ``croniter`` import (an optional extra, see the v0.5 decision log) is
+only touched when ``jobs_cron_backend == 'inproc'``. This module has no
+optional-dep imports and is safe to load at app startup.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+from collections.abc import AsyncIterator
+
+import asyncpg
+
+from .registry import get_registry
+
+logger = logging.getLogger(__name__)
+
+
+@contextlib.asynccontextmanager
+async def _as_login_role(conn: asyncpg.Connection) -> AsyncIterator[None]:
+    """Temporarily step out of a NOLOGIN role for pg_cron scheduling.
+
+    pg_cron stamps ``current_user`` on the ``cron.job`` row at schedule
+    time and uses that role to initialise a background worker on every
+    tick. The caller of :func:`sync_pg_cron` is expected to be in
+    ``service_role``, which is ``NOLOGIN`` (see
+    ``migrations/0001_extensions_and_roles.sql``); every tick would then
+    FATAL with ``role "service_role" is not permitted to log in`` and
+    the schedule would silently never fire.
+
+    We hop back to the connection's pre-``service_role`` identity for
+    just the ``cron.schedule`` / ``cron.unschedule`` call. That identity
+    is whichever role opened the asyncpg connection (see
+    ``DATABASE_URL``) and is therefore guaranteed LOGIN-capable.
+
+    Uses ``SET LOCAL`` when the caller is inside a transaction so the
+    hop doesn't leak past a ``db.as_service_role()`` block into the
+    pooled connection.
+    """
+    prev_role = await conn.fetchval("select current_user")
+    in_txn = conn.is_in_transaction()
+    scope = "local " if in_txn else ""
+    await conn.execute(f"set {scope}role none")
+    try:
+        yield
+    finally:
+        await conn.execute(f'set {scope}role "{prev_role}"')
+
+
+async def sync_pg_cron(conn: asyncpg.Connection) -> None:
+    """Upsert ``pg_cron`` schedule rows from the registry and remove stale ones.
+
+    The caller is expected to have entered ``db.as_service_role()`` (or
+    the CLI equivalent) before invoking this — the ``jobs.cron_schedules``
+    table is owned by ``service_role``. For the actual ``cron.schedule``
+    / ``cron.unschedule`` calls we transiently hop back to a LOGIN role
+    via :func:`_as_login_role` so pg_cron's background worker can
+    initialise a session at tick time.
+
+    When pg_cron is installed, errors from ``cron.schedule`` propagate
+    to the caller. 
+
+    When pg_cron is NOT installed the metadata row is still upserted so
+    the in-process scheduler (or a manual runner) can pick it up, and
+    ``cron.schedule`` is skipped entirely.
+    """
+    registry = get_registry()
+    has_pg_cron = await conn.fetchval(
+        "select exists(select 1 from pg_extension where extname = 'pg_cron')"
+    )
+
+    for cron_defn in registry.iter_crons():
+        await conn.execute(
+            """
+            insert into jobs.cron_schedules
+                (name, cron_expr, job_name, job_version, payload, queue, enabled)
+            values ($1, $2, $3, $4, $5::jsonb, $6, true)
+            on conflict (name) do update set
+                cron_expr   = excluded.cron_expr,
+                job_name    = excluded.job_name,
+                job_version = excluded.job_version,
+                payload     = excluded.payload,
+                queue       = excluded.queue,
+                enabled     = excluded.enabled
+            """,
+            cron_defn.name,
+            cron_defn.cron_expr,
+            cron_defn.job_name,
+            cron_defn.job_version,
+            json.dumps(cron_defn.payload),
+            cron_defn.queue,
+        )
+
+        if not has_pg_cron:
+            continue
+
+        # Build the pg_cron command via ``format(..., %L, %L, %L)`` so
+        # Postgres handles quoting/escaping of the payload JSON and text
+        # args instead of interpolating them from Python. This closes
+        # the pre-grooming bug where f-string interpolation produced
+        # invalid JSON for any non-trivial payload.
+        command = await conn.fetchval(
+            """
+            select format(
+                'select jobs.enqueue(p_name := %L, p_payload := %L::jsonb, p_queue := %L)',
+                $1::text, $2::text, $3::text
+            )
+            """,
+            cron_defn.job_name,
+            json.dumps(cron_defn.payload),
+            cron_defn.queue,
+        )
+
+        async with _as_login_role(conn):
+            await conn.execute(
+                "select cron.schedule($1, $2, $3)",
+                cron_defn.name,
+                cron_defn.cron_expr,
+                command,
+            )
+
+    registered_names = {c.name for c in registry.iter_crons()}
+    existing = await conn.fetch("select name from jobs.cron_schedules")
+    for row in existing:
+        if row["name"] in registered_names:
+            continue
+        if has_pg_cron:
+            async with _as_login_role(conn):
+                # Stale metadata may no longer have a matching cron.job
+                # row (e.g. manually unscheduled); tolerate that single
+                # case. Everything else — permission denied, syntax
+                # error, etc. — indicates a misconfiguration and is
+                # surfaced to the caller.
+                try:
+                    await conn.execute(
+                        "select cron.unschedule($1)", row["name"]
+                    )
+                except asyncpg.exceptions.RaiseError as exc:
+                    if "could not find" not in str(exc):
+                        raise
+                    logger.debug(
+                        "jobs.cron.unschedule_noop",
+                        extra={"cron_name": row["name"]},
+                    )
+        await conn.execute(
+            "delete from jobs.cron_schedules where name = $1",
+            row["name"],
+        )

supython/jobs/cron_inproc.py

@@ -0,0 +1,118 @@
+"""Optional in-process cron scheduler (``croniter``-based).
+
+Loaded only when ``jobs_cron_backend == 'inproc'``. ``croniter`` is an
+optional extra — users opt in with ``pip install supython[cron-inproc]``
+per the 2026-04-21 decision log row and §15.5 dependency budget.
+
+Two bugs in the pre-grooming implementation were fixed here:
+
+1. **Firing condition** — ``croniter.get_next(datetime)`` returns the next
+   fire time strictly after its anchor, so the old ``next_fire <= now``
+   test was never true. We now track a per-schedule ``_last_fire`` anchor
+   and compare ``next_fire`` against the current ``now`` after the sleep.
+2. **Advisory lock lifetime** — ``pg_advisory_lock`` is session-scoped, so
+   acquiring on one pool connection and releasing on another leaks the
+   lock forever. Both now happen on the same connection for a single
+   cron tick.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+from .. import db
+from ..settings import Settings
+from .registry import CronDefinition, get_registry
+from .service import enqueue
+
+logger = logging.getLogger(__name__)
+
+
+def _require_croniter() -> Any:
+    try:
+        import croniter  # type: ignore[import-not-found]
+
+        return croniter
+    except ImportError as exc:  # pragma: no cover — depends on extras
+        raise ImportError(
+            "croniter is required for in-process cron scheduling. "
+            "Install with: pip install supython[cron-inproc]"
+        ) from exc
+
+
+class InProcScheduler:
+    """croniter-based fallback scheduler.
+
+    One tick per minute; at each tick, every registered cron expression that
+    has moved past its next scheduled fire time enqueues a single job.
+    Advisory-lock + idempotency-key form a belt-and-braces guard against
+    duplicate enqueues across replicas.
+    """
+
+    def __init__(self, settings: Settings) -> None:
+        self._settings = settings
+        self._running = False
+        self._last_fire: dict[str, datetime] = {}
+
+    async def start(self) -> None:
+        croniter_mod = _require_croniter()
+        self._running = True
+
+        registry = get_registry()
+
+        # Seed the ``_last_fire`` map so that the first tick does not
+        # retroactively fire schedules that would otherwise look "overdue"
+        # after a process restart.
+        now = datetime.now(UTC)
+        for cron_defn in registry.iter_crons():
+            if cron_defn.name not in self._last_fire:
+                self._last_fire[cron_defn.name] = now
+
+        while self._running:
+            now = datetime.now(UTC)
+            for cron_defn in registry.iter_crons():
+                try:
+                    anchor = self._last_fire.get(cron_defn.name, now)
+                    cron = croniter_mod.croniter(cron_defn.cron_expr, anchor)
+                    next_fire = cron.get_next(datetime)
+                    if next_fire <= now:
+                        fired = await self._try_fire(cron_defn, next_fire)
+                        if fired:
+                            self._last_fire[cron_defn.name] = next_fire
+                except Exception:
+                    logger.exception(
+                        "jobs.cron.tick_error",
+                        extra={"cron_name": cron_defn.name},
+                    )
+
+            await asyncio.sleep(60)
+
+    async def stop(self) -> None:
+        self._running = False
+
+    async def _try_fire(
+        self, cron_defn: CronDefinition, tick: datetime
+    ) -> bool:
+        """Acquire-enqueue-release on one connection; skip if another worker has it."""
+        async with db.as_service_role() as conn:
+            locked = await conn.fetchval(
+                "select pg_try_advisory_lock(hashtext($1))", cron_defn.name
+            )
+            if not locked:
+                return False
+            try:
+                await enqueue(
+                    conn,
+                    name=cron_defn.job_name,
+                    payload=cron_defn.payload,
+                    queue=cron_defn.queue,
+                    idempotency_key=f"{cron_defn.name}:{tick.isoformat()}",
+                )
+                return True
+            finally:
+                await conn.execute(
+                    "select pg_advisory_unlock(hashtext($1))", cron_defn.name
+                )

supython/jobs/decorators.py

@@ -0,0 +1,76 @@
+"""Decorators for registering jobs and cron schedules."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Coroutine
+from enum import StrEnum
+from typing import Any
+
+from .registry import CronDefinition, JobDefinition, get_registry
+
+Handler = Callable[..., Coroutine[Any, Any, None]]
+
+
+class Backoff(StrEnum):
+    EXPONENTIAL = "exponential"
+    LINEAR = "linear"
+    CONSTANT = "constant"
+
+
+def job(
+    name: str,
+    *,
+    version: int = 1,
+    max_attempts: int = 3,
+    backoff: Backoff | str = Backoff.EXPONENTIAL,
+    backoff_base_s: float = 5.0,
+    backoff_max_s: float = 300.0,
+    queue: str = "default",
+    role: str = "service_role",
+    claims_from: str | None = None,
+    accepts_payload: bool = True,
+) -> Callable[..., Any]:
+    def decorator(fn: Handler) -> Handler:
+        get_registry().register_job(
+            JobDefinition(
+                name=name,
+                version=version,
+                handler=fn,
+                max_attempts=max_attempts,
+                backoff=backoff if isinstance(backoff, str) else backoff.value,
+                backoff_base_s=backoff_base_s,
+                backoff_max_s=backoff_max_s,
+                queue=queue,
+                role=role,
+                claims_from=claims_from,
+                accepts_payload=accepts_payload,
+            )
+        )
+        return fn
+
+    return decorator
+
+
+def cron(
+    cron_expr: str,
+    *,
+    name: str,
+    job_name: str | None = None,
+    job_version: int = 1,
+    payload: dict | None = None,
+    queue: str = "default",
+) -> Callable[..., Any]:
+    def decorator(fn: Handler) -> Handler:
+        get_registry().register_cron(
+            CronDefinition(
+                name=name,
+                cron_expr=cron_expr,
+                job_name=job_name or name,
+                job_version=job_version,
+                payload=payload or {},
+                queue=queue,
+            )
+        )
+        return fn
+
+    return decorator

supython/jobs/registry.py

@@ -0,0 +1,79 @@
+"""Job and cron definitions registry (process-global singleton)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Coroutine
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class JobDefinition:
+    name: str
+    handler: Callable[..., Coroutine[Any, Any, None]] = field(repr=False)
+    version: int = 1
+    max_attempts: int = 3
+    backoff: str = "exponential"
+    backoff_base_s: float = 5.0
+    backoff_max_s: float = 300.0
+    queue: str = "default"
+    role: str = "service_role"
+    claims_from: str | None = None
+    accepts_payload: bool = True
+
+
+@dataclass
+class CronDefinition:
+    name: str
+    cron_expr: str
+    job_name: str
+    job_version: int = 1
+    payload: dict = field(default_factory=dict)
+    queue: str = "default"
+
+
+class Registry:
+    def __init__(self) -> None:
+        self._jobs: dict[tuple[str, int], JobDefinition] = {}
+        self._crons: dict[str, CronDefinition] = {}
+
+    def register_job(self, defn: JobDefinition) -> None:
+        key = (defn.name, defn.version)
+        if key in self._jobs:
+            raise ValueError(f"job {defn.name!r} v{defn.version} already registered")
+        self._jobs[key] = defn
+
+    def register_cron(self, defn: CronDefinition) -> None:
+        if defn.name in self._crons:
+            raise ValueError(f"cron {defn.name!r} already registered")
+        self._crons[defn.name] = defn
+
+    def get(self, name: str, version: int) -> JobDefinition | None:
+        return self._jobs.get((name, version))
+
+    def get_latest(self, name: str) -> JobDefinition | None:
+        versions = [v for (n, v) in self._jobs if n == name]
+        if not versions:
+            return None
+        return self._jobs[(name, max(versions))]
+
+    def iter_jobs(self):
+        return iter(self._jobs.values())
+
+    def iter_crons(self):
+        return iter(self._crons.values())
+
+
+_registry: Registry | None = None
+
+
+def get_registry() -> Registry:
+    global _registry
+    if _registry is None:
+        _registry = Registry()
+    return _registry
+
+
+def reset_registry() -> None:
+    global _registry
+    _registry = None