redis-message-queue 7.0.0__tar.gz → 7.0.1__tar.gz

{redis_message_queue-7.0.0 → redis_message_queue-7.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redis-message-queue
-Version: 7.0.0
+Version: 7.0.1
 Summary: Python message queuing with Redis and message deduplication
 License: MIT
 License-File: LICENSE
@@ -26,7 +26,7 @@ Description-Content-Type: text/markdown
 
 # redis-message-queue
 
-[![PyPI Version](https://img.shields.io/badge/v7.0.0-version?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
+[![PyPI Version](https://img.shields.io/badge/v7.0.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)
@@ -37,46 +37,50 @@ 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>=6.0.0,<7.0.0"
+pip install "redis-message-queue>=7.0.0,<8.0.0"
 ```
 
 Requires Redis server >= 6.2.
 
 ## Quickstart
 
-### Publish messages
+Redis must be running locally first: use `redis-server` or
+`docker run -p 6379:6379 redis:7`.
 
 ```python
 from redis import Redis
 from redis_message_queue import RedisMessageQueue
 
 client = Redis.from_url("redis://localhost:6379/0", decode_responses=True)
-queue = RedisMessageQueue("my_queue", client=client, deduplication=True)
-
-queue.publish("order:1234")           # returns True
-queue.publish("order:1234")           # returns False (deduplicated)
-queue.publish({"user": "alice"})      # dicts work too
+queue = RedisMessageQueue("quickstart", client=client, deduplication=True)
+queue.publish("hello")
+with queue.process_message() as message:
+    if message is not None:
+        print(f"got {message}")
+# Expected output: got hello
 ```
 
-### Consume messages
+`RedisMessageQueue` itself is not a context manager. Use
+`with queue.process_message() as message:` for each message.
+
+### Async quickstart
 
 ```python
-from redis import Redis
-from redis_message_queue import RedisMessageQueue
+import asyncio
+from redis.asyncio import Redis
+from redis_message_queue.asyncio import RedisMessageQueue
 
-client = Redis.from_url("redis://localhost:6379/0", decode_responses=True)
-queue = RedisMessageQueue("my_queue", client=client)
+async def main():
+    client = Redis.from_url("redis://localhost:6379/0", decode_responses=True)
+    queue = RedisMessageQueue("quickstart", client=client, deduplication=True)
+    await queue.publish("hello")
+    async with queue.process_message() as message:
+        print(f"got {message}")
+    await client.aclose()
 
-while True:
-    with queue.process_message() as message:
-        if message is not None:
-            print(f"Processing: {message}")
-            # Auto-acknowledged on success; cleaned up on exception
+asyncio.run(main())  # Expected output: got hello
 ```
 
-`RedisMessageQueue` itself is not a context manager. Use
-`with queue.process_message() as message:` for each message.
-
 ## Why redis-message-queue
 
 **The problem:** You're sending messages between services or workers and need guarantees. Simple Redis LPUSH/BRPOP loses messages on crashes, doesn't deduplicate, and gives you no visibility into what succeeded or failed.
@@ -124,6 +128,29 @@ queue = RedisMessageQueue(
 queue = RedisMessageQueue("q", client=client, deduplication=False)
 ```
 
+#### Custom dedup key callable must return a non-empty, high-cardinality, tenant-scoped string
+
+When `get_deduplication_key` is a callable, it is called once per publish and
+must return a `str` that uniquely represents the deduplication scope for that
+message. Returning `None` or `""` raises `ConfigurationError` at publish time;
+returning a non-`str` value raises `TypeError`.
+
+Use stable, high-cardinality keys that include any tenant or account boundary
+needed by your system:
+
+```python
+queue = RedisMessageQueue(
+    "orders",
+    client=client,
+    deduplication=True,
+    get_deduplication_key=lambda msg: f"{msg['tenant_id']}:{msg['order_id']}",
+)
+```
+
+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.
+
 ### Success and failure tracking
 
 ```python
@@ -588,17 +615,46 @@ events_total = Counter(
     "redis-message-queue lifecycle events",
     ["queue", "operation", "outcome", "exception_type"],
 )
+SPAN_SINK_TRUSTED = False
 
 def observe(event: QueueEvent) -> None:
     events_total.labels(
         event.queue, event.operation, event.outcome, event.exception_type or ""
     ).inc()
-    if event.error is not None:
+    if event.error is not None and SPAN_SINK_TRUSTED:
         trace.get_current_span().record_exception(event.error)
 
 queue = RedisMessageQueue("jobs", client=client, on_event=observe)
 ```
 
+#### ⚠ Secrets in `event.error`
+
+`event.error` is the actual exception object — it retains the exception
+message, `__cause__` chain, and traceback. These can contain sensitive content:
+Redis credentials in connection-error messages, message payloads in handler
+exceptions, environment values in stack-frame locals.
+
+When exporting to telemetry sinks (OpenTelemetry, Sentry, Datadog), prefer the
+redaction-friendly `event.exception_type` for metrics and labels. Use
+`event.error` for full structured error data ONLY if your sink is
+trust-equivalent to your application logs and is access-controlled.
+
+Recommended pattern:
+
+```python
+def on_event(event: QueueEvent) -> None:
+    # Metric labels — always safe (just the exception class name)
+    metric_counter.labels(
+        operation=event.operation,
+        outcome=event.outcome,
+        exception_type=event.exception_type or "none",
+    ).inc()
+
+    # Full exception — only if your span sink is trusted
+    if event.error is not None and SPAN_SINK_TRUSTED:
+        span.record_exception(event.error)
+```
+
 #### Event dispatch context
 
 Callbacks fire inline:
@@ -704,10 +760,39 @@ For a full analysis, see [docs/production-readiness.md](docs/production-readines
 
 ### v6 to v7 migration
 
-v7.0.0 changes explicit drain shutdown semantics. After `queue.drain()` /
-`queue.close()` (sync) or `await queue.drain()` / `await queue.aclose()`
-(async), the same queue instance rejects `publish()` with
-`QueueDrainedError("queue is drained")`.
+v7.0.0 has four breaking changes to check during upgrade.
+
+**AC-02: queue event operation/outcome types are `StrEnum` members.**
+Runtime string comparisons keep working because `StrEnum` subclasses `str`,
+but type-strict code should replace old `Literal[...]` annotations and raw
+string constants with enum members.
+
+Before:
+
+```python
+from typing import Literal
+
+QueueOperation = Literal["publish", "claim", "ack"]
+
+def record(operation: QueueOperation) -> None:
+    if operation == "publish":
+        print("published")
+```
+
+After:
+
+```python
+from redis_message_queue import EventOperation
+
+def record(operation: EventOperation) -> None:
+    if operation is EventOperation.PUBLISH:
+        print("published")
+```
+
+**AC-03: drained queue instances refuse new publishes.** After
+`queue.drain()` / `queue.close()` (sync) or `await queue.drain()` /
+`await queue.aclose()` (async), the same queue instance rejects `publish()`
+with `QueueDrainedError("queue is drained")`.
 
 This state is queue-local and process-local; it is not stored in Redis. If a
 producer must continue publishing after a worker has drained, use a separate
@@ -715,6 +800,42 @@ producer must continue publishing after a worker has drained, use a separate
 shutdown, catch `QueueDrainedError` only at boundaries where late publishes are
 expected and safe to drop or reschedule.
 
+```python
+from redis_message_queue import QueueDrainedError
+
+try:
+    queue.publish("late shutdown audit event")
+except QueueDrainedError:
+    # The queue instance already began draining; drop or reschedule elsewhere.
+    pass
+```
+
+**AC-09: unsafe `drop_oldest` combinations now fail at construction.** These
+configurations raise `ConfigurationError` before the queue or gateway is
+created:
+
+- `pending_overload_policy="drop_oldest"` with `max_pending_length=None`:
+  `drop_oldest requires max_pending_length to be set. Use a positive
+  max_pending_length to define what can be dropped, or use
+  pending_overload_policy='raise' or 'block' for unbounded queues.`
+- `pending_overload_policy="drop_oldest"` with deduplication enabled or
+  `get_deduplication_key` configured:
+  `'pending_overload_policy=drop_oldest' cannot be used with deduplication
+  because dropped messages leave their deduplication keys in Redis, causing
+  future publishes of the same payload to be silently suppressed. Use 'raise'
+  or 'block' for deduplicated queues, or disable deduplication if 'drop_oldest'
+  is required.`
+- `pending_overload_policy="drop_oldest"` with `max_delivery_count` set:
+  `drop_oldest is incompatible with max_delivery_count (set
+  max_delivery_count=None or pick another policy to avoid silent loss of
+  pending DLQ candidates). Use pending_overload_policy='raise' or 'block' when
+  dead-letter handling is required.`
+
+**AC-16: redis-py is capped below 8.0.0.** The package dependency is
+`redis>=5.0.0,<8.0.0` until redis-py 8 RESP3-default behavior is verified.
+Users on redis-py 7.x and earlier are unaffected. If you installed a redis-py
+8.0.0 beta explicitly, downgrade with `pip install "redis<8.0.0"`.
+
 ### Configuration changes on live queues
 
 > **Warning:** These changes are destructive on live queues. Drain the queue completely before applying them.

{redis_message_queue-7.0.0 → redis_message_queue-7.0.1}/README.md

@@ -1,6 +1,6 @@
 # redis-message-queue
 
-[![PyPI Version](https://img.shields.io/badge/v7.0.0-version?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
+[![PyPI Version](https://img.shields.io/badge/v7.0.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)
@@ -11,46 +11,50 @@
 **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>=6.0.0,<7.0.0"
+pip install "redis-message-queue>=7.0.0,<8.0.0"
 ```
 
 Requires Redis server >= 6.2.
 
 ## Quickstart
 
-### Publish messages
+Redis must be running locally first: use `redis-server` or
+`docker run -p 6379:6379 redis:7`.
 
 ```python
 from redis import Redis
 from redis_message_queue import RedisMessageQueue
 
 client = Redis.from_url("redis://localhost:6379/0", decode_responses=True)
-queue = RedisMessageQueue("my_queue", client=client, deduplication=True)
-
-queue.publish("order:1234")           # returns True
-queue.publish("order:1234")           # returns False (deduplicated)
-queue.publish({"user": "alice"})      # dicts work too
+queue = RedisMessageQueue("quickstart", client=client, deduplication=True)
+queue.publish("hello")
+with queue.process_message() as message:
+    if message is not None:
+        print(f"got {message}")
+# Expected output: got hello
 ```
 
-### Consume messages
+`RedisMessageQueue` itself is not a context manager. Use
+`with queue.process_message() as message:` for each message.
+
+### Async quickstart
 
 ```python
-from redis import Redis
-from redis_message_queue import RedisMessageQueue
+import asyncio
+from redis.asyncio import Redis
+from redis_message_queue.asyncio import RedisMessageQueue
 
-client = Redis.from_url("redis://localhost:6379/0", decode_responses=True)
-queue = RedisMessageQueue("my_queue", client=client)
+async def main():
+    client = Redis.from_url("redis://localhost:6379/0", decode_responses=True)
+    queue = RedisMessageQueue("quickstart", client=client, deduplication=True)
+    await queue.publish("hello")
+    async with queue.process_message() as message:
+        print(f"got {message}")
+    await client.aclose()
 
-while True:
-    with queue.process_message() as message:
-        if message is not None:
-            print(f"Processing: {message}")
-            # Auto-acknowledged on success; cleaned up on exception
+asyncio.run(main())  # Expected output: got hello
 ```
 
-`RedisMessageQueue` itself is not a context manager. Use
-`with queue.process_message() as message:` for each message.
-
 ## Why redis-message-queue
 
 **The problem:** You're sending messages between services or workers and need guarantees. Simple Redis LPUSH/BRPOP loses messages on crashes, doesn't deduplicate, and gives you no visibility into what succeeded or failed.
@@ -98,6 +102,29 @@ queue = RedisMessageQueue(
 queue = RedisMessageQueue("q", client=client, deduplication=False)
 ```
 
+#### Custom dedup key callable must return a non-empty, high-cardinality, tenant-scoped string
+
+When `get_deduplication_key` is a callable, it is called once per publish and
+must return a `str` that uniquely represents the deduplication scope for that
+message. Returning `None` or `""` raises `ConfigurationError` at publish time;
+returning a non-`str` value raises `TypeError`.
+
+Use stable, high-cardinality keys that include any tenant or account boundary
+needed by your system:
+
+```python
+queue = RedisMessageQueue(
+    "orders",
+    client=client,
+    deduplication=True,
+    get_deduplication_key=lambda msg: f"{msg['tenant_id']}:{msg['order_id']}",
+)
+```
+
+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.
+
 ### Success and failure tracking
 
 ```python
@@ -562,17 +589,46 @@ events_total = Counter(
     "redis-message-queue lifecycle events",
     ["queue", "operation", "outcome", "exception_type"],
 )
+SPAN_SINK_TRUSTED = False
 
 def observe(event: QueueEvent) -> None:
     events_total.labels(
         event.queue, event.operation, event.outcome, event.exception_type or ""
     ).inc()
-    if event.error is not None:
+    if event.error is not None and SPAN_SINK_TRUSTED:
         trace.get_current_span().record_exception(event.error)
 
 queue = RedisMessageQueue("jobs", client=client, on_event=observe)
 ```
 
+#### ⚠ Secrets in `event.error`
+
+`event.error` is the actual exception object — it retains the exception
+message, `__cause__` chain, and traceback. These can contain sensitive content:
+Redis credentials in connection-error messages, message payloads in handler
+exceptions, environment values in stack-frame locals.
+
+When exporting to telemetry sinks (OpenTelemetry, Sentry, Datadog), prefer the
+redaction-friendly `event.exception_type` for metrics and labels. Use
+`event.error` for full structured error data ONLY if your sink is
+trust-equivalent to your application logs and is access-controlled.
+
+Recommended pattern:
+
+```python
+def on_event(event: QueueEvent) -> None:
+    # Metric labels — always safe (just the exception class name)
+    metric_counter.labels(
+        operation=event.operation,
+        outcome=event.outcome,
+        exception_type=event.exception_type or "none",
+    ).inc()
+
+    # Full exception — only if your span sink is trusted
+    if event.error is not None and SPAN_SINK_TRUSTED:
+        span.record_exception(event.error)
+```
+
 #### Event dispatch context
 
 Callbacks fire inline:
@@ -678,10 +734,39 @@ For a full analysis, see [docs/production-readiness.md](docs/production-readines
 
 ### v6 to v7 migration
 
-v7.0.0 changes explicit drain shutdown semantics. After `queue.drain()` /
-`queue.close()` (sync) or `await queue.drain()` / `await queue.aclose()`
-(async), the same queue instance rejects `publish()` with
-`QueueDrainedError("queue is drained")`.
+v7.0.0 has four breaking changes to check during upgrade.
+
+**AC-02: queue event operation/outcome types are `StrEnum` members.**
+Runtime string comparisons keep working because `StrEnum` subclasses `str`,
+but type-strict code should replace old `Literal[...]` annotations and raw
+string constants with enum members.
+
+Before:
+
+```python
+from typing import Literal
+
+QueueOperation = Literal["publish", "claim", "ack"]
+
+def record(operation: QueueOperation) -> None:
+    if operation == "publish":
+        print("published")
+```
+
+After:
+
+```python
+from redis_message_queue import EventOperation
+
+def record(operation: EventOperation) -> None:
+    if operation is EventOperation.PUBLISH:
+        print("published")
+```
+
+**AC-03: drained queue instances refuse new publishes.** After
+`queue.drain()` / `queue.close()` (sync) or `await queue.drain()` /
+`await queue.aclose()` (async), the same queue instance rejects `publish()`
+with `QueueDrainedError("queue is drained")`.
 
 This state is queue-local and process-local; it is not stored in Redis. If a
 producer must continue publishing after a worker has drained, use a separate
@@ -689,6 +774,42 @@ producer must continue publishing after a worker has drained, use a separate
 shutdown, catch `QueueDrainedError` only at boundaries where late publishes are
 expected and safe to drop or reschedule.
 
+```python
+from redis_message_queue import QueueDrainedError
+
+try:
+    queue.publish("late shutdown audit event")
+except QueueDrainedError:
+    # The queue instance already began draining; drop or reschedule elsewhere.
+    pass
+```
+
+**AC-09: unsafe `drop_oldest` combinations now fail at construction.** These
+configurations raise `ConfigurationError` before the queue or gateway is
+created:
+
+- `pending_overload_policy="drop_oldest"` with `max_pending_length=None`:
+  `drop_oldest requires max_pending_length to be set. Use a positive
+  max_pending_length to define what can be dropped, or use
+  pending_overload_policy='raise' or 'block' for unbounded queues.`
+- `pending_overload_policy="drop_oldest"` with deduplication enabled or
+  `get_deduplication_key` configured:
+  `'pending_overload_policy=drop_oldest' cannot be used with deduplication
+  because dropped messages leave their deduplication keys in Redis, causing
+  future publishes of the same payload to be silently suppressed. Use 'raise'
+  or 'block' for deduplicated queues, or disable deduplication if 'drop_oldest'
+  is required.`
+- `pending_overload_policy="drop_oldest"` with `max_delivery_count` set:
+  `drop_oldest is incompatible with max_delivery_count (set
+  max_delivery_count=None or pick another policy to avoid silent loss of
+  pending DLQ candidates). Use pending_overload_policy='raise' or 'block' when
+  dead-letter handling is required.`
+
+**AC-16: redis-py is capped below 8.0.0.** The package dependency is
+`redis>=5.0.0,<8.0.0` until redis-py 8 RESP3-default behavior is verified.
+Users on redis-py 7.x and earlier are unaffected. If you installed a redis-py
+8.0.0 beta explicitly, downgrade with `pip install "redis<8.0.0"`.
+
 ### Configuration changes on live queues
 
 > **Warning:** These changes are destructive on live queues. Drain the queue completely before applying them.

{redis_message_queue-7.0.0 → redis_message_queue-7.0.1}/pyproject.toml

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

{redis_message_queue-7.0.0 → redis_message_queue-7.0.1}/redis_message_queue/_config.py

@@ -237,11 +237,14 @@ def validate_gateway_parameters(
         )
     if message_deduplication_log_ttl_seconds <= 0:
         raise ConfigurationError(
-            f"'message_deduplication_log_ttl_seconds' must be positive, got {message_deduplication_log_ttl_seconds}"
+            f"'message_deduplication_log_ttl_seconds' must be positive, "
+            f"got {message_deduplication_log_ttl_seconds}. Use a positive int in seconds "
+            "(e.g., 3600) to keep deduplication keys for that window."
         )
     if message_wait_interval_seconds < 0:
         raise ConfigurationError(
-            f"'message_wait_interval_seconds' must be non-negative, got {message_wait_interval_seconds}"
+            f"'message_wait_interval_seconds' must be non-negative, got {message_wait_interval_seconds}. "
+            "Use 0 for non-blocking polls or a positive int in seconds to wait for messages."
         )
     if message_visibility_timeout_seconds is not None:
         if not isinstance(message_visibility_timeout_seconds, int) or isinstance(
@@ -255,14 +258,18 @@ def validate_gateway_parameters(
         if message_visibility_timeout_seconds <= 0:
             raise ConfigurationError(
                 "'message_visibility_timeout_seconds' must be positive when provided, "
-                f"got {message_visibility_timeout_seconds}"
+                f"got {message_visibility_timeout_seconds}. Use a positive int in seconds for at-least-once "
+                "redelivery or None for at-most-once processing."
             )
 
     if not isinstance(retry_budget_seconds, int) or isinstance(retry_budget_seconds, bool):
         bool_hint = " (use True or False, not 1/0)" if isinstance(retry_budget_seconds, bool) else ""
         raise TypeError(f"'retry_budget_seconds' must be an int, got {type(retry_budget_seconds).__name__}{bool_hint}")
     if retry_budget_seconds < 0:
-        raise ConfigurationError(f"'retry_budget_seconds' must be non-negative, got {retry_budget_seconds}")
+        raise ConfigurationError(
+            f"'retry_budget_seconds' must be non-negative, got {retry_budget_seconds}. "
+            "Use 0 to disable redis-message-queue retries or a positive int in seconds to bound retry time."
+        )
 
     if isinstance(retry_max_delay_seconds, bool) or not isinstance(retry_max_delay_seconds, (int, float)):
         bool_hint = " (use True or False, not 1/0)" if isinstance(retry_max_delay_seconds, bool) else ""
@@ -271,7 +278,8 @@ def validate_gateway_parameters(
         )
     if not math.isfinite(retry_max_delay_seconds) or retry_max_delay_seconds <= 0:
         raise ConfigurationError(
-            f"'retry_max_delay_seconds' must be a finite positive number, got {retry_max_delay_seconds}"
+            f"'retry_max_delay_seconds' must be a finite positive number, got {retry_max_delay_seconds}. "
+            "Use a positive number of seconds (e.g., 5.0) for the maximum retry backoff delay."
         )
 
     if isinstance(retry_initial_delay_seconds, bool) or not isinstance(retry_initial_delay_seconds, (int, float)):
@@ -282,12 +290,14 @@ def validate_gateway_parameters(
         )
     if not math.isfinite(retry_initial_delay_seconds) or retry_initial_delay_seconds <= 0:
         raise ConfigurationError(
-            f"'retry_initial_delay_seconds' must be a finite positive number, got {retry_initial_delay_seconds}"
+            f"'retry_initial_delay_seconds' must be a finite positive number, got {retry_initial_delay_seconds}. "
+            "Use a positive number of seconds (e.g., 0.01) for the first retry backoff delay."
         )
     if retry_initial_delay_seconds > retry_max_delay_seconds:
         raise ConfigurationError(
             "'retry_initial_delay_seconds' must be <= 'retry_max_delay_seconds', "
-            f"got {retry_initial_delay_seconds} > {retry_max_delay_seconds}"
+            f"got {retry_initial_delay_seconds} > {retry_max_delay_seconds}. "
+            "Use an initial delay less than or equal to the max delay."
         )
 
 
@@ -307,16 +317,24 @@ def validate_pending_backpressure_parameters(
                 f"'max_pending_length' must be an int or None, got {type(max_pending_length).__name__}{bool_hint}"
             )
         if max_pending_length <= 0:
-            raise ConfigurationError(f"'max_pending_length' must be positive when provided, got {max_pending_length}")
+            raise ConfigurationError(
+                f"'max_pending_length' must be positive when provided, got {max_pending_length}. "
+                "Use a positive int (e.g., 1000) or None to disable the cap."
+            )
     if not isinstance(pending_overload_policy, str):
         raise TypeError(f"'pending_overload_policy' must be a string, got {type(pending_overload_policy).__name__}")
     if pending_overload_policy not in PENDING_OVERLOAD_POLICIES:
         allowed = "', '".join(PENDING_OVERLOAD_POLICIES)
         raise ConfigurationError(
-            f"'pending_overload_policy' must be one of '{allowed}', got {pending_overload_policy!r}"
+            f"'pending_overload_policy' must be one of '{allowed}', got {pending_overload_policy!r}. "
+            "Use 'raise' to reject immediately, 'block' to wait for capacity, or 'drop_oldest' only for lossy queues."
         )
     if pending_overload_policy == "drop_oldest" and max_pending_length is None:
-        raise ConfigurationError("drop_oldest requires max_pending_length to be set")
+        raise ConfigurationError(
+            "drop_oldest requires max_pending_length to be set. "
+            "Use a positive max_pending_length to define what can be dropped, or use "
+            "pending_overload_policy='raise' or 'block' for unbounded queues."
+        )
     if pending_overload_policy == "drop_oldest" and (deduplication or get_deduplication_key_configured):
         raise ConfigurationError(
             "'pending_overload_policy=drop_oldest' cannot be used with deduplication because dropped messages "
@@ -328,7 +346,8 @@ def validate_pending_backpressure_parameters(
         raise ConfigurationError(
             "drop_oldest is incompatible with max_delivery_count "
             "(set max_delivery_count=None or pick another policy "
-            "to avoid silent loss of pending DLQ candidates)"
+            "to avoid silent loss of pending DLQ candidates). Use pending_overload_policy='raise' or 'block' "
+            "when dead-letter handling is required."
         )
     if isinstance(pending_overload_block_timeout_seconds, bool) or not isinstance(
         pending_overload_block_timeout_seconds, (int, float)
@@ -341,7 +360,8 @@ def validate_pending_backpressure_parameters(
     if not math.isfinite(pending_overload_block_timeout_seconds) or pending_overload_block_timeout_seconds < 0:
         raise ConfigurationError(
             "'pending_overload_block_timeout_seconds' must be a finite non-negative number, "
-            f"got {pending_overload_block_timeout_seconds}"
+            f"got {pending_overload_block_timeout_seconds}. Use 0 to fail immediately under 'block' policy "
+            "or a positive number of seconds to wait for capacity."
         )
 
 
@@ -357,20 +377,33 @@ def validate_dead_letter_parameters(
                 f"'max_delivery_count' must be an int or None, got {type(max_delivery_count).__name__}{bool_hint}"
             )
         if max_delivery_count <= 0:
-            raise ConfigurationError(f"'max_delivery_count' must be positive, got {max_delivery_count}")
+            raise ConfigurationError(
+                f"'max_delivery_count' must be positive, got {max_delivery_count}. "
+                "Use a positive int (e.g., 5) to dead-letter poison messages or None to disable delivery limits."
+            )
         if message_visibility_timeout_seconds is None:
-            raise ConfigurationError("'max_delivery_count' requires 'message_visibility_timeout_seconds' to be set.")
+            raise ConfigurationError(
+                "'max_delivery_count' requires 'message_visibility_timeout_seconds' to be set. "
+                "Use a positive visibility timeout so failed deliveries can be counted before DLQ routing."
+            )
     if dead_letter_queue is not None and not isinstance(dead_letter_queue, str):
         bool_hint = " (use True or False, not 1/0)" if isinstance(dead_letter_queue, bool) else ""
         raise TypeError(f"'dead_letter_queue' must be a str or None, got {type(dead_letter_queue).__name__}{bool_hint}")
     if isinstance(dead_letter_queue, str) and dead_letter_queue and not dead_letter_queue.strip():
         raise ConfigurationError(
-            f"'dead_letter_queue' must contain non-whitespace characters; got {dead_letter_queue!r}"
+            f"'dead_letter_queue' must contain non-whitespace characters; got {dead_letter_queue!r}. "
+            "Use a real Redis list key name (e.g., 'jobs:dead') or None to disable DLQ routing."
         )
     if max_delivery_count is not None and not dead_letter_queue:
-        raise ConfigurationError("'dead_letter_queue' is required when 'max_delivery_count' is set.")
+        raise ConfigurationError(
+            "'dead_letter_queue' is required when 'max_delivery_count' is set. "
+            "Use a Redis list key name for poison messages or set max_delivery_count=None."
+        )
     if dead_letter_queue and max_delivery_count is None:
-        raise ConfigurationError("'max_delivery_count' is required when 'dead_letter_queue' is set.")
+        raise ConfigurationError(
+            "'max_delivery_count' is required when 'dead_letter_queue' is set. "
+            "Use a positive max_delivery_count to route poison messages or set dead_letter_queue=None."
+        )
 
 
 DEFAULT_MESSAGE_DEDUPLICATION_LOG_TTL = 60 * 60  # 1 hour = 60 seconds * 60 minutes

{redis_message_queue-7.0.0 → redis_message_queue-7.0.1}/redis_message_queue/_exceptions.py

@@ -24,6 +24,20 @@ class CleanupFailedError(RedisMessageQueueError):
 class QueueBackpressureError(RedisMessageQueueError):
     """Publish rejected because the pending queue is at its configured limit."""
 
+    _REMEDIATION = (
+        "consider increasing `max_pending_length`, switching to "
+        "`pending_overload_policy='block'`, or adding consumer capacity."
+    )
+
+    def __init__(self, *args: object) -> None:
+        message = "Pending queue reached its configured limit" if not args else args[0]
+        if not isinstance(message, str) or len(args) > 1:
+            super().__init__(*args)
+            return
+        if self._REMEDIATION not in message:
+            message = f"{message}; {self._REMEDIATION}"
+        super().__init__(message)
+
 
 class QueueDrainedError(RedisMessageQueueError):
     """Raised when publish() is called after drain() or aclose()."""
@@ -32,6 +46,19 @@ class QueueDrainedError(RedisMessageQueueError):
 class RetryBudgetExhaustedError(redis.exceptions.RedisError, RedisMessageQueueError):
     """Tenacity retry budget exhausted; underlying redis-py exception is .__cause__."""
 
+    _REMEDIATION = (
+        "verify Redis connectivity and consider increasing `retry_budget_seconds` if transient failures are expected."
+    )
+
+    def __init__(self, *args: object) -> None:
+        message = "Redis retry budget exhausted" if not args else args[0]
+        if not isinstance(message, str) or len(args) > 1:
+            super().__init__(*args)
+            return
+        if self._REMEDIATION not in message:
+            message = f"{message}; {self._REMEDIATION}"
+        super().__init__(message)
+
 
 def wrap_lua_response_error(exc: redis.exceptions.ResponseError) -> LuaScriptError | None:
     message = str(exc)

{redis_message_queue-7.0.0 → redis_message_queue-7.0.1}/redis_message_queue/_queue_key_manager.py

@@ -1,6 +1,21 @@
 from redis_message_queue._exceptions import ConfigurationError
 
 
+def validate_callable_deduplication_key(dedup_key: object, message: str | dict) -> str:
+    if dedup_key is None:
+        raise ConfigurationError(
+            f"get_deduplication_key returned None for message {message!r}; the callable must return a non-empty string"
+        )
+    if not isinstance(dedup_key, str):
+        raise TypeError(f"get_deduplication_key must return a str, got {type(dedup_key).__name__}")
+    if dedup_key == "":
+        raise ConfigurationError(
+            f"get_deduplication_key returned an empty string for message {message!r}; "
+            "the callable must return a non-empty, high-cardinality key"
+        )
+    return dedup_key
+
+
 class QueueKeyManager:
     # Logs message existence to prevent duplication.
     # Messages are marked for the duration of their lifecycle.
@@ -52,8 +67,16 @@ class QueueKeyManager:
         self._key_separator = key_separator
 
     def deduplication(self, message: str) -> str:
+        if not isinstance(message, str):
+            raise TypeError(f"'deduplication_key' must be a str, got {type(message).__name__}")
+        if message == "":
+            raise ConfigurationError("'deduplication_key' must be a non-empty string")
         return f"{self._queue_name}{self._key_separator}{self._MESSAGE_DEDUPLICATION_LOG}{self._key_separator}{message}"
 
+    @property
+    def deduplication_prefix(self) -> str:
+        return f"{self._queue_name}{self._key_separator}{self._MESSAGE_DEDUPLICATION_LOG}{self._key_separator}"
+
     @property
     def pending(self) -> str:
         return f"{self._queue_name}{self._key_separator}{self._PENDING_MESSAGES}"

{redis_message_queue-7.0.0 → redis_message_queue-7.0.1}/redis_message_queue/_redis_cluster.py

@@ -18,7 +18,7 @@ def validate_queue_keys_for_redis_cluster(
     dead_letter_queue: str | None = None,
 ) -> None:
     queue_name = getattr(key_manager, "_queue_name", "<unknown>")
-    deduplication_prefix = key_manager.deduplication("")
+    deduplication_prefix = key_manager.deduplication_prefix
     if _HASH_TAG_PATTERN.search(deduplication_prefix) is None:
         raise ConfigurationError(
             "Redis Cluster requires queue keys to share a hash tag; "

{redis_message_queue-7.0.0 → redis_message_queue-7.0.1}/redis_message_queue/_redis_gateway.py

@@ -37,6 +37,7 @@ from redis_message_queue._config import (
 )
 from redis_message_queue._event import EventOperation, EventOutcome
 from redis_message_queue._exceptions import (
+    ConfigurationError,
     QueueBackpressureError,
     RetryBudgetExhaustedError,
     wrap_lua_response_error,
@@ -200,6 +201,7 @@ class RedisGateway(AbstractRedisGateway):
         self._pending_claim_ids: dict[str, list[str]] = {}
         self._recovering_claim_ids: dict[str, set[str]] = {}
         self._pending_claim_ids_lock = threading.Lock()
+        self._drain_pending_claim_ids_lock = threading.Lock()
         self._event_queue_name: str | None = None
         self._event_emitter: Callable[..., None] | None = None
 
@@ -289,6 +291,13 @@ class RedisGateway(AbstractRedisGateway):
         return isinstance(self._redis_client, redis.RedisCluster)
 
     def publish_message(self, queue: str, message: str, dedup_key: str) -> bool:
+        if not isinstance(dedup_key, str):
+            raise TypeError(f"'dedup_key' must be a str, got {type(dedup_key).__name__}")
+        if dedup_key == "":
+            raise ConfigurationError(
+                "'dedup_key' must be a non-empty string; "
+                "an empty key would create a bare-prefix Redis marker that silently suppresses unrelated messages"
+            )
         stored_message = encode_stored_message(message)
         operation_id = uuid.uuid4().hex
         operation_result_key = self._publish_operation_result_key(dedup_key, operation_id)
@@ -961,6 +970,19 @@ class RedisGateway(AbstractRedisGateway):
         exit (AA-05-F2). Returns True if no pending ids remain; False if
         the deadline fired or transient Redis errors prevented full drain.
         """
+        with self._drain_pending_claim_ids_lock:
+            return self._drain_pending_claim_ids_unlocked(
+                processing_queue,
+                deadline_monotonic=deadline_monotonic,
+            )
+
+    def _drain_pending_claim_ids_unlocked(
+        self,
+        processing_queue: str,
+        *,
+        deadline_monotonic: float | None,
+    ) -> bool:
+        """Recover every in-memory pending claim id for ``processing_queue``."""
         if self._message_visibility_timeout_seconds is not None:
             recover = self._recover_pending_visibility_timeout_claim
         else:

{redis_message_queue-7.0.0 → redis_message_queue-7.0.1}/redis_message_queue/asyncio/_redis_gateway.py

@@ -36,6 +36,7 @@ from redis_message_queue._config import (
 )
 from redis_message_queue._event import EventOperation, EventOutcome
 from redis_message_queue._exceptions import (
+    ConfigurationError,
     QueueBackpressureError,
     RetryBudgetExhaustedError,
     wrap_lua_response_error,
@@ -191,6 +192,7 @@ class RedisGateway(AbstractRedisGateway):
         self._pending_claim_ids: dict[str, list[str]] = {}
         self._recovering_claim_ids: dict[str, set[str]] = {}
         self._pending_claim_ids_lock = threading.Lock()
+        self._drain_pending_claim_ids_lock = asyncio.Lock()
         self._event_queue_name: str | None = None
         self._event_emitter: Callable[..., Awaitable[None]] | None = None
 
@@ -285,6 +287,13 @@ class RedisGateway(AbstractRedisGateway):
         return isinstance(self._redis_client, redis.asyncio.RedisCluster)
 
     async def publish_message(self, queue: str, message: str, dedup_key: str) -> bool:
+        if not isinstance(dedup_key, str):
+            raise TypeError(f"'dedup_key' must be a str, got {type(dedup_key).__name__}")
+        if dedup_key == "":
+            raise ConfigurationError(
+                "'dedup_key' must be a non-empty string; "
+                "an empty key would create a bare-prefix Redis marker that silently suppresses unrelated messages"
+            )
         stored_message = encode_stored_message(message)
         operation_id = uuid.uuid4().hex
         operation_result_key = self._publish_operation_result_key(dedup_key, operation_id)
@@ -958,6 +967,19 @@ class RedisGateway(AbstractRedisGateway):
         soft shutdown can flush ambiguous-claim state. Returns True if no
         pending ids remain; False on deadline expiry or transient errors.
         """
+        async with self._drain_pending_claim_ids_lock:
+            return await self._drain_pending_claim_ids_unlocked(
+                processing_queue,
+                deadline_monotonic=deadline_monotonic,
+            )
+
+    async def _drain_pending_claim_ids_unlocked(
+        self,
+        processing_queue: str,
+        *,
+        deadline_monotonic: float | None,
+    ) -> bool:
+        """Recover every in-memory pending claim id for ``processing_queue``."""
         if self._message_visibility_timeout_seconds is not None:
             recover = self._recover_pending_visibility_timeout_claim
         else:

{redis_message_queue-7.0.0 → redis_message_queue-7.0.1}/redis_message_queue/asyncio/redis_message_queue.py

@@ -24,7 +24,7 @@ from redis_message_queue._exceptions import (
     GatewayContractError,
     QueueDrainedError,
 )
-from redis_message_queue._queue_key_manager import QueueKeyManager
+from redis_message_queue._queue_key_manager import QueueKeyManager, validate_callable_deduplication_key
 from redis_message_queue._redis_cluster import validate_queue_keys_for_redis_cluster
 from redis_message_queue._stored_message import (
     ClaimedMessage,
@@ -816,8 +816,7 @@ class RedisMessageQueue:
             dedup_key = self._get_deduplication_key(message)
             if inspect.isawaitable(dedup_key):
                 dedup_key = await dedup_key
-            if not isinstance(dedup_key, str):
-                raise TypeError(f"'get_deduplication_key' must return a string, got {type(dedup_key).__name__}")
+            dedup_key = validate_callable_deduplication_key(dedup_key, message)
         else:
             dedup_key = message_str
         dedup_key = self.key.deduplication(dedup_key)
@@ -1136,10 +1135,14 @@ class RedisMessageQueue:
                 return self._aclose_result
             loop = asyncio.get_running_loop()
             deadline_monotonic = None if timeout is None else (loop.time() + float(timeout))
-            self._aclose_result = await _await_preserving_cancellation(
+            result = await _await_preserving_cancellation(
                 drainer(self.key.processing, deadline_monotonic=deadline_monotonic)
             )
-            return self._aclose_result
+            if result is True:
+                self._aclose_result = True
+            else:
+                self._aclose_result = None
+            return result
 
     async def drain(self, timeout: float | None = None) -> bool:
         """Alias of :meth:`aclose` for explicit async drain naming."""

{redis_message_queue-7.0.0 → redis_message_queue-7.0.1}/redis_message_queue/redis_message_queue.py

@@ -25,7 +25,7 @@ from redis_message_queue._exceptions import (
     GatewayContractError,
     QueueDrainedError,
 )
-from redis_message_queue._queue_key_manager import QueueKeyManager
+from redis_message_queue._queue_key_manager import QueueKeyManager, validate_callable_deduplication_key
 from redis_message_queue._redis_cluster import validate_queue_keys_for_redis_cluster
 from redis_message_queue._redis_gateway import RedisGateway
 from redis_message_queue._stored_message import (
@@ -566,6 +566,8 @@ class RedisMessageQueue:
         self._draining = False
         self._drained = threading.Event()
         self._publish_lock = threading.Lock()
+        self._drain_lock = threading.Lock()
+        self._drain_result: bool | None = None
         self._deduplication = deduplication
         self._enable_completed_queue = enable_completed_queue
         self._enable_failed_queue = enable_failed_queue
@@ -777,8 +779,7 @@ class RedisMessageQueue:
                 raise TypeError(
                     "'get_deduplication_key' returned an awaitable; use the async RedisMessageQueue for async callables"
                 )
-            if not isinstance(dedup_key, str):
-                raise TypeError(f"'get_deduplication_key' must return a string, got {type(dedup_key).__name__}")
+            dedup_key = validate_callable_deduplication_key(dedup_key, message)
         else:
             dedup_key = message_str
         dedup_key = self.key.deduplication(dedup_key)
@@ -1080,14 +1081,24 @@ class RedisMessageQueue:
             raise TypeError(f"'timeout' must be a number or None, got {type(timeout).__name__}")
         if timeout is not None and timeout < 0:
             raise ConfigurationError(f"'timeout' must be non-negative when provided, got {timeout}")
-        with self._publish_lock:
-            self._draining = True
-            self._drained.set()
-        drainer = getattr(self._redis, "_drain_pending_claim_ids", None)
-        if drainer is None:
-            return True
-        deadline_monotonic = None if timeout is None else (time.monotonic() + float(timeout))
-        return drainer(self.key.processing, deadline_monotonic=deadline_monotonic)
+        with self._drain_lock:
+            if self._drain_result is True:
+                return True
+
+            with self._publish_lock:
+                self._draining = True
+                self._drained.set()
+            drainer = getattr(self._redis, "_drain_pending_claim_ids", None)
+            if drainer is None:
+                self._drain_result = True
+                return True
+            deadline_monotonic = None if timeout is None else (time.monotonic() + float(timeout))
+            result = drainer(self.key.processing, deadline_monotonic=deadline_monotonic)
+            if result is True:
+                self._drain_result = True
+            else:
+                self._drain_result = None
+            return result
 
     def close(self, timeout: float | None = None) -> bool:
         """Alias of :meth:`drain` for consistency with redis-py naming.