tina4-python 3.13.40__tar.gz → 3.13.42__tar.gz

{tina4_python-3.13.40 → tina4_python-3.13.42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.13.40
+Version: 3.13.42
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT

{tina4_python-3.13.40 → tina4_python-3.13.42}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tina4-python"
-version = "3.13.40"
+version = "3.13.42"
 description = "Tina4 Python v3 — Zero-dependency, lightweight web framework"
 authors = [
     {name = "Andre van Zuydam", email = "andrevanzuydam@gmail.com"}

{tina4_python-3.13.40 → tina4_python-3.13.42}/tina4_python/CLAUDE.md

@@ -1145,9 +1145,14 @@ for job in queue.consume():
 ```python
 queue = Queue(topic="tasks", max_retries=3)
 
+# Reservation / visibility timeout (seconds): a popped job is reserved this long;
+# if the consumer dies before complete()/fail() the next pop() reclaims it
+# (at-least-once delivery). Default 300; env TINA4_QUEUE_VISIBILITY_TIMEOUT; <= 0 disables.
+queue = Queue(topic="tasks", visibility_timeout=300)
+
 # Check queue size
 queue.size()                    # pending jobs
-queue.size("reserved")          # currently processing
+queue.size("reserved")          # currently reserved (in-flight) jobs
 
 # Retry failed jobs (under max_retries limit)
 queue.retry_failed()
@@ -1159,6 +1164,14 @@ dead = queue.dead_letters()
 queue.purge("completed")
 ```
 
+**At-least-once delivery (file + MongoDB backends).** A popped job is held as a
+reservation for `visibility_timeout` seconds. If the consumer crashes, OOMs, or
+is evicted before calling `job.complete()` / `job.fail()`, the next `pop()`
+reclaims the abandoned reservation: it increments `attempts` and re-enqueues the
+job, or dead-letters it once it has hit `max_retries`. A dead consumer therefore
+never strands a job. RabbitMQ and Kafka delegate redelivery to the broker (the
+framework timeout does not apply there).
+
 ### When to use queues
 - Sending emails or SMS
 - Generating PDFs/reports
@@ -1644,6 +1657,37 @@ TINA4_SWAGGER_LICENSE=            # SPDX license name (e.g. MIT) for info.licens
 TINA4_SWAGGER_SERVERS=            # comma-separated server URLs for the OpenAPI servers[] block; falls back to SWAGGER_DEV_URL
 TINA4_SWAGGER_UI_CDN=             # base URL for the Swagger UI assets (default jsdelivr); point at a self-hosted mirror for air-gapped use
 SWAGGER_DEV_URL=http://localhost:7145  # single dev-server URL (used when TINA4_SWAGGER_SERVERS is unset)
+TINA4_SWAGGER_OPENAPI=3.0.3       # OpenAPI version: 3.0.3 (default) or 3.1 (-> emits 3.1.0)
+TINA4_SWAGGER_BEARER_FORMAT=JWT   # bearerFormat on the built-in bearerAuth scheme (e.g. opaque for sk_live_ keys)
+TINA4_SWAGGER_API_KEY_NAME=       # if set, emit an apiKeyAuth scheme with this header/query name (e.g. X-Api-Key)
+TINA4_SWAGGER_API_KEY_IN=header   # where the apiKey lives: header (default) | query | cookie
+TINA4_SWAGGER_DEFAULT_SCHEME=bearerAuth  # scheme secured routes use when no @security is set
+TINA4_SWAGGER_INCLUDE=            # comma-separated path prefixes to include (allow-list; only these documented)
+TINA4_SWAGGER_EXCLUDE=            # comma-separated path prefixes to drop (/swagger + /__dev are always excluded)
+```
+
+**Per-route security + reusable schemas (v3.13.42).** Configure named security
+schemes (configurable `bearerFormat`, an optional `apiKey` scheme, or register
+arbitrary schemes incl. `oauth2` with scopes via `Swagger.add_security_scheme(name, def)`),
+then declare them per route with `@security`:
+
+```python
+from tina4_python.swagger import security, request_schema, response_schema, Swagger
+
+@security("oauth2", scopes=["read:users"])   # scopes kept only for oauth2/openIdConnect
+@get("/api/v1/users")
+async def list_users(request, response): ...
+
+@security("public")                          # explicitly public (overrides write-secure-by-default)
+@post("/api/v1/webhook")
+async def webhook(request, response): ...
+
+# Reusable component schemas referenced by $ref (beyond ORM-model auto-schemas):
+Swagger.add_schema("CreateUser", {"type": "object", "properties": {"email": {"type": "string"}}})
+@request_schema("CreateUser")
+@response_schema("User", status=200)
+@post("/api/v1/users")
+async def create_user(request, response): ...
 ```
 
 The spec is OpenAPI 3.0.3. ORM models registered via AutoCrud become reusable

{tina4_python-3.13.40 → tina4_python-3.13.42}/tina4_python/__init__.py

@@ -8,7 +8,7 @@ Tina4 Python v3.0 — Zero-dependency, lightweight web framework.
 
 One import, everything works.
 """
-__version__ = "3.13.40"
+__version__ = "3.13.42"
 
 # ── Route decorators ──
 from tina4_python.core.router import (  # noqa: E402, F401

{tina4_python-3.13.40 → tina4_python-3.13.42}/tina4_python/queue/__init__.py

@@ -17,6 +17,10 @@ Environment variables:
     TINA4_QUEUE_BACKEND   — 'file' (default), 'rabbitmq', 'kafka', or 'mongodb'
     TINA4_QUEUE_URL       — connection URL for rabbitmq/kafka
     TINA4_QUEUE_PATH      — file backend storage path (default: data/queue)
+    TINA4_QUEUE_VISIBILITY_TIMEOUT — seconds a popped job stays reserved before
+                            a dead consumer's job is reclaimed (default 300;
+                            <= 0 disables reclaim). File + MongoDB backends only;
+                            RabbitMQ/Kafka delegate visibility to the broker.
     TINA4_RABBITMQ_HOST   — RabbitMQ host (default: localhost)
     TINA4_KAFKA_BROKERS   — Kafka brokers (default: localhost:9092)
     TINA4_MONGO_HOST      — MongoDB host (default: localhost)
@@ -24,7 +28,6 @@ Environment variables:
 import json
 import os
 import time
-import threading
 from datetime import datetime, timezone
 
 from tina4_python.queue.job import Job
@@ -34,19 +37,31 @@ from tina4_python.queue.kafka_backend import KafkaBackend
 from tina4_python.queue.mongo_backend import MongoBackend
 
 
-def _resolve_backend(topic: str, backend: str | None, max_retries: int, retry_backoff: int = 0):
+def _default_visibility_timeout() -> float:
+    """Reservation/visibility timeout in seconds, from env (default 300 = 5 min)."""
+    try:
+        return float(os.environ.get("TINA4_QUEUE_VISIBILITY_TIMEOUT", "300"))
+    except (TypeError, ValueError):
+        return 300.0
+
+
+def _resolve_backend(topic: str, backend: str | None, max_retries: int,
+                     retry_backoff: int = 0, visibility_timeout: float = 300.0):
     """Resolve which backend adapter to use."""
     chosen = backend or os.environ.get("TINA4_QUEUE_BACKEND", "file")
     chosen = chosen.lower().strip()
 
     if chosen in ("file", "default", "lite"):
-        return LiteBackend(topic, max_retries, retry_backoff)
+        return LiteBackend(topic, max_retries, retry_backoff, visibility_timeout)
     elif chosen == "rabbitmq":
+        # Broker manages visibility/redelivery (unacked messages requeue on
+        # channel close) — the framework timeout is accepted but not used.
         return RabbitMQBackend(topic, max_retries)
     elif chosen == "kafka":
+        # Consumer-group offsets manage redelivery — framework timeout N/A.
         return KafkaBackend(topic, max_retries)
     elif chosen in ("mongodb", "mongo"):
-        return MongoBackend(topic, max_retries)
+        return MongoBackend(topic, max_retries, visibility_timeout)
     else:
         raise ValueError(f"Unknown queue backend: {chosen!r}. Use 'file', 'rabbitmq', 'kafka', or 'mongodb'.")
 
@@ -63,13 +78,23 @@ class Queue:
     """
 
     def __init__(self, topic: str = "default", max_retries: int = 3,
-                 backend: str | None = None, retry_backoff: int = 0):
+                 backend: str | None = None, retry_backoff: int = 0,
+                 visibility_timeout: float | None = None):
         self.topic = topic
         self.max_retries = max_retries
         # Seconds to wait before a failed job is re-attempted (file backend).
         # Default 0 = retry on the very next pop()/consume() iteration.
         self.retry_backoff = retry_backoff
-        self._backend = _resolve_backend(topic, backend, max_retries, retry_backoff)
+        # Reservation/visibility timeout (seconds). A popped job is reserved for
+        # this long; if the consumer dies before complete()/fail() the next
+        # pop() reclaims it (at-least-once delivery). Falls back to
+        # TINA4_QUEUE_VISIBILITY_TIMEOUT, else 300 (5 min). <= 0 disables reclaim.
+        self.visibility_timeout = (
+            visibility_timeout if visibility_timeout is not None
+            else _default_visibility_timeout()
+        )
+        self._backend = _resolve_backend(topic, backend, max_retries, retry_backoff,
+                                         self.visibility_timeout)
 
     def push(self, data: dict, priority: int = 0, delay_seconds: int = 0):
         """Add a job to the queue. Returns job ID."""
@@ -211,12 +236,14 @@ class Queue:
 
         old_topic = self.topic
         self.topic = topic
-        self._backend = _resolve_backend(topic, None, self.max_retries, self.retry_backoff)
+        self._backend = _resolve_backend(topic, None, self.max_retries, self.retry_backoff,
+                                         self.visibility_timeout)
         try:
             return self.push(data, priority, delay_seconds)
         finally:
             self.topic = old_topic
-            self._backend = _resolve_backend(old_topic, None, self.max_retries, self.retry_backoff)
+            self._backend = _resolve_backend(old_topic, None, self.max_retries, self.retry_backoff,
+                                             self.visibility_timeout)
 
     def consume(self, topic: str = None, job_id: str = None, poll_interval: float = 1.0,
                 iterations: int = 0, batch_size: int = 1):
@@ -305,6 +332,9 @@ class Queue:
                     with open(filepath) as f:
                         job_data = json.load(f)
                     if job_data.get("id") == job_id and job_data.get("status") == "pending":
+                        # Reserve (so a dead consumer's job is reclaimable) then
+                        # claim the pending file — mirrors LiteBackend.pop().
+                        self._backend._write_reserved(job_data)
                         os.unlink(filepath)
                         return Job(
                             queue=self, job_id=job_data["id"],

{tina4_python-3.13.40 → tina4_python-3.13.42}/tina4_python/queue/lite_backend.py

@@ -30,13 +30,22 @@ class LiteBackend:
     Each job is stored as a separate .queue-data JSON file.
     """
 
-    def __init__(self, topic: str, max_retries: int, retry_backoff: int = 0):
+    def __init__(self, topic: str, max_retries: int, retry_backoff: int = 0,
+                 visibility_timeout: float = 300.0):
         self._topic = topic
         self._max_retries = max_retries
         # Seconds to delay a job's next attempt when it is automatically
         # re-enqueued by fail(). 0 (the default) means retry immediately —
         # the next pop()/consume() iteration picks it up straight away.
         self._retry_backoff = retry_backoff
+        # Reservation/visibility timeout (seconds). When a job is popped it is
+        # held in reserved/ with available_at = now + visibility_timeout. If the
+        # consumer dies before complete()/fail() (crash, OOM, k8s eviction), the
+        # next pop() reclaims it once the window expires — incrementing attempts
+        # and re-enqueuing, or dead-lettering past max_retries. <= 0 disables the
+        # reclaim (a reservation then lasts until the consumer acks — the old
+        # at-most-once behaviour).
+        self._visibility_timeout = visibility_timeout
         self._base_path = os.environ.get("TINA4_QUEUE_PATH", "data/queue")
         self._lock = threading.Lock()
         self._seq = 0
@@ -47,6 +56,7 @@ class LiteBackend:
         failed_dir = os.path.join(queue_dir, "failed")
         os.makedirs(queue_dir, exist_ok=True)
         os.makedirs(failed_dir, exist_ok=True)
+        os.makedirs(self._reserved_dir(), exist_ok=True)
 
     def _queue_dir(self) -> str:
         return os.path.join(self._base_path, self._topic)
@@ -54,6 +64,12 @@ class LiteBackend:
     def _failed_dir(self) -> str:
         return os.path.join(self._base_path, self._topic, "failed")
 
+    def _reserved_dir(self) -> str:
+        return os.path.join(self._base_path, self._topic, "reserved")
+
+    def _reserved_path(self, job_id: str) -> str:
+        return os.path.join(self._reserved_dir(), f"{job_id}.queue-data")
+
     def _next_prefix(self) -> str:
         self._seq += 1
         return f"{int(time.time() * 1000)}-{self._seq:06d}"
@@ -119,14 +135,92 @@ class LiteBackend:
         )
         return candidates
 
-    def pop(self, queue_ref) -> Job | None:
+    def _write_reserved(self, job_data: dict, attempts: int | None = None):
+        """Persist a reservation record so a dead consumer's job is reclaimable.
+
+        Stores reserved_at + available_at = now + visibility_timeout. The next
+        pop() reclaims this job once available_at has passed (see
+        _reclaim_expired). complete()/fail()/retry() delete the record.
+        """
         now = _now()
+        vt = self._visibility_timeout or 0
+        record = {
+            "id": job_data["id"],
+            "topic": job_data.get("topic", self._topic),
+            "data": job_data.get("data", {}),
+            "status": "reserved",
+            "priority": job_data.get("priority", 0),
+            "attempts": job_data.get("attempts", 0) if attempts is None else attempts,
+            "error": job_data.get("error"),
+            "reserved_at": now,
+            "available_at": _future(vt) if vt > 0 else now,
+            "created_at": job_data.get("created_at", now),
+        }
+        os.makedirs(self._reserved_dir(), exist_ok=True)
+        with open(self._reserved_path(record["id"]), "w") as f:
+            json.dump(record, f, indent=2, default=str)
+
+    def _reclaim_expired(self, now: str):
+        """Return expired reservations to the queue (at-least-once delivery).
+
+        A reserved job whose ``available_at <= now`` means its consumer never
+        acknowledged in time (crash / OOM / pod eviction). Increment attempts
+        and either re-enqueue it (so the next pop picks it up) or dead-letter it
+        once it has hit max_retries. Disabled when visibility_timeout <= 0.
+        """
+        if not self._visibility_timeout or self._visibility_timeout <= 0:
+            return
+        reserved_dir = self._reserved_dir()
+        try:
+            filenames = os.listdir(reserved_dir)
+        except FileNotFoundError:
+            return
+        for filename in filenames:
+            if not filename.endswith(".queue-data"):
+                continue
+            filepath = os.path.join(reserved_dir, filename)
+            try:
+                with open(filepath) as f:
+                    job_data = json.load(f)
+            except (json.JSONDecodeError, FileNotFoundError):
+                continue
+            if job_data.get("available_at", "") > now:
+                continue  # reservation still valid
+            # Atomically claim the expired reservation by deleting its file.
+            try:
+                os.unlink(filepath)
+            except FileNotFoundError:
+                continue  # another worker reclaimed it first
+            attempts = job_data.get("attempts", 0) + 1
+            error = ("reservation timed out — consumer did not acknowledge "
+                     "within the visibility timeout")
+            job = Job(
+                queue=None,
+                job_id=job_data["id"],
+                topic=job_data.get("topic", self._topic),
+                data=job_data.get("data", {}),
+                priority=job_data.get("priority", 0),
+                attempts=attempts,
+                error=error,
+            )
+            if attempts >= self._max_retries:
+                self._dead_letter(job, error)
+            else:
+                self._requeue(job, delay_seconds=0, error=error)
+
+    def pop(self, queue_ref) -> Job | None:
         queue_dir = self._queue_dir()
 
         with self._lock:
+            # First return any reservations whose consumer died mid-flight.
+            self._reclaim_expired(_now())
+            now = _now()
             for filename, job_data in self._available_candidates(now):
                 filepath = os.path.join(queue_dir, filename)
-                # Claim the job by deleting the file
+                # Write the reservation BEFORE claiming the pending file, so a
+                # crash between claim and reserve can never strand the job.
+                # Only the worker that wins the unlink owns — and returns — it.
+                self._write_reserved(job_data)
                 try:
                     os.unlink(filepath)
                 except FileNotFoundError:
@@ -149,15 +243,17 @@ class LiteBackend:
 
         Returns a partial batch if fewer than ``count`` are available.
         """
-        now = _now()
         queue_dir = self._queue_dir()
         results = []
 
         with self._lock:
+            self._reclaim_expired(_now())
+            now = _now()
             for filename, job_data in self._available_candidates(now):
                 if len(results) >= count:
                     break
                 filepath = os.path.join(queue_dir, filename)
+                self._write_reserved(job_data)
                 try:
                     os.unlink(filepath)
                 except FileNotFoundError:
@@ -180,7 +276,12 @@ class LiteBackend:
     _DEAD_STATES = ("failed", "dead", "dead_letter")
 
     def size(self, status: str = "pending") -> int:
-        scan_dir = self._failed_dir() if status in self._DEAD_STATES else self._queue_dir()
+        if status == "reserved":
+            scan_dir = self._reserved_dir()
+        elif status in self._DEAD_STATES:
+            scan_dir = self._failed_dir()
+        else:
+            scan_dir = self._queue_dir()
         count = 0
         try:
             for filename in os.listdir(scan_dir):
@@ -192,9 +293,9 @@ class LiteBackend:
                         job_data = json.load(f)
                 except (json.JSONDecodeError, FileNotFoundError):
                     continue
-                if status in self._DEAD_STATES:
-                    # Every file in failed/ is a dead-letter; count them all
-                    # regardless of the exact stored status string.
+                if status in self._DEAD_STATES or status == "reserved":
+                    # Every file in the failed/ (or reserved/) dir matches the
+                    # requested status; count them all.
                     count += 1
                 elif job_data.get("status") == status:
                     count += 1
@@ -332,25 +433,32 @@ class LiteBackend:
             return False
 
     def clear(self) -> int:
-        queue_dir = self._queue_dir()
         count = 0
+        for scan_dir in (self._queue_dir(), self._reserved_dir()):
+            try:
+                for filename in os.listdir(scan_dir):
+                    if not filename.endswith(".queue-data"):
+                        continue
+                    try:
+                        os.unlink(os.path.join(scan_dir, filename))
+                        count += 1
+                    except FileNotFoundError:
+                        continue
+            except FileNotFoundError:
+                pass
+        return count
+
+    def _clear_reservation(self, job_id: str):
+        """Delete a job's reservation record (best-effort)."""
         try:
-            for filename in os.listdir(queue_dir):
-                if not filename.endswith(".queue-data"):
-                    continue
-                try:
-                    os.unlink(os.path.join(queue_dir, filename))
-                    count += 1
-                except FileNotFoundError:
-                    continue
+            os.unlink(self._reserved_path(job_id))
         except FileNotFoundError:
             pass
-        return count
 
     def complete(self, job: Job):
-        # Job file was already deleted on pop — nothing to do. complete() is
-        # terminal: the job is done and gone.
-        pass
+        # The pending file was claimed on pop and a reservation record written;
+        # complete() is terminal, so drop the reservation. The job is done.
+        self._clear_reservation(job.id)
 
     def _requeue(self, job: Job, delay_seconds: int = 0, error: str | None = None):
         """Write the job back to the pending queue (queue dir).
@@ -405,6 +513,8 @@ class LiteBackend:
         attempted ``max_retries`` times (``attempts >= max_retries``) it is
         moved to the dead-letter store, where dead_letters() returns it.
         """
+        # Clear the reservation — the consumer acknowledged (with a failure).
+        self._clear_reservation(job.id)
         job.attempts += 1
         job.error = error
         if job.attempts < self._max_retries:
@@ -418,5 +528,6 @@ class LiteBackend:
         Always re-enqueues regardless of the retry limit — this is a manual
         override, distinct from the automatic fail() path.
         """
+        self._clear_reservation(job.id)
         job.attempts += 1
         self._requeue(job, delay_seconds=delay_seconds, error=None)

{tina4_python-3.13.40 → tina4_python-3.13.42}/tina4_python/queue/mongo_backend.py

@@ -23,11 +23,11 @@ def _future(seconds: int) -> str:
 class MongoBackend:
     """Backend adapter wrapping MongoBackend for the unified Queue API."""
 
-    def __init__(self, topic: str, max_retries: int):
+    def __init__(self, topic: str, max_retries: int, visibility_timeout: float = 300.0):
         from tina4_python.queue_backends import MongoConnector as _MongoBackend
 
         url = os.environ.get("TINA4_QUEUE_URL", "")
-        config = {}
+        config = {"visibility_timeout": visibility_timeout}
         if url:
             config["uri"] = url
         self._backend = _MongoBackend(**config)
@@ -39,6 +39,12 @@ class MongoBackend:
         return self._backend.enqueue(self._topic, msg)
 
     def pop(self, queue_ref) -> Job | None:
+        # Reclaim any reservations whose consumer died before acking, then take
+        # the next available message (at-least-once delivery).
+        try:
+            self._backend.reclaim_expired(self._topic, self._max_retries)
+        except AttributeError:
+            pass  # older connector without reclaim support
         result = self._backend.dequeue(self._topic)
         if result is None:
             return None

{tina4_python-3.13.40 → tina4_python-3.13.42}/tina4_python/queue_backends/mongo_backend.py

@@ -25,7 +25,6 @@ Document schema:
         completed_at: str | None,
     }
 """
-import json
 import os
 import uuid
 from datetime import datetime, timezone
@@ -47,6 +46,16 @@ class MongoConnector:
         self._collection_name = config.get(
             "collection", os.environ.get("TINA4_MONGO_COLLECTION", "tina4_queue")
         )
+        # Reservation/visibility timeout (seconds): a dequeued message is held
+        # reserved with available_at = now + timeout; reclaim_expired() returns
+        # it once that passes (consumer died mid-flight). <= 0 disables reclaim.
+        try:
+            self._visibility_timeout = float(config.get(
+                "visibility_timeout",
+                os.environ.get("TINA4_QUEUE_VISIBILITY_TIMEOUT", "300"),
+            ))
+        except (TypeError, ValueError):
+            self._visibility_timeout = 300.0
 
         self._pymongo = None
         self._client = None
@@ -105,7 +114,13 @@ class MongoConnector:
         return msg_id
 
     def dequeue(self, topic: str) -> dict | None:
-        """Atomically claim the next available message. Returns message dict or None."""
+        """Atomically claim the next available message. Returns message dict or None.
+
+        The claim advances ``available_at`` to ``now + visibility_timeout`` and
+        records ``reserved_at`` so reclaim_expired() can return the job if the
+        consumer dies before acknowledge()/reject(). This is the fix for the
+        "reserved forever" bug — previously available_at was left unchanged.
+        """
         self._ensure_connected()
         now = _now()
 
@@ -115,7 +130,11 @@ class MongoConnector:
                 "status": "pending",
                 "available_at": {"$lte": now},
             },
-            {"$set": {"status": "reserved"}},
+            {"$set": {
+                "status": "reserved",
+                "reserved_at": now,
+                "available_at": _future(self._visibility_timeout),
+            }},
             sort=[("priority", self._pymongo.DESCENDING), ("created_at", self._pymongo.ASCENDING)],
             return_document=self._pymongo.ReturnDocument.AFTER,
         )
@@ -126,6 +145,50 @@ class MongoConnector:
         result["id"] = doc["_id"]
         return result
 
+    def reclaim_expired(self, topic: str, max_retries: int) -> int:
+        """Return reservations whose visibility window expired (at-least-once).
+
+        A message left ``reserved`` with ``available_at <= now`` had a consumer
+        die before acknowledging. Each is atomically flipped back to ``pending``
+        with ``attempts`` incremented (so the next dequeue re-delivers it); once
+        ``attempts >= max_retries`` it is dead-lettered instead. Returns the
+        number reclaimed. Disabled when visibility_timeout <= 0.
+        """
+        if not self._visibility_timeout or self._visibility_timeout <= 0:
+            return 0
+        self._ensure_connected()
+        reclaimed = 0
+        while True:
+            now = _now()
+            doc = self._collection.find_one_and_update(
+                {
+                    "topic": topic,
+                    "status": "reserved",
+                    "available_at": {"$lte": now},
+                },
+                {"$set": {"status": "pending", "available_at": now, "reserved_at": None},
+                 "$inc": {"attempts": 1}},
+                sort=[("available_at", self._pymongo.ASCENDING)],
+                return_document=self._pymongo.ReturnDocument.AFTER,
+            )
+            if doc is None:
+                break
+            reclaimed += 1
+            if doc.get("attempts", 0) >= max_retries:
+                # Out of retries — move it to the dead-letter queue and remove
+                # the original so it is not re-delivered.
+                payload = doc.get("data", {})
+                self.dead_letter(topic, {
+                    "id": doc["_id"],
+                    "payload": payload,
+                    "priority": doc.get("priority", 0),
+                    "attempts": doc.get("attempts", 0),
+                    "error": "reservation timed out — consumer did not "
+                             "acknowledge within the visibility timeout",
+                })
+                self._collection.delete_one({"_id": doc["_id"], "topic": topic})
+        return reclaimed
+
     def acknowledge(self, topic: str, message_id: str):
         """Acknowledge a message as processed."""
         self._ensure_connected()
@@ -211,5 +274,10 @@ class MongoConnector:
 def _now() -> str:
     return datetime.now(timezone.utc).isoformat()
 
+
+def _future(seconds: float) -> str:
+    import time
+    return datetime.fromtimestamp(time.time() + seconds, tz=timezone.utc).isoformat()
+
 # Backwards-compatible alias — external code and tests may use the old name.
 MongoBackend = MongoConnector