oban 0.5.0__py3-none-any.whl

oban/__init__.py

@@ -0,0 +1,22 @@
+from importlib.metadata import version
+
+from .decorators import job, worker
+from .job import Cancel, Job, Record, Snooze
+from .oban import Oban
+
+try:
+    import oban_pro  # noqa: F401  # ty: ignore[unresolved-import]
+except ImportError:
+    pass
+
+__all__ = [
+    "Cancel",
+    "Job",
+    "Oban",
+    "Record",
+    "Snooze",
+    "job",
+    "worker",
+]
+
+__version__ = version("oban")

oban/__main__.py

@@ -0,0 +1,12 @@
+import contextlib
+
+from oban.cli import main
+
+
+def safe_main() -> None:
+    with contextlib.suppress(KeyboardInterrupt):
+        main()
+
+
+if __name__ == "__main__":
+    safe_main()

oban/_backoff.py

@@ -0,0 +1,87 @@
+import random
+from typing import Literal
+
+
+def exponential(
+    attempt: int, *, max_pow: int = 10, min_pad: int = 0, mult: int = 1
+) -> int:
+    """Calculate exponential backoff delay in seconds.
+
+    Args:
+        attempt: The retry attempt number
+        max_pow: Maximum power of 2 (default: 10)
+        min_pad: Minimum padding in seconds (default: 0)
+        mult: Multiplier for the exponential value (default: 1)
+
+    Returns:
+        Backoff delay in seconds
+    """
+    return min_pad + mult * pow(2, min(attempt, max_pow))
+
+
+def jitter(
+    time: int, *, mode: Literal["inc", "dec", "both"] = "both", mult: float = 0.1
+) -> int:
+    """Add jitter to a backoff time.
+
+    Args:
+        time: Base time in seconds
+        mode: Jitter mode - "inc" (increase only), "dec" (decrease only), or "both" (default: "both")
+        mult: Jitter multiplier (default: 0.1)
+
+    Returns:
+        Time with jitter applied
+    """
+    rand = random.random()
+    diff = int(rand * mult * time)
+
+    match mode:
+        case "inc":
+            return time + diff
+        case "dec":
+            return time - diff
+        case "both":
+            return time + diff if rand >= 0.5 else time - diff
+
+
+def jittery_exponential(
+    attempt: int, *, max_pow: int = 10, min_pad: int = 0, mult: int = 1
+) -> int:
+    """Calculate exponential backoff with jitter.
+
+    Args:
+        attempt: The retry attempt number
+        max_pow: Maximum power of 2 (default: 10, caps at ~1024 seconds)
+        min_pad: Minimum padding in seconds (default: 0)
+        mult: Multiplier for the exponential value (default: 1)
+
+    Returns:
+        Backoff delay in seconds with jitter applied
+    """
+    time = exponential(attempt, max_pow=max_pow, min_pad=min_pad, mult=mult)
+
+    return jitter(time, mode="both")
+
+
+def jittery_clamped(attempt: int, max_attempts: int, *, clamped_max: int = 20) -> int:
+    """Calculate jittery clamped backoff for job retries.
+
+    Clamps the attempt number proportionally to max_attempts, then applies
+    exponential backoff with a minimum padding and jitter that only increases.
+
+    Args:
+        attempt: The retry attempt number
+        max_attempts: Maximum attempts allowed
+        clamped_max: Maximum value to clamp attempts to (default: 20)
+
+    Returns:
+        Backoff delay in seconds with exponential backoff and jitter
+    """
+    if max_attempts <= clamped_max:
+        clamped_attempt = attempt
+    else:
+        clamped_attempt = round(attempt / max_attempts * clamped_max)
+
+    time = exponential(clamped_attempt, mult=1, max_pow=100, min_pad=15)
+
+    return jitter(time, mode="inc")

oban/_config.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+from typing import Any
+
+from psycopg_pool import AsyncConnectionPool
+
+from oban import Oban
+
+
+@dataclass
+class Config:
+    """Configuration for Oban instances.
+
+    Can be used by both CLI and programmatic usage to create Oban instances
+    with consistent configuration.
+    """
+
+    dsn: str | None = None
+    queues: dict[str, int] = field(default_factory=dict)
+    name: str | None = None
+    node: str | None = None
+    prefix: str | None = None
+    leadership: bool | None = None
+
+    # Core loop configurations
+    lifeline: dict[str, Any] | None = None
+    pruner: dict[str, Any] | None = None
+    refresher: dict[str, Any] | None = None
+    scheduler: dict[str, Any] | None = None
+    stager: dict[str, Any] | None = None
+
+    # Connection pool options
+    pool_min_size: int = 1
+    pool_max_size: int = 10
+    pool_timeout: float = 30.0
+
+    @staticmethod
+    def _parse_queues(input: str) -> dict[str, int]:
+        if not input:
+            return {}
+
+        return {
+            name.strip(): int(limit.strip())
+            for line in input.split(",")
+            if line.strip() and ":" in line
+            for name, limit in [line.split(":", 1)]
+        }
+
+    @classmethod
+    def from_env(cls) -> Config:
+        """Load configuration from environment variables.
+
+        Supported environment variables:
+
+        - OBAN_DSN: Database connection string (required)
+        - OBAN_QUEUES: Comma-separated queue:limit pairs (e.g., "default:10,mailers:5")
+        - OBAN_PREFIX: Schema prefix (default: "public")
+        - OBAN_NODE: Node identifier (default: hostname)
+        - OBAN_POOL_MIN_SIZE: Minimum connection pool size (default: 1)
+        - OBAN_POOL_MAX_SIZE: Maximum connection pool size (default: 10)
+        """
+        return cls(
+            dsn=os.getenv("OBAN_DSN"),
+            queues=cls._parse_queues(os.getenv("OBAN_QUEUES", "")),
+            node=os.getenv("OBAN_NODE"),
+            prefix=os.getenv("OBAN_PREFIX", "public"),
+            pool_min_size=int(os.getenv("OBAN_POOL_MIN_SIZE", "1")),
+            pool_max_size=int(os.getenv("OBAN_POOL_MAX_SIZE", "10")),
+        )
+
+    @classmethod
+    def from_cli(cls, params: dict[str, Any]) -> Config:
+        if queues := params.pop("queues", None):
+            params["queues"] = cls._parse_queues(queues)
+
+        return cls(**params)
+
+    @classmethod
+    def from_toml(cls, path: str | None = None) -> Config:
+        params = {}
+        path_obj = Path(path or "oban.toml")
+
+        if path_obj.exists():
+            with open(path_obj, "rb") as file:
+                params = tomllib.load(file)
+
+        return cls(**params)
+
+    @classmethod
+    def load(cls, path: str | None = None, **overrides: Any) -> Config:
+        tml_conf = cls.from_toml(path)
+        env_conf = cls.from_env()
+        cli_conf = cls(**overrides)
+
+        return tml_conf.merge(env_conf).merge(cli_conf)
+
+    def merge(self, other: Config) -> Config:
+        def merge_dicts(this, that) -> dict | None:
+            if that is None or this is None:
+                return this
+
+            merged = this.copy()
+            merged.update(that)
+
+            return merged
+
+        merged = {}
+
+        for field_ref in fields(self):
+            name = field_ref.name
+            this_val = getattr(self, name)
+            that_val = getattr(other, name)
+
+            if isinstance(that_val, dict):
+                merged[name] = merge_dicts(this_val, that_val)
+            elif that_val is not None:
+                merged[name] = that_val
+            else:
+                merged[name] = this_val
+
+        return Config(**merged)
+
+    async def create_pool(self) -> AsyncConnectionPool:
+        if not self.dsn:
+            raise ValueError("dsn is required to create a connection pool")
+
+        pool = AsyncConnectionPool(
+            conninfo=self.dsn,
+            min_size=self.pool_min_size,
+            max_size=self.pool_max_size,
+            timeout=self.pool_timeout,
+            open=False,
+        )
+
+        await pool.open()
+        await pool.wait()
+
+        return pool
+
+    async def create_oban(
+        self, pool: AsyncConnectionPool | None = None, dispatcher: Any = None
+    ) -> Oban:
+        pool = pool or await self.create_pool()
+
+        params: dict[str, Any] = {
+            "pool": pool,
+            "dispatcher": dispatcher,
+            "name": self.name,
+            "prefix": self.prefix,
+            "queues": self.queues,
+        }
+
+        extras = {
+            key: getattr(self, key)
+            for key in [
+                "leadership",
+                "lifeline",
+                "node",
+                "pruner",
+                "refresher",
+                "scheduler",
+                "stager",
+            ]
+            if getattr(self, key) is not None
+        }
+
+        return Oban(**params, **extras)

oban/_executor.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import time
+import traceback
+
+from contextvars import ContextVar
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+from . import telemetry
+from ._backoff import jittery_clamped
+from ._extensions import use_ext
+from ._worker import resolve_worker
+from .job import Cancel, Record, Snooze
+
+if TYPE_CHECKING:
+    from .job import Job
+
+_current_job: ContextVar[Job | None] = ContextVar("oban_current_job", default=None)
+
+
+@dataclass(frozen=True, slots=True)
+class AckAction:
+    job: Job
+    state: str
+    attempt_change: int | None = None
+    error: dict | None = None
+    meta: dict | None = None
+    schedule_in: int | None = None
+
+    @property
+    def id(self) -> int | None:
+        return self.job.id
+
+
+class Executor:
+    def __init__(self, job: Job, safe: bool = True):
+        self.job = job
+        self.safe = safe
+
+        self.action = None
+        self.result = None
+        self.worker = None
+
+        self._start_time = time.monotonic_ns()
+        self._traceback = None
+
+    @staticmethod
+    def current_job() -> Job | None:
+        return _current_job.get()
+
+    async def execute(self) -> Executor:
+        self._report_started()
+        await self._process()
+        self._record_stopped()
+        self._report_stopped()
+        self._reraise_unsafe()
+
+        return self
+
+    @property
+    def status(self) -> str | None:
+        if self.action:
+            return self.action.state
+
+    def _report_started(self) -> None:
+        telemetry.execute(
+            "oban.job.start",
+            {"job": self.job, "monotonic_time": self._start_time},
+        )
+
+    async def _process(self) -> None:
+        token = _current_job.set(self.job)
+
+        try:
+            self.worker = resolve_worker(self.job.worker)()
+            self.result = await self.worker.process(self.job)
+        except Exception as error:
+            self.result = error
+            self._traceback = traceback.format_exc()
+        finally:
+            _current_job.reset(token)
+
+    def _record_stopped(self) -> None:
+        # This is largely for type checking, as executing an unpersisted job wouldn't happen
+        # during actual job processing.
+        if self.job.id is None:
+            self.job.id = 0
+
+        result = use_ext(
+            "executor.wrap_result", lambda _job, res: res, self.job, self.result
+        )
+
+        match result:
+            case Exception() as error:
+                if self.job.attempt >= self.job.max_attempts:
+                    self.action = AckAction(
+                        job=self.job,
+                        state="discarded",
+                        error=self._format_error(error),
+                    )
+                else:
+                    self.action = AckAction(
+                        job=self.job,
+                        state="retryable",
+                        error=self._format_error(error),
+                        schedule_in=self._retry_backoff(),
+                    )
+
+            case Cancel(reason=reason):
+                self.action = AckAction(
+                    job=self.job, state="cancelled", error=self._format_error(reason)
+                )
+
+            case Snooze(seconds=seconds):
+                self.action = AckAction(
+                    job=self.job,
+                    attempt_change=-1,
+                    state="scheduled",
+                    schedule_in=seconds,
+                    meta={"snoozed": self.job.meta.get("snoozed", 0) + 1},
+                )
+
+            case Record(encoded=encoded):
+                self.action = AckAction(
+                    job=self.job,
+                    state="completed",
+                    meta={"recorded": True, "return": encoded},
+                )
+
+            case _:
+                self.action = AckAction(job=self.job, state="completed")
+
+    def _report_stopped(self) -> None:
+        stop_time = time.monotonic_ns()
+
+        meta = {
+            "monotonic_time": stop_time,
+            "duration": stop_time - self._start_time,
+            "queue_time": self._queue_time(),
+            "job": self.job,
+            "state": self.status,
+        }
+
+        if self.status in ("retryable", "discarded"):
+            error_meta = {
+                "error_message": str(self.result),
+                "error_type": type(self.result).__name__,
+                "traceback": self._traceback,
+            }
+
+            telemetry.execute("oban.job.exception", {**meta, **error_meta})
+        else:
+            telemetry.execute("oban.job.stop", meta)
+
+    def _reraise_unsafe(self) -> None:
+        if not self.safe and isinstance(self.result, BaseException):
+            raise self.result
+
+    def _retry_backoff(self) -> int:
+        if hasattr(self.worker, "backoff"):
+            return self.worker.backoff(self.job)
+        else:
+            return jittery_clamped(self.job.attempt, self.job.max_attempts)
+
+    def _queue_time(self) -> int:
+        attempted_at = self.job.attempted_at
+        scheduled_at = self.job.scheduled_at
+
+        if attempted_at and scheduled_at:
+            delta = (attempted_at - scheduled_at).total_seconds()
+
+            return int(delta * 1_000_000_000)
+        else:
+            return 0
+
+    def _format_error(self, error: Exception | str) -> dict:
+        if isinstance(error, str):
+            error_str = error
+        else:
+            error_str = repr(error)
+
+        return {
+            "attempt": self.job.attempt,
+            "at": datetime.now(timezone.utc).isoformat(),
+            "error": error_str,
+        }

oban/_extensions.py

@@ -0,0 +1,16 @@
+from typing import Any, Callable
+
+_extensions: dict[str, Callable] = {}
+
+
+def get_ext(name: str, default: Callable) -> Callable:
+    return _extensions.get(name, default)
+
+
+def put_ext(name: str, func: Callable) -> None:
+    _extensions[name] = func
+
+
+def use_ext(name: str, default: Callable, *args, **kwargs) -> Any:
+    func = _extensions.get(name, default)
+    return func(*args, **kwargs)

oban/_leader.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from . import telemetry
+
+if TYPE_CHECKING:
+    from ._notifier import Notifier
+    from ._query import Query
+
+
+class Leader:
+    """Manages leadership election and coordination across Oban nodes.
+
+    This class is managed internally by Oban and shouldn't be constructed directly.
+    Instead, check leadership status via the Oban.is_leader property:
+
+        >>> async with Oban(pool=pool, queues={"default": 10}) as oban:
+        ...     if oban.is_leader:
+        ...         # Perform leader-only operations
+    """
+
+    def __init__(
+        self,
+        *,
+        enabled: bool = True,
+        interval: float = 30.0,
+        name: str = "oban",
+        node: str,
+        notifier: Notifier,
+        query: Query,
+    ) -> None:
+        self._enabled = enabled
+        self._interval = interval
+        self._name = name
+        self._node = node
+        self._notifier = notifier
+        self._query = query
+
+        self._is_leader = False
+        self._listen_token = None
+        self._loop_task = None
+        self._started = asyncio.Event()
+
+        self._validate(interval=interval)
+
+    @staticmethod
+    def _validate(*, interval: float) -> None:
+        if not isinstance(interval, (int, float)):
+            raise TypeError(f"interval must be a number, got {interval}")
+        if interval <= 0:
+            raise ValueError(f"interval must be positive, got {interval}")
+
+    @property
+    def is_leader(self) -> bool:
+        return self._is_leader
+
+    async def start(self) -> None:
+        if not self._enabled:
+            self._started.set()
+            return
+
+        self._listen_token = await self._notifier.listen(
+            "leader", self._on_notification, wait=False
+        )
+        self._loop_task = asyncio.create_task(self._loop(), name="oban-leader")
+
+        await self._started.wait()
+
+    async def stop(self) -> None:
+        if self._listen_token:
+            await self._notifier.unlisten(self._listen_token)
+
+        if self._loop_task:
+            self._loop_task.cancel()
+
+            try:
+                await self._loop_task
+            except asyncio.CancelledError:
+                pass
+
+        if self._is_leader:
+            payload = {"action": "resign", "node": self._node, "name": self._name}
+
+            await self._notifier.notify("leader", payload)
+            await self._query.resign_leader(self._name, self._node)
+
+    async def _loop(self) -> None:
+        while True:
+            try:
+                await self._election()
+            except asyncio.CancelledError:
+                break
+            except Exception:
+                pass
+            finally:
+                if not self._started.is_set():
+                    self._started.set()
+
+            # Sleep for half interval if leader (to boost their refresh interval and allow them to
+            # retain leadership), full interval otherwise
+            sleep_duration = self._interval / 2 if self._is_leader else self._interval
+
+            await asyncio.sleep(sleep_duration)
+
+    async def _election(self) -> None:
+        meta = {"leader": self._is_leader}
+
+        with telemetry.span("oban.leader.election", meta) as context:
+            self._is_leader = await self._query.attempt_leadership(
+                self._name, self._node, int(self._interval), self._is_leader
+            )
+
+            context.add({"leader": self._is_leader})
+
+    async def _on_notification(self, _channel: str, _payload: dict) -> None:
+        await self._election()

oban/_lifeline.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from . import telemetry
+from ._extensions import use_ext
+
+if TYPE_CHECKING:
+    from ._leader import Leader
+    from ._query import Query
+
+
+async def _rescue(query: Query, rescue_after: float) -> None:
+    with telemetry.span("oban.lifeline.rescue", {}) as context:
+        rescued = await query.rescue_jobs(rescue_after)
+
+        context.add({"rescued_count": rescued})
+
+
+class Lifeline:
+    def __init__(
+        self,
+        *,
+        query: Query,
+        leader: Leader,
+        interval: float = 60.0,
+        rescue_after: float = 300.0,
+    ) -> None:
+        self._leader = leader
+        self._interval = interval
+        self._rescue_after = rescue_after
+        self._query = query
+
+        self._loop_task = None
+
+        self._validate(interval=interval, rescue_after=rescue_after)
+
+    @staticmethod
+    def _validate(*, interval: float, rescue_after: float) -> None:
+        if not isinstance(interval, (int, float)):
+            raise TypeError(f"interval must be a number, got {interval}")
+        if interval <= 0:
+            raise ValueError(f"interval must be positive, got {interval}")
+        if not isinstance(rescue_after, (int, float)):
+            raise TypeError(f"rescue_after must be a number, got {rescue_after}")
+        if rescue_after <= 0:
+            raise ValueError(f"rescue_after must be positive, got {rescue_after}")
+
+    async def start(self) -> None:
+        self._loop_task = asyncio.create_task(self._loop(), name="oban-lifeline")
+
+    async def stop(self) -> None:
+        if self._loop_task:
+            self._loop_task.cancel()
+
+            try:
+                await self._loop_task
+            except asyncio.CancelledError:
+                pass
+
+    async def _loop(self) -> None:
+        while True:
+            try:
+                await asyncio.sleep(self._interval)
+
+                await self._rescue()
+            except asyncio.CancelledError:
+                break
+            except Exception:
+                pass
+
+    async def _rescue(self) -> None:
+        if not self._leader.is_leader:
+            return
+
+        await use_ext("lifeline.rescue", _rescue, self._query, self._rescue_after)