Custom lock prefix

Added a new :paramref:`.RedisBackend.lock_prefix` parameter to the
:class:`.RedisBackend` and :class:`.ValkeyBackend` backends to allow
customization of the lock key prefix. The prefix must be between 2 and 10
characters long and may contain any alphanumeric character and the symbols
``_-.:`` . This allows for improved visual clarity when inspecting backend
keys, particularly when key names may be ambiguous with the default
``_lock`` prefix.  Pull request courtesy Jonathan Vanasco.

Extends Redis/Valkey with a "lock_prefix" argument, which allows users to override the default "_lock{0}" template.

I proposed this 10 years ago, and have been using it in a custom backend.  I keep forgetting to turn this into a PR.

The rationale for this PR: The current design uses a template of `"_lock{0}" % key` which can be visually confusing to scan during manual audits: _lockkey1, _lockkey2, etc.  This PR allows for `"_lok.{0}" % key`, which is easier to read: _lok.key1, _lok.key2, etc.

A regex is used to validate the lock_prefix, restricting it to 2-10 chars `[A-Z0-9_-:.]`

A test for correct usage is provided.  Because the test system uses setupclass, I could not think of a good way to implement bad config args.

Fixes: #76

Closes: #277
Pull-request: #277
Pull-request-sha: dda8fff

Change-Id: I22a6776168c78030e4472591a0c1e12a45b67cfb

Author: jvanasco

docs/build/unreleased/76.rst

@@ -0,0 +1,11 @@
+.. change::
+    :tags: feature, redis
+    :tickets: 76
+
+    Added a new :paramref:`.RedisBackend.lock_prefix` parameter to the
+    :class:`.RedisBackend` and :class:`.ValkeyBackend` backends to allow
+    customization of the lock key prefix. The prefix must be between 2 and 10
+    characters long and may contain any alphanumeric character and the symbols
+    ``_-.:`` . This allows for improved visual clarity when inspecting backend
+    keys, particularly when key names may be ambiguous with the default
+    ``_lock`` prefix.  Pull request courtesy Jonathan Vanasco.

dogpile/cache/backends/redis.py

@@ -6,6 +6,7 @@
 
 """
 
+import re
 import typing
 import warnings
 
@@ -21,6 +22,9 @@
 __all__ = ("RedisBackend", "RedisSentinelBackend", "RedisClusterBackend")
 
 
+RE_VALID_PREFIX = re.compile(r"^[\w\-\.\:]{2,10}$")
+
+
 class RedisBackend(BytesBackend):
     r"""A `Redis <http://redis.io/>`__ backend, using the
     `redis-py <http://pypi.python.org/pypi/redis/>`__ driver.
@@ -87,6 +91,12 @@ class RedisBackend(BytesBackend):
 
      .. versionadded:: 1.4.1
 
+    :param lock_prefix: string. This prefix is used for generating the name of
+     locks. If customized, the prefix must be between 2 and 10 characters long,
+     and may contain any alphanumeric character and the symbols "_-.:".
+
+     .. versionadded:: 1.5.0
+
     :param socket_timeout: float, seconds for socket timeout.
      Default is None (no timeout).
 
@@ -132,6 +142,8 @@ class RedisBackend(BytesBackend):
      .. versionadded:: 1.1.6
     """
 
+    lock_template: str = "_lock{0}"
+
     def __init__(self, arguments):
         arguments = arguments.copy()
         self._imports()
@@ -174,6 +186,16 @@ def __init__(self, arguments):
         self.redis_expiration_time = arguments.pop("redis_expiration_time", 0)
         self.connection_pool = arguments.pop("connection_pool", None)
 
+        lock_prefix = arguments.pop("lock_prefix", None)
+        if lock_prefix:
+            if (not isinstance(lock_prefix, str)) or (
+                not RE_VALID_PREFIX.match(lock_prefix)
+            ):
+                raise ValueError(
+                    "Invalid `lock_prefix` submitted: `%s`." % lock_prefix
+                )
+            self.lock_template = "%s{0}" % lock_prefix
+
         self._create_client()
 
     def _imports(self):
@@ -225,7 +247,7 @@ def get_mutex(self, key):
         if self.distributed_lock:
             return _RedisLockWrapper(
                 self.writer_client.lock(
-                    "_lock{0}".format(key),
+                    self.lock_template.format(key),
                     timeout=self.lock_timeout,
                     sleep=self.lock_sleep,
                     thread_local=self.thread_local_lock,

dogpile/cache/backends/valkey.py

@@ -6,6 +6,7 @@
 
 """
 
+import re
 import typing
 import warnings
 
@@ -21,6 +22,9 @@
 __all__ = ("ValkeyBackend", "ValkeySentinelBackend", "ValkeyClusterBackend")
 
 
+RE_VALID_PREFIX = re.compile(r"^[\w\-\.\:]{2,10}$")
+
+
 class ValkeyBackend(BytesBackend):
     r"""A `Valkey <http://valkey.io/>`__ backend, using the
     `valkey-py <http://pypi.python.org/pypi/valkey/>`__ driver.
@@ -88,6 +92,12 @@ class ValkeyBackend(BytesBackend):
 
      .. versionadded:: 1.4.1
 
+    :param lock_prefix: string. This prefix is used for generating the name of
+     locks. If customized, the prefix must be between 2 and 10 characters long,
+     and may contain any alphanumeric character and the symbols "_-.:".
+
+     .. versionadded:: 1.5.0
+
     :param socket_timeout: float, seconds for socket timeout.
      Default is None (no timeout).
 
@@ -125,6 +135,8 @@ class ValkeyBackend(BytesBackend):
      ``charset``, etc.
     """
 
+    lock_template: str = "_lock{0}"
+
     def __init__(self, arguments):
         arguments = arguments.copy()
         self._imports()
@@ -168,6 +180,15 @@ def __init__(self, arguments):
             "valkey_expiration_time", 0
         )
         self.connection_pool = arguments.pop("connection_pool", None)
+
+        lock_prefix = arguments.pop("lock_prefix", None)
+        if lock_prefix:
+            if (not isinstance(lock_prefix, str)) or (
+                not RE_VALID_PREFIX.match(lock_prefix)
+            ):
+                raise ValueError("Invalid `lock_prefix` submitted.")
+            self.lock_template = "%s{0}" % lock_prefix
+
         self._create_client()
 
     def _imports(self):
@@ -219,7 +240,7 @@ def get_mutex(self, key):
         if self.distributed_lock:
             return _ValkeyLockWrapper(
                 self.writer_client.lock(
-                    "_lock{0}".format(key),
+                    self.lock_template.format(key),
                     timeout=self.lock_timeout,
                     sleep=self.lock_sleep,
                     thread_local=self.thread_local_lock,

tests/cache/test_redis_backend.py

@@ -64,6 +64,19 @@ class RedisDistributedMutexTest(_TestRedisConn, _GenericMutexTestSuite):
     }
 
 
+class RedisDistributedMutexPrefixTest(_TestRedisConn, _GenericMutexTestSuite):
+    backend = "dogpile.cache.redis"
+    config_args = {
+        "arguments": {
+            "host": REDIS_HOST,
+            "port": REDIS_PORT,
+            "db": 0,
+            "distributed_lock": True,
+            "lock_prefix": "_lok.",
+        }
+    }
+
+
 class RedisAsyncCreationTest(_TestRedisConn, _GenericBackendFixture):
     backend = "dogpile.cache.redis"
     config_args = {

tests/cache/test_valkey_backend.py

@@ -64,6 +64,21 @@ class ValkeyDistributedMutexTest(_TestValkeyConn, _GenericMutexTestSuite):
     }
 
 
+class ValkeyDistributedMutexPrefixTest(
+    _TestValkeyConn, _GenericMutexTestSuite
+):
+    backend = "dogpile.cache.valkey"
+    config_args = {
+        "arguments": {
+            "host": VALKEY_HOST,
+            "port": VALKEY_PORT,
+            "db": 0,
+            "distributed_lock": True,
+            "lock_prefix": "_lok.",
+        }
+    }
+
+
 class ValkeyAsyncCreationTest(_TestValkeyConn, _GenericBackendFixture):
     backend = "dogpile.cache.valkey"
     config_args = {