redis-message-queue 8.1.0__tar.gz → 8.2.1__tar.gz

redis_message_queue-8.2.1/.gitignore

@@ -0,0 +1,158 @@
+.DS_Store
+
+# Claude Code
+.claude/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

{redis_message_queue-8.1.0 → redis_message_queue-8.2.1}/PKG-INFO

@@ -1,32 +1,29 @@
 Metadata-Version: 2.4
 Name: redis-message-queue
-Version: 8.1.0
+Version: 8.2.1
 Summary: Python message queuing with Redis and message deduplication
+Project-URL: Homepage, https://github.com/Elijas/redis-message-queue
+Project-URL: Repository, https://github.com/Elijas/redis-message-queue
+Project-URL: Issues, https://github.com/Elijas/redis-message-queue/issues
+Author-email: Elijas <4084885+Elijas@users.noreply.github.com>
 License: MIT
 License-File: LICENSE
-Keywords: redis,message-queue,deduplication,task-queue
-Author: Elijas
-Author-email: 4084885+Elijas@users.noreply.github.com
-Requires-Python: >=3.12,<4.0
+Keywords: deduplication,message-queue,redis,task-queue
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: System :: Distributed Computing
-Requires-Dist: redis (>=5.0.0,<8.0.0)
-Requires-Dist: tenacity (>=8.1.0)
-Project-URL: Homepage, https://github.com/Elijas/redis-message-queue
-Project-URL: Issues, https://github.com/Elijas/redis-message-queue/issues
-Project-URL: Repository, https://github.com/Elijas/redis-message-queue
+Requires-Python: <4.0,>=3.12
+Requires-Dist: redis<8.0.0,>=5.0.1
+Requires-Dist: tenacity>=8.1.0
 Description-Content-Type: text/markdown
 
 # redis-message-queue
 
-[![PyPI Version](https://img.shields.io/badge/v8.0.1-version?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
+[![PyPI Version](https://img.shields.io/pypi/v/redis-message-queue?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 +34,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>=8.0.0,<9.0.0"
+pip install "redis-message-queue>=8.2.1,<9.0.0"
 ```
 
 Requires Redis server >= 6.2.
@@ -1090,14 +1087,13 @@ Try the [examples](https://github.com/Elijas/redis-message-queue/tree/main/examp
 
 ```bash
 # Two publishers
-poetry run python -m examples.send_messages
-poetry run python -m examples.send_messages
+uv run python -m examples.send_messages
+uv run python -m examples.send_messages
 
 # Three consumers
-poetry run python -m examples.receive_messages
-poetry run python -m examples.receive_messages
-poetry run python -m examples.receive_messages
+uv run python -m examples.receive_messages
+uv run python -m examples.receive_messages
+uv run python -m examples.receive_messages
 ```
 
 ![GitHub Repo stars](https://img.shields.io/github/stars/elijas/redis-message-queue?style=flat&color=fcfcfc&labelColor=white&logo=github&logoColor=black&label=stars)
-

{redis_message_queue-8.1.0 → redis_message_queue-8.2.1}/README.md

@@ -1,6 +1,6 @@
 # redis-message-queue
 
-[![PyPI Version](https://img.shields.io/badge/v8.0.1-version?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
+[![PyPI Version](https://img.shields.io/pypi/v/redis-message-queue?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
 [![PyPI Downloads](https://img.shields.io/pypi/dm/redis-message-queue?color=43cd0f&style=flat&label=downloads)](https://pypistats.org/packages/redis-message-queue)
 [![License: MIT](https://img.shields.io/badge/License-MIT-43cd0f.svg?style=flat&label=license)](LICENSE)
 [![Maintained: yes](https://img.shields.io/badge/yes-43cd0f.svg?style=flat&label=maintained)](https://github.com/Elijas/redis-message-queue/issues)
@@ -11,7 +11,7 @@
 **Lightweight Python message queuing with Redis and built-in publish-side deduplication.** Deduplicate publishes within a TTL window, with optional crash recovery — across any number of producers and consumers.
 
 ```bash
-pip install "redis-message-queue>=8.0.0,<9.0.0"
+pip install "redis-message-queue>=8.2.1,<9.0.0"
 ```
 
 Requires Redis server >= 6.2.
@@ -1064,13 +1064,13 @@ Try the [examples](https://github.com/Elijas/redis-message-queue/tree/main/examp
 
 ```bash
 # Two publishers
-poetry run python -m examples.send_messages
-poetry run python -m examples.send_messages
+uv run python -m examples.send_messages
+uv run python -m examples.send_messages
 
 # Three consumers
-poetry run python -m examples.receive_messages
-poetry run python -m examples.receive_messages
-poetry run python -m examples.receive_messages
+uv run python -m examples.receive_messages
+uv run python -m examples.receive_messages
+uv run python -m examples.receive_messages
 ```
 
 ![GitHub Repo stars](https://img.shields.io/github/stars/elijas/redis-message-queue?style=flat&color=fcfcfc&labelColor=white&logo=github&logoColor=black&label=stars)

{redis_message_queue-8.1.0 → redis_message_queue-8.2.1}/pyproject.toml

@@ -1,11 +1,11 @@
-[tool.poetry]
+[project]
 name = "redis-message-queue"
-version = "8.1.0"
+version = "8.2.1"
 description = "Python message queuing with Redis and message deduplication"
-authors = ["Elijas <4084885+Elijas@users.noreply.github.com>"]
+authors = [{ name = "Elijas", email = "4084885+Elijas@users.noreply.github.com" }]
 readme = "README.md"
-license = "MIT"
-include = ["redis_message_queue/py.typed"]
+license = { text = "MIT" }
+license-files = ["LICENSE"]
 keywords = ["redis", "message-queue", "deduplication", "task-queue"]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
@@ -16,26 +16,65 @@ classifiers = [
     "Topic :: Software Development :: Libraries",
     "Topic :: System :: Distributed Computing",
 ]
+requires-python = ">=3.12,<4.0"
+dependencies = [
+    "redis>=5.0.1,<8.0.0",
+    "tenacity>=8.1.0",
+]
 
-[tool.poetry.urls]
+[project.urls]
 Homepage = "https://github.com/Elijas/redis-message-queue"
 Repository = "https://github.com/Elijas/redis-message-queue"
 Issues = "https://github.com/Elijas/redis-message-queue/issues"
 
-[tool.poetry.dependencies]
-python = "^3.12"
-redis = ">=5.0.0,<8.0.0"
-tenacity = ">=8.1.0"
+[dependency-groups]
+dev = [
+    "bump-my-version>=1.1.2",
+    "mypy",
+    "ruff",
+]
+test = [
+    "fakeredis[lua]",
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+]
+
+[tool.uv]
+default-groups = ["dev", "test"]
+
+##############################
+### BUMP VERSION
+##############################
 
-[tool.poetry.group.test.dependencies]
-pytest = "*"
-pytest-asyncio = "*"
-pytest-cov = "*"
-fakeredis = {version = "*", extras = ["lua"]}
+[tool.bumpversion]
+current_version = "8.2.1"
+parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
+serialize = ["{major}.{minor}.{patch}"]
+search = "{current_version}"
+replace = "{new_version}"
+regex = false
+ignore_missing_version = false
+ignore_missing_files = false
+tag = false
+sign_tags = false
+tag_name = "v{new_version}"
+tag_message = "Bump version: {current_version} -> {new_version}"
+allow_dirty = true
+commit = true
+message = "chore(release): bump version from {current_version} to {new_version}"
+moveable_tags = []
+commit_args = ""
+setup_hooks = []
+pre_commit_hooks = []
+post_commit_hooks = []
 
 [build-system]
-requires = ["poetry-core"]
-build-backend = "poetry.core.masonry.api"
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+packages = ["redis_message_queue"]
 
 [tool.ruff]
 target-version = "py312"

{redis_message_queue-8.1.0 → redis_message_queue-8.2.1}/redis_message_queue/__init__.py

@@ -1,19 +1,22 @@
 from redis_message_queue._abstract_redis_gateway import AbstractRedisGateway
 from redis_message_queue._event import EventOperation, EventOutcome, QueueEvent
 from redis_message_queue._exceptions import (
+    ClaimStoreFailedError,
     CleanupFailedError,
     ConfigurationError,
     DrainFailedError,
     GatewayContractError,
     LuaScriptError,
     MalformedStoredMessageError,
+    PayloadTooDeepError,
+    PayloadTooLargeError,
     QueueBackpressureError,
     QueueDrainedError,
     RedisMessageQueueError,
     RetryBudgetExhaustedError,
 )
 from redis_message_queue._redis_gateway import RedisGateway
-from redis_message_queue._stored_message import ClaimedMessage, MessageData
+from redis_message_queue._stored_message import ClaimedMessage, MessageData, MessagePayload
 from redis_message_queue.interrupt_handler import (
     BaseGracefulInterruptHandler,
     EventDrivenInterruptHandler,
@@ -27,6 +30,7 @@ __all__ = [
     "AbstractRedisGateway",
     "ClaimedMessage",
     "MessageData",
+    "MessagePayload",
     "EventDrivenInterruptHandler",
     "GracefulInterruptHandler",
     "BaseGracefulInterruptHandler",
@@ -34,11 +38,14 @@ __all__ = [
     "EventOperation",
     "EventOutcome",
     "RedisMessageQueueError",
+    "ClaimStoreFailedError",
     "ConfigurationError",
     "DrainFailedError",
     "GatewayContractError",
     "LuaScriptError",
     "MalformedStoredMessageError",
+    "PayloadTooLargeError",
+    "PayloadTooDeepError",
     "QueueBackpressureError",
     "QueueDrainedError",
     "CleanupFailedError",

{redis_message_queue-8.1.0 → redis_message_queue-8.2.1}/redis_message_queue/_abstract_redis_gateway.py

@@ -12,13 +12,12 @@ class AbstractRedisGateway(ABC):
     gateways MUST uphold the same behavioral contracts documented on each method
     to avoid phantom heartbeats, undetected lease conflicts, or silent data loss.
 
-    Gateways that support visibility timeouts (lease-based claiming) MUST expose
-    a ``message_visibility_timeout_seconds`` property (int or None). This is not
-    abstract because it is configuration rather than protocol, but it is required
-    when the queue is configured with ``heartbeat_interval_seconds``.
-    Lease-capable custom gateways MUST expose this property; omitting it
-    silently disables heartbeat validation and lease-token safety checks,
-    causing the queue to treat the gateway as a non-lease implementation.
+    Gateways that support visibility timeouts (lease-based claiming) MUST
+    override the ``message_visibility_timeout_seconds`` property with a positive
+    int. The abstract base declares this property with a ``None`` default so
+    non-lease custom gateways keep the existing behavior, while lease-capable
+    custom gateways have a typeable contract to override. A positive value is
+    required when the queue is configured with ``heartbeat_interval_seconds``.
 
     The queue also reads ``max_delivery_count`` and ``dead_letter_queue``
     from the gateway. The abstract base provides ``None`` defaults via
@@ -65,6 +64,14 @@ class AbstractRedisGateway(ABC):
     def dead_letter_queue(self) -> str | None:
         return None
 
+    @property
+    def message_visibility_timeout_seconds(self) -> int | None:
+        """Visibility timeout (lease duration) in seconds. Override to enable
+        lease-based crash recovery; return None to disable. Required when the
+        queue is configured with ``heartbeat_interval_seconds``.
+        """
+        return None
+
     @abstractmethod
     def publish_message(self, queue: str, message: str, dedup_key: str) -> bool:
         """Publish a message with deduplication.

{redis_message_queue-8.1.0 → redis_message_queue-8.2.1}/redis_message_queue/_config.py

@@ -31,6 +31,7 @@ DEFAULT_RETRY_INITIAL_DELAY_SECONDS = 0.01
 DEFAULT_PENDING_OVERLOAD_BLOCK_TIMEOUT_SECONDS = 1.0
 INTERRUPTIBLE_RETRY_SLEEP_POLL_SECONDS = 0.05
 PENDING_OVERLOAD_LUA_SENTINEL = -1
+CLAIM_STORE_FAILED_LUA_SENTINEL = "\0__rmq_claim_store_failed__"
 PENDING_OVERLOAD_POLICIES = ("raise", "drop_oldest", "block")
 DEDUPLICATION_REQUIRES_KEY_MESSAGE = (
     "deduplication=True requires get_deduplication_key (callable returning a non-empty str). "
@@ -53,6 +54,13 @@ def is_redis_retryable_exception(exception):
     if isinstance(exception, redis.exceptions.ClusterError) and "TTL exhausted" in str(exception):
         return True
 
+    no_script_error = getattr(redis.exceptions, "NoScriptError", None)
+    if no_script_error is not None and isinstance(exception, no_script_error):
+        return True
+
+    if isinstance(exception, redis.exceptions.ResponseError) and str(exception).startswith("NOSCRIPT"):
+        return True
+
     # 2. Explicit retryable exceptions (BusyLoadingError is a ConnectionError
     #    subclass, so it is already handled by branch 1 above)
     return isinstance(
@@ -832,11 +840,13 @@ if #to_requeue > 0 then
     redis.call('RPUSH', KEYS[1], unpack(to_requeue))
 end
 local dead_lettered_events = {}
+local claim_store_failed_sentinel = string.char(0) .. '__rmq_claim_store_failed__'
 
 local function store_claim_and_return(stored)
     -- pcall guards against OOM mid-write: compensate by returning message to pending
     local ok, result = pcall(function()
-        local lease_token = tostring(redis.call('INCR', KEYS[5]))
+        redis.call('INCR', KEYS[5])
+        local lease_token = redis.call('GET', KEYS[5])
         local claim_payload = cjson.encode({stored, lease_token})
         redis.call('ZADD', KEYS[3], now_ms + tonumber(ARGV[1]), stored)
         redis.call('HSET', KEYS[4], stored, lease_token)
@@ -847,9 +857,10 @@ local function store_claim_and_return(stored)
         return {stored, lease_token, reclaimed_events, dead_lettered_events}
     end)
     if not ok then
+        redis.call('HINCRBY', KEYS[6], stored, -1)
         redis.call('LREM', KEYS[2], 1, stored)
         redis.pcall('RPUSH', KEYS[1], stored)
-        return false
+        return {claim_store_failed_sentinel, tostring(result), stored}
     end
     return result
 end

{redis_message_queue-8.1.0 → redis_message_queue-8.2.1}/redis_message_queue/_exceptions.py

@@ -48,6 +48,14 @@ class CleanupFailedError(RedisMessageQueueError):
     """Cleanup after handler completion failed."""
 
 
+class ClaimStoreFailedError(RedisMessageQueueError):
+    """Raised when the VT-claim Lua store_claim_and_return pcall failed.
+
+    The script decremented the speculative delivery_count increment and
+    compensated by returning the message to pending before surfacing this error.
+    """
+
+
 class DrainFailedError(RedisMessageQueueError):
     """Wraps a non-RMQ exception caught during drain pending-claim recovery.
 
@@ -62,6 +70,14 @@ class MalformedStoredMessageError(RedisMessageQueueError):
     """Stored value is not a valid RMQ envelope for the configured decode mode."""
 
 
+class PayloadTooLargeError(RedisMessageQueueError, ValueError):
+    """Publish payload exceeds the configured serialized byte limit."""
+
+
+class PayloadTooDeepError(RedisMessageQueueError, ValueError):
+    """Publish payload exceeds the configured nesting-depth limit."""
+
+
 class QueueBackpressureError(RedisMessageQueueError):
     """Publish rejected because the pending queue is at its configured limit."""
 

redis_message_queue-8.2.1/redis_message_queue/_payload_limits.py

@@ -0,0 +1,72 @@
+import json
+
+from redis_message_queue._exceptions import ConfigurationError, PayloadTooDeepError, PayloadTooLargeError
+
+
+def validate_payload_limit_parameter(name: str, value: int | None) -> int | None:
+    if value is None:
+        return None
+    if not isinstance(value, int) or isinstance(value, bool):
+        bool_hint = " (use a positive int or None, not True/False)" if isinstance(value, bool) else ""
+        raise TypeError(f"'{name}' must be an int or None, got {type(value).__name__}{bool_hint}")
+    if value <= 0:
+        raise ConfigurationError(f"'{name}' must be positive when provided, got {value}")
+    return value
+
+
+def validate_max_payload_depth(message: dict, max_payload_depth: int | None) -> None:
+    if max_payload_depth is None:
+        return
+
+    stack: list[tuple[object, str, int]] = [(message, "message", 0)]
+    seen: set[int] = set()
+    while stack:
+        value, path, depth = stack.pop()
+        if depth > max_payload_depth:
+            raise PayloadTooDeepError(
+                f"max_payload_depth={max_payload_depth} exceeded: depth {depth} reached at {path}"
+            )
+        if isinstance(value, dict):
+            current_id = id(value)
+            if current_id in seen:
+                continue
+            seen.add(current_id)
+            children = list(value.items())
+            for key, child in reversed(children):
+                stack.append((child, f"{path}[{key!r}]", depth + 1))
+        elif isinstance(value, (list, tuple)):
+            current_id = id(value)
+            if current_id in seen:
+                continue
+            seen.add(current_id)
+            for index in range(len(value) - 1, -1, -1):
+                stack.append((value[index], f"{path}[{index}]", depth + 1))
+
+
+def serialize_dict_payload_with_limit(message: dict, max_payload_bytes: int | None) -> str:
+    message_str = json.dumps(message, sort_keys=True, allow_nan=False)
+    if max_payload_bytes is not None:
+        validate_max_payload_bytes(
+            len(message_str.encode("utf-8")),
+            max_payload_bytes,
+            payload_type="dict message",
+        )
+    return message_str
+
+
+def validate_str_payload_size(message: str, max_payload_bytes: int | None) -> None:
+    if max_payload_bytes is None:
+        return
+    validate_max_payload_bytes(
+        len(message.encode("utf-8")),
+        max_payload_bytes,
+        payload_type="str message",
+    )
+
+
+def validate_max_payload_bytes(size_bytes: int, max_payload_bytes: int | None, *, payload_type: str) -> None:
+    if max_payload_bytes is None or size_bytes <= max_payload_bytes:
+        return
+    raise PayloadTooLargeError(
+        f"max_payload_bytes={max_payload_bytes} exceeded: payload is {size_bytes} bytes ({payload_type})"
+    )

{redis_message_queue-8.1.0 → redis_message_queue-8.2.1}/redis_message_queue/_queue_key_manager.py

@@ -1,7 +1,8 @@
 from redis_message_queue._exceptions import ConfigurationError
+from redis_message_queue._stored_message import MessagePayload
 
 
-def validate_callable_deduplication_key(dedup_key: object, message: str | dict) -> str:
+def validate_callable_deduplication_key(dedup_key: object, message: MessagePayload) -> 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"

{redis_message_queue-8.1.0 → redis_message_queue-8.2.1}/redis_message_queue/_redis_gateway.py

@@ -16,6 +16,7 @@ from redis_message_queue._config import (
     ADD_MESSAGE_LUA_SCRIPT,
     CLAIM_MESSAGE_LUA_SCRIPT,
     CLAIM_MESSAGE_WITH_VISIBILITY_TIMEOUT_LUA_SCRIPT,
+    CLAIM_STORE_FAILED_LUA_SENTINEL,
     CLEANUP_DRAINED_LEASE_TOKEN_COUNTER_LUA_SCRIPT,
     DEFAULT_MESSAGE_DEDUPLICATION_LOG_TTL,
     DEFAULT_MESSAGE_WAIT_INTERVAL_SECONDS,
@@ -39,6 +40,7 @@ from redis_message_queue._config import (
 )
 from redis_message_queue._event import EventOperation, EventOutcome
 from redis_message_queue._exceptions import (
+    ClaimStoreFailedError,
     ConfigurationError,
     QueueBackpressureError,
     RedisMessageQueueError,
@@ -76,6 +78,7 @@ _OPTIONAL_DEAD_LETTER_PLACEHOLDER_SUFFIX = ":dead_letter_placeholder"
 _VISIBILITY_TIMEOUT_POLL_INTERVAL_SECONDS = 0.25
 _PENDING_OVERLOAD_INITIAL_BACKOFF_SECONDS = 0.010
 _PENDING_OVERLOAD_MAX_BACKOFF_SECONDS = 0.500
+_CLAIM_STORE_FAILED_LUA_SENTINEL_BYTES = CLAIM_STORE_FAILED_LUA_SENTINEL.encode("utf-8")
 
 
 class _DrainDeadlineExceeded(Exception):
@@ -138,6 +141,22 @@ def _decode_lua_text(value: object) -> str | None:
     return None
 
 
+def _decode_lua_error(value: object) -> str:
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+    if isinstance(value, str) and value:
+        return value
+    return "unknown Lua error"
+
+
+def _is_claim_store_failed_result(result: object) -> bool:
+    return (
+        isinstance(result, list | tuple)
+        and len(result) >= 2
+        and result[0] in (CLAIM_STORE_FAILED_LUA_SENTINEL, _CLAIM_STORE_FAILED_LUA_SENTINEL_BYTES)
+    )
+
+
 def _coerce_lua_message_attempts(value: object) -> list[_MessageAttemptEvent]:
     if not isinstance(value, list | tuple):
         return []
@@ -931,6 +950,16 @@ class RedisGateway(AbstractRedisGateway):
         if result is None:
             return None
 
+        if _is_claim_store_failed_result(result):
+            stored_message = result[2] if len(result) > 2 else None
+            message_id = extract_stored_message_id(stored_message) if isinstance(stored_message, (str, bytes)) else None
+            raise ClaimStoreFailedError(
+                f"VT claim store failed after delivery_count rollback: {_decode_lua_error(result[1])}",
+                queue=from_queue,
+                message_id=message_id,
+                operation="claim",
+            )
+
         stored_message, lease_token = result[0], result[1]
         reclaimed_attempts = _coerce_lua_message_attempts(result[2]) if len(result) > 2 else []
         dead_lettered_attempts = _coerce_lua_message_attempts(result[3]) if len(result) > 3 else []

{redis_message_queue-8.1.0 → redis_message_queue-8.2.1}/redis_message_queue/_stored_message.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 from redis_message_queue._exceptions import MalformedStoredMessageError
 
 MessageData = str | bytes
+MessagePayload = str | dict[str, object]
 
 _STORED_MESSAGE_PREFIX = "\x1eRMQ1:"
 _STORED_MESSAGE_PREFIX_BYTES = _STORED_MESSAGE_PREFIX.encode("utf-8")

{redis_message_queue-8.1.0 → redis_message_queue-8.2.1}/redis_message_queue/asyncio/__init__.py

@@ -1,17 +1,20 @@
 from redis_message_queue._event import EventOperation, EventOutcome, QueueEvent
 from redis_message_queue._exceptions import (
+    ClaimStoreFailedError,
     CleanupFailedError,
     ConfigurationError,
     DrainFailedError,
     GatewayContractError,
     LuaScriptError,
     MalformedStoredMessageError,
+    PayloadTooDeepError,
+    PayloadTooLargeError,
     QueueBackpressureError,
     QueueDrainedError,
     RedisMessageQueueError,
     RetryBudgetExhaustedError,
 )
-from redis_message_queue._stored_message import ClaimedMessage, MessageData
+from redis_message_queue._stored_message import ClaimedMessage, MessageData, MessagePayload
 from redis_message_queue.asyncio._abstract_redis_gateway import AbstractRedisGateway
 from redis_message_queue.asyncio._redis_gateway import RedisGateway
 from redis_message_queue.asyncio.redis_message_queue import RedisMessageQueue
@@ -27,6 +30,7 @@ __all__ = [
     "AbstractRedisGateway",
     "ClaimedMessage",
     "MessageData",
+    "MessagePayload",
     "EventDrivenInterruptHandler",
     "GracefulInterruptHandler",
     "BaseGracefulInterruptHandler",
@@ -34,11 +38,14 @@ __all__ = [
     "EventOperation",
     "EventOutcome",
     "RedisMessageQueueError",
+    "ClaimStoreFailedError",
     "ConfigurationError",
     "DrainFailedError",
     "GatewayContractError",
     "LuaScriptError",
     "MalformedStoredMessageError",
+    "PayloadTooLargeError",
+    "PayloadTooDeepError",
     "QueueBackpressureError",
     "QueueDrainedError",
     "CleanupFailedError",

{redis_message_queue-8.1.0 → redis_message_queue-8.2.1}/redis_message_queue/asyncio/_abstract_redis_gateway.py

@@ -13,13 +13,12 @@ class AbstractRedisGateway(ABC):
     documented on each method to avoid phantom heartbeats, undetected lease conflicts,
     or silent data loss.
 
-    Gateways that support visibility timeouts (lease-based claiming) MUST expose
-    a ``message_visibility_timeout_seconds`` property (int or None). This is not
-    abstract because it is configuration rather than protocol, but it is required
-    when the queue is configured with ``heartbeat_interval_seconds``.
-    Lease-capable custom gateways MUST expose this property; omitting it
-    silently disables heartbeat validation and lease-token safety checks,
-    causing the queue to treat the gateway as a non-lease implementation.
+    Gateways that support visibility timeouts (lease-based claiming) MUST
+    override the ``message_visibility_timeout_seconds`` property with a positive
+    int. The abstract base declares this property with a ``None`` default so
+    non-lease custom gateways keep the existing behavior, while lease-capable
+    custom gateways have a typeable contract to override. A positive value is
+    required when the queue is configured with ``heartbeat_interval_seconds``.
 
     The queue also reads ``max_delivery_count`` and ``dead_letter_queue``
     from the gateway. The abstract base provides ``None`` defaults via
@@ -65,6 +64,14 @@ class AbstractRedisGateway(ABC):
     def dead_letter_queue(self) -> str | None:
         return None
 
+    @property
+    def message_visibility_timeout_seconds(self) -> int | None:
+        """Visibility timeout (lease duration) in seconds. Override to enable
+        lease-based crash recovery; return None to disable. Required when the
+        queue is configured with ``heartbeat_interval_seconds``.
+        """
+        return None
+
     @abstractmethod
     async def publish_message(self, queue: str, message: str, dedup_key: str) -> bool:
         """Publish a message with deduplication.

{redis_message_queue-8.1.0 → redis_message_queue-8.2.1}/redis_message_queue/asyncio/_redis_gateway.py

@@ -14,6 +14,7 @@ from redis_message_queue._config import (
     ADD_MESSAGE_LUA_SCRIPT,
     CLAIM_MESSAGE_LUA_SCRIPT,
     CLAIM_MESSAGE_WITH_VISIBILITY_TIMEOUT_LUA_SCRIPT,
+    CLAIM_STORE_FAILED_LUA_SENTINEL,
     CLEANUP_DRAINED_LEASE_TOKEN_COUNTER_LUA_SCRIPT,
     DEFAULT_MESSAGE_DEDUPLICATION_LOG_TTL,
     DEFAULT_MESSAGE_WAIT_INTERVAL_SECONDS,
@@ -37,6 +38,7 @@ from redis_message_queue._config import (
 )
 from redis_message_queue._event import EventOperation, EventOutcome
 from redis_message_queue._exceptions import (
+    ClaimStoreFailedError,
     ConfigurationError,
     QueueBackpressureError,
     RedisMessageQueueError,
@@ -75,6 +77,7 @@ _OPTIONAL_DEAD_LETTER_PLACEHOLDER_SUFFIX = ":dead_letter_placeholder"
 _VISIBILITY_TIMEOUT_POLL_INTERVAL_SECONDS = 0.25
 _PENDING_OVERLOAD_INITIAL_BACKOFF_SECONDS = 0.010
 _PENDING_OVERLOAD_MAX_BACKOFF_SECONDS = 0.500
+_CLAIM_STORE_FAILED_LUA_SENTINEL_BYTES = CLAIM_STORE_FAILED_LUA_SENTINEL.encode("utf-8")
 
 
 class _DrainDeadlineExceeded(Exception):
@@ -121,6 +124,22 @@ def _decode_lua_text(value: object) -> str | None:
     return None
 
 
+def _decode_lua_error(value: object) -> str:
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+    if isinstance(value, str) and value:
+        return value
+    return "unknown Lua error"
+
+
+def _is_claim_store_failed_result(result: object) -> bool:
+    return (
+        isinstance(result, list | tuple)
+        and len(result) >= 2
+        and result[0] in (CLAIM_STORE_FAILED_LUA_SENTINEL, _CLAIM_STORE_FAILED_LUA_SENTINEL_BYTES)
+    )
+
+
 def _coerce_lua_message_attempts(value: object) -> list[_MessageAttemptEvent]:
     if not isinstance(value, list | tuple):
         return []
@@ -911,6 +930,16 @@ class RedisGateway(AbstractRedisGateway):
         if result is None:
             return None
 
+        if _is_claim_store_failed_result(result):
+            stored_message = result[2] if len(result) > 2 else None
+            message_id = extract_stored_message_id(stored_message) if isinstance(stored_message, (str, bytes)) else None
+            raise ClaimStoreFailedError(
+                f"VT claim store failed after delivery_count rollback: {_decode_lua_error(result[1])}",
+                queue=from_queue,
+                message_id=message_id,
+                operation="claim",
+            )
+
         stored_message, lease_token = result[0], result[1]
         reclaimed_attempts = _coerce_lua_message_attempts(result[2]) if len(result) > 2 else []
         dead_lettered_attempts = _coerce_lua_message_attempts(result[3]) if len(result) > 3 else []

{redis_message_queue-8.1.0 → redis_message_queue-8.2.1}/redis_message_queue/asyncio/redis_message_queue.py

@@ -1,7 +1,6 @@
 import asyncio
 import hashlib
 import inspect
-import json
 import logging
 import math
 import time
@@ -29,6 +28,12 @@ from redis_message_queue._exceptions import (
     RedisMessageQueueError,
     _set_exception_context,
 )
+from redis_message_queue._payload_limits import (
+    serialize_dict_payload_with_limit,
+    validate_max_payload_depth,
+    validate_payload_limit_parameter,
+    validate_str_payload_size,
+)
 from redis_message_queue._queue_key_manager import QueueKeyManager, validate_callable_deduplication_key
 from redis_message_queue._redis_cluster import (
     plain_redis_cluster_client_error,
@@ -38,6 +43,7 @@ from redis_message_queue._redis_cluster import (
 from redis_message_queue._stored_message import (
     ClaimedMessage,
     MessageData,
+    MessagePayload,
     decode_stored_message,
     extract_stored_message_id,
 )
@@ -86,23 +92,24 @@ def _find_non_string_dict_keys(value: object) -> list[object]:
     non_str_keys: list[object] = []
     seen: set[int] = set()
 
-    def visit(current: object) -> None:
+    stack = [value]
+    while stack:
+        current = stack.pop()
         if not isinstance(current, (dict, list, tuple)):
-            return
+            continue
         current_id = id(current)
         if current_id in seen:
-            return
+            continue
         seen.add(current_id)
         if isinstance(current, dict):
+            children = []
             for key, child in current.items():
                 if not isinstance(key, str):
                     non_str_keys.append(key)
-                visit(child)
-            return
-        for child in current:
-            visit(child)
-
-    visit(value)
+                children.append(child)
+            stack.extend(reversed(children))
+        else:
+            stack.extend(reversed(current))
     return non_str_keys
 
 
@@ -565,8 +572,10 @@ class RedisMessageQueue:
         pending_overload_policy: Literal["raise", "drop_oldest", "block"] = "raise",
         pending_overload_block_timeout_seconds: float = DEFAULT_PENDING_OVERLOAD_BLOCK_TIMEOUT_SECONDS,
         key_separator: str = "::",
-        get_deduplication_key: Optional[Callable[[str | dict], str]] = None,
+        get_deduplication_key: Optional[Callable[[MessagePayload], str | Awaitable[str]]] = None,
         strict_payload_types: bool = False,
+        max_payload_bytes: int | None = None,
+        max_payload_depth: int | None = None,
         interrupt: BaseGracefulInterruptHandler | None = None,
         on_heartbeat_failure: Callable[[], Awaitable[None] | None] | None = None,
         on_event: Callable[[QueueEvent], Awaitable[None]] | None = None,
@@ -601,6 +610,10 @@ class RedisMessageQueue:
         sets, bytes, and datetime objects with a path-aware ``TypeError``.
         The default ``False`` preserves the existing ``json.dumps`` behavior.
 
+        ``max_payload_bytes`` and ``max_payload_depth`` default to ``None``
+        (unbounded). Set positive integers to reject oversized serialized
+        payloads or overly deep dict/list payload trees before enqueue.
+
         ``max_pending_length`` defaults to ``None`` (unbounded). Set it to a
         positive integer to cap pending-list depth during publish.
 
@@ -654,6 +667,8 @@ class RedisMessageQueue:
                 f"'strict_payload_types' must be a bool, got {type(strict_payload_types).__name__}"
                 " (use True or False, not 1/0)"
             )
+        max_payload_bytes = validate_payload_limit_parameter("max_payload_bytes", max_payload_bytes)
+        max_payload_depth = validate_payload_limit_parameter("max_payload_depth", max_payload_depth)
         if max_completed_length is not None:
             if not isinstance(max_completed_length, int) or isinstance(max_completed_length, bool):
                 bool_hint = " (use True or False, not 1/0)" if isinstance(max_completed_length, bool) else ""
@@ -702,7 +717,8 @@ class RedisMessageQueue:
         if get_deduplication_key is not None and not callable(get_deduplication_key):
             raise TypeError(
                 f"'get_deduplication_key' must be callable, got {type(get_deduplication_key).__name__}."
-                " Expected a function that takes the message (str | dict) and returns a str (or an awaitable thereof)."
+                " Expected a function that takes the message (MessagePayload) and returns a str"
+                " (or an awaitable thereof)."
                 " Example: get_deduplication_key=lambda msg: msg['user_id']"
             )
         validate_dedup_configuration(
@@ -750,6 +766,8 @@ class RedisMessageQueue:
         self._max_delivery_count = max_delivery_count
         self._get_deduplication_key = get_deduplication_key
         self._strict_payload_types = strict_payload_types
+        self._max_payload_bytes = max_payload_bytes
+        self._max_payload_depth = max_payload_depth
         self._heartbeat_interval_seconds = None
         self._warned_no_lease_for_heartbeat = False
         self._requires_claimed_message = False
@@ -951,7 +969,7 @@ class RedisMessageQueue:
                 raise plain_redis_cluster_client_error(type(client).__name__)
             self._plain_redis_cluster_probe_client = None
 
-    async def publish(self, message: str | dict) -> bool:
+    async def publish(self, message: MessagePayload) -> bool:
         """Publish a message.
 
         Dict messages are serialized via ``json.dumps(message, sort_keys=True)``.
@@ -978,7 +996,7 @@ class RedisMessageQueue:
                 raise QueueDrainedError("queue is drained", queue=self._queue_name, operation="drain")
             return await self._publish_unlocked(message)
 
-    async def _publish_unlocked(self, message: str | dict) -> bool:
+    async def _publish_unlocked(self, message: MessagePayload) -> bool:
         started_at = time.perf_counter()
         try:
             await self._ensure_plain_redis_client_is_not_cluster()
@@ -993,8 +1011,10 @@ class RedisMessageQueue:
                     )
                 if self._strict_payload_types:
                     _validate_strict_payload_types(message)
-                message_str = json.dumps(message, sort_keys=True, allow_nan=False)
+                validate_max_payload_depth(message, self._max_payload_depth)
+                message_str = serialize_dict_payload_with_limit(message, self._max_payload_bytes)
             else:
+                validate_str_payload_size(message, self._max_payload_bytes)
                 message_str = message
 
             if not self._deduplication:

{redis_message_queue-8.1.0 → redis_message_queue-8.2.1}/redis_message_queue/redis_message_queue.py

@@ -1,6 +1,5 @@
 import hashlib
 import inspect
-import json
 import logging
 import math
 import threading
@@ -30,6 +29,12 @@ from redis_message_queue._exceptions import (
     RedisMessageQueueError,
     _set_exception_context,
 )
+from redis_message_queue._payload_limits import (
+    serialize_dict_payload_with_limit,
+    validate_max_payload_depth,
+    validate_payload_limit_parameter,
+    validate_str_payload_size,
+)
 from redis_message_queue._queue_key_manager import QueueKeyManager, validate_callable_deduplication_key
 from redis_message_queue._redis_cluster import (
     plain_redis_cluster_client_error,
@@ -40,6 +45,7 @@ from redis_message_queue._redis_gateway import RedisGateway
 from redis_message_queue._stored_message import (
     ClaimedMessage,
     MessageData,
+    MessagePayload,
     decode_stored_message,
     extract_stored_message_id,
 )
@@ -89,23 +95,24 @@ def _find_non_string_dict_keys(value: object) -> list[object]:
     non_str_keys: list[object] = []
     seen: set[int] = set()
 
-    def visit(current: object) -> None:
+    stack = [value]
+    while stack:
+        current = stack.pop()
         if not isinstance(current, (dict, list, tuple)):
-            return
+            continue
         current_id = id(current)
         if current_id in seen:
-            return
+            continue
         seen.add(current_id)
         if isinstance(current, dict):
+            children = []
             for key, child in current.items():
                 if not isinstance(key, str):
                     non_str_keys.append(key)
-                visit(child)
-            return
-        for child in current:
-            visit(child)
-
-    visit(value)
+                children.append(child)
+            stack.extend(reversed(children))
+        else:
+            stack.extend(reversed(current))
     return non_str_keys
 
 
@@ -517,8 +524,10 @@ class RedisMessageQueue:
         pending_overload_policy: Literal["raise", "drop_oldest", "block"] = "raise",
         pending_overload_block_timeout_seconds: float = DEFAULT_PENDING_OVERLOAD_BLOCK_TIMEOUT_SECONDS,
         key_separator: str = "::",
-        get_deduplication_key: Optional[Callable[[str | dict], str]] = None,
+        get_deduplication_key: Optional[Callable[[MessagePayload], str]] = None,
         strict_payload_types: bool = False,
+        max_payload_bytes: int | None = None,
+        max_payload_depth: int | None = None,
         interrupt: BaseGracefulInterruptHandler | None = None,
         on_heartbeat_failure: Callable[[], None] | None = None,
         on_event: Callable[[QueueEvent], None] | None = None,
@@ -553,6 +562,10 @@ class RedisMessageQueue:
         sets, bytes, and datetime objects with a path-aware ``TypeError``.
         The default ``False`` preserves the existing ``json.dumps`` behavior.
 
+        ``max_payload_bytes`` and ``max_payload_depth`` default to ``None``
+        (unbounded). Set positive integers to reject oversized serialized
+        payloads or overly deep dict/list payload trees before enqueue.
+
         ``max_pending_length`` defaults to ``None`` (unbounded). Set it to a
         positive integer to cap pending-list depth during publish.
 
@@ -605,6 +618,8 @@ class RedisMessageQueue:
                 f"'strict_payload_types' must be a bool, got {type(strict_payload_types).__name__}"
                 " (use True or False, not 1/0)"
             )
+        max_payload_bytes = validate_payload_limit_parameter("max_payload_bytes", max_payload_bytes)
+        max_payload_depth = validate_payload_limit_parameter("max_payload_depth", max_payload_depth)
         if max_completed_length is not None:
             if not isinstance(max_completed_length, int) or isinstance(max_completed_length, bool):
                 bool_hint = " (use True or False, not 1/0)" if isinstance(max_completed_length, bool) else ""
@@ -653,7 +668,7 @@ class RedisMessageQueue:
         if get_deduplication_key is not None and not callable(get_deduplication_key):
             raise TypeError(
                 f"'get_deduplication_key' must be callable, got {type(get_deduplication_key).__name__}."
-                " Expected a function that takes the message (str | dict) and returns a str."
+                " Expected a function that takes the message (MessagePayload) and returns a str."
                 " Example: get_deduplication_key=lambda msg: msg['user_id']"
             )
         if get_deduplication_key is not None and is_async_callable(get_deduplication_key):
@@ -713,6 +728,8 @@ class RedisMessageQueue:
         self._max_delivery_count = max_delivery_count
         self._get_deduplication_key = get_deduplication_key
         self._strict_payload_types = strict_payload_types
+        self._max_payload_bytes = max_payload_bytes
+        self._max_payload_depth = max_payload_depth
         self._heartbeat_interval_seconds = None
         self._warned_no_lease_for_heartbeat = False
         self._requires_claimed_message = False
@@ -900,7 +917,7 @@ class RedisMessageQueue:
         wrapped_error.__cause__ = raw_error
         return wrapped_error
 
-    def publish(self, message: str | dict) -> bool:
+    def publish(self, message: MessagePayload) -> bool:
         """Publish a message.
 
         Dict messages are serialized via ``json.dumps(message, sort_keys=True)``.
@@ -927,7 +944,7 @@ class RedisMessageQueue:
                 raise QueueDrainedError("queue is drained", queue=self._queue_name, operation="drain")
             return self._publish_unlocked(message)
 
-    def _publish_unlocked(self, message: str | dict) -> bool:
+    def _publish_unlocked(self, message: MessagePayload) -> bool:
         started_at = time.perf_counter()
         try:
             if not isinstance(message, (str, dict)):
@@ -941,8 +958,10 @@ class RedisMessageQueue:
                     )
                 if self._strict_payload_types:
                     _validate_strict_payload_types(message)
-                message_str = json.dumps(message, sort_keys=True, allow_nan=False)
+                validate_max_payload_depth(message, self._max_payload_depth)
+                message_str = serialize_dict_payload_with_limit(message, self._max_payload_bytes)
             else:
+                validate_str_payload_size(message, self._max_payload_bytes)
                 message_str = message
 
             if not self._deduplication: