taskqueue-toolkit 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

taskqueue_toolkit/queue/delivery.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+FIRST_DELIVERY = 1
+"""QueuedTask.delivery_count for a message being seen for the first time.
+
+The protocol counts deliveries starting at 1, so this is both the floor and
+the value to fall back on whenever a broker's own counter is missing or
+unreadable — see QueuedTask.delivery_count.
+"""
+
+
+def delivery_count_from(raw: object, *, counts_redeliveries: bool = False) -> int:
+    """Normalize a broker's own counter onto the protocol's convention.
+
+    Brokers disagree on what they count. SQS's ApproximateReceiveCount,
+    Pub/Sub's delivery_attempt and Redis Streams' times_delivered all count
+    *deliveries* starting at 1, which is the convention as-is. RabbitMQ's
+    x-delivery-count instead counts *re*deliveries — absent on the first
+    delivery, 1 on the second — so pass counts_redeliveries=True to shift
+    it by one.
+
+    A counter that is missing, unparseable, or below its floor reports a
+    first delivery: these values only ever gate a consumer's decision to
+    stop retrying, so a bad reading should cost one extra attempt rather
+    than crash the consumer or silently drop the task.
+    """
+    floor = 0 if counts_redeliveries else FIRST_DELIVERY
+    offset = FIRST_DELIVERY if counts_redeliveries else 0
+
+    if raw is None or isinstance(raw, bool) or not isinstance(raw, int | float | str):
+        return FIRST_DELIVERY
+    try:
+        count = int(raw)
+    except ValueError:
+        return FIRST_DELIVERY
+    return max(count, floor) + offset

taskqueue_toolkit/queue/dsn.py

@@ -12,6 +12,18 @@ class UnsupportedDsnSchemeError(Exception):
         )
 
 
+_DEFAULT_QUEUE_TYPE = "quorum"
+_VALID_QUEUE_TYPES = ("quorum", "classic")
+
+
+class UnsupportedQueueTypeError(Exception):
+    def __init__(self, queue_type: str) -> None:
+        super().__init__(
+            f"Unsupported RabbitMQ queue type: {queue_type!r} "
+            f"(expected one of {', '.join(_VALID_QUEUE_TYPES)})"
+        )
+
+
 def _query(raw_query: str) -> dict[str, str]:
     return {key: values[0] for key, values in parse_qs(raw_query).items()}
 
@@ -20,6 +32,15 @@ def _query(raw_query: str) -> dict[str, str]:
 class RabbitMqDsn:
     url: str
     queue_name: str
+    # "quorum" (the default) or "classic". Quorum is RabbitMQ's recommended
+    # type for task workloads and the only one that maintains the
+    # x-delivery-count header QueuedTask.delivery_count reads — under
+    # "classic", delivery_count always reports 1. The escape hatch exists
+    # because a queue's type cannot be changed in place: pointing this
+    # library at an existing classic queue fails with PRECONDITION_FAILED
+    # unless you either declare classic here or delete and recreate the
+    # queue.
+    queue_type: str = _DEFAULT_QUEUE_TYPE
 
 
 @dataclass(frozen=True, slots=True)
@@ -77,6 +98,7 @@ def parse_task_queue_dsn(dsn: str) -> TaskQueueDsn:
 
     Examples:
       amqp://guest:guest@host:5672/?queue=my.tasks
+      amqp://guest:guest@host:5672/?queue=my.tasks&queue_type=classic
       redis://:password@host:6379/0?stream=my.tasks&group=workers&consumer=worker-1
       sqs://eu-west-3/my.tasks?endpoint_url=...&access_key_id=...&secret_access_key=...
       sns://eu-west-3/my-tasks?endpoint_url=...&access_key_id=...&secret_access_key=...
@@ -86,9 +108,13 @@ def parse_task_queue_dsn(dsn: str) -> TaskQueueDsn:
     query = _query(parts.query)
 
     if parts.scheme in ("amqp", "amqps"):
+        queue_type = query.get("queue_type", _DEFAULT_QUEUE_TYPE)
+        if queue_type not in _VALID_QUEUE_TYPES:
+            raise UnsupportedQueueTypeError(queue_type)
         return RabbitMqDsn(
             url=dsn.split("?", 1)[0],
             queue_name=query.get("queue", _DEFAULT_QUEUE_NAME),
+            queue_type=queue_type,
         )
 
     if parts.scheme in ("redis", "rediss"):

taskqueue_toolkit/queue/factory.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from collections.abc import Iterator
+from contextlib import contextmanager
 from typing import assert_never
 from urllib.parse import urlsplit
 
@@ -13,16 +15,46 @@ from taskqueue_toolkit.queue.dsn import (
     missing_production_aws_auth,
     parse_task_queue_dsn,
 )
-from taskqueue_toolkit.queue.pubsub import PubsubTaskQueue
-from taskqueue_toolkit.queue.rabbitmq import RabbitMqTaskQueue
-from taskqueue_toolkit.queue.redis_streams import RedisStreamsTaskQueue
 from taskqueue_toolkit.queue.registry import resolve_registered_scheme
-from taskqueue_toolkit.queue.sns import SnsTaskQueue
-from taskqueue_toolkit.queue.sqs import SqsTaskQueue
 from taskqueue_toolkit.queue.task_queue import Decoder, Encoder, TaskQueue
 
 _BUILT_IN_SCHEMES = frozenset({"amqp", "amqps", "redis", "rediss", "sqs", "sns", "pubsub"})
 
+# Which extra installs the SDK each built-in adapter imports at module
+# level, for the error message when it's missing.
+_EXTRA_FOR_SCHEME = {
+    "amqp": "rabbitmq",
+    "redis": "redis-streams",
+    "sqs": "aws",
+    "sns": "aws",
+    "pubsub": "pubsub",
+}
+
+
+class MissingBrokerExtraError(Exception):
+    def __init__(self, scheme: str, extra: str) -> None:
+        super().__init__(
+            f"the {scheme!r} DSN scheme needs a broker SDK that isn't "
+            f"installed — install it with: pip install "
+            f"'taskqueue-toolkit[{extra}]'"
+        )
+
+
+@contextmanager
+def _adapter_import(scheme: str) -> Iterator[None]:
+    """Turn a missing broker SDK into an actionable install instruction.
+
+    Adapters are imported inside create_task_queue() rather than at module
+    level so that installing one extra is enough to use that one broker —
+    a top-level import of all five would make every extra mandatory,
+    including for callers who only plug in their own broker through
+    register_scheme().
+    """
+    try:
+        yield
+    except ImportError as exc:
+        raise MissingBrokerExtraError(scheme, _EXTRA_FOR_SCHEME[scheme]) from exc
+
 
 class MissingAwsAuthError(Exception):
     def __init__(self, environment: str) -> None:
@@ -81,14 +113,24 @@ def create_task_queue[T](
         raise MissingAwsAuthError(environment)
 
     if isinstance(parsed, RabbitMqDsn):
+        with _adapter_import("amqp"):
+            from taskqueue_toolkit.queue.rabbitmq import RabbitMqTaskQueue
         return RabbitMqTaskQueue(dsn=parsed, encode=encode, decode=decode)
     if isinstance(parsed, RedisStreamsDsn):
+        with _adapter_import("redis"):
+            from taskqueue_toolkit.queue.redis_streams import RedisStreamsTaskQueue
         return RedisStreamsTaskQueue(dsn=parsed, encode=encode, decode=decode)
     if isinstance(parsed, SqsDsn):
+        with _adapter_import("sqs"):
+            from taskqueue_toolkit.queue.sqs import SqsTaskQueue
         return SqsTaskQueue(dsn=parsed, encode=encode, decode=decode)
     if isinstance(parsed, SnsDsn):
+        with _adapter_import("sns"):
+            from taskqueue_toolkit.queue.sns import SnsTaskQueue
         return SnsTaskQueue(dsn=parsed, encode=encode, decode=decode)
     if isinstance(parsed, PubsubDsn):
+        with _adapter_import("pubsub"):
+            from taskqueue_toolkit.queue.pubsub import PubsubTaskQueue
         return PubsubTaskQueue(dsn=parsed, encode=encode, decode=decode)
 
     assert_never(parsed)

taskqueue_toolkit/queue/pubsub.py

@@ -4,12 +4,10 @@ import asyncio
 import logging
 import os
 from collections.abc import AsyncIterator, Callable
-from contextlib import suppress
 from dataclasses import dataclass, field
+from typing import Any, Protocol, cast
 
-from google.api_core.exceptions import AlreadyExists
-from google.cloud import pubsub_v1
-
+from taskqueue_toolkit.queue.delivery import delivery_count_from
 from taskqueue_toolkit.queue.dsn import PubsubDsn
 from taskqueue_toolkit.queue.task_queue import Decoder, Encoder
 
@@ -17,17 +15,93 @@ logger = logging.getLogger(__name__)
 
 _PULL_TIMEOUT_SECONDS = 10.0
 
-PublisherFactory = Callable[[], "pubsub_v1.PublisherClient"]
-SubscriberFactory = Callable[[], "pubsub_v1.SubscriberClient"]
+
+class MessageSettler(Protocol):
+    """The two Pub/Sub calls needed to settle a pulled message.
+
+    Synchronous, like the official gRPC client — PubsubQueuedTask calls
+    these through asyncio.to_thread. Split out from Subscriber because a
+    received task holds only this much, not the whole client.
+    """
+
+    def acknowledge(self, *, subscription: str, ack_ids: list[str]) -> Any: ...
+
+    def modify_ack_deadline(
+        self, *, subscription: str, ack_ids: list[str], ack_deadline_seconds: int
+    ) -> Any: ...
+
+
+class Publisher(Protocol):
+    """A Pub/Sub publisher, narrowed to the three calls this adapter makes.
+
+    Synchronous, like the official gRPC client — the adapter drives these
+    through asyncio.to_thread.
+    """
+
+    def topic_path(self, project: str, topic: str) -> Any: ...
+
+    def create_topic(self, *, name: str) -> Any: ...
+
+    def publish(self, topic_path: str, data: bytes) -> Any: ...
+
+
+class Subscriber(MessageSettler, Protocol):
+    """A Pub/Sub subscriber: settling a message, plus provisioning and
+    pulling from the subscription."""
+
+    def subscription_path(self, project: str, subscription: str) -> Any: ...
+
+    def create_subscription(self, *, name: str, topic: str) -> Any: ...
+
+    # Names the three parameters the adapter actually passes, plus
+    # **kwargs so a client taking more than these still qualifies.
+    def pull(
+        self, *, subscription: str, max_messages: int = ..., timeout: float = ..., **kwargs: Any
+    ) -> Any: ...
+
+
+PublisherFactory = Callable[[], Publisher]
+SubscriberFactory = Callable[[], Subscriber]
+
+
+def _default_publisher() -> Publisher:
+    """Default PublisherFactory: the official SDK's publisher client.
+
+    google-cloud-pubsub is imported here rather than at module level so the
+    adapter carries no import-time dependency on it — a caller injecting
+    their own factories needs neither the SDK nor its credentials.
+    """
+    from google.cloud import pubsub_v1
+
+    return cast("Publisher", pubsub_v1.PublisherClient())
+
+
+def _default_subscriber() -> Subscriber:
+    """Default SubscriberFactory: the official SDK's subscriber client."""
+    from google.cloud import pubsub_v1
+
+    return cast("Subscriber", pubsub_v1.SubscriberClient())
+
+
+def _is_already_exists(exc: BaseException) -> bool:
+    """Whether an exception means "this topic/subscription already exists".
+
+    Matched by class name rather than catching
+    google.api_core.exceptions.AlreadyExists directly: importing that class
+    would put a google-cloud-pubsub import back at module level, which is
+    the one thing the injectable factories exist to avoid.
+    """
+    return type(exc).__name__ == "AlreadyExists"
 
 
 @dataclass(slots=True)
 class PubsubQueuedTask[T]:
-    _subscriber: pubsub_v1.SubscriberClient
+    task: T
+    delivery_count: int
+    # Settling identifies the message by the ack id it was pulled with.
+    _subscriber: MessageSettler
     _subscription_path: str
     _ack_id: str
-    delivery_count: int
-    task: T
 
     async def ack(self) -> None:
         await asyncio.to_thread(
@@ -75,10 +149,10 @@ class PubsubTaskQueue[T]:
     decode: Decoder[T]
     # Overridable for tests (inject fake clients) or a shared client the
     # caller already manages; each defaults to the real SDK client.
-    publisher_factory: PublisherFactory = field(default=pubsub_v1.PublisherClient)
-    subscriber_factory: SubscriberFactory = field(default=pubsub_v1.SubscriberClient)
-    _publisher_client: pubsub_v1.PublisherClient | None = field(default=None, init=False)
-    _subscriber_client: pubsub_v1.SubscriberClient | None = field(default=None, init=False)
+    publisher_factory: PublisherFactory = field(default=_default_publisher)
+    subscriber_factory: SubscriberFactory = field(default=_default_subscriber)
+    _publisher_client: Publisher | None = field(default=None, init=False)
+    _subscriber_client: Subscriber | None = field(default=None, init=False)
 
     def _apply_emulator_host(self) -> None:
         # The official client only knows to target an emulator via this env
@@ -91,7 +165,7 @@ class PubsubTaskQueue[T]:
             os.environ["PUBSUB_EMULATOR_HOST"] = self.dsn.emulator_host
 
     @property
-    def _publisher(self) -> pubsub_v1.PublisherClient:
+    def _publisher(self) -> Publisher:
         # Built lazily, not at __init__ time (e.g. via default_factory) —
         # constructing the client eagerly authenticates against GCP
         # immediately, which fails outside an environment with real or
@@ -102,7 +176,7 @@ class PubsubTaskQueue[T]:
         return self._publisher_client
 
     @property
-    def _subscriber(self) -> pubsub_v1.SubscriberClient:
+    def _subscriber(self) -> Subscriber:
         if self._subscriber_client is None:
             self._apply_emulator_host()
             self._subscriber_client = self.subscriber_factory()
@@ -118,16 +192,22 @@ class PubsubTaskQueue[T]:
 
     async def _ensure_topic(self) -> str:
         topic_path = self._topic_path()
-        with suppress(AlreadyExists):
+        try:
             await asyncio.to_thread(self._publisher.create_topic, name=topic_path)
+        except Exception as exc:
+            if not _is_already_exists(exc):
+                raise
         return topic_path
 
     async def _ensure_subscription(self, topic_path: str) -> str:
         subscription_path = self._subscription_path()
-        with suppress(AlreadyExists):
+        try:
             await asyncio.to_thread(
                 self._subscriber.create_subscription, name=subscription_path, topic=topic_path
             )
+        except Exception as exc:
+            if not _is_already_exists(exc):
+                raise
         return subscription_path
 
     async def publish(self, task: T) -> None:
@@ -155,16 +235,17 @@ 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
+                # delivery_attempt counts deliveries from 1, matching
+                # QueuedTask.delivery_count directly — but Pub/Sub only
+                # populates it when the subscription has a dead-letter
+                # policy. Without one it stays absent and this always
+                # reports a first delivery, so a consumer relying on it to
+                # stop retrying would retry forever.
+                delivery_count = delivery_count_from(getattr(received, "delivery_attempt", None))
                 yield PubsubQueuedTask(
+                    task=self.decode(received.message.data),
+                    delivery_count=delivery_count,
                     _subscriber=self._subscriber,
                     _subscription_path=subscription_path,
                     _ack_id=received.ack_id,
-                    delivery_count=delivery_count,
-                    task=self.decode(received.message.data),
                 )

taskqueue_toolkit/queue/rabbitmq.py

@@ -1,47 +1,142 @@
 from __future__ import annotations
 
 import logging
-from collections.abc import AsyncIterator, Awaitable, Callable
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
 from contextlib import suppress
 from dataclasses import dataclass, field
+from typing import Any, Protocol
 
-import aio_pika
-from pamqp.common import FieldTable
-
+from taskqueue_toolkit.queue.delivery import delivery_count_from
 from taskqueue_toolkit.queue.dsn import RabbitMqDsn
 from taskqueue_toolkit.queue.task_queue import Decoder, Encoder
 
 logger = logging.getLogger(__name__)
 
-Connect = Callable[[str], Awaitable["aio_pika.abc.AbstractRobustConnection"]]
+# Structurally what pamqp calls a FieldTable (AMQP queue arguments),
+# spelled out rather than imported so this module carries no import-time
+# dependency on a RabbitMQ SDK — see _connect_robust for the rest of that
+# reasoning.
+FieldTable = Mapping[str, Any]
+
+
+class Deliverable(Protocol):
+    """An incoming message, as this adapter reads it."""
 
+    @property
+    def body(self) -> bytes: ...
+
+    @property
+    def headers(self) -> Mapping[str, Any] | None: ...
 
-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]
+    async def ack(self) -> None: ...
+
+    async def nack(self, *, requeue: bool = True) -> None: ...
+
+
+class Consumable(Protocol):
+    """A declared queue, iterated to receive messages."""
+
+    @property
+    def name(self) -> str: ...
+
+    def iterator(self) -> AsyncIterator[Deliverable]: ...
+
+
+class Publishable(Protocol):
+    """An exchange, as this adapter publishes through it.
+
+    Takes a message object the caller builds — see MessageFactory for why
+    that object isn't constructed here.
+    """
+
+    async def publish(self, message: Any, *, routing_key: str) -> Any: ...
+
+
+# Builds whatever message type the injected client publishes: (body,
+# persistent) -> that client's message object.
+#
+# Kept a parameter rather than calling aio_pika.Message() inline so a
+# different RabbitMQ client (pika, aiormq, ...) can be injected through
+# connect= without also receiving an aio_pika object it can't publish.
+MessageFactory = Callable[[bytes, bool], Any]
+
+
+class Channel(Protocol):
+    """A channel, narrowed to the three members this adapter uses.
+
+    Signatures stay permissive (positional-or-keyword, *args/**kwargs)
+    because real clients accept more parameters here than this adapter ever
+    passes — a signature narrowed to just our call sites would reject them.
+    """
+
+    @property
+    def default_exchange(self) -> Any: ...
+
+    def set_qos(self, prefetch_count: int = ..., *args: Any, **kwargs: Any) -> Any: ...
+
+    def declare_queue(
+        self, name: Any = ..., *args: Any, **kwargs: Any
+    ) -> Awaitable[Consumable]: ...
+
+
+class Connection(Protocol):
+    """A broker connection, narrowed to what this adapter uses.
+
+    Declaring the chain structurally rather than borrowing aio_pika's own
+    types keeps the dependency to the handful of calls actually made, and
+    lets the in-memory double in taskqueue_toolkit.testing satisfy it
+    honestly instead of being cast to an SDK interface it doesn't
+    implement.
+    """
+
+    # Two deliberate looseneses so real clients qualify. Not `async def`:
+    # aio_pika's channel() is a sync call returning an awaitable, and both
+    # shapes are awaited identically at the call site. And *args/**kwargs:
+    # clients take extra optional parameters here (channel number,
+    # publisher confirms, ...) that this adapter never passes, but a
+    # narrower signature would reject them.
+    def channel(self, *args: Any, **kwargs: Any) -> Awaitable[Channel]: ...
+
+    async def close(self) -> Any: ...
+
+
+Connect = Callable[[str], Awaitable[Connection]]
+
+
+async def _connect_robust(url: str) -> Connection:
+    """Default Connect: aio_pika's own robust (auto-reconnecting) connection.
+
+    Wrapped rather than referenced directly for two reasons: connect_robust
+    is an overloaded function, which doesn't match a plain Callable alias;
+    and importing aio_pika here rather than at module level keeps the whole
+    adapter usable with a different RabbitMQ client, without aio-pika
+    installed at all.
+    """
+    import aio_pika
+
+    return await aio_pika.connect_robust(url)
+
+
+def _aio_pika_message(body: bytes, persistent: bool) -> Any:
+    """Default MessageFactory: aio_pika's own message type."""
+    import aio_pika
+
+    return aio_pika.Message(
+        body=body,
+        delivery_mode=(
+            aio_pika.DeliveryMode.PERSISTENT if persistent else aio_pika.DeliveryMode.NOT_PERSISTENT
+        ),
+    )
 
 
 @dataclass(slots=True)
 class RabbitMqQueuedTask[T]:
-    _message: aio_pika.abc.AbstractIncomingMessage
     task: T
-
-    @property
-    def delivery_count(self) -> int:
-        return _delivery_count(self._message)
+    delivery_count: int
+    # AMQP acknowledges by delivery tag on the channel the message arrived
+    # on, and only the message object carries that pairing — unlike the
+    # other adapters, there is no id to hold onto instead.
+    _message: Deliverable
 
     async def ack(self) -> None:
         await self._message.ack()
@@ -57,16 +152,22 @@ class RabbitMqTaskQueue[T]:
     decode: Decoder[T]
     # Overridable for tests (inject a fake connection) or to share/pool a
     # connection strategy the caller already has; defaults to the real SDK.
-    connect: Connect = field(default=aio_pika.connect_robust)
+    connect: Connect = field(default=_connect_robust)
+    # Override alongside connect= when injecting a different RabbitMQ
+    # client: publish() hands the message this builds straight to that
+    # client's exchange, so the two have to agree on the type.
+    build_message: MessageFactory = field(default=_aio_pika_message)
 
     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"}
+        # A queue's type is fixed at declaration and cannot be changed in
+        # place, so this has to match whatever the queue already is —
+        # declaring a different type against an existing queue fails with
+        # PRECONDITION_FAILED. Hence queue_type being part of the DSN
+        # rather than hardcoded here: quorum by default (RabbitMQ's
+        # recommendation for task workloads, and the only type that
+        # maintains x-delivery-count), classic for pointing at a queue
+        # that already exists as one.
+        return {"x-queue-type": self.dsn.queue_type}
 
     async def publish(self, task: T) -> None:
         connection = await self.connect(self.dsn.url)
@@ -76,10 +177,7 @@ class RabbitMqTaskQueue[T]:
                 self.dsn.queue_name, durable=True, arguments=self._queue_arguments()
             )
             await channel.default_exchange.publish(
-                aio_pika.Message(
-                    body=self.encode(task),
-                    delivery_mode=aio_pika.DeliveryMode.PERSISTENT,
-                ),
+                self.build_message(self.encode(task), True),
                 routing_key=queue.name,
             )
             logger.info("task published", extra={"queue": self.dsn.queue_name})
@@ -96,7 +194,17 @@ class RabbitMqTaskQueue[T]:
             )
 
             async for message in queue.iterator():
-                yield RabbitMqQueuedTask(_message=message, task=self.decode(message.body))
+                # x-delivery-count counts redeliveries, and only quorum
+                # queues maintain it at all — against a classic queue it is
+                # always absent and this always reports a first delivery.
+                yield RabbitMqQueuedTask(
+                    task=self.decode(message.body),
+                    delivery_count=delivery_count_from(
+                        (message.headers or {}).get("x-delivery-count"),
+                        counts_redeliveries=True,
+                    ),
+                    _message=message,
+                )
         finally:
             # The consumer (a worker's `async for`) can stop iterating at any
             # point — graceful shutdown, an unhandled error, etc. — which