redis-message-queue 3.0.0__tar.gz → 3.1.1__tar.gz

{redis_message_queue-3.0.0 → redis_message_queue-3.1.1}/PKG-INFO

@@ -1,22 +1,32 @@
 Metadata-Version: 2.4
 Name: redis-message-queue
-Version: 3.0.0
+Version: 3.1.1
 Summary: Python message queuing with Redis and message deduplication
+License: MIT
 License-File: LICENSE
+Keywords: redis,message-queue,deduplication,task-queue
 Author: Elijas
 Author-email: 4084885+Elijas@users.noreply.github.com
 Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Distributed Computing
 Requires-Dist: redis (>=5.0.0)
 Requires-Dist: tenacity (>=8.1.0)
+Project-URL: Homepage, https://github.com/Elijas/redis-message-queue
+Project-URL: Issues, https://github.com/Elijas/redis-message-queue/issues
+Project-URL: Repository, https://github.com/Elijas/redis-message-queue
 Description-Content-Type: text/markdown
 
 # redis-message-queue
 
-[![PyPI Version](https://img.shields.io/badge/v3.0.0-version?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
+[![PyPI Version](https://img.shields.io/badge/v3.1.1-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)
@@ -150,7 +160,7 @@ This enables lease-based redelivery for messages left in `processing` by a crash
 Tradeoffs:
 - delivery becomes at-least-once after lease expiry
 - the timeout must be longer than your normal processing time if you do not use heartbeats
-- if you do use heartbeats, the heartbeat interval must be no more than half of the visibility timeout
+- if you do use heartbeats, the heartbeat interval must be less than half of the visibility timeout
 - recovery happens on consumer polling cadence rather than instantly
 - heartbeats add background renewal work for active messages
 - if a heartbeat fails (network error or stale lease), the heartbeat stops silently; the consumer continues processing but may find at ack time that the message was reclaimed by another consumer
@@ -234,12 +244,12 @@ 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`. Setting `retry_budget_seconds=0` disables retry
+`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.
+impossible. Note: tenacity may allow one additional attempt beyond the budget if the budget check passes at attempt start — total wall-clock time can exceed `retry_budget_seconds` by the duration of that final attempt.
 
 To plug in a different retry library (`backoff`, `asyncstdlib.retry`, or your
 own logic) or fundamentally different semantics, subclass
@@ -299,8 +309,10 @@ 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.
+- **Cluster detection uses `isinstance(client, RedisCluster)`.** Wrapped or instrumented cluster clients that delegate without inheriting will bypass hash-tag validation. Custom gateways should set `is_redis_cluster = True` explicitly.
 - **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-3.0.0 → redis_message_queue-3.1.1}/README.md

@@ -1,6 +1,6 @@
 # redis-message-queue
 
-[![PyPI Version](https://img.shields.io/badge/v3.0.0-version?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
+[![PyPI Version](https://img.shields.io/badge/v3.1.1-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)
@@ -134,7 +134,7 @@ This enables lease-based redelivery for messages left in `processing` by a crash
 Tradeoffs:
 - delivery becomes at-least-once after lease expiry
 - the timeout must be longer than your normal processing time if you do not use heartbeats
-- if you do use heartbeats, the heartbeat interval must be no more than half of the visibility timeout
+- if you do use heartbeats, the heartbeat interval must be less than half of the visibility timeout
 - recovery happens on consumer polling cadence rather than instantly
 - heartbeats add background renewal work for active messages
 - if a heartbeat fails (network error or stale lease), the heartbeat stops silently; the consumer continues processing but may find at ack time that the message was reclaimed by another consumer
@@ -218,12 +218,12 @@ 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`. Setting `retry_budget_seconds=0` disables retry
+`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.
+impossible. Note: tenacity may allow one additional attempt beyond the budget if the budget check passes at attempt start — total wall-clock time can exceed `retry_budget_seconds` by the duration of that final attempt.
 
 To plug in a different retry library (`backoff`, `asyncstdlib.retry`, or your
 own logic) or fundamentally different semantics, subclass
@@ -283,8 +283,10 @@ 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.
+- **Cluster detection uses `isinstance(client, RedisCluster)`.** Wrapped or instrumented cluster clients that delegate without inheriting will bypass hash-tag validation. Custom gateways should set `is_redis_cluster = True` explicitly.
 - **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-3.0.0 → redis_message_queue-3.1.1}/pyproject.toml

@@ -1,9 +1,25 @@
 [tool.poetry]
 name = "redis-message-queue"
-version = "3.0.0"
+version = "3.1.1"
 description = "Python message queuing with Redis and message deduplication"
 authors = ["Elijas <4084885+Elijas@users.noreply.github.com>"]
 readme = "README.md"
+license = "MIT"
+keywords = ["redis", "message-queue", "deduplication", "task-queue"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Distributed Computing",
+]
+
+[tool.poetry.urls]
+Homepage = "https://github.com/Elijas/redis-message-queue"
+Repository = "https://github.com/Elijas/redis-message-queue"
+Issues = "https://github.com/Elijas/redis-message-queue/issues"
 
 [tool.poetry.dependencies]
 python = "^3.12"

{redis_message_queue-3.0.0 → redis_message_queue-3.1.1}/redis_message_queue/_abstract_redis_gateway.py

@@ -11,13 +11,21 @@ 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.
+
+    The queue also reads ``max_delivery_count`` and ``dead_letter_queue``
+    from the gateway via ``getattr``. Avoid using these attribute names for
+    unrelated purposes on custom gateway implementations.
+
+    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-3.0.0 → redis_message_queue-3.1.1}/redis_message_queue/_config.py

@@ -179,6 +179,8 @@ def validate_dead_letter_parameters(
             raise ValueError("'max_delivery_count' requires 'message_visibility_timeout_seconds' to be set.")
     if dead_letter_queue is not None and not isinstance(dead_letter_queue, str):
         raise TypeError(f"'dead_letter_queue' must be a str or None, got {type(dead_letter_queue).__name__}")
+    if isinstance(dead_letter_queue, str) and dead_letter_queue and not dead_letter_queue.strip():
+        raise ValueError("'dead_letter_queue' must be a non-empty string")
     if max_delivery_count is not None and not dead_letter_queue:
         raise ValueError("'dead_letter_queue' is required when 'max_delivery_count' is set.")
     if dead_letter_queue and max_delivery_count is None:

{redis_message_queue-3.0.0 → redis_message_queue-3.1.1}/redis_message_queue/_redis_gateway.py

@@ -382,7 +382,7 @@ class RedisGateway(AbstractRedisGateway):
                     if not is_redis_retryable_exception(exc):
                         raise
                     claim_may_need_recovery = True
-                    logger.warning(non_blocking_retry_log, exc)
+                    logger.warning(non_blocking_retry_log, type(exc).__name__)
                     if self._is_interrupted():
                         pending_claim_id_to_share = claim_id
                         return None
@@ -418,7 +418,7 @@ class RedisGateway(AbstractRedisGateway):
                             pending_claim_id_to_share = claim_id
                         raise
                     claim_may_need_recovery = True
-                    logger.warning(polling_retry_log, exc)
+                    logger.warning(polling_retry_log, type(exc).__name__)
                     last_retryable_exception = exc
                 except BaseException:
                     pending_claim_id_to_share = claim_id
@@ -589,7 +589,7 @@ 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 derived from the configured retry budget so the cached
@@ -685,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
@@ -701,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-3.0.0 → redis_message_queue-3.1.1}/redis_message_queue/asyncio/_abstract_redis_gateway.py

@@ -12,13 +12,21 @@ 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.
+
+    The queue also reads ``max_delivery_count`` and ``dead_letter_queue``
+    from the gateway via ``getattr``. Avoid using these attribute names for
+    unrelated purposes on custom gateway implementations.
+
+    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-3.0.0 → redis_message_queue-3.1.1}/redis_message_queue/asyncio/_redis_gateway.py

@@ -382,7 +382,7 @@ class RedisGateway(AbstractRedisGateway):
                     if not is_redis_retryable_exception(exc):
                         raise
                     claim_may_need_recovery = True
-                    logger.warning(non_blocking_retry_log, exc)
+                    logger.warning(non_blocking_retry_log, type(exc).__name__)
                     if self._is_interrupted():
                         pending_claim_id_to_share = claim_id
                         return None
@@ -419,7 +419,7 @@ class RedisGateway(AbstractRedisGateway):
                             pending_claim_id_to_share = claim_id
                         raise
                     claim_may_need_recovery = True
-                    logger.warning(polling_retry_log, exc)
+                    logger.warning(polling_retry_log, type(exc).__name__)
                     last_retryable_exception = exc
                 except BaseException:
                     pending_claim_id_to_share = claim_id
@@ -590,7 +590,7 @@ 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 derived from the configured retry budget so the cached
@@ -686,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
@@ -702,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-3.0.0 → redis_message_queue-3.1.1}/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):
@@ -110,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
 
@@ -385,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)
@@ -402,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.")
@@ -449,7 +460,7 @@ class RedisMessageQueue:
                     "'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)
+            message_str = json.dumps(message, sort_keys=True, allow_nan=False)
         else:
             message_str = message
 
@@ -535,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
@@ -555,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-3.0.0 → redis_message_queue-3.1.1}/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 (
@@ -60,7 +61,10 @@ class GracefulInterruptHandler(BaseGracefulInterruptHandler):
                     f"'signals' must contain signal.Signals members, got {type(sig).__name__} at position {i}"
                 )
         for sig in signals:
-            current = signal.getsignal(sig)
+            try:
+                current = signal.getsignal(sig)
+            except OSError:
+                raise ValueError(f"Signal {sig.name} cannot be caught or handled by user code.")
             if _is_graceful_interrupt_handler(current):
                 raise ValueError(
                     f"Signal {sig.name} is already owned by another GracefulInterruptHandler."
@@ -70,13 +74,19 @@ 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
         self._signals = signals
         self._previous_handlers = {sig: signal.getsignal(sig) for sig in self._signals}
         for sig in self._signals:
-            signal.signal(sig, self._signal_handler)
+            try:
+                signal.signal(sig, self._signal_handler)
+            except ValueError as e:
+                if "main thread" in str(e):
+                    raise ValueError("GracefulInterruptHandler must be created on the main thread.") from e
+                raise
 
     def is_interrupted(self) -> bool:
         return self._interrupted
@@ -91,6 +101,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-3.0.0 → redis_message_queue-3.1.1}/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.")
@@ -391,7 +402,8 @@ class RedisMessageQueue:
         ``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.
+        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__}")
@@ -402,7 +414,7 @@ class RedisMessageQueue:
                     "'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)
+            message_str = json.dumps(message, sort_keys=True, allow_nan=False)
         else:
             message_str = message
 
@@ -492,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
@@ -508,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()