redis-message-queue 3.1.2__tar.gz → 6.0.0__tar.gz

{redis_message_queue-3.1.2 → redis_message_queue-6.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redis-message-queue
-Version: 3.1.2
+Version: 6.0.0
 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/v3.1.2-version?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
+[![PyPI Version](https://img.shields.io/badge/v6.0.0-version?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
 [![PyPI Downloads](https://img.shields.io/pypi/dm/redis-message-queue?color=43cd0f&style=flat&label=downloads)](https://pypistats.org/packages/redis-message-queue)
 [![License: MIT](https://img.shields.io/badge/License-MIT-43cd0f.svg?style=flat&label=license)](LICENSE)
 [![Maintained: yes](https://img.shields.io/badge/yes-43cd0f.svg?style=flat&label=maintained)](https://github.com/Elijas/redis-message-queue/issues)
@@ -37,7 +37,7 @@ Description-Content-Type: text/markdown
 **Lightweight Python message queuing with Redis and built-in publish-side deduplication.** Deduplicate publishes within a TTL window, with optional crash recovery — across any number of producers and consumers.
 
 ```bash
-pip install "redis-message-queue>=3.0.0,<4.0.0"
+pip install "redis-message-queue>=6.0.0,<7.0.0"
 ```
 
 Requires Redis server >= 6.2.
@@ -50,7 +50,7 @@ Requires Redis server >= 6.2.
 from redis import Redis
 from redis_message_queue import RedisMessageQueue
 
-client = Redis.from_url("redis://localhost:6379/0")
+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
@@ -74,6 +74,9 @@ while True:
             # Auto-acknowledged on success; cleaned up on exception
 ```
 
+`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.
@@ -97,8 +100,8 @@ All features are optional and can be enabled or disabled as needed.
 
 | Configuration | Delivery guarantee |
 |---|---|
-| Default (no visibility timeout) | **At-most-once** — a consumer crash loses the in-flight message |
-| With `visibility_timeout_seconds` | **At-least-once** — expired messages are reclaimed and redelivered |
+| Default (`visibility_timeout_seconds=300`) | **At-least-once** — expired messages are reclaimed and redelivered |
+| With `visibility_timeout_seconds=None` | **At-most-once** — a consumer crash loses the in-flight message |
 
 See [Crash recovery with visibility timeout](#crash-recovery-with-visibility-timeout) for details and tradeoffs.
 
@@ -107,7 +110,7 @@ See [Crash recovery with visibility timeout](#crash-recovery-with-visibility-tim
 ### Deduplication
 
 ```python
-# Default: deduplicate by full message content (1-hour TTL)
+# Default: deduplicate by SHA-256 hash of canonical message content (1-hour TTL)
 queue = RedisMessageQueue("q", client=client, deduplication=True)
 
 # Custom dedup key (e.g., deduplicate by order ID only)
@@ -131,7 +134,8 @@ queue = RedisMessageQueue(
 )
 ```
 
-To prevent unbounded growth, cap the queue lengths:
+Completed and failed tracking queues are capped at 1,000 entries by default
+when enabled. Override the caps when you need a different retention window:
 
 ```python
 queue = RedisMessageQueue(
@@ -144,6 +148,45 @@ queue = RedisMessageQueue(
 ```
 
 When set, `LTRIM` is called after each message is moved to the completed/failed queue. This is best-effort cleanup — if the trim fails, the queue is slightly longer until the next successful trim.
+Pass `max_completed_length=None` or `max_failed_length=None` explicitly if you
+want unbounded tracking queues.
+
+### Publish backpressure
+
+By default, the pending queue is unbounded (`max_pending_length=None`), matching
+the v5 behavior. Set `max_pending_length` when producers can outrun consumers
+and Redis memory must fail closed before the broker is exhausted:
+
+```python
+queue = RedisMessageQueue(
+    "q",
+    client=client,
+    max_pending_length=100_000,
+    pending_overload_policy="raise",  # "raise", "drop_oldest", or "block"
+)
+```
+
+The built-in Redis path checks pending depth and enqueues in the same Lua script,
+so concurrent publishers cannot race above the configured cap. Overload policies:
+
+- `raise` raises `QueueBackpressureError` and leaves the pending list unchanged.
+- `drop_oldest` removes the oldest pending message (`RPOP`) before enqueueing the
+  new message. This is silent data loss by design; deduplication markers for
+  dropped messages are not removed, so a dropped duplicate may still be
+  suppressed until its dedup TTL expires.
+- `block` retries the atomic check until space opens or
+  `pending_overload_block_timeout_seconds` elapses (default: 1.0), then raises
+  `QueueBackpressureError`.
+
+These limits apply only to the pending list at publish time. They do not cap
+messages already in `processing`, dead-letter queues, deduplication keys, or
+replay metadata. `max_completed_length` and `max_failed_length` only bound the
+completed/failed history lists. Size pending payload memory separately from the
+dedup/replay metadata described in
+[Redis memory sizing](#redis-memory-sizing-for-deduplication-and-replay-metadata).
+
+When using `gateway=`, configure backpressure on the gateway directly, for
+example `RedisGateway(redis_client=client, max_pending_length=100_000)`.
 
 ### Crash recovery with visibility timeout
 
@@ -180,6 +223,43 @@ 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.
 
+### Ordering and multi-consumer fairness
+
+The built-in queue is a shared-pull Redis list. Successful publishes push to the
+left side of the pending list, and claims pop from the right side, so Redis
+grants claims in enqueue order in the no-failure path.
+
+This is a claim-order guarantee only. It is not a completion-order guarantee:
+multiple consumers process concurrently, handlers can run for different
+durations, and younger messages can finish before older messages.
+
+With `visibility_timeout_seconds` enabled, expired messages from `processing`
+are reclaimed before fresh pending work on the next consumer poll. A reclaimed
+message may be delivered after younger messages were already processed, and may
+be processed concurrently with a stale original handler if that handler keeps
+running after its lease expires.
+
+Expired reclaims are ordered by lease deadline within one reclaim batch.
+`CLAIM_MESSAGE_WITH_VISIBILITY_TIMEOUT_LUA_SCRIPT` selects expired leases with
+`ZRANGEBYSCORE ... LIMIT 0, 100` to bound Redis Lua execution time. When more
+than 100 messages expire together, the next poll can append a later reclaim
+batch at the claimable end of the pending list ahead of leftovers from the
+previous batch, so cross-batch redelivery order is not guaranteed.
+
+`max_delivery_count` can skip over poison messages during a claim poll by moving
+over-limit messages to the dead-letter queue and returning a later pending
+message. Deduplication is publish-side only: duplicate publishes are not
+enqueued and therefore do not occupy a queue position.
+
+Handler exceptions are not retries: the default behavior removes the message
+from `processing`, or moves it to the failed queue when enabled. Redelivery is
+for crash, stall, or stale-lease paths where cleanup does not complete.
+
+Multiple consumers contend for the same queue. The next message goes to the
+consumer whose claim request Redis executes next. There is no round-robin,
+equal-share, or starvation-freedom guarantee; faster consumers can receive more
+than 1/N of messages.
+
 ### Dead-letter queue
 
 ```python
@@ -191,14 +271,14 @@ queue = RedisMessageQueue(
 )
 ```
 
-When a message has been delivered more than `max_delivery_count` times (due to consumer crashes causing visibility-timeout reclaim), it is automatically routed to a dead-letter queue (`{name}::dead_letter`) instead of being redelivered. This prevents poison messages from cycling indefinitely.
+When a message has been delivered more than `max_delivery_count` times (due to consumer crashes causing visibility-timeout reclaim), it is automatically routed to a dead-letter queue (`{name}::dlq`) instead of being redelivered. `max_delivery_count` defaults to `10` on the built-in `client=` path, with the DLQ name auto-derived from the queue name. This prevents poison messages from cycling indefinitely.
 
 Notes:
 - requires `visibility_timeout_seconds` to be set (poison messages are only a concern with VT reclaim)
 - the delivery count is tracked per-message in a Redis HASH and cleaned up on successful ack or move to completed/failed
 - the delivery count increments when Redis grants the claim/lease, not when your handler begins running. If a process exits after Redis claims a message, that claim still counts toward `max_delivery_count`
 - `max_delivery_count=1` means the message is delivered once; any reclaim routes it to the dead-letter queue
-- without `max_delivery_count`, messages are redelivered indefinitely (existing behavior)
+- set `max_delivery_count=None` explicitly for unlimited redelivery
 - dead-lettered messages contain the **raw payload** only — the internal envelope (which carries a per-delivery UUID) is stripped before pushing to the DLQ, consistent with how completed/failed queues store messages. Two identical payloads dead-lettered separately are indistinguishable in the DLQ
 
 ### Graceful shutdown
@@ -224,10 +304,46 @@ while not interrupt.is_interrupted():
 > (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.
 
+There are three distinct shutdown shapes; pick the one that matches your runtime:
+
+| Shape | Trigger | In-flight handler | Pending claim IDs |
+|---|---|---|---|
+| **Flag-based soft drain** (`GracefulInterruptHandler`) | First SIGINT/SIGTERM flips a flag | Runs to completion | Drained on the next claim call, not on signal arrival |
+| **Async task cancellation** (`asyncio.CancelledError`) | Framework cancels the worker task (Uvicorn/K8s SIGTERM in many setups) | **Hard abort** — message stays in `processing`; with VT it is reclaimed at deadline expiry, without VT it is orphaned | Not drained |
+| **Explicit drain** (`drain()` / `aclose()`) | You call the method | Caller's responsibility to let it finish (drain does **not** cancel) | Drained synchronously via the gateway recovery path |
+
+Use `drain()` / `aclose()` to bridge K8s `preStop` / SIGTERM grace windows without
+relying on signal interception:
+
+```python
+# sync — in your SIGTERM handler or preStop hook
+queue.drain(timeout=25)   # refuses new claims, recovers pending claim IDs
+worker_thread.join()      # wait for in-flight process_message to finish
+
+# async — same shape
+await queue.aclose(timeout=25)
+await worker_task         # task observes ``_draining`` and exits its loop
+```
+
+`drain()` / `aclose()` set a queue-local flag so subsequent `process_message()`
+calls yield `None` immediately. They do not cancel in-flight handlers — the
+caller must arrange handler exit through normal thread/task coordination.
+Returns `True` if all in-memory 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.
+
+> **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
+> Redis after the caller believes shutdown is complete. The renewal is bounded
+> by the configured visibility timeout and the lease token check on the Redis
+> side, but plan for a small post-shutdown overlap rather than instant quiesce.
+
 ### Custom gateway
 
 ```python
-from redis_message_queue._redis_gateway import RedisGateway
+from redis_message_queue import RedisGateway
 
 # Tune retry budget, dedup TTL, or wait interval
 gateway = RedisGateway(
@@ -244,17 +360,17 @@ queue = RedisMessageQueue("q", gateway=gateway)
 
 The retry knobs configure an internal `tenacity` strategy: exponential
 backoff with jitter, retry on transient Redis errors only, capped at
-`retry_budget_seconds`. The budget is wall-clock time from the first attempt (including attempt duration), not inter-attempt delay; a single attempt that takes longer than the budget results in zero retries. Setting `retry_budget_seconds=0` disables retry
+`retry_budget_seconds`. The budget is monotonic elapsed time from the first attempt (including attempt duration), not inter-attempt delay; it is unaffected by Python-host NTP jumps. 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. 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.
+impossible. Note: tenacity may allow one additional attempt beyond the budget if the budget check passes at attempt start, so total monotonic elapsed 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
-`AbstractRedisGateway` from `redis_message_queue._abstract_redis_gateway`
-(or `redis_message_queue.asyncio._abstract_redis_gateway`) and override the
+`AbstractRedisGateway` from `redis_message_queue` (or
+`redis_message_queue.asyncio` for the async sibling) and override the
 operation methods directly.
 
 If your custom gateway uses visibility timeouts, it must expose a public
@@ -285,6 +401,16 @@ Use a separate gateway instance per queue when `max_delivery_count` is enabled.
 Dead-letter routing is gateway-scoped, so reusing the same gateway across different
 queues is rejected.
 
+If you use Redis Sentinel, pass the Redis client returned by
+`sentinel.master_for(name)` to `client=` or `RedisGateway(redis_client=...)`, not
+the `sentinel` object itself.
+
+### Connection pool sizing
+
+Each queue with `heartbeat_interval_seconds` set uses up to 2 simultaneous
+connections: one for the main operation and one for heartbeat renewal. Size Redis
+client pools with `max_connections >= 2 * number_of_queues + headroom`.
+
 ## Async API
 
 Replace the import to use the async variant — the API is identical:
@@ -293,6 +419,11 @@ Replace the import to use the async variant — the API is identical:
 from redis_message_queue.asyncio import RedisMessageQueue
 ```
 
+The sync and async classes intentionally share names. In modules that use both,
+alias the imports explicitly, for example
+`from redis_message_queue import RedisMessageQueue as SyncRedisMessageQueue` and
+`from redis_message_queue.asyncio import RedisMessageQueue as AsyncRedisMessageQueue`.
+
 All examples work the same way. Remember to close the connection when done:
 
 ```python
@@ -303,18 +434,138 @@ client = redis.Redis()
 await client.aclose()
 ```
 
+For the sync Redis client, call `client.close()` during application shutdown when
+you own the client lifecycle.
+
+## Production notes
+
+### Fork safety and pre-fork servers
+
+Construct Redis clients and `RedisMessageQueue` instances after a process forks.
+This is the recommended pattern for `multiprocessing`, `ProcessPoolExecutor`,
+and pre-fork servers such as gunicorn with `--preload`.
+
+```python
+def worker_main():
+    client = redis.Redis()
+    queue = RedisMessageQueue("jobs", client=client)
+    ...
+```
+
+Avoid constructing a queue/client in a parent process and then using that same
+object in forked children, especially if the parent has already run any Redis
+command. The queue stores the user-provided Redis client and process-local
+claim-recovery state. Inherited Redis sockets can corrupt the Redis protocol if
+two processes use the same file descriptor.
+
+Notes:
+
+- The sync redis-py pooled client attempts to reset its connection pool after
+  fork, but this does not apply to every client shape.
+- The built-in sync gateway rejects `redis.Redis(single_connection_client=True)`
+  because that mode pins one socket instead of using the pool.
+- Do not share `redis.asyncio.Redis` or async queues across fork; create or
+  reconnect them in the child process.
+- If you use `GracefulInterruptHandler`, create it in the worker process after
+  fork so signal ownership is local to that worker.
+- The heartbeat sidecar is lazy and starts only while processing a leased
+  message. Do not call `fork()` from inside active message handlers unless the
+  child exits without using the inherited queue/client.
+
+### Redis memory sizing for deduplication and replay metadata
+
+When deduplication is enabled, each distinct dedup key creates one Redis string
+for `message_deduplication_log_ttl_seconds` (default: 3600 seconds). The default
+dedup key is a SHA-256 hash of the canonical message payload, so distinct
+payloads are distinct keys. Size Redis for:
+
+```text
+peak_unique_publish_rate_per_second
+* message_deduplication_log_ttl_seconds
+* bytes_per_dedup_key
+```
+
+Use 200 bytes per dedup key as a conservative starting point for short queue
+names, then validate with `MEMORY USAGE` in your Redis version. Example:
+1,000 unique messages/s * 3,600s * 200 B ~= 720 MB for dedup markers alone.
+A 24h dedup window at the same rate is 86.4M keys, or roughly 17 GB before
+message payload lists, lease metadata, completed/failed queues, and allocator
+fragmentation.
+
+Operation-result replay keys are normally deleted after a successful call, but
+may live until their TTL after ambiguous connection drops or failed cleanup
+deletes. With visibility timeouts, active claims also store replay metadata
+until ack or reclaim. Without visibility timeouts, abandoned claims leave
+`claim_result_ids` and `claim_result_backrefs` fields until the message is
+acked or manually cleaned.
+
+`max_completed_length` and `max_failed_length` only bound the completed/failed
+lists. They do not bound deduplication keys or replay metadata.
+
+Avoid sharing queue Redis DBs with unrelated high-cardinality workloads. If
+idempotency matters, prefer explicit capacity planning and `noeviction` with
+alerts over LRU/random eviction policies: evicting dedup/replay keys before
+their TTL can weaken duplicate suppression and retry result replay.
+
+## Observability
+
+Queue instances accept an optional `on_event` callback for metrics, tracing, or
+structured logging. The sync queue expects a regular callable; the async queue
+expects an async callable:
+
+```python
+from redis_message_queue import QueueEvent, RedisMessageQueue
+
+def on_event(event: QueueEvent) -> None:
+    ...
+
+queue = RedisMessageQueue("jobs", client=client, on_event=on_event)
+```
+
+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.
+
+```python
+from prometheus_client import Counter
+from redis_message_queue import QueueEvent, RedisMessageQueue
+
+events_total = Counter(
+    "rmq_events_total",
+    "redis-message-queue lifecycle events",
+    ["queue", "operation", "outcome", "exception_type"],
+)
+
+def observe(event: QueueEvent) -> None:
+    events_total.labels(
+        event.queue, event.operation, event.outcome, event.exception_type or ""
+    ).inc()
+
+queue = RedisMessageQueue("jobs", client=client, on_event=observe)
+```
+
+The public exception hierarchy is rooted at `RedisMessageQueueError`.
+Configuration value/combinations raise `ConfigurationError` (also a
+`ValueError`), custom gateway contract violations raise `GatewayContractError`
+(also a `TypeError`), and Lua `redis.error_reply(...)` failures raise
+`LuaScriptError` (also a redis-py `ResponseError`). Publish overload raises
+`QueueBackpressureError`. `CleanupFailedError` and `RetryBudgetExhaustedError`
+are reserved categories for cleanup and retry surfaces.
+
 ## Known limitations
 
-- **No metrics or observability hooks.** The library logs warnings (stale leases, heartbeat failures, transient errors) via Python's `logging` module but does not expose callbacks, event hooks, or metric counters. To monitor queue health, inspect the underlying Redis keys directly or parse log output.
 - **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.
-- **Default dedup key is the full message.** Without a custom `get_deduplication_key`, the entire serialized message becomes a Redis key name for dedup tracking. For large messages (>1KB), provide a custom key function to avoid excessive Redis memory usage.
 - **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.
 - **Non-ASCII payloads use ~2x storage.** The default `ensure_ascii=True` in JSON serialization encodes non-ASCII characters as `\uXXXX` escape sequences. This is a deliberate compatibility choice.
-- **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`.
+- **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` by default, or a single non-idempotent Lua enqueue when `max_pending_length` is set: 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 enqueue 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`.
+- **Redis Cluster default retry can stack with this library's retry budget.** In redis-py 6.0+, `RedisCluster()` constructs a default `ExponentialWithJitterBackoff` retry below this library's `retry_budget_seconds`. If you need a single retry surface, pass `retry=Retry(NoBackoff(), 0)` to the cluster client or reduce `retry_budget_seconds` to account for the lower-level retry window.
 
 For a full analysis, see [docs/production-readiness.md](docs/production-readiness.md).
 
@@ -324,9 +575,17 @@ For a full analysis, see [docs/production-readiness.md](docs/production-readines
 
 > **Warning:** These changes are destructive on live queues. Drain the queue completely before applying them.
 
-- **Do not change `key_separator` on a live queue.** All existing Redis keys become invisible to the new key scheme. Drain the queue completely before changing separators.
-- **Do not switch from no-VT to VT with messages in processing.** Messages claimed by non-VT consumers have no lease deadline entries. VT-enabled consumers cannot reclaim them. Drain the processing queue first.
+- **Do not change `name` or `key_separator` on a live queue.** Both settings define the Redis key namespace. Existing Redis keys become invisible to the new key scheme. Drain the queue completely before changing either value.
+- **Do not rename `dead_letter_queue` on a live queue.** Existing DLQ records stay in the old list, while new failures route to the new list. Inspect or drain the old DLQ manually before switching names.
+- **Do not toggle visibility timeout in either direction with messages in processing.** Messages claimed by non-VT consumers have no lease metadata, so VT-enabled consumers cannot reclaim them. Disabling VT later orphans existing lease deadline, lease token, and delivery count metadata and removes crash recovery for those in-flight messages. Drain the processing queue first.
 - **Reducing `max_delivery_count` retroactively DLQs messages.** The delivery count hash persists across restarts. Messages whose accumulated count exceeds the new limit are immediately dead-lettered on next claim.
+- **Changing `max_delivery_count` from a number to `None` leaves delivery metadata behind.** The delivery count hash continues to exist but is no longer consulted. Use this only after draining or after planning manual cleanup of the delivery-count hash.
+- **Changing `get_deduplication_key` changes the dedup keyspace.** Existing dedup records become inert for the duration of their TTL. Drain the queue or clear the old deduplication keys before switching between the default hash, explicit `None`, or a custom key function.
+- **Disabling `deduplication` has a retention-window overlap.** Existing dedup records remain in Redis until their TTL expires, but new publishes bypass them. Republishes that would have been suppressed under the old setting can enqueue during that window.
+- **Disabling `enable_failed_queue` stops recording handler failures.** Existing failed entries remain in Redis, but new failures are removed from `processing` without being appended to the failed queue. If `max_delivery_count=None` is also set, repeated handler failures can be dropped with no DLQ or failed-queue record; see [Dead-letter queue](#dead-letter-queue).
+- **Lowering `max_completed_length` or `max_failed_length` trims existing history.** The next completed or failed move calls `LTRIM`, so changing `None` to `N` or lowering `N` can immediately reduce historical entries to the new cap.
+- **Do not switch sync and async gateway instances mid-process while claims are active.** Redis state is compatible across deploys, but each gateway instance keeps its own pending claim-recovery IDs. In-flight claim recovery state does not transfer between instances.
+- **Switching between `gateway=` and `client=` can retarget the DLQ.** The built-in `client=` path derives the DLQ from the queue name. If a custom gateway used a different `dead_letter_queue`, switching paths has the same orphaning impact as renaming the DLQ.
 
 ### v2 to v3 migration