redis-message-queue 2.1.0__tar.gz → 3.1.0__tar.gz

{redis_message_queue-2.1.0 → redis_message_queue-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redis-message-queue
-Version: 2.1.0
+Version: 3.1.0
 Summary: Python message queuing with Redis and message deduplication
 License-File: LICENSE
 Author: Elijas
@@ -16,7 +16,7 @@ Description-Content-Type: text/markdown
 
 # redis-message-queue
 
-[![PyPI Version](https://img.shields.io/badge/v2.1.0-version?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
+[![PyPI Version](https://img.shields.io/badge/v3.1.0-version?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
 [![PyPI Downloads](https://img.shields.io/pypi/dm/redis-message-queue?color=43cd0f&style=flat&label=downloads)](https://pypistats.org/packages/redis-message-queue)
 [![License: MIT](https://img.shields.io/badge/License-MIT-43cd0f.svg?style=flat&label=license)](LICENSE)
 [![Maintained: yes](https://img.shields.io/badge/yes-43cd0f.svg?style=flat&label=maintained)](https://github.com/Elijas/redis-message-queue/issues)
@@ -27,7 +27,7 @@ Description-Content-Type: text/markdown
 **Lightweight Python message queuing with Redis and built-in publish-side deduplication.** Deduplicate publishes within a TTL window, with optional crash recovery — across any number of producers and consumers.
 
 ```bash
-pip install "redis-message-queue>=2.0.0,<3.0.0"
+pip install "redis-message-queue>=3.0.0,<4.0.0"
 ```
 
 Requires Redis server >= 6.2.
@@ -219,10 +219,12 @@ while not interrupt.is_interrupted():
 ```python
 from redis_message_queue._redis_gateway import RedisGateway
 
-# Custom retry logic, dedup TTL, or wait interval
+# Tune retry budget, dedup TTL, or wait interval
 gateway = RedisGateway(
     redis_client=client,
-    retry_strategy=my_custom_retry,
+    retry_budget_seconds=120,          # total retry window (set 0 to disable retry)
+    retry_max_delay_seconds=5.0,       # cap on per-attempt backoff
+    retry_initial_delay_seconds=0.01,  # first backoff
     message_deduplication_log_ttl_seconds=3600,
     message_wait_interval_seconds=10,
     message_visibility_timeout_seconds=300,
@@ -230,6 +232,21 @@ gateway = RedisGateway(
 queue = RedisMessageQueue("q", gateway=gateway)
 ```
 
+The retry knobs configure an internal `tenacity` strategy: exponential
+backoff with jitter, retry on transient Redis errors only, capped at
+`retry_budget_seconds`. The budget is wall-clock time from the first attempt (including attempt duration), not inter-attempt delay; a single attempt that takes longer than the budget results in zero retries. Setting `retry_budget_seconds=0` disables retry
+entirely (single attempt; exceptions propagate). The library uses
+`retry_budget_seconds` to size the operation-result cache TTL automatically,
+so the previous footgun of an over-long retry budget out-living the cache
+and producing misleading "cleanup was a no-op" warnings is now structurally
+impossible.
+
+To plug in a different retry library (`backoff`, `asyncstdlib.retry`, or your
+own logic) or fundamentally different semantics, subclass
+`AbstractRedisGateway` from `redis_message_queue._abstract_redis_gateway`
+(or `redis_message_queue.asyncio._abstract_redis_gateway`) and override the
+operation methods directly.
+
 If your custom gateway uses visibility timeouts, it must expose a public
 `message_visibility_timeout_seconds` value and return `ClaimedMessage` from
 `wait_for_message_and_move()`. The queue now fails closed if a lease-capable
@@ -240,16 +257,6 @@ the queue cannot detect that lease semantics are in play and will treat the
 gateway as a non-lease gateway. In that misconfigured state, lease-token safety
 checks and heartbeat validation are bypassed.
 
-A custom `retry_strategy` MUST have a total retry budget no longer than
-`max(message_visibility_timeout_seconds, 300)` seconds. That value is the TTL
-of the built-in gateway's ambiguous-success cache: if a retry arrives after the
-cache has expired, the gateway re-runs the Lua script and — because the message
-was already acked on the first attempt — sees `LREM=0` and returns `False`. This
-surfaces as a misleading "cleanup was a no-op" warning from `process_message`;
-no data is lost or double-processed, but a `max_completed_length` /
-`max_failed_length` bound may be skipped on that call. The default
-`tenacity.stop_after_delay(120)` is safely within the 300 s floor.
-
 When using a custom gateway with dead-letter queue support, configure `max_delivery_count`
 and `dead_letter_queue` directly on the gateway — do **not** pass `max_delivery_count` to
 `RedisMessageQueue`:
@@ -292,8 +299,9 @@ await client.aclose()
 - **Timed waits use polling claim loops.** To make claims recoverable after ambiguous connection drops, `wait_for_message_and_move()` uses idempotent Lua claim polling instead of raw blocking list-move commands. This adds a small polling cadence during timed waits.
 - **Redis Lua is atomic, not rollback-transactional.** The built-in scripts now preflight queue key types and fail closed on `WRONGTYPE` before mutating queue state, but Redis does not undo earlier writes if a later script command fails for another reason (for example `OOM` under severe memory pressure).
 - **Batch reclaim limit of 100.** The visibility-timeout reclaim Lua script processes at most 100 expired messages per consumer poll. Under extreme backlog this may delay recovery, but prevents any single poll from blocking Redis.
+- **Claim-attempt loop limit of 100 per poll.** The VT claim Lua script attempts at most 100 LMOVE+delivery-count checks per invocation. Under pathological conditions (>100 consecutive poison messages in pending), a single poll returns no message even though non-poison messages exist deeper in the queue. Subsequent polls drain the poison batch 100 at a time.
 - **Redis Cluster requires hash tags.** The built-in queue uses multiple Redis keys per operation. Wrap the queue name in hash tags (for example `{myqueue}`) so every generated key lands in the same slot. When you pass a Redis Cluster client to the built-in queue/gateway path, incompatible names are rejected early.
-- **Client-side `Retry` can duplicate non-deduplicated publishes.** If you construct your `redis.Redis` client with `retry=Retry(...)`, redis-py retries `ConnectionError` / `TimeoutError` at the connection layer — *below* this library. Idempotent operations (deduplicated `publish()`, lease-scoped cleanup) are safe because their Lua scripts replay the original result. `add_message()` (used by `publish()` when `deduplication=False`) is a bare `LPUSH`: this library deliberately does not retry it, but a client-level `Retry` will, and if the server executed the command before the response was lost the message is enqueued twice. Leave `retry=None` (the default) if you need strict at-most-once semantics for non-deduplicated publishes, or accept the duplication risk.
+- **Client-side `Retry` can duplicate non-deduplicated publishes.** If you construct your `redis.Redis` client with `retry=Retry(...)`, redis-py retries `ConnectionError` / `TimeoutError` at the connection layer — *below* this library. Idempotent operations (deduplicated `publish()`, lease-scoped cleanup) are safe because their Lua scripts replay the original result. `add_message()` (used by `publish()` when `deduplication=False`) is a bare `LPUSH`: this library deliberately does not retry it, but a client-level `Retry` will, and if the server executed the command before the response was lost the message is enqueued twice. Leave `retry=None` (the default) if you need strict at-most-once semantics for non-deduplicated publishes, or accept the duplication risk. More broadly, any non-idempotent `LPUSH` path is vulnerable if the connection drops after server execution but before the client receives the response; all other built-in operations (deduplicated publish, lease-scoped ack/move, lease renewal) use replay markers and are safe under client-level `Retry`.
 
 For a full analysis, see [docs/production-readiness.md](docs/production-readiness.md).
 

{redis_message_queue-2.1.0 → redis_message_queue-3.1.0}/README.md

@@ -1,6 +1,6 @@
 # redis-message-queue
 
-[![PyPI Version](https://img.shields.io/badge/v2.1.0-version?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
+[![PyPI Version](https://img.shields.io/badge/v3.1.0-version?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
 [![PyPI Downloads](https://img.shields.io/pypi/dm/redis-message-queue?color=43cd0f&style=flat&label=downloads)](https://pypistats.org/packages/redis-message-queue)
 [![License: MIT](https://img.shields.io/badge/License-MIT-43cd0f.svg?style=flat&label=license)](LICENSE)
 [![Maintained: yes](https://img.shields.io/badge/yes-43cd0f.svg?style=flat&label=maintained)](https://github.com/Elijas/redis-message-queue/issues)
@@ -11,7 +11,7 @@
 **Lightweight Python message queuing with Redis and built-in publish-side deduplication.** Deduplicate publishes within a TTL window, with optional crash recovery — across any number of producers and consumers.
 
 ```bash
-pip install "redis-message-queue>=2.0.0,<3.0.0"
+pip install "redis-message-queue>=3.0.0,<4.0.0"
 ```
 
 Requires Redis server >= 6.2.
@@ -203,10 +203,12 @@ while not interrupt.is_interrupted():
 ```python
 from redis_message_queue._redis_gateway import RedisGateway
 
-# Custom retry logic, dedup TTL, or wait interval
+# Tune retry budget, dedup TTL, or wait interval
 gateway = RedisGateway(
     redis_client=client,
-    retry_strategy=my_custom_retry,
+    retry_budget_seconds=120,          # total retry window (set 0 to disable retry)
+    retry_max_delay_seconds=5.0,       # cap on per-attempt backoff
+    retry_initial_delay_seconds=0.01,  # first backoff
     message_deduplication_log_ttl_seconds=3600,
     message_wait_interval_seconds=10,
     message_visibility_timeout_seconds=300,
@@ -214,6 +216,21 @@ gateway = RedisGateway(
 queue = RedisMessageQueue("q", gateway=gateway)
 ```
 
+The retry knobs configure an internal `tenacity` strategy: exponential
+backoff with jitter, retry on transient Redis errors only, capped at
+`retry_budget_seconds`. The budget is wall-clock time from the first attempt (including attempt duration), not inter-attempt delay; a single attempt that takes longer than the budget results in zero retries. Setting `retry_budget_seconds=0` disables retry
+entirely (single attempt; exceptions propagate). The library uses
+`retry_budget_seconds` to size the operation-result cache TTL automatically,
+so the previous footgun of an over-long retry budget out-living the cache
+and producing misleading "cleanup was a no-op" warnings is now structurally
+impossible.
+
+To plug in a different retry library (`backoff`, `asyncstdlib.retry`, or your
+own logic) or fundamentally different semantics, subclass
+`AbstractRedisGateway` from `redis_message_queue._abstract_redis_gateway`
+(or `redis_message_queue.asyncio._abstract_redis_gateway`) and override the
+operation methods directly.
+
 If your custom gateway uses visibility timeouts, it must expose a public
 `message_visibility_timeout_seconds` value and return `ClaimedMessage` from
 `wait_for_message_and_move()`. The queue now fails closed if a lease-capable
@@ -224,16 +241,6 @@ the queue cannot detect that lease semantics are in play and will treat the
 gateway as a non-lease gateway. In that misconfigured state, lease-token safety
 checks and heartbeat validation are bypassed.
 
-A custom `retry_strategy` MUST have a total retry budget no longer than
-`max(message_visibility_timeout_seconds, 300)` seconds. That value is the TTL
-of the built-in gateway's ambiguous-success cache: if a retry arrives after the
-cache has expired, the gateway re-runs the Lua script and — because the message
-was already acked on the first attempt — sees `LREM=0` and returns `False`. This
-surfaces as a misleading "cleanup was a no-op" warning from `process_message`;
-no data is lost or double-processed, but a `max_completed_length` /
-`max_failed_length` bound may be skipped on that call. The default
-`tenacity.stop_after_delay(120)` is safely within the 300 s floor.
-
 When using a custom gateway with dead-letter queue support, configure `max_delivery_count`
 and `dead_letter_queue` directly on the gateway — do **not** pass `max_delivery_count` to
 `RedisMessageQueue`:
@@ -276,8 +283,9 @@ await client.aclose()
 - **Timed waits use polling claim loops.** To make claims recoverable after ambiguous connection drops, `wait_for_message_and_move()` uses idempotent Lua claim polling instead of raw blocking list-move commands. This adds a small polling cadence during timed waits.
 - **Redis Lua is atomic, not rollback-transactional.** The built-in scripts now preflight queue key types and fail closed on `WRONGTYPE` before mutating queue state, but Redis does not undo earlier writes if a later script command fails for another reason (for example `OOM` under severe memory pressure).
 - **Batch reclaim limit of 100.** The visibility-timeout reclaim Lua script processes at most 100 expired messages per consumer poll. Under extreme backlog this may delay recovery, but prevents any single poll from blocking Redis.
+- **Claim-attempt loop limit of 100 per poll.** The VT claim Lua script attempts at most 100 LMOVE+delivery-count checks per invocation. Under pathological conditions (>100 consecutive poison messages in pending), a single poll returns no message even though non-poison messages exist deeper in the queue. Subsequent polls drain the poison batch 100 at a time.
 - **Redis Cluster requires hash tags.** The built-in queue uses multiple Redis keys per operation. Wrap the queue name in hash tags (for example `{myqueue}`) so every generated key lands in the same slot. When you pass a Redis Cluster client to the built-in queue/gateway path, incompatible names are rejected early.
-- **Client-side `Retry` can duplicate non-deduplicated publishes.** If you construct your `redis.Redis` client with `retry=Retry(...)`, redis-py retries `ConnectionError` / `TimeoutError` at the connection layer — *below* this library. Idempotent operations (deduplicated `publish()`, lease-scoped cleanup) are safe because their Lua scripts replay the original result. `add_message()` (used by `publish()` when `deduplication=False`) is a bare `LPUSH`: this library deliberately does not retry it, but a client-level `Retry` will, and if the server executed the command before the response was lost the message is enqueued twice. Leave `retry=None` (the default) if you need strict at-most-once semantics for non-deduplicated publishes, or accept the duplication risk.
+- **Client-side `Retry` can duplicate non-deduplicated publishes.** If you construct your `redis.Redis` client with `retry=Retry(...)`, redis-py retries `ConnectionError` / `TimeoutError` at the connection layer — *below* this library. Idempotent operations (deduplicated `publish()`, lease-scoped cleanup) are safe because their Lua scripts replay the original result. `add_message()` (used by `publish()` when `deduplication=False`) is a bare `LPUSH`: this library deliberately does not retry it, but a client-level `Retry` will, and if the server executed the command before the response was lost the message is enqueued twice. Leave `retry=None` (the default) if you need strict at-most-once semantics for non-deduplicated publishes, or accept the duplication risk. More broadly, any non-idempotent `LPUSH` path is vulnerable if the connection drops after server execution but before the client receives the response; all other built-in operations (deduplicated publish, lease-scoped ack/move, lease renewal) use replay markers and are safe under client-level `Retry`.
 
 For a full analysis, see [docs/production-readiness.md](docs/production-readiness.md).
 

{redis_message_queue-2.1.0 → redis_message_queue-3.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "redis-message-queue"
-version = "2.1.0"
+version = "3.1.0"
 description = "Python message queuing with Redis and message deduplication"
 authors = ["Elijas <4084885+Elijas@users.noreply.github.com>"]
 readme = "README.md"

{redis_message_queue-2.1.0 → redis_message_queue-3.1.0}/redis_message_queue/_abstract_redis_gateway.py

@@ -11,13 +11,17 @@ class AbstractRedisGateway(ABC):
     gateways MUST uphold the same behavioral contracts documented on each method
     to avoid phantom heartbeats, undetected lease conflicts, or silent data loss.
 
-    Gateways that support visibility timeouts (lease-based claiming) should expose
+    Gateways that support visibility timeouts (lease-based claiming) MUST expose
     a ``message_visibility_timeout_seconds`` property (int or None). This is not
     abstract because it is configuration rather than protocol, but it is required
     when the queue is configured with ``heartbeat_interval_seconds``.
-    Lease-capable custom gateways should always expose this property; otherwise
-    the queue cannot enforce lease-specific fail-closed checks and will treat the
-    gateway as a non-lease implementation.
+    Lease-capable custom gateways MUST expose this property; omitting it
+    silently disables heartbeat validation and lease-token safety checks,
+    causing the queue to treat the gateway as a non-lease implementation.
+
+    Gateways that wrap a Redis Cluster client should expose an
+    ``is_redis_cluster`` property returning ``True`` so the queue can apply
+    hash-tag validation at construction time.
 
     Concurrency
     -----------

{redis_message_queue-2.1.0 → redis_message_queue-3.1.0}/redis_message_queue/_config.py

@@ -1,4 +1,5 @@
 import logging
+import math
 import typing
 
 import redis
@@ -19,6 +20,10 @@ from redis_message_queue.interrupt_handler._interface import (
 
 logger = logging.getLogger(__name__)
 
+DEFAULT_RETRY_BUDGET_SECONDS = 120
+DEFAULT_RETRY_MAX_DELAY_SECONDS = 5.0
+DEFAULT_RETRY_INITIAL_DELAY_SECONDS = 0.01
+
 
 def is_redis_retryable_exception(exception):
     # 1. Handle ConnectionError hierarchy (retryable except credentials/config issues)
@@ -62,10 +67,27 @@ class interruptable_retry(retry_base):
         return self._parent_instance.__call__(retry_state)
 
 
-def get_default_redis_connection_retry_strategy(*, interrupt: BaseGracefulInterruptHandler | None = None):
+def _noop_retry(func):
+    return func
+
+
+def build_retry_strategy(
+    *,
+    retry_budget_seconds: int,
+    retry_max_delay_seconds: float,
+    retry_initial_delay_seconds: float,
+    interrupt: BaseGracefulInterruptHandler | None = None,
+):
+    if retry_budget_seconds == 0:
+        return _noop_retry
     return retry(
-        stop=stop_after_delay(120),
-        wait=wait_exponential_jitter(initial=0.01, exp_base=2, max=5, jitter=0.1),
+        stop=stop_after_delay(retry_budget_seconds),
+        wait=wait_exponential_jitter(
+            initial=retry_initial_delay_seconds,
+            exp_base=2,
+            max=retry_max_delay_seconds,
+            jitter=0.1,
+        ),
         retry=interruptable_retry(
             interrupt=interrupt,
             get_parent_retry=lambda: retry_if_exception(is_redis_retryable_exception),
@@ -82,6 +104,10 @@ def validate_gateway_parameters(
     message_deduplication_log_ttl_seconds: int,
     message_wait_interval_seconds: int,
     message_visibility_timeout_seconds: int | None = None,
+    *,
+    retry_budget_seconds: int,
+    retry_max_delay_seconds: float,
+    retry_initial_delay_seconds: float,
 ) -> None:
     if not isinstance(message_deduplication_log_ttl_seconds, int) or isinstance(
         message_deduplication_log_ttl_seconds, bool
@@ -114,6 +140,30 @@ def validate_gateway_parameters(
                 f"got {message_visibility_timeout_seconds}"
             )
 
+    if not isinstance(retry_budget_seconds, int) or isinstance(retry_budget_seconds, bool):
+        raise TypeError(f"'retry_budget_seconds' must be an int, got {type(retry_budget_seconds).__name__}")
+    if retry_budget_seconds < 0:
+        raise ValueError(f"'retry_budget_seconds' must be non-negative, got {retry_budget_seconds}")
+
+    if isinstance(retry_max_delay_seconds, bool) or not isinstance(retry_max_delay_seconds, (int, float)):
+        raise TypeError(f"'retry_max_delay_seconds' must be a number, got {type(retry_max_delay_seconds).__name__}")
+    if not math.isfinite(retry_max_delay_seconds) or retry_max_delay_seconds <= 0:
+        raise ValueError(f"'retry_max_delay_seconds' must be a finite positive number, got {retry_max_delay_seconds}")
+
+    if isinstance(retry_initial_delay_seconds, bool) or not isinstance(retry_initial_delay_seconds, (int, float)):
+        raise TypeError(
+            f"'retry_initial_delay_seconds' must be a number, got {type(retry_initial_delay_seconds).__name__}"
+        )
+    if not math.isfinite(retry_initial_delay_seconds) or retry_initial_delay_seconds <= 0:
+        raise ValueError(
+            f"'retry_initial_delay_seconds' must be a finite positive number, got {retry_initial_delay_seconds}"
+        )
+    if retry_initial_delay_seconds > retry_max_delay_seconds:
+        raise ValueError(
+            "'retry_initial_delay_seconds' must be <= 'retry_max_delay_seconds', "
+            f"got {retry_initial_delay_seconds} > {retry_max_delay_seconds}"
+        )
+
 
 def validate_dead_letter_parameters(
     max_delivery_count: int | None,

{redis_message_queue-2.1.0 → redis_message_queue-3.1.0}/redis_message_queue/_redis_gateway.py

@@ -9,19 +9,21 @@ import redis
 import redis.asyncio
 
 from redis_message_queue._abstract_redis_gateway import AbstractRedisGateway
-from redis_message_queue._callable_utils import is_async_callable
 from redis_message_queue._config import (
     CLAIM_MESSAGE_LUA_SCRIPT,
     CLAIM_MESSAGE_WITH_VISIBILITY_TIMEOUT_LUA_SCRIPT,
     DEFAULT_MESSAGE_DEDUPLICATION_LOG_TTL,
     DEFAULT_MESSAGE_WAIT_INTERVAL_SECONDS,
+    DEFAULT_RETRY_BUDGET_SECONDS,
+    DEFAULT_RETRY_INITIAL_DELAY_SECONDS,
+    DEFAULT_RETRY_MAX_DELAY_SECONDS,
     MOVE_MESSAGE_LUA_SCRIPT,
     MOVE_MESSAGE_WITH_LEASE_TOKEN_LUA_SCRIPT,
     PUBLISH_MESSAGE_LUA_SCRIPT,
     REMOVE_MESSAGE_LUA_SCRIPT,
     REMOVE_MESSAGE_WITH_LEASE_TOKEN_LUA_SCRIPT,
     RENEW_MESSAGE_LEASE_LUA_SCRIPT,
-    get_default_redis_connection_retry_strategy,
+    build_retry_strategy,
     is_redis_retryable_exception,
     validate_dead_letter_parameters,
     validate_gateway_parameters,
@@ -54,11 +56,28 @@ _VISIBILITY_TIMEOUT_POLL_INTERVAL_SECONDS = 0.25
 
 
 class RedisGateway(AbstractRedisGateway):
+    """Sync Redis gateway with built-in tenacity-based retry on transient errors.
+
+    The retry knobs (``retry_budget_seconds``, ``retry_max_delay_seconds``,
+    ``retry_initial_delay_seconds``) configure the internal tenacity strategy.
+    Setting ``retry_budget_seconds=0`` disables retry entirely (single attempt;
+    exceptions propagate). The library uses ``retry_budget_seconds`` to size the
+    operation-result cache TTL so that a successfully-acked operation cannot
+    appear "not removed" to a retry that arrives after the budget elapses.
+
+    Power-user escape hatch: to plug in a different retry library
+    (``backoff``, ``asyncstdlib.retry``, custom exponential backoff, etc.) or
+    fundamentally different retry semantics, subclass
+    :class:`AbstractRedisGateway` and override the operation methods directly.
+    """
+
     def __init__(
         self,
         *,
         redis_client: redis.Redis,
-        retry_strategy: Optional[Callable] = None,
+        retry_budget_seconds: int = DEFAULT_RETRY_BUDGET_SECONDS,
+        retry_max_delay_seconds: float = DEFAULT_RETRY_MAX_DELAY_SECONDS,
+        retry_initial_delay_seconds: float = DEFAULT_RETRY_INITIAL_DELAY_SECONDS,
         message_deduplication_log_ttl_seconds: Optional[int] = None,
         message_wait_interval_seconds: Optional[int] = None,
         message_visibility_timeout_seconds: Optional[int] = None,
@@ -78,21 +97,9 @@ class RedisGateway(AbstractRedisGateway):
                 "Pass the underlying redis.Redis instance instead."
             )
         self._redis_client = redis_client
-        if retry_strategy is not None and not callable(retry_strategy):
-            raise TypeError(f"'retry_strategy' must be callable, got {type(retry_strategy).__name__}")
-        if retry_strategy is not None and is_async_callable(retry_strategy):
-            raise TypeError(
-                "'retry_strategy' is an async callable; "
-                "use the async RedisGateway from redis_message_queue.asyncio instead"
-            )
         if interrupt is not None and not isinstance(interrupt, BaseGracefulInterruptHandler):
             raise TypeError(f"'interrupt' must be a BaseGracefulInterruptHandler, got {type(interrupt).__name__}")
         self._interrupt = interrupt
-        self._retry_strategy = (
-            get_default_redis_connection_retry_strategy(interrupt=interrupt)
-            if retry_strategy is None
-            else retry_strategy
-        )
         self._message_deduplication_log_ttl_seconds = (
             DEFAULT_MESSAGE_DEDUPLICATION_LOG_TTL
             if message_deduplication_log_ttl_seconds is None
@@ -108,12 +115,22 @@ class RedisGateway(AbstractRedisGateway):
             self._message_deduplication_log_ttl_seconds,
             self._message_wait_interval_seconds,
             self._message_visibility_timeout_seconds,
+            retry_budget_seconds=retry_budget_seconds,
+            retry_max_delay_seconds=retry_max_delay_seconds,
+            retry_initial_delay_seconds=retry_initial_delay_seconds,
         )
         validate_dead_letter_parameters(
             max_delivery_count,
             dead_letter_queue,
             self._message_visibility_timeout_seconds,
         )
+        self._retry_budget_seconds = retry_budget_seconds
+        self._retry_strategy = build_retry_strategy(
+            retry_budget_seconds=retry_budget_seconds,
+            retry_max_delay_seconds=retry_max_delay_seconds,
+            retry_initial_delay_seconds=retry_initial_delay_seconds,
+            interrupt=interrupt,
+        )
         self._max_delivery_count = max_delivery_count
         self._dead_letter_queue = dead_letter_queue
         self._pending_claim_ids: dict[str, list[str]] = {}
@@ -572,23 +589,20 @@ class RedisGateway(AbstractRedisGateway):
         return f"{processing_queue}{_OPERATION_RESULT_SUFFIX}:{lease_token}:{operation_id}"
 
     def _publish_operation_result_ttl_ms(self) -> str:
-        return str(max(self._message_deduplication_log_ttl_seconds, 3600) * 1000)
+        return str(max(self._message_deduplication_log_ttl_seconds, 3600, self._retry_budget_seconds + 180) * 1000)
 
     def _operation_result_ttl_ms(self) -> str:
-        # Floor is 300s so the cached result outlives tenacity's
-        # stop_after_delay(120) retry budget with margin. Equal deadlines
-        # produce a boundary race where a retry arriving past 120s finds the
-        # cache just expired and wrongly returns 0.
+        # Floor is derived from the configured retry budget so the cached
+        # operation result outlives the retry window with a 180s margin. Equal
+        # deadlines produce a boundary race where a retry arriving past the
+        # budget finds the cache just expired and re-runs the Lua, which then
+        # observes LREM=0 for an already-acked message and returns False.
         #
-        # This is ALSO an upper bound on any caller-supplied ``retry_strategy``:
-        # a custom retry budget longer than max(visibility_timeout, 300) can
-        # step past this TTL and re-run the Lua with a stale cache, causing an
-        # already-acked move/remove to report False. Documented in README under
-        # the custom gateway section.
-        ttl_seconds = self._message_visibility_timeout_seconds
-        if ttl_seconds is None:
-            ttl_seconds = 120
-        return str(max(ttl_seconds, 300) * 1000)
+        # Sized internally from ``retry_budget_seconds`` (which the library now
+        # owns), so the relationship is a structural invariant rather than a
+        # caller-supplied constraint.
+        vt_seconds = self._message_visibility_timeout_seconds or 0
+        return str(max(vt_seconds, self._retry_budget_seconds + 180) * 1000)
 
     def _lease_operation_result_ttl_ms(self) -> str:
         return self._operation_result_ttl_ms()
@@ -671,8 +685,6 @@ class RedisGateway(AbstractRedisGateway):
         claim_result_key = self._claim_result_key(processing_queue, claim_id)
         cached_claim = self._redis_client.get(claim_result_key)
         if cached_claim is None:
-            if self._is_interrupted():
-                return None
             cached_claim = self._redis_client.hget(self._claim_result_ids_key(processing_queue), claim_id)
             if cached_claim is None:
                 return None
@@ -687,8 +699,6 @@ class RedisGateway(AbstractRedisGateway):
         claim_result_key = self._claim_result_key(processing_queue, claim_id)
         cached_claim = self._redis_client.get(claim_result_key)
         if cached_claim is None:
-            if self._is_interrupted():
-                return None
             cached_claim = self._redis_client.hget(self._claim_result_ids_key(processing_queue), claim_id)
             if cached_claim is None:
                 return None

{redis_message_queue-2.1.0 → redis_message_queue-3.1.0}/redis_message_queue/asyncio/_abstract_redis_gateway.py

@@ -12,13 +12,17 @@ class AbstractRedisGateway(ABC):
     documented on each method to avoid phantom heartbeats, undetected lease conflicts,
     or silent data loss.
 
-    Gateways that support visibility timeouts (lease-based claiming) should expose
+    Gateways that support visibility timeouts (lease-based claiming) MUST expose
     a ``message_visibility_timeout_seconds`` property (int or None). This is not
     abstract because it is configuration rather than protocol, but it is required
     when the queue is configured with ``heartbeat_interval_seconds``.
-    Lease-capable custom gateways should always expose this property; otherwise
-    the queue cannot enforce lease-specific fail-closed checks and will treat the
-    gateway as a non-lease implementation.
+    Lease-capable custom gateways MUST expose this property; omitting it
+    silently disables heartbeat validation and lease-token safety checks,
+    causing the queue to treat the gateway as a non-lease implementation.
+
+    Gateways that wrap a Redis Cluster client should expose an
+    ``is_redis_cluster`` property returning ``True`` so the queue can apply
+    hash-tag validation at construction time.
 
     Concurrency
     -----------

{redis_message_queue-2.1.0 → redis_message_queue-3.1.0}/redis_message_queue/asyncio/_redis_gateway.py

@@ -8,19 +8,21 @@ from typing import Awaitable, Callable, Optional, TypeVar
 import redis
 import redis.asyncio
 
-from redis_message_queue._callable_utils import is_async_callable
 from redis_message_queue._config import (
     CLAIM_MESSAGE_LUA_SCRIPT,
     CLAIM_MESSAGE_WITH_VISIBILITY_TIMEOUT_LUA_SCRIPT,
     DEFAULT_MESSAGE_DEDUPLICATION_LOG_TTL,
     DEFAULT_MESSAGE_WAIT_INTERVAL_SECONDS,
+    DEFAULT_RETRY_BUDGET_SECONDS,
+    DEFAULT_RETRY_INITIAL_DELAY_SECONDS,
+    DEFAULT_RETRY_MAX_DELAY_SECONDS,
     MOVE_MESSAGE_LUA_SCRIPT,
     MOVE_MESSAGE_WITH_LEASE_TOKEN_LUA_SCRIPT,
     PUBLISH_MESSAGE_LUA_SCRIPT,
     REMOVE_MESSAGE_LUA_SCRIPT,
     REMOVE_MESSAGE_WITH_LEASE_TOKEN_LUA_SCRIPT,
     RENEW_MESSAGE_LEASE_LUA_SCRIPT,
-    get_default_redis_connection_retry_strategy,
+    build_retry_strategy,
     is_redis_retryable_exception,
     validate_dead_letter_parameters,
     validate_gateway_parameters,
@@ -54,11 +56,28 @@ _VISIBILITY_TIMEOUT_POLL_INTERVAL_SECONDS = 0.25
 
 
 class RedisGateway(AbstractRedisGateway):
+    """Async Redis gateway with built-in tenacity-based retry on transient errors.
+
+    The retry knobs (``retry_budget_seconds``, ``retry_max_delay_seconds``,
+    ``retry_initial_delay_seconds``) configure the internal tenacity strategy.
+    Setting ``retry_budget_seconds=0`` disables retry entirely (single attempt;
+    exceptions propagate). The library uses ``retry_budget_seconds`` to size the
+    operation-result cache TTL so that a successfully-acked operation cannot
+    appear "not removed" to a retry that arrives after the budget elapses.
+
+    Power-user escape hatch: to plug in a different retry library
+    (``backoff``, ``asyncstdlib.retry``, custom exponential backoff, etc.) or
+    fundamentally different retry semantics, subclass
+    :class:`AbstractRedisGateway` and override the operation methods directly.
+    """
+
     def __init__(
         self,
         *,
         redis_client: redis.asyncio.Redis,
-        retry_strategy: Optional[Callable] = None,
+        retry_budget_seconds: int = DEFAULT_RETRY_BUDGET_SECONDS,
+        retry_max_delay_seconds: float = DEFAULT_RETRY_MAX_DELAY_SECONDS,
+        retry_initial_delay_seconds: float = DEFAULT_RETRY_INITIAL_DELAY_SECONDS,
         message_deduplication_log_ttl_seconds: Optional[int] = None,
         message_wait_interval_seconds: Optional[int] = None,
         message_visibility_timeout_seconds: Optional[int] = None,
@@ -78,21 +97,9 @@ class RedisGateway(AbstractRedisGateway):
                 "Pass the underlying redis.asyncio.Redis instance instead."
             )
         self._redis_client = redis_client
-        if retry_strategy is not None and not callable(retry_strategy):
-            raise TypeError(f"'retry_strategy' must be callable, got {type(retry_strategy).__name__}")
-        if retry_strategy is not None and is_async_callable(retry_strategy):
-            raise TypeError(
-                "'retry_strategy' must not be an async callable. "
-                "Provide a synchronous callable decorator (e.g., tenacity.retry(...))"
-            )
         if interrupt is not None and not isinstance(interrupt, BaseGracefulInterruptHandler):
             raise TypeError(f"'interrupt' must be a BaseGracefulInterruptHandler, got {type(interrupt).__name__}")
         self._interrupt = interrupt
-        self._retry_strategy = (
-            get_default_redis_connection_retry_strategy(interrupt=interrupt)
-            if retry_strategy is None
-            else retry_strategy
-        )
         self._message_deduplication_log_ttl_seconds = (
             DEFAULT_MESSAGE_DEDUPLICATION_LOG_TTL
             if message_deduplication_log_ttl_seconds is None
@@ -108,12 +115,22 @@ class RedisGateway(AbstractRedisGateway):
             self._message_deduplication_log_ttl_seconds,
             self._message_wait_interval_seconds,
             self._message_visibility_timeout_seconds,
+            retry_budget_seconds=retry_budget_seconds,
+            retry_max_delay_seconds=retry_max_delay_seconds,
+            retry_initial_delay_seconds=retry_initial_delay_seconds,
         )
         validate_dead_letter_parameters(
             max_delivery_count,
             dead_letter_queue,
             self._message_visibility_timeout_seconds,
         )
+        self._retry_budget_seconds = retry_budget_seconds
+        self._retry_strategy = build_retry_strategy(
+            retry_budget_seconds=retry_budget_seconds,
+            retry_max_delay_seconds=retry_max_delay_seconds,
+            retry_initial_delay_seconds=retry_initial_delay_seconds,
+            interrupt=interrupt,
+        )
         self._max_delivery_count = max_delivery_count
         self._dead_letter_queue = dead_letter_queue
         self._pending_claim_ids: dict[str, list[str]] = {}
@@ -573,23 +590,20 @@ class RedisGateway(AbstractRedisGateway):
         return f"{processing_queue}{_OPERATION_RESULT_SUFFIX}:{lease_token}:{operation_id}"
 
     def _publish_operation_result_ttl_ms(self) -> str:
-        return str(max(self._message_deduplication_log_ttl_seconds, 3600) * 1000)
+        return str(max(self._message_deduplication_log_ttl_seconds, 3600, self._retry_budget_seconds + 180) * 1000)
 
     def _operation_result_ttl_ms(self) -> str:
-        # Floor is 300s so the cached result outlives tenacity's
-        # stop_after_delay(120) retry budget with margin. Equal deadlines
-        # produce a boundary race where a retry arriving past 120s finds the
-        # cache just expired and wrongly returns 0.
+        # Floor is derived from the configured retry budget so the cached
+        # operation result outlives the retry window with a 180s margin. Equal
+        # deadlines produce a boundary race where a retry arriving past the
+        # budget finds the cache just expired and re-runs the Lua, which then
+        # observes LREM=0 for an already-acked message and returns False.
         #
-        # This is ALSO an upper bound on any caller-supplied ``retry_strategy``:
-        # a custom retry budget longer than max(visibility_timeout, 300) can
-        # step past this TTL and re-run the Lua with a stale cache, causing an
-        # already-acked move/remove to report False. Documented in README under
-        # the custom gateway section.
-        ttl_seconds = self._message_visibility_timeout_seconds
-        if ttl_seconds is None:
-            ttl_seconds = 120
-        return str(max(ttl_seconds, 300) * 1000)
+        # Sized internally from ``retry_budget_seconds`` (which the library now
+        # owns), so the relationship is a structural invariant rather than a
+        # caller-supplied constraint.
+        vt_seconds = self._message_visibility_timeout_seconds or 0
+        return str(max(vt_seconds, self._retry_budget_seconds + 180) * 1000)
 
     def _lease_operation_result_ttl_ms(self) -> str:
         return self._operation_result_ttl_ms()
@@ -672,8 +686,6 @@ class RedisGateway(AbstractRedisGateway):
         claim_result_key = self._claim_result_key(processing_queue, claim_id)
         cached_claim = await self._redis_client.get(claim_result_key)
         if cached_claim is None:
-            if self._is_interrupted():
-                return None
             cached_claim = await self._redis_client.hget(self._claim_result_ids_key(processing_queue), claim_id)
             if cached_claim is None:
                 return None
@@ -688,8 +700,6 @@ class RedisGateway(AbstractRedisGateway):
         claim_result_key = self._claim_result_key(processing_queue, claim_id)
         cached_claim = await self._redis_client.get(claim_result_key)
         if cached_claim is None:
-            if self._is_interrupted():
-                return None
             cached_claim = await self._redis_client.hget(self._claim_result_ids_key(processing_queue), claim_id)
             if cached_claim is None:
                 return None

{redis_message_queue-2.1.0 → redis_message_queue-3.1.0}/redis_message_queue/asyncio/redis_message_queue.py

@@ -20,6 +20,17 @@ logger = logging.getLogger(__name__)
 _T = TypeVar("_T")
 _GATEWAY_BOUND_PENDING_QUEUE_ATTR = "_rmq_bound_pending_queue"
 
+_STALE_LEASE_ACK_WARNING = (
+    "Message cleanup after successful processing was a no-op: "
+    "the lease expired and the message was likely reclaimed by another consumer. "
+    "This is expected at-least-once delivery behavior under visibility timeout."
+)
+_STALE_LEASE_NACK_WARNING = (
+    "Message cleanup after failed processing was a no-op: "
+    "the lease expired and the message was likely reclaimed by another consumer. "
+    "This is expected at-least-once delivery behavior under visibility timeout."
+)
+
 
 class _TaskBaseException(Exception):
     def __init__(self, original: BaseException):
@@ -36,10 +47,16 @@ async def _run_operation_in_task(operation: Awaitable[_T]) -> _T:
         raise _TaskBaseException(exc) from None
 
 
+def _consume_task_exception(task: "asyncio.Task[_T]") -> None:
+    if not task.cancelled():
+        task.exception()
+
+
 async def _await_preserving_cancellation(operation: Awaitable[_T]) -> _T:
     """Finish cleanup before propagating task cancellation."""
 
     task = asyncio.create_task(_run_operation_in_task(operation))
+    task.add_done_callback(_consume_task_exception)
     try:
         return await asyncio.shield(task)
     except asyncio.CancelledError:
@@ -68,6 +85,7 @@ async def _await_suppressing_external_cancellation(operation: Awaitable[_T]) ->
     """
 
     task = asyncio.create_task(_run_operation_in_task(operation))
+    task.add_done_callback(_consume_task_exception)
     try:
         return await asyncio.shield(task)
     except asyncio.CancelledError:
@@ -103,10 +121,10 @@ def _validate_heartbeat_interval_seconds(
                 "'heartbeat_interval_seconds' requires a configured visibility timeout."
             )
         raise ValueError(require_visibility_timeout_message)
-    if heartbeat_interval_seconds > visibility_timeout_seconds / 2:
+    if heartbeat_interval_seconds >= visibility_timeout_seconds / 2:
         raise ValueError(
-            "'heartbeat_interval_seconds' must be no more than half of 'visibility_timeout_seconds' "
-            f"({heartbeat_interval_seconds} > {visibility_timeout_seconds / 2})"
+            "'heartbeat_interval_seconds' must be less than half of 'visibility_timeout_seconds' "
+            f"({heartbeat_interval_seconds} >= {visibility_timeout_seconds / 2})"
         )
     return heartbeat_interval_seconds
 
@@ -378,7 +396,6 @@ class RedisMessageQueue:
                 raise TypeError(f"'gateway' must be an AbstractRedisGateway, got {type(gateway).__name__}")
             gateway_visibility_timeout_seconds = _get_optional_gateway_visibility_timeout_seconds(gateway)
             self._requires_claimed_message = gateway_visibility_timeout_seconds is not None
-            _bind_dead_letter_gateway_to_queue(gateway, self.key.pending)
             _validate_cluster_configuration(self.key, gateway=gateway)
             if heartbeat_interval_seconds is not None:
                 gateway_visibility_timeout_seconds = _get_gateway_visibility_timeout_seconds(gateway)
@@ -395,6 +412,7 @@ class RedisMessageQueue:
                     "'max_delivery_count' cannot be provided alongside 'gateway'."
                     " Configure 'max_delivery_count' and 'dead_letter_queue' on the gateway directly instead."
                 )
+            _bind_dead_letter_gateway_to_queue(gateway, self.key.pending)
             self._redis = gateway
         elif client is None:
             raise ValueError("Either 'client' or 'gateway' must be provided.")
@@ -427,12 +445,21 @@ class RedisMessageQueue:
         """Publish a message.
 
         Dict messages are serialized via ``json.dumps(message, sort_keys=True)``.
-        Non-string dict keys are coerced to strings by ``json.dumps``, so
-        ``{1: "x"}`` and ``{"1": "x"}`` produce the same dedup key.
+        All top-level dict keys must be strings; non-string keys raise
+        ``TypeError`` to avoid silent ``json.dumps`` coercion that would
+        collapse distinct keys into the same dedup key (e.g. ``{1: "x"}``
+        vs ``{"1": "x"}``). Only top-level keys are validated; nested
+        dicts follow ``json.dumps`` defaults.
         """
         if not isinstance(message, (str, dict)):
             raise TypeError(f"'message' must be a str or dict, got {type(message).__name__}")
         if isinstance(message, dict):
+            non_str_keys = [k for k in message if not isinstance(k, str)]
+            if non_str_keys:
+                raise TypeError(
+                    "'message' dict keys must all be strings; "
+                    f"got non-string keys: {non_str_keys[:3]}" + (" (and more)" if len(non_str_keys) > 3 else "")
+                )
             message_str = json.dumps(message, sort_keys=True)
         else:
             message_str = message
@@ -519,11 +546,7 @@ class RedisMessageQueue:
                         self._remove_processed_message(stored_message, lease_token)
                     )
                 if lease_token is not None and not applied:
-                    logger.warning(
-                        "Message cleanup after failed processing was a no-op: "
-                        "the lease expired and the message was likely reclaimed by another consumer. "
-                        "This is expected at-least-once delivery behavior under visibility timeout."
-                    )
+                    logger.warning(_STALE_LEASE_NACK_WARNING)
             except BaseException:
                 logger.exception("Failed to clean up message from processing queue")
             raise
@@ -539,11 +562,7 @@ class RedisMessageQueue:
                     self._remove_processed_message(stored_message, lease_token)
                 )
             if lease_token is not None and not applied:
-                logger.warning(
-                    "Message cleanup after successful processing was a no-op: "
-                    "the lease expired and the message was likely reclaimed by another consumer. "
-                    "This is expected at-least-once delivery behavior under visibility timeout."
-                )
+                logger.warning(_STALE_LEASE_ACK_WARNING)
             finished_without_error = True
         finally:
             if lease_heartbeat is not None:

{redis_message_queue-2.1.0 → redis_message_queue-3.1.0}/redis_message_queue/interrupt_handler/_implementation.py

@@ -1,5 +1,6 @@
 import os
 import signal
+import sys
 from typing import Iterable
 
 from redis_message_queue.interrupt_handler._interface import (
@@ -70,6 +71,7 @@ class GracefulInterruptHandler(BaseGracefulInterruptHandler):
                 raise ValueError(
                     f"Signal {sig.name} already has a non-default handler installed."
                     " GracefulInterruptHandler refuses to replace existing handlers."
+                    " If running inside asyncio.run(), create the handler before asyncio.run() starts."
                 )
         self._interrupted = False
         self._verbose = verbose
@@ -91,6 +93,9 @@ class GracefulInterruptHandler(BaseGracefulInterruptHandler):
                 return
             os.kill(os.getpid(), signum)
             return
-        if self._verbose:
-            print(f"Received signal: {signal.strsignal(signum)}")
         self._interrupted = True
+        if self._verbose:
+            try:
+                print(f"Received signal: {signal.strsignal(signum)}", file=sys.stderr)
+            except Exception:
+                pass

{redis_message_queue-2.1.0 → redis_message_queue-3.1.0}/redis_message_queue/redis_message_queue.py

@@ -20,6 +20,17 @@ from redis_message_queue.interrupt_handler import BaseGracefulInterruptHandler
 logger = logging.getLogger(__name__)
 _GATEWAY_BOUND_PENDING_QUEUE_ATTR = "_rmq_bound_pending_queue"
 
+_STALE_LEASE_ACK_WARNING = (
+    "Message cleanup after successful processing was a no-op: "
+    "the lease expired and the message was likely reclaimed by another consumer. "
+    "This is expected at-least-once delivery behavior under visibility timeout."
+)
+_STALE_LEASE_NACK_WARNING = (
+    "Message cleanup after failed processing was a no-op: "
+    "the lease expired and the message was likely reclaimed by another consumer. "
+    "This is expected at-least-once delivery behavior under visibility timeout."
+)
+
 
 def _validate_heartbeat_interval_seconds(
     heartbeat_interval_seconds: int | float | None,
@@ -45,10 +56,10 @@ def _validate_heartbeat_interval_seconds(
                 "'heartbeat_interval_seconds' requires a configured visibility timeout."
             )
         raise ValueError(require_visibility_timeout_message)
-    if heartbeat_interval_seconds > visibility_timeout_seconds / 2:
+    if heartbeat_interval_seconds >= visibility_timeout_seconds / 2:
         raise ValueError(
-            "'heartbeat_interval_seconds' must be no more than half of 'visibility_timeout_seconds' "
-            f"({heartbeat_interval_seconds} > {visibility_timeout_seconds / 2})"
+            "'heartbeat_interval_seconds' must be less than half of 'visibility_timeout_seconds' "
+            f"({heartbeat_interval_seconds} >= {visibility_timeout_seconds / 2})"
         )
     return heartbeat_interval_seconds
 
@@ -338,7 +349,6 @@ class RedisMessageQueue:
                 raise TypeError(f"'gateway' must be an AbstractRedisGateway, got {type(gateway).__name__}")
             gateway_visibility_timeout_seconds = _get_optional_gateway_visibility_timeout_seconds(gateway)
             self._requires_claimed_message = gateway_visibility_timeout_seconds is not None
-            _bind_dead_letter_gateway_to_queue(gateway, self.key.pending)
             _validate_cluster_configuration(self.key, gateway=gateway)
             if heartbeat_interval_seconds is not None:
                 gateway_visibility_timeout_seconds = _get_gateway_visibility_timeout_seconds(gateway)
@@ -355,6 +365,7 @@ class RedisMessageQueue:
                     "'max_delivery_count' cannot be provided alongside 'gateway'."
                     " Configure 'max_delivery_count' and 'dead_letter_queue' on the gateway directly instead."
                 )
+            _bind_dead_letter_gateway_to_queue(gateway, self.key.pending)
             self._redis = gateway
         elif client is None:
             raise ValueError("Either 'client' or 'gateway' must be provided.")
@@ -387,12 +398,22 @@ class RedisMessageQueue:
         """Publish a message.
 
         Dict messages are serialized via ``json.dumps(message, sort_keys=True)``.
-        Non-string dict keys are coerced to strings by ``json.dumps``, so
-        ``{1: "x"}`` and ``{"1": "x"}`` produce the same dedup key.
+        All top-level dict keys must be strings; non-string keys raise
+        ``TypeError`` to avoid silent ``json.dumps`` coercion that would
+        collapse distinct keys into the same dedup key (e.g. ``{1: "x"}``
+        vs ``{"1": "x"}``). Only top-level keys are validated; nested
+        dicts follow ``json.dumps`` defaults (e.g. nested non-string keys
+        are silently coerced: integer keys become strings).
         """
         if not isinstance(message, (str, dict)):
             raise TypeError(f"'message' must be a str or dict, got {type(message).__name__}")
         if isinstance(message, dict):
+            non_str_keys = [k for k in message if not isinstance(k, str)]
+            if non_str_keys:
+                raise TypeError(
+                    "'message' dict keys must all be strings; "
+                    f"got non-string keys: {non_str_keys[:3]}" + (" (and more)" if len(non_str_keys) > 3 else "")
+                )
             message_str = json.dumps(message, sort_keys=True)
         else:
             message_str = message
@@ -483,11 +504,7 @@ class RedisMessageQueue:
                 else:
                     applied = self._remove_processed_message(stored_message, lease_token)
                 if lease_token is not None and not applied:
-                    logger.warning(
-                        "Message cleanup after failed processing was a no-op: "
-                        "the lease expired and the message was likely reclaimed by another consumer. "
-                        "This is expected at-least-once delivery behavior under visibility timeout."
-                    )
+                    logger.warning(_STALE_LEASE_NACK_WARNING)
             except BaseException:
                 logger.exception("Failed to clean up message from processing queue")
             raise
@@ -499,11 +516,7 @@ class RedisMessageQueue:
             else:
                 applied = self._remove_processed_message(stored_message, lease_token)
             if lease_token is not None and not applied:
-                logger.warning(
-                    "Message cleanup after successful processing was a no-op: "
-                    "the lease expired and the message was likely reclaimed by another consumer. "
-                    "This is expected at-least-once delivery behavior under visibility timeout."
-                )
+                logger.warning(_STALE_LEASE_ACK_WARNING)
         finally:
             if lease_heartbeat is not None:
                 lease_heartbeat.stop()