nat-engine 1__py3-none-any.whl

mannf/product/scheduling/queue.py

@@ -0,0 +1,894 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""Job queue backends for the NAT worker pool.
+
+Provides a ``JobQueue`` abstract base class and three concrete
+implementations:
+
+* :class:`InMemoryJobQueue` — in-process queue for local/dev mode.
+* :class:`SQLiteJobQueue` — lightweight persistent queue backed by SQLite.
+* :class:`RedisJobQueue` — production-grade distributed queue backed by Redis.
+
+All implementations share the same interface::
+
+    queue = InMemoryJobQueue()
+    job_id = await queue.enqueue("scan", {"scan_id": "abc", "base_url": "…"})
+    job = await queue.dequeue()          # returns a :class:`Job` or None
+    await queue.ack(job.job_id)
+    status = await queue.status()        # returns :class:`QueueStats`
+
+Job states
+----------
+``pending`` → ``running`` → ``completed``
+                          ↘ ``failed``
+                          ↘ ``retrying``
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import sqlite3
+import threading
+import time
+import uuid
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+#: All valid job state labels.
+JOB_STATES = ("pending", "running", "completed", "failed", "retrying")
+
+
+@dataclass
+class Job:
+    """A single unit of work managed by the queue.
+
+    Parameters
+    ----------
+    job_id:
+        Unique identifier for this job (UUID4 string).
+    job_type:
+        Logical job type, e.g. ``"scan"``, ``"security_scan"``,
+        ``"autonomous_sweep"``.
+    payload:
+        Arbitrary serialisable dict of job parameters.
+    status:
+        Current state; one of ``pending``, ``running``, ``completed``,
+        ``failed``, ``retrying``.
+    created_at:
+        ISO-8601 UTC timestamp at which the job was enqueued.
+    updated_at:
+        ISO-8601 UTC timestamp at which the job state last changed.
+    worker_id:
+        ID of the worker that claimed this job, if any.
+    attempt:
+        Number of times this job has been attempted (starts at 0).
+    error:
+        Last error message if the job is in ``failed`` / ``retrying`` state.
+    dedup_key:
+        Optional deduplication key.  A second ``enqueue()`` call with the same
+        key will be silently dropped when the job is still pending/running.
+    """
+
+    job_id: str
+    job_type: str
+    payload: Dict[str, Any]
+    status: str = "pending"
+    created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    updated_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    worker_id: Optional[str] = None
+    attempt: int = 0
+    error: Optional[str] = None
+    dedup_key: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "job_id": self.job_id,
+            "job_type": self.job_type,
+            "payload": self.payload,
+            "status": self.status,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "worker_id": self.worker_id,
+            "attempt": self.attempt,
+            "error": self.error,
+            "dedup_key": self.dedup_key,
+        }
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Job":
+        return cls(
+            job_id=d["job_id"],
+            job_type=d["job_type"],
+            payload=d.get("payload") or {},
+            status=d.get("status", "pending"),
+            created_at=d.get("created_at", datetime.now(timezone.utc).isoformat()),
+            updated_at=d.get("updated_at", datetime.now(timezone.utc).isoformat()),
+            worker_id=d.get("worker_id"),
+            attempt=int(d.get("attempt", 0)),
+            error=d.get("error"),
+            dedup_key=d.get("dedup_key"),
+        )
+
+
+@dataclass
+class QueueStats:
+    """Snapshot of queue depth by state."""
+
+    pending: int = 0
+    running: int = 0
+    completed: int = 0
+    failed: int = 0
+    retrying: int = 0
+
+    @property
+    def total(self) -> int:
+        return self.pending + self.running + self.completed + self.failed + self.retrying
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "pending": self.pending,
+            "running": self.running,
+            "completed": self.completed,
+            "failed": self.failed,
+            "retrying": self.retrying,
+            "total": self.total,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Abstract interface
+# ---------------------------------------------------------------------------
+
+
+class JobQueue(ABC):
+    """Abstract job queue interface.
+
+    All mutating operations are ``async`` to support both in-memory
+    (asyncio-native) and I/O-backed (SQLite / Redis) implementations.
+    """
+
+    @abstractmethod
+    async def enqueue(
+        self,
+        job_type: str,
+        payload: Dict[str, Any],
+        *,
+        dedup_key: Optional[str] = None,
+    ) -> str:
+        """Add a job to the queue and return its ``job_id``.
+
+        If *dedup_key* is provided and an active job (``pending`` or
+        ``running``) with the same key already exists, the existing
+        ``job_id`` is returned without adding a duplicate.
+        """
+
+    @abstractmethod
+    async def dequeue(self, worker_id: Optional[str] = None) -> Optional[Job]:
+        """Atomically claim the next ``pending`` job and mark it ``running``.
+
+        Returns ``None`` when the queue is empty.
+        """
+
+    @abstractmethod
+    async def ack(self, job_id: str) -> None:
+        """Mark a job as ``completed``."""
+
+    @abstractmethod
+    async def nack(
+        self,
+        job_id: str,
+        *,
+        error: Optional[str] = None,
+        retry: bool = False,
+        max_attempts: int = 3,
+    ) -> None:
+        """Mark a job as ``failed`` (or ``retrying`` if *retry* is True and the
+        attempt count is below *max_attempts*).  A retried job is moved back
+        to ``pending`` so it can be claimed again.
+        """
+
+    @abstractmethod
+    async def get(self, job_id: str) -> Optional[Job]:
+        """Retrieve a job by ID without modifying its state."""
+
+    @abstractmethod
+    async def list_jobs(
+        self,
+        *,
+        status: Optional[str] = None,
+        limit: int = 100,
+    ) -> List[Job]:
+        """Return a list of jobs, optionally filtered by *status*."""
+
+    @abstractmethod
+    async def status(self) -> QueueStats:
+        """Return a point-in-time snapshot of queue depth by state."""
+
+    @abstractmethod
+    async def purge(self, *, status: Optional[str] = None) -> int:
+        """Delete jobs.  If *status* is given, only that state is purged.
+        Returns the number of deleted jobs.
+        """
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _new_job_id() -> str:
+        return str(uuid.uuid4())
+
+    @staticmethod
+    def _now() -> str:
+        return datetime.now(timezone.utc).isoformat()
+
+
+# ---------------------------------------------------------------------------
+# In-memory implementation
+# ---------------------------------------------------------------------------
+
+
+class InMemoryJobQueue(JobQueue):
+    """Thread/asyncio-safe in-process queue backed by a plain dict.
+
+    Suitable for single-process local/dev/test mode.  State is lost when the
+    process restarts.
+    """
+
+    def __init__(self) -> None:
+        self._jobs: Dict[str, Job] = {}
+        # asyncio.Lock is *not* thread-safe — use a threading.Lock for the
+        # underlying dict so worker threads can also call these methods.
+        self._lock = threading.Lock()
+
+    # ------------------------------------------------------------------
+    # Core interface
+    # ------------------------------------------------------------------
+
+    async def enqueue(
+        self,
+        job_type: str,
+        payload: Dict[str, Any],
+        *,
+        dedup_key: Optional[str] = None,
+    ) -> str:
+        with self._lock:
+            # Deduplication check
+            if dedup_key is not None:
+                for job in self._jobs.values():
+                    if (
+                        job.dedup_key == dedup_key
+                        and job.status in ("pending", "running", "retrying")
+                    ):
+                        logger.debug(
+                            "Job deduplication: key=%r already active as job_id=%s",
+                            dedup_key,
+                            job.job_id,
+                        )
+                        return job.job_id
+
+            job_id = self._new_job_id()
+            now = self._now()
+            job = Job(
+                job_id=job_id,
+                job_type=job_type,
+                payload=payload,
+                status="pending",
+                created_at=now,
+                updated_at=now,
+                dedup_key=dedup_key,
+            )
+            self._jobs[job_id] = job
+            logger.debug("Enqueued job %s type=%s", job_id, job_type)
+            return job_id
+
+    async def dequeue(self, worker_id: Optional[str] = None) -> Optional[Job]:
+        with self._lock:
+            for job in sorted(self._jobs.values(), key=lambda j: j.created_at):
+                if job.status == "pending":
+                    job.status = "running"
+                    job.worker_id = worker_id
+                    job.attempt += 1
+                    job.updated_at = self._now()
+                    return job
+        return None
+
+    async def ack(self, job_id: str) -> None:
+        with self._lock:
+            job = self._jobs.get(job_id)
+            if job is None:
+                return
+            job.status = "completed"
+            job.updated_at = self._now()
+
+    async def nack(
+        self,
+        job_id: str,
+        *,
+        error: Optional[str] = None,
+        retry: bool = False,
+        max_attempts: int = 3,
+    ) -> None:
+        with self._lock:
+            job = self._jobs.get(job_id)
+            if job is None:
+                return
+            job.error = error
+            job.updated_at = self._now()
+            if retry and job.attempt < max_attempts:
+                # Reset to pending so the job can be claimed again
+                job.status = "pending"
+                logger.info(
+                    "Job %s will retry (attempt %d/%d): %s",
+                    job_id,
+                    job.attempt,
+                    max_attempts,
+                    error,
+                )
+            else:
+                job.status = "failed"
+                logger.warning("Job %s failed: %s", job_id, error)
+
+    async def get(self, job_id: str) -> Optional[Job]:
+        with self._lock:
+            return self._jobs.get(job_id)
+
+    async def list_jobs(
+        self,
+        *,
+        status: Optional[str] = None,
+        limit: int = 100,
+    ) -> List[Job]:
+        with self._lock:
+            jobs = list(self._jobs.values())
+        if status is not None:
+            jobs = [j for j in jobs if j.status == status]
+        # Most-recently-created first
+        jobs.sort(key=lambda j: j.created_at, reverse=True)
+        return jobs[:limit]
+
+    async def status(self) -> QueueStats:
+        with self._lock:
+            jobs = list(self._jobs.values())
+        stats = QueueStats()
+        for job in jobs:
+            if job.status == "pending":
+                stats.pending += 1
+            elif job.status == "running":
+                stats.running += 1
+            elif job.status == "completed":
+                stats.completed += 1
+            elif job.status == "failed":
+                stats.failed += 1
+            elif job.status == "retrying":
+                stats.retrying += 1
+        return stats
+
+    async def purge(self, *, status: Optional[str] = None) -> int:
+        with self._lock:
+            if status is None:
+                count = len(self._jobs)
+                self._jobs.clear()
+                return count
+            to_delete = [jid for jid, j in self._jobs.items() if j.status == status]
+            for jid in to_delete:
+                del self._jobs[jid]
+            return len(to_delete)
+
+
+# ---------------------------------------------------------------------------
+# SQLite implementation
+# ---------------------------------------------------------------------------
+
+_SQLITE_SCHEMA = """
+CREATE TABLE IF NOT EXISTS nat_jobs (
+    job_id      TEXT PRIMARY KEY,
+    job_type    TEXT NOT NULL,
+    payload     TEXT NOT NULL,
+    status      TEXT NOT NULL DEFAULT 'pending',
+    created_at  TEXT NOT NULL,
+    updated_at  TEXT NOT NULL,
+    worker_id   TEXT,
+    attempt     INTEGER NOT NULL DEFAULT 0,
+    error       TEXT,
+    dedup_key   TEXT
+);
+CREATE INDEX IF NOT EXISTS nat_jobs_status ON nat_jobs (status);
+CREATE INDEX IF NOT EXISTS nat_jobs_dedup  ON nat_jobs (dedup_key, status);
+"""
+
+
+class SQLiteJobQueue(JobQueue):
+    """Persistent job queue backed by a SQLite database.
+
+    Suitable as a single-host persistent option (survives process restarts).
+    Uses a threading lock around the SQLite connection for coroutine safety.
+
+    Parameters
+    ----------
+    db_path:
+        Filesystem path to the SQLite database file.
+        Defaults to ``":memory:"`` (in-process, non-persistent) for tests.
+    """
+
+    def __init__(self, db_path: str = ":memory:") -> None:
+        self._db_path = db_path
+        self._lock = threading.Lock()
+        self._conn: sqlite3.Connection | None = None
+        self._ensure_schema()
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _get_conn(self) -> sqlite3.Connection:
+        if self._conn is None:
+            self._conn = sqlite3.connect(
+                self._db_path,
+                check_same_thread=False,
+                isolation_level=None,  # autocommit
+            )
+            self._conn.row_factory = sqlite3.Row
+        return self._conn
+
+    def _ensure_schema(self) -> None:
+        with self._lock:
+            conn = self._get_conn()
+            conn.executescript(_SQLITE_SCHEMA)
+
+    @staticmethod
+    def _row_to_job(row: sqlite3.Row) -> Job:
+        return Job(
+            job_id=row["job_id"],
+            job_type=row["job_type"],
+            payload=json.loads(row["payload"]),
+            status=row["status"],
+            created_at=row["created_at"],
+            updated_at=row["updated_at"],
+            worker_id=row["worker_id"],
+            attempt=row["attempt"],
+            error=row["error"],
+            dedup_key=row["dedup_key"],
+        )
+
+    # ------------------------------------------------------------------
+    # Core interface
+    # ------------------------------------------------------------------
+
+    async def enqueue(
+        self,
+        job_type: str,
+        payload: Dict[str, Any],
+        *,
+        dedup_key: Optional[str] = None,
+    ) -> str:
+        with self._lock:
+            conn = self._get_conn()
+            # Dedup check
+            if dedup_key is not None:
+                row = conn.execute(
+                    "SELECT job_id FROM nat_jobs WHERE dedup_key = ? AND status IN ('pending','running','retrying') LIMIT 1",
+                    (dedup_key,),
+                ).fetchone()
+                if row is not None:
+                    return row["job_id"]
+
+            job_id = self._new_job_id()
+            now = self._now()
+            conn.execute(
+                """INSERT INTO nat_jobs
+                   (job_id, job_type, payload, status, created_at, updated_at, worker_id, attempt, error, dedup_key)
+                   VALUES (?,?,?,?,?,?,?,?,?,?)""",
+                (
+                    job_id,
+                    job_type,
+                    json.dumps(payload),
+                    "pending",
+                    now,
+                    now,
+                    None,
+                    0,
+                    None,
+                    dedup_key,
+                ),
+            )
+            return job_id
+
+    async def dequeue(self, worker_id: Optional[str] = None) -> Optional[Job]:
+        with self._lock:
+            conn = self._get_conn()
+            row = conn.execute(
+                "SELECT * FROM nat_jobs WHERE status = 'pending' ORDER BY created_at ASC LIMIT 1"
+            ).fetchone()
+            if row is None:
+                return None
+            now = self._now()
+            conn.execute(
+                "UPDATE nat_jobs SET status='running', worker_id=?, attempt=attempt+1, updated_at=? WHERE job_id=?",
+                (worker_id, now, row["job_id"]),
+            )
+            updated = conn.execute(
+                "SELECT * FROM nat_jobs WHERE job_id=?", (row["job_id"],)
+            ).fetchone()
+            return self._row_to_job(updated)
+
+    async def ack(self, job_id: str) -> None:
+        with self._lock:
+            conn = self._get_conn()
+            conn.execute(
+                "UPDATE nat_jobs SET status='completed', updated_at=? WHERE job_id=?",
+                (self._now(), job_id),
+            )
+
+    async def nack(
+        self,
+        job_id: str,
+        *,
+        error: Optional[str] = None,
+        retry: bool = False,
+        max_attempts: int = 3,
+    ) -> None:
+        with self._lock:
+            conn = self._get_conn()
+            row = conn.execute(
+                "SELECT attempt FROM nat_jobs WHERE job_id=?", (job_id,)
+            ).fetchone()
+            if row is None:
+                return
+            now = self._now()
+            if retry and row["attempt"] < max_attempts:
+                new_status = "pending"
+            else:
+                new_status = "failed"
+            conn.execute(
+                "UPDATE nat_jobs SET status=?, error=?, updated_at=? WHERE job_id=?",
+                (new_status, error, now, job_id),
+            )
+
+    async def get(self, job_id: str) -> Optional[Job]:
+        with self._lock:
+            conn = self._get_conn()
+            row = conn.execute(
+                "SELECT * FROM nat_jobs WHERE job_id=?", (job_id,)
+            ).fetchone()
+            return self._row_to_job(row) if row else None
+
+    async def list_jobs(
+        self,
+        *,
+        status: Optional[str] = None,
+        limit: int = 100,
+    ) -> List[Job]:
+        with self._lock:
+            conn = self._get_conn()
+            if status is not None:
+                rows = conn.execute(
+                    "SELECT * FROM nat_jobs WHERE status=? ORDER BY created_at DESC LIMIT ?",
+                    (status, limit),
+                ).fetchall()
+            else:
+                rows = conn.execute(
+                    "SELECT * FROM nat_jobs ORDER BY created_at DESC LIMIT ?",
+                    (limit,),
+                ).fetchall()
+            return [self._row_to_job(r) for r in rows]
+
+    async def status(self) -> QueueStats:
+        with self._lock:
+            conn = self._get_conn()
+            rows = conn.execute(
+                "SELECT status, COUNT(*) AS cnt FROM nat_jobs GROUP BY status"
+            ).fetchall()
+        stats = QueueStats()
+        for row in rows:
+            s, cnt = row["status"], int(row["cnt"])
+            if s == "pending":
+                stats.pending = cnt
+            elif s == "running":
+                stats.running = cnt
+            elif s == "completed":
+                stats.completed = cnt
+            elif s == "failed":
+                stats.failed = cnt
+            elif s == "retrying":
+                stats.retrying = cnt
+        return stats
+
+    async def purge(self, *, status: Optional[str] = None) -> int:
+        with self._lock:
+            conn = self._get_conn()
+            if status is None:
+                cur = conn.execute("DELETE FROM nat_jobs")
+            else:
+                cur = conn.execute("DELETE FROM nat_jobs WHERE status=?", (status,))
+            return cur.rowcount
+
+    def close(self) -> None:
+        """Close the underlying SQLite connection."""
+        with self._lock:
+            if self._conn is not None:
+                self._conn.close()
+                self._conn = None
+
+
+# ---------------------------------------------------------------------------
+# Redis implementation (optional — requires redis-py)
+# ---------------------------------------------------------------------------
+
+
+class RedisJobQueue(JobQueue):
+    """Distributed job queue backed by Redis.
+
+    Uses a sorted-set-based pattern for FIFO ordering and atomic Lua scripts
+    for claim/dequeue operations.
+
+    Requires ``redis`` (redis-py ≥ 4.0) to be installed.
+
+    Parameters
+    ----------
+    redis_url:
+        Redis connection URL, e.g. ``"redis://localhost:6379/0"``.
+    key_prefix:
+        Redis key namespace prefix (default: ``"nat:jobs:"``)
+    ttl_completed:
+        Seconds to retain completed/failed jobs in Redis (default: 86400 = 1 day).
+    """
+
+    def __init__(
+        self,
+        redis_url: str = "redis://localhost:6379/0",
+        key_prefix: str = "nat:jobs:",
+        ttl_completed: int = 86400,
+    ) -> None:
+        try:
+            import redis.asyncio as aioredis  # noqa: PLC0415
+        except ImportError as exc:
+            raise ImportError(
+                "RedisJobQueue requires 'redis' (redis-py ≥ 4.0). "
+                "Install it with: pip install redis"
+            ) from exc
+
+        self._url = redis_url
+        self._prefix = key_prefix
+        self._ttl = ttl_completed
+        self._redis = aioredis.from_url(redis_url, decode_responses=True)
+
+    # Key helpers
+    def _job_key(self, job_id: str) -> str:
+        return f"{self._prefix}job:{job_id}"
+
+    def _pending_key(self) -> str:
+        return f"{self._prefix}pending"
+
+    def _dedup_key(self, dk: str) -> str:
+        return f"{self._prefix}dedup:{dk}"
+
+    async def enqueue(
+        self,
+        job_type: str,
+        payload: Dict[str, Any],
+        *,
+        dedup_key: Optional[str] = None,
+    ) -> str:
+        # Dedup check
+        if dedup_key is not None:
+            existing = await self._redis.get(self._dedup_key(dedup_key))
+            if existing:
+                return existing
+
+        job_id = self._new_job_id()
+        now = self._now()
+        job = Job(
+            job_id=job_id,
+            job_type=job_type,
+            payload=payload,
+            status="pending",
+            created_at=now,
+            updated_at=now,
+            dedup_key=dedup_key,
+        )
+        pipe = self._redis.pipeline()
+        pipe.set(self._job_key(job_id), json.dumps(job.to_dict()))
+        # Score = unix timestamp for FIFO ordering
+        score = time.time()
+        pipe.zadd(self._pending_key(), {job_id: score})
+        if dedup_key is not None:
+            # Dedup key expires with a generous TTL (1 hour)
+            pipe.setex(self._dedup_key(dedup_key), 3600, job_id)
+        await pipe.execute()
+        return job_id
+
+    async def dequeue(self, worker_id: Optional[str] = None) -> Optional[Job]:
+        # Pop the lowest-score (oldest) job_id from pending set
+        result = await self._redis.zpopmin(self._pending_key(), count=1)
+        if not result:
+            return None
+        job_id, _score = result[0]
+        raw = await self._redis.get(self._job_key(job_id))
+        if raw is None:
+            return None
+        job = Job.from_dict(json.loads(raw))
+        job.status = "running"
+        job.worker_id = worker_id
+        job.attempt += 1
+        job.updated_at = self._now()
+        await self._redis.set(self._job_key(job_id), json.dumps(job.to_dict()))
+        return job
+
+    async def ack(self, job_id: str) -> None:
+        raw = await self._redis.get(self._job_key(job_id))
+        if raw is None:
+            return
+        job = Job.from_dict(json.loads(raw))
+        job.status = "completed"
+        job.updated_at = self._now()
+        pipe = self._redis.pipeline()
+        pipe.set(self._job_key(job_id), json.dumps(job.to_dict()))
+        pipe.expire(self._job_key(job_id), self._ttl)
+        await pipe.execute()
+
+    async def nack(
+        self,
+        job_id: str,
+        *,
+        error: Optional[str] = None,
+        retry: bool = False,
+        max_attempts: int = 3,
+    ) -> None:
+        raw = await self._redis.get(self._job_key(job_id))
+        if raw is None:
+            return
+        job = Job.from_dict(json.loads(raw))
+        job.error = error
+        job.updated_at = self._now()
+        if retry and job.attempt < max_attempts:
+            job.status = "pending"
+            pipe = self._redis.pipeline()
+            pipe.set(self._job_key(job_id), json.dumps(job.to_dict()))
+            pipe.zadd(self._pending_key(), {job_id: time.time()})
+            await pipe.execute()
+        else:
+            job.status = "failed"
+            pipe = self._redis.pipeline()
+            pipe.set(self._job_key(job_id), json.dumps(job.to_dict()))
+            pipe.expire(self._job_key(job_id), self._ttl)
+            await pipe.execute()
+
+    async def get(self, job_id: str) -> Optional[Job]:
+        raw = await self._redis.get(self._job_key(job_id))
+        if raw is None:
+            return None
+        return Job.from_dict(json.loads(raw))
+
+    async def list_jobs(
+        self,
+        *,
+        status: Optional[str] = None,
+        limit: int = 100,
+    ) -> List[Job]:
+        # Scan all job keys — not efficient for large queues; for production
+        # use a proper index or query the sorted set.
+        pattern = f"{self._prefix}job:*"
+        cursor = 0
+        jobs: List[Job] = []
+        while True:
+            cursor, keys = await self._redis.scan(cursor, match=pattern, count=200)
+            if keys:
+                raws = await self._redis.mget(*keys)
+                for raw in raws:
+                    if raw is not None:
+                        j = Job.from_dict(json.loads(raw))
+                        if status is None or j.status == status:
+                            jobs.append(j)
+            if cursor == 0:
+                break
+        jobs.sort(key=lambda j: j.created_at, reverse=True)
+        return jobs[:limit]
+
+    async def status(self) -> QueueStats:
+        pending_count = await self._redis.zcard(self._pending_key())
+        # For running/completed/failed, we need to scan (best-effort)
+        pattern = f"{self._prefix}job:*"
+        counts: Dict[str, int] = {"pending": 0, "running": 0, "completed": 0, "failed": 0, "retrying": 0}
+        counts["pending"] = pending_count
+        cursor = 0
+        while True:
+            cursor, keys = await self._redis.scan(cursor, match=pattern, count=500)
+            if keys:
+                raws = await self._redis.mget(*keys)
+                for raw in raws:
+                    if raw is not None:
+                        j = Job.from_dict(json.loads(raw))
+                        if j.status != "pending" and j.status in counts:
+                            counts[j.status] = counts.get(j.status, 0) + 1
+            if cursor == 0:
+                break
+        return QueueStats(
+            pending=counts["pending"],
+            running=counts["running"],
+            completed=counts["completed"],
+            failed=counts["failed"],
+            retrying=counts["retrying"],
+        )
+
+    async def purge(self, *, status: Optional[str] = None) -> int:
+        if status == "pending" or status is None:
+            await self._redis.delete(self._pending_key())
+        if status is None:
+            # Delete all job keys
+            pattern = f"{self._prefix}job:*"
+            cursor = 0
+            count = 0
+            while True:
+                cursor, keys = await self._redis.scan(cursor, match=pattern, count=200)
+                if keys:
+                    await self._redis.delete(*keys)
+                    count += len(keys)
+                if cursor == 0:
+                    break
+            return count
+        # Status-specific purge
+        jobs = await self.list_jobs(status=status)
+        for job in jobs:
+            await self._redis.delete(self._job_key(job.job_id))
+        return len(jobs)
+
+    async def close(self) -> None:
+        """Close the Redis connection."""
+        await self._redis.aclose()
+
+
+# ---------------------------------------------------------------------------
+# Factory helper
+# ---------------------------------------------------------------------------
+
+
+def create_job_queue(backend: str = "memory", **kwargs: Any) -> JobQueue:
+    """Factory function to create a :class:`JobQueue` by *backend* name.
+
+    Parameters
+    ----------
+    backend:
+        One of ``"memory"``, ``"sqlite"``, ``"redis"``.
+    **kwargs:
+        Forwarded to the concrete implementation constructor.
+    """
+    backend = backend.lower()
+    if backend == "memory":
+        return InMemoryJobQueue()
+    if backend == "sqlite":
+        return SQLiteJobQueue(**kwargs)
+    if backend == "redis":
+        return RedisJobQueue(**kwargs)
+    raise ValueError(
+        f"Unknown queue backend {backend!r}. "
+        "Choose from: 'memory', 'sqlite', 'redis'."
+    )
+
+
+# Module-level singleton — replaced by server/CLI init when configured.
+_default_queue: Optional[JobQueue] = None
+
+
+def get_default_queue() -> Optional[JobQueue]:
+    """Return the process-wide default :class:`JobQueue`, or ``None``."""
+    return _default_queue
+
+
+def set_default_queue(queue: Optional[JobQueue]) -> None:
+    """Set the process-wide default :class:`JobQueue`."""
+    global _default_queue
+    _default_queue = queue