redis-message-queue 8.0.1__tar.gz → 8.0.3__tar.gz

{redis_message_queue-8.0.1 → redis_message_queue-8.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redis-message-queue
-Version: 8.0.1
+Version: 8.0.3
 Summary: Python message queuing with Redis and message deduplication
 License: MIT
 License-File: LICENSE
@@ -68,6 +68,13 @@ with queue.process_message() as message:
 `RedisMessageQueue` itself is not a context manager. Use
 `with queue.process_message() as message:` for each message.
 
+> **Important:** In the sync API, work inside `process_message()` must be
+> synchronous. If your handler is `async def`, returns a coroutine, or returns
+> any other awaitable, use `redis_message_queue.asyncio.RedisMessageQueue`.
+> The sync context manager does not inspect the handler's return value; an
+> unawaited coroutine can be dropped while the message is acked. An ergonomic
+> callback API that detects this is planned for v8.1.
+
 ### Async quickstart
 
 ```python
@@ -119,6 +126,12 @@ All features are optional and can be enabled or disabled as needed.
 
 See [Crash recovery with visibility timeout](#crash-recovery-with-visibility-timeout) for details and tradeoffs.
 
+> **Important:** Handler exceptions are terminal. This library is a payload
+> queue, not a task framework: raising inside `process_message()` does not
+> requeue the message. With `enable_failed_queue=False`, the message is removed
+> from `processing`; with `enable_failed_queue=True`, it is moved to the failed
+> list.
+
 ## Configuration
 
 ### Deduplication
@@ -159,6 +172,13 @@ Avoid fallback patterns such as `lambda msg: msg.get("order_id", "")`.
 Missing fields should fail loudly instead of collapsing unrelated messages into
 one deduplication key.
 
+Deduplication markers and publish retry-safety markers are Redis TTL keys. A
+large forward step in the Redis server expiration clock during an in-call retry
+window can expire those markers before the Python-side monotonic retry budget
+elapses, allowing a duplicate publish. This is an extreme anomaly, mainly
+relevant under cluster-wide NTP step corrections while a producer is retrying
+after an ambiguous Redis write.
+
 ### Success and failure tracking
 
 ```python
@@ -234,6 +254,11 @@ queue = RedisMessageQueue(
 )
 ```
 
+> **Important:** `visibility_timeout_seconds` is a lease, not a handler runtime
+> cap. rmq never interrupts a long-running handler. If the lease expires while
+> the handler continues, another consumer can reclaim and process the same
+> message concurrently.
+
 This enables lease-based redelivery for messages left in `processing` by a crashed worker and renews the lease while a healthy long-running handler is still working.
 Tradeoffs:
 - delivery becomes at-least-once after lease expiry
@@ -258,6 +283,13 @@ The callback is **advisory** — it may fire briefly after a successful `process
 
 Without a visibility timeout, messages already moved to `processing` remain there indefinitely after a consumer crash and are not redelivered, even if the crash happened before your handler started running.
 
+Visibility deadlines use Redis server time (`TIME`), not Python process time.
+A forward step in the Redis server clock can make a live lease appear expired
+and allow premature redelivery while the original consumer is still processing;
+a backward step can delay reclaim of truly abandoned messages. Treat NTP step
+corrections on Redis hosts as a deployment risk. Prefer time-synchronization
+discipline that slews corrections rather than stepping the Redis clock.
+
 ### Ordering and multi-consumer fairness
 
 The built-in queue is a shared-pull Redis list. Successful publishes push to the
@@ -354,6 +386,11 @@ while not interrupt.is_interrupted():
 > `ValueError`. A repeated owned signal falls back to the default behavior
 > (for example, a second Ctrl+C raises `KeyboardInterrupt`). If you need multiple
 > shutdown hooks, use a single handler and fan out in your own code.
+>
+> Process-global signal ownership cannot be safely chained with task-worker
+> CLIs such as Celery, RQ, or Dramatiq. Run sibling workers in separate
+> processes, or install one top-level signal owner that calls `queue.drain()`
+> / `queue.aclose()` or sets an application stop event.
 
 There are three distinct shutdown shapes; pick the one that matches your runtime:
 
@@ -383,7 +420,10 @@ if a publish is already inside the queue instance's publish path, drain waits
 for that publish to finish before it returns; publishes that arrive after the
 drained flag is set are rejected. The drained state is local to that Python
 queue object and is not written to Redis, so constructing a fresh
-`RedisMessageQueue(...)` over the same keys remains usable.
+`RedisMessageQueue(...)` over the same keys remains usable. A separate process
+or separate queue instance against the same Redis keys is not marked drained by
+this call. For multi-process graceful shutdown, each process must drain its own
+queue instances.
 
 Drain does not cancel in-flight handlers — the caller must arrange handler
 exit through normal thread/task coordination. Returns `True` if all in-memory
@@ -391,6 +431,24 @@ pending claim IDs were recovered within the timeout; `False` if the deadline
 fired or transient Redis errors left claim IDs pending (call again to retry).
 `timeout=0` reports current state without attempting recovery.
 
+#### Abandoned in-flight messages
+
+Abandoned in-flight messages are recovered lazily. Async tasks cancelled
+without `aclose()`, or sync processes killed mid-handler, can leave the message
+and its processing/lease metadata in Redis until a later consumer claim path
+triggers visibility-timeout reclaim. With visibility timeouts enabled, this is
+the designed at-least-once recovery path: the message is delayed by the lease,
+not lost. With `visibility_timeout_seconds=None`, there is no automatic reclaim
+path. For low-visibility-timeout workloads, prefer an explicit `drain()` /
+`aclose()` during shutdown so local pending claim IDs are recovered before
+process exit.
+
+`drain()` / `aclose()` timeouts are measured with Python monotonic clocks, but
+any lease deadlines they recover were created from Redis server time. The same
+Redis-clock step caveats from
+[Crash recovery with visibility timeout](#crash-recovery-with-visibility-timeout)
+apply to when abandoned work becomes reclaimable.
+
 > **Heartbeat caveat (best-effort stop):** when `heartbeat_interval_seconds` is
 > set, the heartbeat sidecar's `stop()` is bounded but not strictly quiescent —
 > a slow renewal in flight when `process_message` exits may still write to
@@ -495,6 +553,42 @@ await client.aclose()
 For the sync Redis client, call `client.close()` during application shutdown when
 you own the client lifecycle.
 
+## Migrating from RQ / Celery / Dramatiq / taskiq
+
+redis-message-queue is a payload queue, not a task framework. It has no task
+registry, job object, result backend, scheduler, workflow canvas, callback
+graph, or handler-level retry policy. Producers publish a `str` or `dict`
+payload, and consumers decide what that payload means.
+
+The most important semantic differences from sibling task libraries are:
+
+- Handler exceptions are terminal. Raising inside `process_message()` removes
+  the message from `processing`, or moves it to the failed list when
+  `enable_failed_queue=True`; it does not requeue or retry the message.
+- `visibility_timeout_seconds` is a crash/stall recovery lease, not a runtime
+  limit. Slow handlers are not interrupted; after the lease expires another
+  consumer can process the same payload concurrently.
+- `on_event` is telemetry only. Callback exceptions are logged and emitted as
+  `RuntimeWarning`, but they do not affect ack/nack, failed-queue movement, or
+  any other message outcome. Do not use `on_event` for sagas, follow-up writes,
+  billing callbacks, or other correctness-critical work.
+- Dict payloads are JSON data, not Python call arguments. JSON does not
+  preserve every Python type: tuples become lists, and sets or custom objects
+  raise unless you encode them into JSON-native values first.
+- Process-global signal ownership cannot be safely chained with Celery, RQ, or
+  Dramatiq CLI workers. Prefer one top-level owner that calls `queue.drain()`
+  or sets an application stop event, and run sibling workers in separate
+  processes.
+
+When migrating on the same Redis deployment, prefer separate Redis DBs or hard
+namespaces. Do not point a Celery, RQ, Dramatiq, or taskiq worker at an rmq
+pending key. A sibling worker can pop the rmq stored message, fail its own
+decoder, and leave the rmq queue without that message. Also avoid custom
+`key_separator` values that synthesize another library's key namespace, such as
+using `":queue:"` with a queue name that overlaps RQ keys. rmq has no fixed
+library prefix; generated keys share the Redis DB namespace with every other
+Redis user.
+
 ## Production notes
 
 ### Fork safety and pre-fork servers
@@ -610,8 +704,10 @@ Events cover publish, dedup hits, claim/empty polls, reclaim, ack/nack,
 completed/failed cleanup, DLQ moves, heartbeat renewal, stale leases, cleanup
 and trim failures, and retry attempts. Callback exceptions are logged and
 reported with `RuntimeWarning`, but never propagate into queue operations.
-Package logs remain diagnostic; use `on_event` rather than log parsing for
-metrics.
+`on_event` is telemetry only: use it for metrics, tracing, and logging, not for
+sagas, follow-up writes, billing callbacks, or other correctness-critical
+work. Package logs remain diagnostic; use `on_event` rather than log parsing
+for metrics.
 
 ```python
 from opentelemetry import trace

{redis_message_queue-8.0.1 → redis_message_queue-8.0.3}/README.md

@@ -42,6 +42,13 @@ with queue.process_message() as message:
 `RedisMessageQueue` itself is not a context manager. Use
 `with queue.process_message() as message:` for each message.
 
+> **Important:** In the sync API, work inside `process_message()` must be
+> synchronous. If your handler is `async def`, returns a coroutine, or returns
+> any other awaitable, use `redis_message_queue.asyncio.RedisMessageQueue`.
+> The sync context manager does not inspect the handler's return value; an
+> unawaited coroutine can be dropped while the message is acked. An ergonomic
+> callback API that detects this is planned for v8.1.
+
 ### Async quickstart
 
 ```python
@@ -93,6 +100,12 @@ All features are optional and can be enabled or disabled as needed.
 
 See [Crash recovery with visibility timeout](#crash-recovery-with-visibility-timeout) for details and tradeoffs.
 
+> **Important:** Handler exceptions are terminal. This library is a payload
+> queue, not a task framework: raising inside `process_message()` does not
+> requeue the message. With `enable_failed_queue=False`, the message is removed
+> from `processing`; with `enable_failed_queue=True`, it is moved to the failed
+> list.
+
 ## Configuration
 
 ### Deduplication
@@ -133,6 +146,13 @@ Avoid fallback patterns such as `lambda msg: msg.get("order_id", "")`.
 Missing fields should fail loudly instead of collapsing unrelated messages into
 one deduplication key.
 
+Deduplication markers and publish retry-safety markers are Redis TTL keys. A
+large forward step in the Redis server expiration clock during an in-call retry
+window can expire those markers before the Python-side monotonic retry budget
+elapses, allowing a duplicate publish. This is an extreme anomaly, mainly
+relevant under cluster-wide NTP step corrections while a producer is retrying
+after an ambiguous Redis write.
+
 ### Success and failure tracking
 
 ```python
@@ -208,6 +228,11 @@ queue = RedisMessageQueue(
 )
 ```
 
+> **Important:** `visibility_timeout_seconds` is a lease, not a handler runtime
+> cap. rmq never interrupts a long-running handler. If the lease expires while
+> the handler continues, another consumer can reclaim and process the same
+> message concurrently.
+
 This enables lease-based redelivery for messages left in `processing` by a crashed worker and renews the lease while a healthy long-running handler is still working.
 Tradeoffs:
 - delivery becomes at-least-once after lease expiry
@@ -232,6 +257,13 @@ The callback is **advisory** — it may fire briefly after a successful `process
 
 Without a visibility timeout, messages already moved to `processing` remain there indefinitely after a consumer crash and are not redelivered, even if the crash happened before your handler started running.
 
+Visibility deadlines use Redis server time (`TIME`), not Python process time.
+A forward step in the Redis server clock can make a live lease appear expired
+and allow premature redelivery while the original consumer is still processing;
+a backward step can delay reclaim of truly abandoned messages. Treat NTP step
+corrections on Redis hosts as a deployment risk. Prefer time-synchronization
+discipline that slews corrections rather than stepping the Redis clock.
+
 ### Ordering and multi-consumer fairness
 
 The built-in queue is a shared-pull Redis list. Successful publishes push to the
@@ -328,6 +360,11 @@ while not interrupt.is_interrupted():
 > `ValueError`. A repeated owned signal falls back to the default behavior
 > (for example, a second Ctrl+C raises `KeyboardInterrupt`). If you need multiple
 > shutdown hooks, use a single handler and fan out in your own code.
+>
+> Process-global signal ownership cannot be safely chained with task-worker
+> CLIs such as Celery, RQ, or Dramatiq. Run sibling workers in separate
+> processes, or install one top-level signal owner that calls `queue.drain()`
+> / `queue.aclose()` or sets an application stop event.
 
 There are three distinct shutdown shapes; pick the one that matches your runtime:
 
@@ -357,7 +394,10 @@ if a publish is already inside the queue instance's publish path, drain waits
 for that publish to finish before it returns; publishes that arrive after the
 drained flag is set are rejected. The drained state is local to that Python
 queue object and is not written to Redis, so constructing a fresh
-`RedisMessageQueue(...)` over the same keys remains usable.
+`RedisMessageQueue(...)` over the same keys remains usable. A separate process
+or separate queue instance against the same Redis keys is not marked drained by
+this call. For multi-process graceful shutdown, each process must drain its own
+queue instances.
 
 Drain does not cancel in-flight handlers — the caller must arrange handler
 exit through normal thread/task coordination. Returns `True` if all in-memory
@@ -365,6 +405,24 @@ pending claim IDs were recovered within the timeout; `False` if the deadline
 fired or transient Redis errors left claim IDs pending (call again to retry).
 `timeout=0` reports current state without attempting recovery.
 
+#### Abandoned in-flight messages
+
+Abandoned in-flight messages are recovered lazily. Async tasks cancelled
+without `aclose()`, or sync processes killed mid-handler, can leave the message
+and its processing/lease metadata in Redis until a later consumer claim path
+triggers visibility-timeout reclaim. With visibility timeouts enabled, this is
+the designed at-least-once recovery path: the message is delayed by the lease,
+not lost. With `visibility_timeout_seconds=None`, there is no automatic reclaim
+path. For low-visibility-timeout workloads, prefer an explicit `drain()` /
+`aclose()` during shutdown so local pending claim IDs are recovered before
+process exit.
+
+`drain()` / `aclose()` timeouts are measured with Python monotonic clocks, but
+any lease deadlines they recover were created from Redis server time. The same
+Redis-clock step caveats from
+[Crash recovery with visibility timeout](#crash-recovery-with-visibility-timeout)
+apply to when abandoned work becomes reclaimable.
+
 > **Heartbeat caveat (best-effort stop):** when `heartbeat_interval_seconds` is
 > set, the heartbeat sidecar's `stop()` is bounded but not strictly quiescent —
 > a slow renewal in flight when `process_message` exits may still write to
@@ -469,6 +527,42 @@ await client.aclose()
 For the sync Redis client, call `client.close()` during application shutdown when
 you own the client lifecycle.
 
+## Migrating from RQ / Celery / Dramatiq / taskiq
+
+redis-message-queue is a payload queue, not a task framework. It has no task
+registry, job object, result backend, scheduler, workflow canvas, callback
+graph, or handler-level retry policy. Producers publish a `str` or `dict`
+payload, and consumers decide what that payload means.
+
+The most important semantic differences from sibling task libraries are:
+
+- Handler exceptions are terminal. Raising inside `process_message()` removes
+  the message from `processing`, or moves it to the failed list when
+  `enable_failed_queue=True`; it does not requeue or retry the message.
+- `visibility_timeout_seconds` is a crash/stall recovery lease, not a runtime
+  limit. Slow handlers are not interrupted; after the lease expires another
+  consumer can process the same payload concurrently.
+- `on_event` is telemetry only. Callback exceptions are logged and emitted as
+  `RuntimeWarning`, but they do not affect ack/nack, failed-queue movement, or
+  any other message outcome. Do not use `on_event` for sagas, follow-up writes,
+  billing callbacks, or other correctness-critical work.
+- Dict payloads are JSON data, not Python call arguments. JSON does not
+  preserve every Python type: tuples become lists, and sets or custom objects
+  raise unless you encode them into JSON-native values first.
+- Process-global signal ownership cannot be safely chained with Celery, RQ, or
+  Dramatiq CLI workers. Prefer one top-level owner that calls `queue.drain()`
+  or sets an application stop event, and run sibling workers in separate
+  processes.
+
+When migrating on the same Redis deployment, prefer separate Redis DBs or hard
+namespaces. Do not point a Celery, RQ, Dramatiq, or taskiq worker at an rmq
+pending key. A sibling worker can pop the rmq stored message, fail its own
+decoder, and leave the rmq queue without that message. Also avoid custom
+`key_separator` values that synthesize another library's key namespace, such as
+using `":queue:"` with a queue name that overlaps RQ keys. rmq has no fixed
+library prefix; generated keys share the Redis DB namespace with every other
+Redis user.
+
 ## Production notes
 
 ### Fork safety and pre-fork servers
@@ -584,8 +678,10 @@ Events cover publish, dedup hits, claim/empty polls, reclaim, ack/nack,
 completed/failed cleanup, DLQ moves, heartbeat renewal, stale leases, cleanup
 and trim failures, and retry attempts. Callback exceptions are logged and
 reported with `RuntimeWarning`, but never propagate into queue operations.
-Package logs remain diagnostic; use `on_event` rather than log parsing for
-metrics.
+`on_event` is telemetry only: use it for metrics, tracing, and logging, not for
+sagas, follow-up writes, billing callbacks, or other correctness-critical
+work. Package logs remain diagnostic; use `on_event` rather than log parsing
+for metrics.
 
 ```python
 from opentelemetry import trace

{redis_message_queue-8.0.1 → redis_message_queue-8.0.3}/pyproject.toml

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

{redis_message_queue-8.0.1 → redis_message_queue-8.0.3}/redis_message_queue/__init__.py

@@ -5,6 +5,7 @@ from redis_message_queue._exceptions import (
     ConfigurationError,
     GatewayContractError,
     LuaScriptError,
+    MalformedStoredMessageError,
     QueueBackpressureError,
     QueueDrainedError,
     RedisMessageQueueError,
@@ -33,6 +34,7 @@ __all__ = [
     "ConfigurationError",
     "GatewayContractError",
     "LuaScriptError",
+    "MalformedStoredMessageError",
     "QueueBackpressureError",
     "QueueDrainedError",
     "CleanupFailedError",

{redis_message_queue-8.0.1 → redis_message_queue-8.0.3}/redis_message_queue/_config.py

@@ -50,6 +50,9 @@ def is_redis_retryable_exception(exception):
             ),
         )
 
+    if isinstance(exception, redis.exceptions.ClusterError) and "TTL exhausted" in str(exception):
+        return True
+
     # 2. Explicit retryable exceptions (BusyLoadingError is a ConnectionError
     #    subclass, so it is already handled by branch 1 above)
     return isinstance(
@@ -739,6 +742,26 @@ local function redis_message_queue_decode_claim(cached_claim)
     return nil
 end
 
+local function redis_message_queue_decode_envelope(stored)
+    local prefix = string.char(30) .. 'RMQ1:'
+    if type(stored) ~= 'string' or string.sub(stored, 1, string.len(prefix)) ~= prefix then
+        return nil
+    end
+    local ok, envelope = pcall(cjson.decode, string.sub(stored, string.len(prefix) + 1))
+    if ok and type(envelope) == 'table' and type(envelope['id']) == 'string' then
+        return envelope
+    end
+    return nil
+end
+
+local function redis_message_queue_message_id(stored)
+    local envelope = redis_message_queue_decode_envelope(stored)
+    if envelope then
+        return envelope['id']
+    end
+    return ''
+end
+
 local time = redis.call('TIME')
 local now_ms = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)
 
@@ -779,6 +802,7 @@ end
 -- With a single consumer polling at default interval, 1000 expired leases drain in ~2.5s.
 local expired = redis.call('ZRANGEBYSCORE', KEYS[3], '-inf', now_ms, 'LIMIT', 0, 100)
 local to_requeue = {}
+local reclaimed_events = {}
 for i = #expired, 1, -1 do
     local expired_lease_token = redis.call('HGET', KEYS[4], expired[i])
     redis.call('ZREM', KEYS[3], expired[i])
@@ -800,13 +824,14 @@ for i = #expired, 1, -1 do
     end
     if redis.call('LREM', KEYS[2], 1, expired[i]) == 1 then
         table.insert(to_requeue, expired[i])
+        local delivery_count = redis.call('HGET', KEYS[6], expired[i])
+        table.insert(reclaimed_events, {redis_message_queue_message_id(expired[i]), tostring(delivery_count or '0')})
     end
 end
 if #to_requeue > 0 then
     redis.call('RPUSH', KEYS[1], unpack(to_requeue))
 end
-local reclaimed_count = #to_requeue
-local dead_lettered_count = 0
+local dead_lettered_events = {}
 
 local function store_claim_and_return(stored)
     -- pcall guards against OOM mid-write: compensate by returning message to pending
@@ -819,7 +844,7 @@ local function store_claim_and_return(stored)
         redis.call('HSET', KEYS[9], lease_token, KEYS[8])
         redis.call('HSET', KEYS[10], ARGV[4], claim_payload)
         redis.call('HSET', KEYS[11], lease_token, ARGV[4])
-        return {stored, lease_token, tostring(reclaimed_count), tostring(dead_lettered_count)}
+        return {stored, lease_token, reclaimed_events, dead_lettered_events}
     end)
     if not ok then
         redis.call('LREM', KEYS[2], 1, stored)
@@ -835,36 +860,28 @@ while claim_attempts < 100 do
 
     local stored = redis.call('LMOVE', KEYS[1], KEYS[2], 'RIGHT', 'LEFT')
     if not stored then
-        return {'', '', tostring(reclaimed_count), tostring(dead_lettered_count)}
+        return {'', '', reclaimed_events, dead_lettered_events}
     end
 
-    if max_delivery_count > 0 then
-        local count = redis.call('HINCRBY', KEYS[6], stored, 1)
-        if count > max_delivery_count then
-            redis.call('LREM', KEYS[2], 1, stored)
-            redis.call('HDEL', KEYS[6], stored)
-            -- Strip envelope to store raw payload in DLQ, consistent with completed/failed queues.
-            -- The per-delivery UUID in the envelope is lost; see README dead-letter notes.
-            local dead_letter_value = stored
-            local prefix = string.char(30) .. 'RMQ1:'
-            if string.sub(stored, 1, string.len(prefix)) == prefix then
-                local ok, envelope = pcall(cjson.decode, string.sub(stored, string.len(prefix) + 1))
-                if ok and type(envelope) == 'table' and type(envelope['id']) == 'string'
-                        and type(envelope['payload']) == 'string' then
-                    dead_letter_value = envelope['payload']
-                end
-            end
-            redis.call('LPUSH', KEYS[7], dead_letter_value)
-            dead_lettered_count = dead_lettered_count + 1
-        else
-            return store_claim_and_return(stored)
+    local count = redis.call('HINCRBY', KEYS[6], stored, 1)
+    if max_delivery_count > 0 and count > max_delivery_count then
+        redis.call('LREM', KEYS[2], 1, stored)
+        redis.call('HDEL', KEYS[6], stored)
+        -- Strip envelope to store raw payload in DLQ, consistent with completed/failed queues.
+        -- The per-delivery UUID in the envelope is lost; see README dead-letter notes.
+        local dead_letter_value = stored
+        local envelope = redis_message_queue_decode_envelope(stored)
+        if envelope and type(envelope['payload']) == 'string' then
+            dead_letter_value = envelope['payload']
         end
+        redis.call('LPUSH', KEYS[7], dead_letter_value)
+        table.insert(dead_lettered_events, {redis_message_queue_message_id(stored), tostring(count)})
     else
         return store_claim_and_return(stored)
     end
 end
 
-return {'', '', tostring(reclaimed_count), tostring(dead_lettered_count)}
+return {'', '', reclaimed_events, dead_lettered_events}
 """
 )
 
@@ -1037,6 +1054,46 @@ return removed
 """
 )
 
+CLEANUP_DRAINED_LEASE_TOKEN_COUNTER_LUA_SCRIPT = (
+    _LUA_KEY_TYPE_GUARD
+    + """
+local err = redis_message_queue_require_type(KEYS[1], 'list')
+if err then
+    return err
+end
+
+local err = redis_message_queue_require_type(KEYS[2], 'zset')
+if err then
+    return err
+end
+
+local err = redis_message_queue_require_type(KEYS[3], 'hash')
+if err then
+    return err
+end
+
+local err = redis_message_queue_require_type(KEYS[4], 'hash')
+if err then
+    return err
+end
+
+local err = redis_message_queue_require_type(KEYS[5], 'string')
+if err then
+    return err
+end
+
+if redis.call('LLEN', KEYS[1]) == 0
+    and redis.call('ZCARD', KEYS[2]) == 0
+    and redis.call('HLEN', KEYS[3]) == 0
+    and redis.call('HLEN', KEYS[4]) == 0 then
+    redis.call('DEL', KEYS[5])
+    return 1
+end
+
+return 0
+"""
+)
+
 RENEW_MESSAGE_LEASE_LUA_SCRIPT = (
     _LUA_KEY_TYPE_GUARD
     + """

{redis_message_queue-8.0.1 → redis_message_queue-8.0.3}/redis_message_queue/_event.py

@@ -52,6 +52,10 @@ class QueueEvent:
     """a diagnostic hash of the lease token when visibility timeout is enabled"""
     destination_queue: str | None = None
     """the queue a message was moved to, when applicable"""
+    delivery_count: int | None = None
+    """the number of delivery attempts recorded for this message, when applicable"""
+    max_delivery_count: int | None = None
+    """the configured delivery-attempt threshold, when applicable"""
     exception_type: str | None = None
     """
     type name of the raised exception for metrics labels (e.g., 'TimeoutError');

{redis_message_queue-8.0.1 → redis_message_queue-8.0.3}/redis_message_queue/_exceptions.py

@@ -21,6 +21,10 @@ class CleanupFailedError(RedisMessageQueueError):
     """Cleanup after handler completion failed."""
 
 
+class MalformedStoredMessageError(RedisMessageQueueError):
+    """Stored value starts with the RMQ envelope prefix but is not a valid envelope."""
+
+
 class QueueBackpressureError(RedisMessageQueueError):
     """Publish rejected because the pending queue is at its configured limit."""
 

{redis_message_queue-8.0.1 → redis_message_queue-8.0.3}/redis_message_queue/_queue_key_manager.py

@@ -17,6 +17,14 @@ def validate_callable_deduplication_key(dedup_key: object, message: str | dict)
 
 
 class QueueKeyManager:
+    """Build Redis keys for one rmq queue namespace.
+
+    ``key_separator`` is part of every generated key and rmq has no fixed
+    library prefix. Do not choose a separator that overlaps another Redis task
+    library's namespace, such as ``":queue:"`` with RQ-style keys; user-chosen
+    separators interact with every Redis user on the same DB.
+    """
+
     # Logs message existence to prevent duplication.
     # Messages are marked for the duration of their lifecycle.
     _MESSAGE_DEDUPLICATION_LOG = "deduplication"

{redis_message_queue-8.0.1 → redis_message_queue-8.0.3}/redis_message_queue/_redis_cluster.py

@@ -1,4 +1,5 @@
 import re
+from collections.abc import Mapping
 
 from redis.crc import key_slot
 
@@ -6,12 +7,36 @@ from redis_message_queue._exceptions import ConfigurationError
 from redis_message_queue._queue_key_manager import QueueKeyManager
 
 _HASH_TAG_PATTERN = re.compile(r"\{([^{}]+)\}")
+PLAIN_REDIS_CLUSTER_CLIENT_MESSAGE = (
+    "The provided Redis client is a plain {client_type} connected to a Redis Cluster node "
+    "('INFO cluster' reports cluster_enabled=1). Use redis.RedisCluster or "
+    "redis.asyncio.RedisCluster instead, and use a hash-tagged queue name such as '{{myqueue}}' "
+    "so all queue keys share one Redis Cluster slot."
+)
 
 
 def _redis_cluster_key_slot(key: str) -> int:
     return key_slot(key.encode("utf-8"))
 
 
+def redis_info_reports_cluster_enabled(info: object) -> bool:
+    if not isinstance(info, Mapping):
+        return False
+
+    value = info.get("cluster_enabled")
+    if value is None:
+        value = info.get(b"cluster_enabled")
+    if isinstance(value, bytes):
+        value = value.decode("utf-8", errors="replace")
+    if isinstance(value, str):
+        return value.strip() == "1"
+    return value == 1
+
+
+def plain_redis_cluster_client_error(client_type: str) -> ConfigurationError:
+    return ConfigurationError(PLAIN_REDIS_CLUSTER_CLIENT_MESSAGE.format(client_type=client_type))
+
+
 def validate_queue_keys_for_redis_cluster(
     key_manager: QueueKeyManager,
     *,