taskqueue-toolkit 0.1.0__tar.gz → 0.2.0__tar.gz

{taskqueue_toolkit-0.1.0 → taskqueue_toolkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskqueue-toolkit
-Version: 0.1.0
+Version: 0.2.0
 Summary: Broker-agnostic async task queue (RabbitMQ, SQS, SNS, Redis Streams, Pub/Sub) with a Postgres outbox pattern
 Author: Walid Boughdiri
 Author-email: Walid Boughdiri <walid.boughdiri@gmail.com>
@@ -152,6 +152,12 @@ Each adapter constructor takes an injectable client/connection factory for exact
 
 Create one broker instance per test — each owns its own isolated in-memory state, so there's nothing to reset between tests and no risk of one test's queue leaking into another's.
 
+## Security
+
+`Decoder[T]` runs on bytes received from a broker — in most deployments, a source outside this process's control. Using an unsafe deserializer (`pickle.loads`, `yaml.load` without `SafeLoader`, `eval`, ...) as your `decode` callback means whoever can publish to your queue/topic can run arbitrary code in your consumer. Use a safe format (JSON, msgpack, protobuf, ...) unless every publisher is fully trusted.
+
+This package's own code is checked on every push/PR and before every release via [bandit](https://bandit.readthedocs.io/) (unsafe code patterns) and [pip-audit](https://github.com/pypa/pip-audit) (known CVEs in resolved dependencies), alongside ruff, mypy, and the test suite. Found a vulnerability? Please open an issue.
+
 ## Development
 
 ```bash
@@ -160,4 +166,6 @@ uv run pytest
 uv run ruff check .
 uv run ruff format .
 uv run mypy .
+uvx bandit -r src/
+uvx pip-audit --path .venv
 ```

{taskqueue_toolkit-0.1.0 → taskqueue_toolkit-0.2.0}/README.md

@@ -117,6 +117,12 @@ Each adapter constructor takes an injectable client/connection factory for exact
 
 Create one broker instance per test — each owns its own isolated in-memory state, so there's nothing to reset between tests and no risk of one test's queue leaking into another's.
 
+## Security
+
+`Decoder[T]` runs on bytes received from a broker — in most deployments, a source outside this process's control. Using an unsafe deserializer (`pickle.loads`, `yaml.load` without `SafeLoader`, `eval`, ...) as your `decode` callback means whoever can publish to your queue/topic can run arbitrary code in your consumer. Use a safe format (JSON, msgpack, protobuf, ...) unless every publisher is fully trusted.
+
+This package's own code is checked on every push/PR and before every release via [bandit](https://bandit.readthedocs.io/) (unsafe code patterns) and [pip-audit](https://github.com/pypa/pip-audit) (known CVEs in resolved dependencies), alongside ruff, mypy, and the test suite. Found a vulnerability? Please open an issue.
+
 ## Development
 
 ```bash
@@ -125,4 +131,6 @@ uv run pytest
 uv run ruff check .
 uv run ruff format .
 uv run mypy .
+uvx bandit -r src/
+uvx pip-audit --path .venv
 ```

{taskqueue_toolkit-0.1.0 → taskqueue_toolkit-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "taskqueue-toolkit"
-version = "0.1.0"
+version = "0.2.0"
 description = "Broker-agnostic async task queue (RabbitMQ, SQS, SNS, Redis Streams, Pub/Sub) with a Postgres outbox pattern"
 readme = "README.md"
 license = "Apache-2.0"

{taskqueue_toolkit-0.1.0 → taskqueue_toolkit-0.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "taskqueue-toolkit"
-version = "0.1.0"
+version = "0.2.0"
 description = "Broker-agnostic async task queue (RabbitMQ, SQS, SNS, Redis Streams, Pub/Sub) with a Postgres outbox pattern"
 readme = "README.md"
 license = "Apache-2.0"

{taskqueue_toolkit-0.1.0 → taskqueue_toolkit-0.2.0}/src/taskqueue_toolkit/queue/pubsub.py

@@ -26,6 +26,7 @@ class PubsubQueuedTask[T]:
     _subscriber: pubsub_v1.SubscriberClient
     _subscription_path: str
     _ack_id: str
+    delivery_count: int
     task: T
 
     async def ack(self) -> None:
@@ -154,9 +155,16 @@ class PubsubTaskQueue[T]:
                 timeout=_PULL_TIMEOUT_SECONDS,
             )
             for received in response.received_messages:
+                # delivery_attempt is only populated when the subscription
+                # has a dead-letter policy configured — absent (None)
+                # otherwise, in which case this reports 1 rather than
+                # silently misreporting every message as never-redelivered
+                # forever.
+                delivery_count = received.delivery_attempt or 1
                 yield PubsubQueuedTask(
                     _subscriber=self._subscriber,
                     _subscription_path=subscription_path,
                     _ack_id=received.ack_id,
+                    delivery_count=delivery_count,
                     task=self.decode(received.message.data),
                 )

{taskqueue_toolkit-0.1.0 → taskqueue_toolkit-0.2.0}/src/taskqueue_toolkit/queue/rabbitmq.py

@@ -6,6 +6,7 @@ from contextlib import suppress
 from dataclasses import dataclass, field
 
 import aio_pika
+from pamqp.common import FieldTable
 
 from taskqueue_toolkit.queue.dsn import RabbitMqDsn
 from taskqueue_toolkit.queue.task_queue import Decoder, Encoder
@@ -15,11 +16,33 @@ logger = logging.getLogger(__name__)
 Connect = Callable[[str], Awaitable["aio_pika.abc.AbstractRobustConnection"]]
 
 
+def _delivery_count(message: aio_pika.abc.AbstractIncomingMessage) -> int:
+    """1 on first delivery, incremented on every redelivery (a
+    nack(requeue=True), a crashed/disconnected consumer, ...). Sourced from
+    x-delivery-count, which RabbitMQ maintains natively for quorum queues —
+    see the queue declaration in RabbitMqTaskQueue for why the queue type
+    matters here (classic queues don't track this at all; only a
+    dead-letter hop shows up there, via x-death, which a plain requeue never
+    triggers)."""
+    headers = message.headers or {}
+    count = headers.get("x-delivery-count")
+    if count is None:
+        return 1
+    # RabbitMQ always sends this header as a long-int field value — the
+    # broad FieldValue union is what the type carries at rest, not what
+    # actually arrives here.
+    return 1 + int(count)  # type: ignore[arg-type]
+
+
 @dataclass(slots=True)
 class RabbitMqQueuedTask[T]:
     _message: aio_pika.abc.AbstractIncomingMessage
     task: T
 
+    @property
+    def delivery_count(self) -> int:
+        return _delivery_count(self._message)
+
     async def ack(self) -> None:
         await self._message.ack()
 
@@ -36,11 +59,22 @@ class RabbitMqTaskQueue[T]:
     # connection strategy the caller already has; defaults to the real SDK.
     connect: Connect = field(default=aio_pika.connect_robust)
 
+    def _queue_arguments(self) -> FieldTable:
+        # Quorum queues (not RabbitMQ's classic queue type) are what expose
+        # x-delivery-count on redelivery — a classic queue tracks no such
+        # counter at all, so delivery_count would always read 1. This is
+        # also RabbitMQ's own recommended queue type for task-queue-style
+        # workloads (durable, replicated, no classic-queue mirroring), so
+        # this isn't a special case adopted only for the counter.
+        return {"x-queue-type": "quorum"}
+
     async def publish(self, task: T) -> None:
         connection = await self.connect(self.dsn.url)
         try:
             channel = await connection.channel()
-            queue = await channel.declare_queue(self.dsn.queue_name, durable=True)
+            queue = await channel.declare_queue(
+                self.dsn.queue_name, durable=True, arguments=self._queue_arguments()
+            )
             await channel.default_exchange.publish(
                 aio_pika.Message(
                     body=self.encode(task),
@@ -57,7 +91,9 @@ class RabbitMqTaskQueue[T]:
         try:
             channel = await connection.channel()
             await channel.set_qos(prefetch_count=1)
-            queue = await channel.declare_queue(self.dsn.queue_name, durable=True)
+            queue = await channel.declare_queue(
+                self.dsn.queue_name, durable=True, arguments=self._queue_arguments()
+            )
 
             async for message in queue.iterator():
                 yield RabbitMqQueuedTask(_message=message, task=self.decode(message.body))

{taskqueue_toolkit-0.1.0 → taskqueue_toolkit-0.2.0}/src/taskqueue_toolkit/queue/redis_streams.py

@@ -29,6 +29,7 @@ class RedisStreamsQueuedTask[T]:
     _stream: str
     _group: str
     _message_id: str
+    delivery_count: int
     task: T
 
     async def ack(self) -> None:
@@ -61,6 +62,20 @@ class RedisStreamsTaskQueue[T]:
     def _client(self) -> redis.Redis:
         return self.client_factory(self.dsn)
 
+    async def _delivery_count(
+        self, client: redis.Redis, stream: str, group: str, message_id: bytes
+    ) -> int:
+        entries = await client.xpending_range(
+            name=stream, groupname=group, min=message_id, max=message_id, count=1
+        )
+        if not entries:
+            # Already ack'd/claimed away between xreadgroup and this lookup
+            # — vanishingly unlikely for our single-consumer-per-group
+            # usage, but "never delivered before" (1) is the only sane
+            # fallback rather than raising.
+            return 1
+        return int(entries[0]["times_delivered"])
+
     async def _ensure_group(self, client: redis.Redis) -> None:
         try:
             await client.xgroup_create(self.dsn.stream_name, self.dsn.group, id="0", mkstream=True)
@@ -106,11 +121,18 @@ class RedisStreamsTaskQueue[T]:
                     )
                     for _stream_name, messages in response:
                         for message_id, fields in messages:
+                            # xreadgroup itself never reports a delivery
+                            # count — it's only visible via XPENDING, so
+                            # this is a second round trip per message.
+                            delivery_count = await self._delivery_count(
+                                client, stream, group, message_id
+                            )
                             yield RedisStreamsQueuedTask(
                                 _redis=client,
                                 _stream=stream,
                                 _group=group,
                                 _message_id=message_id.decode(),
+                                delivery_count=delivery_count,
                                 task=self.decode(fields[_FIELD.encode()]),
                             )
         finally:

{taskqueue_toolkit-0.1.0 → taskqueue_toolkit-0.2.0}/src/taskqueue_toolkit/queue/sns.py

@@ -6,10 +6,13 @@ import logging
 from collections.abc import AsyncIterator, Callable
 from contextlib import AbstractAsyncContextManager, asynccontextmanager
 from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
 
 import aioboto3
-from types_aiobotocore_sns.client import SNSClient
-from types_aiobotocore_sqs.client import SQSClient
+
+if TYPE_CHECKING:
+    from types_aiobotocore_sns.client import SNSClient
+    from types_aiobotocore_sqs.client import SQSClient
 
 from taskqueue_toolkit.queue.aws_session import aws_session_kwargs
 from taskqueue_toolkit.queue.dsn import SnsDsn
@@ -20,7 +23,7 @@ logger = logging.getLogger(__name__)
 _LONG_POLL_WAIT_SECONDS = 10
 _SUBSCRIBER_QUEUE_SUFFIX = "-subscriber"
 
-ClientFactory = Callable[[SnsDsn], AbstractAsyncContextManager[tuple[SNSClient, SQSClient]]]
+ClientFactory = Callable[[SnsDsn], AbstractAsyncContextManager["tuple[SNSClient, SQSClient]"]]
 
 
 @asynccontextmanager
@@ -62,6 +65,7 @@ class SnsQueuedTask[T]:
     _client: SQSClient
     _queue_url: str
     _receipt_handle: str
+    delivery_count: int
     task: T
 
     async def ack(self) -> None:
@@ -151,12 +155,21 @@ class SnsTaskQueue[T]:
                     QueueUrl=queue_url,
                     MaxNumberOfMessages=1,
                     WaitTimeSeconds=_LONG_POLL_WAIT_SECONDS,
+                    # Not returned unless asked for explicitly — this is the
+                    # source for delivery_count below. SNS fan-out delivers
+                    # into a plain SQS subscriber queue, so the same
+                    # attribute SqsTaskQueue reads applies here too.
+                    AttributeNames=["ApproximateReceiveCount"],
                 )
                 for message in response.get("Messages", []):
+                    receive_count = int(
+                        message.get("Attributes", {}).get("ApproximateReceiveCount", "1")
+                    )
                     envelope = _unwrap_sns_envelope(message["Body"])
                     yield SnsQueuedTask(
                         _client=sqs,
                         _queue_url=queue_url,
                         _receipt_handle=message["ReceiptHandle"],
+                        delivery_count=receive_count,
                         task=self.decode(base64.b64decode(envelope)),
                     )

{taskqueue_toolkit-0.1.0 → taskqueue_toolkit-0.2.0}/src/taskqueue_toolkit/queue/sqs.py

@@ -5,10 +5,12 @@ import logging
 from collections.abc import AsyncIterator, Callable
 from contextlib import AbstractAsyncContextManager
 from dataclasses import dataclass, field
-from typing import cast
+from typing import TYPE_CHECKING, cast
 
 import aioboto3
-from types_aiobotocore_sqs.client import SQSClient
+
+if TYPE_CHECKING:
+    from types_aiobotocore_sqs.client import SQSClient
 
 from taskqueue_toolkit.queue.aws_session import aws_session_kwargs
 from taskqueue_toolkit.queue.dsn import SqsDsn
@@ -18,7 +20,7 @@ logger = logging.getLogger(__name__)
 
 _LONG_POLL_WAIT_SECONDS = 10
 
-ClientFactory = Callable[[SqsDsn], AbstractAsyncContextManager[SQSClient]]
+ClientFactory = Callable[[SqsDsn], AbstractAsyncContextManager["SQSClient"]]
 
 
 def _default_client_factory(dsn: SqsDsn) -> AbstractAsyncContextManager[SQSClient]:
@@ -33,6 +35,7 @@ class SqsQueuedTask[T]:
     _client: SQSClient
     _queue_url: str
     _receipt_handle: str
+    delivery_count: int
     task: T
 
     async def ack(self) -> None:
@@ -93,11 +96,18 @@ class SqsTaskQueue[T]:
                     QueueUrl=queue_url,
                     MaxNumberOfMessages=1,
                     WaitTimeSeconds=_LONG_POLL_WAIT_SECONDS,
+                    # Not returned unless asked for explicitly — this is the
+                    # source for delivery_count below.
+                    AttributeNames=["ApproximateReceiveCount"],
                 )
                 for message in response.get("Messages", []):
+                    receive_count = int(
+                        message.get("Attributes", {}).get("ApproximateReceiveCount", "1")
+                    )
                     yield SqsQueuedTask(
                         _client=client,
                         _queue_url=queue_url,
                         _receipt_handle=message["ReceiptHandle"],
+                        delivery_count=receive_count,
                         task=self.decode(base64.b64decode(message["Body"])),
                     )

{taskqueue_toolkit-0.1.0 → taskqueue_toolkit-0.2.0}/src/taskqueue_toolkit/queue/task_queue.py

@@ -7,6 +7,12 @@ T = TypeVar("T")
 T_co = TypeVar("T_co", covariant=True)
 
 Encoder = Callable[[T], bytes]
+# SECURITY: Decoder runs on bytes received from a broker — a source outside
+# this process's control in most deployments. Using an unsafe deserializer
+# here (pickle.loads, yaml.load without SafeLoader, eval, ...) turns
+# whoever can publish to your queue/topic into someone who can run
+# arbitrary code in your consumer. Prefer a safe format (json, msgpack,
+# protobuf) unless every publisher is fully trusted.
 Decoder = Callable[[bytes], T]
 
 
@@ -22,6 +28,20 @@ class QueuedTask(Protocol[T_co]):
     @property
     def task(self) -> T_co: ...
 
+    @property
+    def delivery_count(self) -> int:
+        """How many times this message has been delivered, including the
+        current delivery — 1 the first time a consumer sees it, 2 after one
+        requeue, and so on. Sourced from each broker's own native counter
+        (RabbitMQ's x-death header behind a dead-letter-to-self queue, SQS's
+        ApproximateReceiveCount, Pub/Sub's delivery_attempt, Redis Streams'
+        pending-entry delivery count) rather than tracked by this package —
+        a consumer that wants to give up after N attempts reads this and
+        calls nack(requeue=False) itself; this package has no opinion on
+        what N should be, that's a decision about the task's own business
+        cost of retrying, not a queueing concern."""
+        ...
+
     async def ack(self) -> None:
         """Mark the task as successfully processed."""
         ...

{taskqueue_toolkit-0.1.0 → taskqueue_toolkit-0.2.0}/src/taskqueue_toolkit/testing/pubsub.py

@@ -40,6 +40,7 @@ class _Message(NamedTuple):
 class _ReceivedMessage(NamedTuple):
     ack_id: str
     message: _Message
+    delivery_attempt: int
 
 
 class _PullResponse(NamedTuple):
@@ -54,11 +55,20 @@ class _PublishFuture:
         return self._message_id
 
 
+@dataclass(slots=True)
+class _Envelope:
+    """A message plus its own delivery attempt count — mirrors Pub/Sub's
+    delivery_attempt (1 on first delivery, incremented on each redelivery)."""
+
+    data: bytes
+    delivery_attempt: int = 0
+
+
 @dataclass(slots=True)
 class _Subscription:
     topic_path: str
-    pending: deque[bytes] = field(default_factory=deque)
-    in_flight: dict[str, bytes] = field(default_factory=dict)
+    pending: deque[_Envelope] = field(default_factory=deque)
+    in_flight: dict[str, _Envelope] = field(default_factory=dict)
 
 
 @dataclass(slots=True)
@@ -79,7 +89,7 @@ class _FakePublisherClient:
     def publish(self, topic_path: str, data: bytes) -> _PublishFuture:
         for sub in self._broker._subscriptions.values():
             if sub.topic_path == topic_path:
-                sub.pending.append(data)
+                sub.pending.append(_Envelope(data=data))
         return _PublishFuture(str(uuid.uuid4()))
 
 
@@ -108,10 +118,17 @@ class _FakeSubscriberClient:
         )
         received = []
         for _ in range(min(max_messages, len(sub.pending))):
-            data = sub.pending.popleft()
+            envelope = sub.pending.popleft()
+            envelope.delivery_attempt += 1
             ack_id = str(uuid.uuid4())
-            sub.in_flight[ack_id] = data
-            received.append(_ReceivedMessage(ack_id=ack_id, message=_Message(data=data)))
+            sub.in_flight[ack_id] = envelope
+            received.append(
+                _ReceivedMessage(
+                    ack_id=ack_id,
+                    message=_Message(data=envelope.data),
+                    delivery_attempt=envelope.delivery_attempt,
+                )
+            )
         return _PullResponse(received_messages=received)
 
     def acknowledge(self, *, subscription: str, ack_ids: list[str]) -> None:
@@ -128,9 +145,9 @@ class _FakeSubscriberClient:
         if sub is None:
             return
         for ack_id in ack_ids:
-            data = sub.in_flight.pop(ack_id, None)
-            if data is not None and ack_deadline_seconds == 0:
-                sub.pending.appendleft(data)
+            envelope = sub.in_flight.pop(ack_id, None)
+            if envelope is not None and ack_deadline_seconds == 0:
+                sub.pending.appendleft(envelope)
 
 
 @dataclass(slots=True)

{taskqueue_toolkit-0.1.0 → taskqueue_toolkit-0.2.0}/src/taskqueue_toolkit/testing/rabbitmq.py

@@ -19,22 +19,34 @@ from dataclasses import dataclass, field
 __all__ = ["FakeRabbitMqBroker"]
 
 
+@dataclass(slots=True)
+class _Envelope:
+    """A message plus its own redelivery count — tracked per in-flight copy
+    of the message, not by content, so two messages with identical bodies
+    (or the same message redelivered many times) each carry their own
+    count."""
+
+    body: bytes
+    delivery_count: int = 0
+
+
 @dataclass(slots=True)
 class _Queue:
     """One named queue's backlog plus messages currently delivered but not
     yet ack()'d/nack()'d — mirrors a real broker's per-queue state."""
 
-    pending: deque[bytes] = field(default_factory=deque)
-    unacked: dict[int, bytes] = field(default_factory=dict)
+    pending: deque[_Envelope] = field(default_factory=deque)
+    unacked: dict[int, _Envelope] = field(default_factory=dict)
     _next_id: int = 0
 
     def push(self, body: bytes) -> None:
-        self.pending.append(body)
+        self.pending.append(_Envelope(body=body))
 
     def requeue(self, delivery_id: int) -> None:
-        body = self.unacked.pop(delivery_id, None)
-        if body is not None:
-            self.pending.appendleft(body)
+        envelope = self.unacked.pop(delivery_id, None)
+        if envelope is not None:
+            envelope.delivery_count += 1
+            self.pending.appendleft(envelope)
 
     def drop(self, delivery_id: int) -> None:
         self.unacked.pop(delivery_id, None)
@@ -47,6 +59,7 @@ class _Queue:
 @dataclass(slots=True)
 class _FakeIncomingMessage:
     body: bytes
+    headers: dict[str, int]
     _delivery_id: int
     _queue: _Queue
 
@@ -74,10 +87,19 @@ class _FakeAioPikaQueue:
     async def __anext__(self) -> _FakeIncomingMessage:
         while not self._queue.pending:
             await asyncio.sleep(0)
-        body = self._queue.pending.popleft()
+        envelope = self._queue.pending.popleft()
         delivery_id = self._queue.next_delivery_id()
-        self._queue.unacked[delivery_id] = body
-        return _FakeIncomingMessage(body=body, _delivery_id=delivery_id, _queue=self._queue)
+        self._queue.unacked[delivery_id] = envelope
+        # Mirrors a real quorum queue's x-delivery-count: absent (no header)
+        # on first delivery, present from the first redelivery onward — see
+        # RabbitMqTaskQueue's _delivery_count(), which reads this as
+        # "1 + count" so a never-redelivered message still reports 1.
+        headers = (
+            {} if envelope.delivery_count == 0 else {"x-delivery-count": envelope.delivery_count}
+        )
+        return _FakeIncomingMessage(
+            body=envelope.body, headers=headers, _delivery_id=delivery_id, _queue=self._queue
+        )
 
 
 @dataclass(slots=True)
@@ -100,7 +122,9 @@ class _FakeChannel:
     async def set_qos(self, *, prefetch_count: int) -> None:
         return None
 
-    async def declare_queue(self, name: str, *, durable: bool = True) -> _FakeAioPikaQueue:
+    async def declare_queue(
+        self, name: str, *, durable: bool = True, arguments: dict[str, str] | None = None
+    ) -> _FakeAioPikaQueue:
         queue = self._broker._queue_for(name)
         self.default_exchange = _FakeExchange(_queue=queue)
         return _FakeAioPikaQueue(name=name, _queue=queue)

{taskqueue_toolkit-0.1.0 → taskqueue_toolkit-0.2.0}/src/taskqueue_toolkit/testing/redis_streams.py

@@ -32,6 +32,10 @@ class _Group:
     # (a real broker's Pending Entries List) — nack(requeue=True) leaves an
     # entry here; xreadgroup's "0" branch redelivers from here first.
     pending_entries: list[tuple[bytes, dict[bytes, bytes]]] = field(default_factory=list)
+    # Mirrors a real group's per-entry times_delivered (visible via
+    # XPENDING) — 0 before the entry's first delivery, matching a real
+    # broker where a never-yet-read entry isn't in the PEL at all.
+    times_delivered: dict[bytes, int] = field(default_factory=dict)
 
 
 @dataclass(slots=True)
@@ -89,6 +93,8 @@ class _FakeRedisClient:
             # per-group, matching this package's single-consumer-per-group
             # usage pattern.
             delivered = grp.pending_entries[: count or len(grp.pending_entries)]
+            for entry_id, _fields in delivered:
+                grp.times_delivered[entry_id] = grp.times_delivered.get(entry_id, 0) + 1
             return [(name.encode(), delivered)]
 
         # ">" branch: deliver new entries the group hasn't seen yet.
@@ -97,6 +103,8 @@ class _FakeRedisClient:
         if new_entries:
             stream.cursor[group_key] = cursor + len(new_entries)
             grp.pending_entries.extend(new_entries)
+            for entry_id, _fields in new_entries:
+                grp.times_delivered[entry_id] = grp.times_delivered.get(entry_id, 0) + 1
             return [(name.encode(), new_entries)]
 
         # Nothing new — a real broker blocks up to `block` ms; the fake
@@ -113,8 +121,28 @@ class _FakeRedisClient:
         ids = set(entry_ids)
         before = len(grp.pending_entries)
         grp.pending_entries = [e for e in grp.pending_entries if e[0] not in ids]
+        for entry_id in ids:
+            grp.times_delivered.pop(entry_id, None)
         return before - len(grp.pending_entries)
 
+    async def xpending_range(
+        self,
+        name: str,
+        groupname: str,
+        min: bytes,
+        max: bytes,
+        count: int,
+        consumername: str | None = None,
+    ) -> list[dict[str, object]]:
+        stream = self._broker._stream_for(name.encode())
+        grp = stream.groups.get(groupname.encode())
+        if grp is None:
+            return []
+        times_delivered = grp.times_delivered.get(min)
+        if times_delivered is None:
+            return []
+        return [{"message_id": min, "times_delivered": times_delivered}]
+
     async def delete(self, *names: str) -> int:
         count = 0
         for name in names:

{taskqueue_toolkit-0.1.0 → taskqueue_toolkit-0.2.0}/src/taskqueue_toolkit/testing/sns.py

@@ -37,10 +37,19 @@ class _Exceptions:
     QueueDoesNotExist: type[Exception] = QueueDoesNotExist
 
 
+@dataclass(slots=True)
+class _Envelope:
+    """A message plus its own receive count — mirrors SQS's
+    ApproximateReceiveCount on the subscriber queue behind the topic."""
+
+    body: str
+    receive_count: int = 0
+
+
 @dataclass(slots=True)
 class _Queue:
-    pending: deque[dict[str, str]] = field(default_factory=deque)
-    in_flight: dict[str, dict[str, str]] = field(default_factory=dict)
+    pending: deque[_Envelope] = field(default_factory=deque)
+    in_flight: dict[str, _Envelope] = field(default_factory=dict)
 
 
 def _topic_arn(name: str) -> str:
@@ -74,7 +83,7 @@ class _FakeSnsClient:
         )
         for queue_url in self._broker._topics.get(TopicArn, set()):
             queue = self._broker._queues.setdefault(queue_url, _Queue())
-            queue.pending.append({"Body": envelope})
+            queue.pending.append(_Envelope(body=envelope))
         return {"MessageId": str(uuid.uuid4())}
 
 
@@ -105,15 +114,27 @@ class _FakeSqsClient:
         return None
 
     async def receive_message(
-        self, *, QueueUrl: str, MaxNumberOfMessages: int = 1, WaitTimeSeconds: int = 0
-    ) -> dict[str, list[dict[str, str]]]:
+        self,
+        *,
+        QueueUrl: str,
+        MaxNumberOfMessages: int = 1,
+        WaitTimeSeconds: int = 0,
+        AttributeNames: list[str] | None = None,
+    ) -> dict[str, list[dict[str, object]]]:
         queue = self._broker._queues.setdefault(QueueUrl, _Queue())
         messages = []
         for _ in range(min(MaxNumberOfMessages, len(queue.pending))):
-            body = queue.pending.popleft()
+            envelope = queue.pending.popleft()
+            envelope.receive_count += 1
             receipt_handle = str(uuid.uuid4())
-            queue.in_flight[receipt_handle] = body
-            messages.append({"Body": body["Body"], "ReceiptHandle": receipt_handle})
+            queue.in_flight[receipt_handle] = envelope
+            message: dict[str, object] = {
+                "Body": envelope.body,
+                "ReceiptHandle": receipt_handle,
+            }
+            if AttributeNames and "ApproximateReceiveCount" in AttributeNames:
+                message["Attributes"] = {"ApproximateReceiveCount": str(envelope.receive_count)}
+            messages.append(message)
         return {"Messages": messages}
 
     async def delete_message(self, *, QueueUrl: str, ReceiptHandle: str) -> None:
@@ -124,9 +145,9 @@ class _FakeSqsClient:
         self, *, QueueUrl: str, ReceiptHandle: str, VisibilityTimeout: int
     ) -> None:
         queue = self._broker._queues.setdefault(QueueUrl, _Queue())
-        body = queue.in_flight.pop(ReceiptHandle, None)
-        if body is not None and VisibilityTimeout == 0:
-            queue.pending.appendleft(body)
+        envelope = queue.in_flight.pop(ReceiptHandle, None)
+        if envelope is not None and VisibilityTimeout == 0:
+            queue.pending.appendleft(envelope)
 
 
 class _FakeSnsContext(AbstractAsyncContextManager[tuple["_FakeSnsClient", "_FakeSqsClient"]]):

{taskqueue_toolkit-0.1.0 → taskqueue_toolkit-0.2.0}/src/taskqueue_toolkit/testing/sqs.py

@@ -33,10 +33,20 @@ class _Exceptions:
     QueueDoesNotExist: type[Exception] = QueueDoesNotExist
 
 
+@dataclass(slots=True)
+class _Envelope:
+    """A message plus its own receive count — tracked per in-flight copy of
+    the message, mirroring SQS's ApproximateReceiveCount (1 on first
+    receive, incremented on each redelivery)."""
+
+    body: str
+    receive_count: int = 0
+
+
 @dataclass(slots=True)
 class _Queue:
-    pending: deque[dict[str, str]] = field(default_factory=deque)
-    in_flight: dict[str, dict[str, str]] = field(default_factory=dict)
+    pending: deque[_Envelope] = field(default_factory=deque)
+    in_flight: dict[str, _Envelope] = field(default_factory=dict)
 
 
 @dataclass(slots=True)
@@ -58,19 +68,31 @@ class _FakeSqsClient:
 
     async def send_message(self, *, QueueUrl: str, MessageBody: str) -> dict[str, str]:
         queue = self._broker._queues.setdefault(QueueUrl, _Queue())
-        queue.pending.append({"Body": MessageBody})
+        queue.pending.append(_Envelope(body=MessageBody))
         return {"MessageId": str(uuid.uuid4())}
 
     async def receive_message(
-        self, *, QueueUrl: str, MaxNumberOfMessages: int = 1, WaitTimeSeconds: int = 0
-    ) -> dict[str, list[dict[str, str]]]:
+        self,
+        *,
+        QueueUrl: str,
+        MaxNumberOfMessages: int = 1,
+        WaitTimeSeconds: int = 0,
+        AttributeNames: list[str] | None = None,
+    ) -> dict[str, list[dict[str, object]]]:
         queue = self._broker._queues.setdefault(QueueUrl, _Queue())
         messages = []
         for _ in range(min(MaxNumberOfMessages, len(queue.pending))):
-            body = queue.pending.popleft()
+            envelope = queue.pending.popleft()
+            envelope.receive_count += 1
             receipt_handle = str(uuid.uuid4())
-            queue.in_flight[receipt_handle] = body
-            messages.append({"Body": body["Body"], "ReceiptHandle": receipt_handle})
+            queue.in_flight[receipt_handle] = envelope
+            message: dict[str, object] = {
+                "Body": envelope.body,
+                "ReceiptHandle": receipt_handle,
+            }
+            if AttributeNames and "ApproximateReceiveCount" in AttributeNames:
+                message["Attributes"] = {"ApproximateReceiveCount": str(envelope.receive_count)}
+            messages.append(message)
         return {"Messages": messages}
 
     async def delete_message(self, *, QueueUrl: str, ReceiptHandle: str) -> None:
@@ -81,9 +103,9 @@ class _FakeSqsClient:
         self, *, QueueUrl: str, ReceiptHandle: str, VisibilityTimeout: int
     ) -> None:
         queue = self._broker._queues.setdefault(QueueUrl, _Queue())
-        body = queue.in_flight.pop(ReceiptHandle, None)
-        if body is not None and VisibilityTimeout == 0:
-            queue.pending.appendleft(body)
+        envelope = queue.in_flight.pop(ReceiptHandle, None)
+        if envelope is not None and VisibilityTimeout == 0:
+            queue.pending.appendleft(envelope)
 
 
 class _FakeClientContext(AbstractAsyncContextManager["_FakeSqsClient"]):