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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskqueue-toolkit
-Version: 0.2.0
+Version: 0.3.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>
@@ -74,12 +74,47 @@ async for queued in queue.consume():
 
 | Scheme | Broker | Example |
 |---|---|---|
-| `amqp` / `amqps` | RabbitMQ | `amqp://guest:guest@host:5672/?queue=my.tasks` |
+| `amqp` / `amqps` | RabbitMQ | `amqp://guest:guest@host:5672/?queue=my.tasks&queue_type=quorum` |
 | `redis` / `rediss` | Redis Streams | `redis://:password@host:6379/0?stream=my.tasks&group=workers&consumer=worker-1` |
 | `sqs` | Amazon SQS | `sqs://eu-west-3/my.tasks?endpoint_url=...&access_key_id=...&secret_access_key=...` |
 | `sns` | Amazon SNS (fan-out) | `sns://eu-west-3/my-tasks?endpoint_url=...&access_key_id=...&secret_access_key=...` |
 | `pubsub` | Google Pub/Sub | `pubsub://project-id/my-tasks?subscription=my-tasks-subscriber&emulator_host=localhost:8085` |
 
+### Giving up after N attempts
+
+Each `QueuedTask` reports `delivery_count` — how many times the broker has delivered that message, counting the current delivery (1 the first time, never 0). A redelivery caused by a crashed consumer or an expired ack deadline counts the same as one caused by an explicit `nack(requeue=True)`, since the broker counts it the same way.
+
+```python
+MAX_ATTEMPTS = 3
+
+async for queued in queue.consume():
+    if queued.delivery_count > MAX_ATTEMPTS:
+        logger.error("giving up on task", extra={"attempts": queued.delivery_count})
+        await queued.nack(requeue=False)
+        continue
+    try:
+        await handle(queued.task)
+    except Exception:
+        await queued.nack(requeue=True)
+    else:
+        await queued.ack()
+```
+
+The value comes from each broker's own counter, not from this package. Treat it as a lower bound — SQS documents its counter as approximate, and no broker promises exactness across a failover. **Two setups can't count at all**, and silently report a first delivery forever:
+
+| Broker | Counts only when |
+|---|---|
+| RabbitMQ | the queue is a **quorum** queue (the default here) — classic queues maintain no `x-delivery-count` |
+| Pub/Sub | the subscription has a **dead-letter policy** — `delivery_attempt` is unset without one |
+
+### RabbitMQ queue type
+
+Queues are declared as **quorum** by default: RabbitMQ's recommendation for task workloads, and the only type that maintains the counter `delivery_count` reads. A queue's type is fixed when it's created, so pointing this package at a queue that already exists as classic fails with `PRECONDITION_FAILED` until you either delete and recreate it, or opt out:
+
+```
+amqp://guest:guest@host:5672/?queue=my.tasks&queue_type=classic
+```
+
 ### Adding a broker this package doesn't ship
 
 The five schemes above are built in and checked for exhaustiveness at type-check time — `create_task_queue()` can't silently forget one. For a broker outside that list (Kafka, NATS, ...), register a handler once, at import/startup time, instead of forking the package:
@@ -99,6 +134,43 @@ queue = create_task_queue("kafka://localhost:9092/my-tasks", encode=..., decode=
 
 A handler receives the raw DSN string plus the `encode`/`decode` pair and returns a `TaskQueue[T]` — parsing and construction happen together, so there's a single call to keep in sync, not a parser and a constructor spread across two files.
 
+**No broker SDK required.** `TaskQueue[T]`/`QueuedTask[T]` are protocols with no dependencies of their own, and `create_task_queue()` imports a built-in adapter only when a DSN actually selects it. So a project that brings its own broker client needs none of the extras installed — and asking for a scheme whose SDK is missing names the extra to install rather than raising a bare `ImportError`:
+
+```
+MissingBrokerExtraError: the 'amqp' DSN scheme needs a broker SDK that isn't
+installed — install it with: pip install 'taskqueue-toolkit[rabbitmq]'
+```
+
+**Reusing a built-in adapter with a different client.** Each adapter types its client against its own narrow protocol (RabbitMQ's `Connection`/`Channel`/`Deliverable`, SQS/SNS's `MessageSettler`, Redis Streams' `EntryAcknowledger`) rather than the SDK's own types, so anything structurally compatible can be injected — that's the same seam the in-memory doubles use.
+
+This holds for every adapter: **no broker SDK is imported at module level anywhere in the package**, so all five adapters (and all five in-memory doubles) import and build on a machine with none of them installed. Each SDK is imported only from that adapter's default client factory, the moment a real connection is opened.
+
+| Adapter | Inject | To replace |
+|---|---|---|
+| RabbitMQ | `connect=`, `build_message=` | aio-pika |
+| SQS | `client_factory=` | aioboto3 |
+| SNS | `client_factory=` | aioboto3 |
+| Redis Streams | `client_factory=` | redis-py |
+| Pub/Sub | `publisher_factory=`, `subscriber_factory=` | google-cloud-pubsub |
+
+For RabbitMQ, override both seams together, since `publish()` hands the message straight to your exchange:
+
+```python
+class MyMessage:
+    def __init__(self, body: bytes, persistent: bool): ...
+
+
+queue = RabbitMqTaskQueue(
+    dsn=dsn,
+    encode=...,
+    decode=...,
+    connect=my_connect,  # -> Connection: channel(), close()
+    build_message=MyMessage,  # (body, persistent) -> your client's message type
+)
+```
+
+`connect` must return an object satisfying `Connection` → `Channel` → `Consumable`/`Publishable` → `Deliverable`; those five protocols are the whole contract, and each lists only the members the adapter actually calls.
+
 ### Outbox pattern
 
 ```python

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

@@ -39,12 +39,47 @@ async for queued in queue.consume():
 
 | Scheme | Broker | Example |
 |---|---|---|
-| `amqp` / `amqps` | RabbitMQ | `amqp://guest:guest@host:5672/?queue=my.tasks` |
+| `amqp` / `amqps` | RabbitMQ | `amqp://guest:guest@host:5672/?queue=my.tasks&queue_type=quorum` |
 | `redis` / `rediss` | Redis Streams | `redis://:password@host:6379/0?stream=my.tasks&group=workers&consumer=worker-1` |
 | `sqs` | Amazon SQS | `sqs://eu-west-3/my.tasks?endpoint_url=...&access_key_id=...&secret_access_key=...` |
 | `sns` | Amazon SNS (fan-out) | `sns://eu-west-3/my-tasks?endpoint_url=...&access_key_id=...&secret_access_key=...` |
 | `pubsub` | Google Pub/Sub | `pubsub://project-id/my-tasks?subscription=my-tasks-subscriber&emulator_host=localhost:8085` |
 
+### Giving up after N attempts
+
+Each `QueuedTask` reports `delivery_count` — how many times the broker has delivered that message, counting the current delivery (1 the first time, never 0). A redelivery caused by a crashed consumer or an expired ack deadline counts the same as one caused by an explicit `nack(requeue=True)`, since the broker counts it the same way.
+
+```python
+MAX_ATTEMPTS = 3
+
+async for queued in queue.consume():
+    if queued.delivery_count > MAX_ATTEMPTS:
+        logger.error("giving up on task", extra={"attempts": queued.delivery_count})
+        await queued.nack(requeue=False)
+        continue
+    try:
+        await handle(queued.task)
+    except Exception:
+        await queued.nack(requeue=True)
+    else:
+        await queued.ack()
+```
+
+The value comes from each broker's own counter, not from this package. Treat it as a lower bound — SQS documents its counter as approximate, and no broker promises exactness across a failover. **Two setups can't count at all**, and silently report a first delivery forever:
+
+| Broker | Counts only when |
+|---|---|
+| RabbitMQ | the queue is a **quorum** queue (the default here) — classic queues maintain no `x-delivery-count` |
+| Pub/Sub | the subscription has a **dead-letter policy** — `delivery_attempt` is unset without one |
+
+### RabbitMQ queue type
+
+Queues are declared as **quorum** by default: RabbitMQ's recommendation for task workloads, and the only type that maintains the counter `delivery_count` reads. A queue's type is fixed when it's created, so pointing this package at a queue that already exists as classic fails with `PRECONDITION_FAILED` until you either delete and recreate it, or opt out:
+
+```
+amqp://guest:guest@host:5672/?queue=my.tasks&queue_type=classic
+```
+
 ### Adding a broker this package doesn't ship
 
 The five schemes above are built in and checked for exhaustiveness at type-check time — `create_task_queue()` can't silently forget one. For a broker outside that list (Kafka, NATS, ...), register a handler once, at import/startup time, instead of forking the package:
@@ -64,6 +99,43 @@ queue = create_task_queue("kafka://localhost:9092/my-tasks", encode=..., decode=
 
 A handler receives the raw DSN string plus the `encode`/`decode` pair and returns a `TaskQueue[T]` — parsing and construction happen together, so there's a single call to keep in sync, not a parser and a constructor spread across two files.
 
+**No broker SDK required.** `TaskQueue[T]`/`QueuedTask[T]` are protocols with no dependencies of their own, and `create_task_queue()` imports a built-in adapter only when a DSN actually selects it. So a project that brings its own broker client needs none of the extras installed — and asking for a scheme whose SDK is missing names the extra to install rather than raising a bare `ImportError`:
+
+```
+MissingBrokerExtraError: the 'amqp' DSN scheme needs a broker SDK that isn't
+installed — install it with: pip install 'taskqueue-toolkit[rabbitmq]'
+```
+
+**Reusing a built-in adapter with a different client.** Each adapter types its client against its own narrow protocol (RabbitMQ's `Connection`/`Channel`/`Deliverable`, SQS/SNS's `MessageSettler`, Redis Streams' `EntryAcknowledger`) rather than the SDK's own types, so anything structurally compatible can be injected — that's the same seam the in-memory doubles use.
+
+This holds for every adapter: **no broker SDK is imported at module level anywhere in the package**, so all five adapters (and all five in-memory doubles) import and build on a machine with none of them installed. Each SDK is imported only from that adapter's default client factory, the moment a real connection is opened.
+
+| Adapter | Inject | To replace |
+|---|---|---|
+| RabbitMQ | `connect=`, `build_message=` | aio-pika |
+| SQS | `client_factory=` | aioboto3 |
+| SNS | `client_factory=` | aioboto3 |
+| Redis Streams | `client_factory=` | redis-py |
+| Pub/Sub | `publisher_factory=`, `subscriber_factory=` | google-cloud-pubsub |
+
+For RabbitMQ, override both seams together, since `publish()` hands the message straight to your exchange:
+
+```python
+class MyMessage:
+    def __init__(self, body: bytes, persistent: bool): ...
+
+
+queue = RabbitMqTaskQueue(
+    dsn=dsn,
+    encode=...,
+    decode=...,
+    connect=my_connect,  # -> Connection: channel(), close()
+    build_message=MyMessage,  # (body, persistent) -> your client's message type
+)
+```
+
+`connect` must return an object satisfying `Connection` → `Channel` → `Consumable`/`Publishable` → `Deliverable`; those five protocols are the whole contract, and each lists only the members the adapter actually calls.
+
 ### Outbox pattern
 
 ```python

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

@@ -1,6 +1,6 @@
 [project]
 name = "taskqueue-toolkit"
-version = "0.2.0"
+version = "0.3.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.2.0 → taskqueue_toolkit-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "taskqueue-toolkit"
-version = "0.2.0"
+version = "0.3.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.3.0/src/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-0.2.0 → taskqueue_toolkit-0.3.0}/src/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-0.2.0 → taskqueue_toolkit-0.3.0}/src/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-0.2.0 → taskqueue_toolkit-0.3.0}/src/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),
                 )