redis-allocator 0.5.2__tar.gz → 0.6.1__tar.gz

{redis_allocator-0.5.2/redis_allocator.egg-info → redis_allocator-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redis-allocator
-Version: 0.5.2
+Version: 0.6.1
 Summary: Redis-based resource allocation system.
 Home-page: https://github.com/invoker-bot/RedisAllocator-python
 Author: Invoker Bot
@@ -21,7 +21,7 @@ Provides-Extra: test
 Requires-Dist: pytest>=7.4.3; extra == "test"
 Requires-Dist: pytest-cov>=4.1.0; extra == "test"
 Requires-Dist: pytest-mock>=3.12.0; extra == "test"
-Requires-Dist: fakeredis[lua]>=2.20.1; extra == "test"
+Requires-Dist: fakeredis[lua]>=2.35.1; extra == "test"
 Requires-Dist: flake8>=6.1.0; extra == "test"
 Requires-Dist: freezegun>=1.4.0; extra == "test"
 Provides-Extra: docs
@@ -33,7 +33,7 @@ Provides-Extra: dev
 Requires-Dist: pytest>=7.4.3; extra == "dev"
 Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
-Requires-Dist: fakeredis[lua]>=2.20.1; extra == "dev"
+Requires-Dist: fakeredis[lua]>=2.35.1; extra == "dev"
 Requires-Dist: flake8>=6.1.0; extra == "dev"
 Requires-Dist: freezegun>=1.4.0; extra == "dev"
 Requires-Dist: sphinx>=7.0.0; extra == "dev"
@@ -91,6 +91,15 @@ RedisAllocator is built around these key ideas:
 - **Shared Mode**: Configurable allocation modes supporting both exclusive and shared resource usage
 - **Soft Binding**: Associates named objects with specific resources for consistent allocation
 
+## Behavior Contracts (Important for API Users)
+
+A few intentional behaviors that may surprise newcomers — knowing them up-front avoids debugging dead-ends:
+
+- **`malloc_key(timeout<=0)` creates a permanent (non-expiring) lock.** Useful for resources whose ownership must outlive process restarts; the caller takes responsibility for releasing via `free_keys`. GC never reclaims it (because expiry is also `-1`). Misuse causes resource leaks — only pass `timeout=0` when you mean "I will manage this lock myself."
+- **`cache_timeout=0` (or negative) creates a permanent soft binding.** Sticks until explicitly overwritten by another `update_soft_bind` for the same name, or removed via `unbind_soft_bind`. Symmetric to the lock-timeout contract above.
+- **`assign()` does not delete the lock keys of items it evicts.** A deliberate write-amplification trade-off: locks expire on their own TTL, and if the same key is later re-`extend`-ed into the pool, the new `extend`/`assign` clears any residual lock so the new entry starts clean. If you evict a key and never re-add it, the lock is an orphan — callers who care must `DEL <prefix>|<suffix>:<key>` themselves.
+- **Pool keys are validated at the API boundary.** `extend()` / `assign()` raise `ValueError` for keys that are empty, equal to the literal `"#ALLOCATED"`, contain the `"||"` separator, contain NUL bytes, or are not strings. These shapes break the on-disk encoding and would silently corrupt the linked list.
+
 ## Documentation
 
 For complete documentation, please visit our [official documentation site](https://invoker-bot.github.io/RedisAllocator-python/).
@@ -487,6 +496,44 @@ The RedisAllocator maintains resources in a doubly-linked list structure stored
   - Cleans up inconsistent states between allocations and locks
 - Soft bindings are implemented as separate locks with their own timeout period
 
+### Concurrency Safety
+
+Each EVAL is atomic on Redis (single-threaded server, Lua never preempted), so no operation can be observed half-completed. Multi-process coordination is then provided by lock TTL plus the GC pass — a process killed mid-sequence leaves at most an orphaned lock, which expires on its TTL or is reclaimed by GC.
+
+The pool linked-list invariants survive arbitrary interleaving of `malloc` / `free` / `extend` / `assign` / `gc` from concurrent processes (validated by both fakeredis multi-thread tests and a Docker-backed stress driver — see Testing below). If you observe persistent invariant violations under load, please file an issue with the operation sequence.
+
+## Testing
+
+The default unit suite is fast (~7s) and self-contained — `pytest` runs it without any external services:
+
+```bash
+pip install -e ".[dev]"
+pytest                            # ~180 tests, fakeredis only, ~7s
+flake8 redis_allocator tests --max-line-length=150
+tox                               # py310 / py311 / flake8, matches CI
+```
+
+Several test categories are **opt-in via pytest markers** (excluded from the default run by `pyproject.toml`):
+
+```bash
+pytest -m concurrency             # multi-thread fakeredis race tests (~25s)
+pytest -m fuzz                    # randomised single-thread sequences
+pytest -m benchmark               # constant-time complexity assertions for malloc/free/extend
+pytest -m "concurrency or fuzz or benchmark"   # all of the above
+```
+
+For the strongest validation against real-world conditions there is a Docker-backed stress driver under `tests/stress_pool_corruption.py`. It is a standalone script (not collected by pytest), spawning multiple worker processes that randomly malloc / free / extend / shrink / assign / gc against a real Redis container while a "murderer" process randomly SIGKILLs workers to simulate crashes. An atomic-snapshot watcher checks pool invariants throughout. Typical run:
+
+```bash
+docker run --rm -d --name allocator-stress -p 6399:6379 redis:7-alpine
+python tests/stress_pool_corruption.py        # 60s default; STRESS_DURATION/STRESS_WORKERS env vars
+docker rm -f allocator-stress
+```
+
+Performance contracts are validated on both backends. Real Redis 7 confirms hard `O(1)` for `malloc + free` and `extend` per-key cost across pool sizes from 10 to 5000 keys. The fakeredis `pytest -m benchmark` enforces the same threshold; it relies on a temporary monkey-patch in `tests/conftest.py` because of [fakeredis upstream PR #473](https://github.com/cunla/fakeredis-py/pull/473) (merged to master, not yet released). The patch is idempotent and self-removable once fakeredis ships a release containing the fix — see the cleanup checklist embedded in `tests/conftest.py`.
+
+A standalone Python script `tests/_perf_real_redis.py` reproduces the benchmark against a real Redis container for cross-checking.
+
 ## Roadmap
 
 *   **Core Focus & Recently Completed:**
@@ -497,6 +544,9 @@ The RedisAllocator maintains resources in a doubly-linked list structure stored
     *   [x] Basic Garbage Collection & Health Checking Foundation
     *   [x] Documentation Improvements (Shared Mode, Soft Binding, Lua Clarity)
     *   [x] Foundational Unit Tests & Allocation Mode Coverage
+    *   [x] **Pool hardened against multi-process race corruption** (input validation, head-pointer maintenance across locked/expired skip, zombie-key prevention, residual-lock cleanup on re-add, soft-binding ordering, GC self-healing) — see [BUGHUNT_REPORT.md](BUGHUNT_REPORT.md).
+    *   [x] **Comprehensive test infrastructure**: bug-hunt regression suite, atomic-snapshot invariant checker, concurrency / fuzz / benchmark / stress markers, Docker-backed stress driver, real-Redis cross-checks.
+    *   [x] **`O(1)` performance contract** for `malloc` / `free` / `extend` validated on both real Redis and patched fakeredis.
 
 *   **Current Development Priorities (Focusing on Proxy Pool Needs):**
     *   [ ] **Resource Prioritization:** Implement priority-based allocation in `RedisAllocator`, likely using Redis Sorted Sets (`ZSET`) for the free pool. *(New - High Priority)*

{redis_allocator-0.5.2 → redis_allocator-0.6.1}/README.md

@@ -36,6 +36,15 @@ RedisAllocator is built around these key ideas:
 - **Shared Mode**: Configurable allocation modes supporting both exclusive and shared resource usage
 - **Soft Binding**: Associates named objects with specific resources for consistent allocation
 
+## Behavior Contracts (Important for API Users)
+
+A few intentional behaviors that may surprise newcomers — knowing them up-front avoids debugging dead-ends:
+
+- **`malloc_key(timeout<=0)` creates a permanent (non-expiring) lock.** Useful for resources whose ownership must outlive process restarts; the caller takes responsibility for releasing via `free_keys`. GC never reclaims it (because expiry is also `-1`). Misuse causes resource leaks — only pass `timeout=0` when you mean "I will manage this lock myself."
+- **`cache_timeout=0` (or negative) creates a permanent soft binding.** Sticks until explicitly overwritten by another `update_soft_bind` for the same name, or removed via `unbind_soft_bind`. Symmetric to the lock-timeout contract above.
+- **`assign()` does not delete the lock keys of items it evicts.** A deliberate write-amplification trade-off: locks expire on their own TTL, and if the same key is later re-`extend`-ed into the pool, the new `extend`/`assign` clears any residual lock so the new entry starts clean. If you evict a key and never re-add it, the lock is an orphan — callers who care must `DEL <prefix>|<suffix>:<key>` themselves.
+- **Pool keys are validated at the API boundary.** `extend()` / `assign()` raise `ValueError` for keys that are empty, equal to the literal `"#ALLOCATED"`, contain the `"||"` separator, contain NUL bytes, or are not strings. These shapes break the on-disk encoding and would silently corrupt the linked list.
+
 ## Documentation
 
 For complete documentation, please visit our [official documentation site](https://invoker-bot.github.io/RedisAllocator-python/).
@@ -432,6 +441,44 @@ The RedisAllocator maintains resources in a doubly-linked list structure stored
   - Cleans up inconsistent states between allocations and locks
 - Soft bindings are implemented as separate locks with their own timeout period
 
+### Concurrency Safety
+
+Each EVAL is atomic on Redis (single-threaded server, Lua never preempted), so no operation can be observed half-completed. Multi-process coordination is then provided by lock TTL plus the GC pass — a process killed mid-sequence leaves at most an orphaned lock, which expires on its TTL or is reclaimed by GC.
+
+The pool linked-list invariants survive arbitrary interleaving of `malloc` / `free` / `extend` / `assign` / `gc` from concurrent processes (validated by both fakeredis multi-thread tests and a Docker-backed stress driver — see Testing below). If you observe persistent invariant violations under load, please file an issue with the operation sequence.
+
+## Testing
+
+The default unit suite is fast (~7s) and self-contained — `pytest` runs it without any external services:
+
+```bash
+pip install -e ".[dev]"
+pytest                            # ~180 tests, fakeredis only, ~7s
+flake8 redis_allocator tests --max-line-length=150
+tox                               # py310 / py311 / flake8, matches CI
+```
+
+Several test categories are **opt-in via pytest markers** (excluded from the default run by `pyproject.toml`):
+
+```bash
+pytest -m concurrency             # multi-thread fakeredis race tests (~25s)
+pytest -m fuzz                    # randomised single-thread sequences
+pytest -m benchmark               # constant-time complexity assertions for malloc/free/extend
+pytest -m "concurrency or fuzz or benchmark"   # all of the above
+```
+
+For the strongest validation against real-world conditions there is a Docker-backed stress driver under `tests/stress_pool_corruption.py`. It is a standalone script (not collected by pytest), spawning multiple worker processes that randomly malloc / free / extend / shrink / assign / gc against a real Redis container while a "murderer" process randomly SIGKILLs workers to simulate crashes. An atomic-snapshot watcher checks pool invariants throughout. Typical run:
+
+```bash
+docker run --rm -d --name allocator-stress -p 6399:6379 redis:7-alpine
+python tests/stress_pool_corruption.py        # 60s default; STRESS_DURATION/STRESS_WORKERS env vars
+docker rm -f allocator-stress
+```
+
+Performance contracts are validated on both backends. Real Redis 7 confirms hard `O(1)` for `malloc + free` and `extend` per-key cost across pool sizes from 10 to 5000 keys. The fakeredis `pytest -m benchmark` enforces the same threshold; it relies on a temporary monkey-patch in `tests/conftest.py` because of [fakeredis upstream PR #473](https://github.com/cunla/fakeredis-py/pull/473) (merged to master, not yet released). The patch is idempotent and self-removable once fakeredis ships a release containing the fix — see the cleanup checklist embedded in `tests/conftest.py`.
+
+A standalone Python script `tests/_perf_real_redis.py` reproduces the benchmark against a real Redis container for cross-checking.
+
 ## Roadmap
 
 *   **Core Focus & Recently Completed:**
@@ -442,6 +489,9 @@ The RedisAllocator maintains resources in a doubly-linked list structure stored
     *   [x] Basic Garbage Collection & Health Checking Foundation
     *   [x] Documentation Improvements (Shared Mode, Soft Binding, Lua Clarity)
     *   [x] Foundational Unit Tests & Allocation Mode Coverage
+    *   [x] **Pool hardened against multi-process race corruption** (input validation, head-pointer maintenance across locked/expired skip, zombie-key prevention, residual-lock cleanup on re-add, soft-binding ordering, GC self-healing) — see [BUGHUNT_REPORT.md](BUGHUNT_REPORT.md).
+    *   [x] **Comprehensive test infrastructure**: bug-hunt regression suite, atomic-snapshot invariant checker, concurrency / fuzz / benchmark / stress markers, Docker-backed stress driver, real-Redis cross-checks.
+    *   [x] **`O(1)` performance contract** for `malloc` / `free` / `extend` validated on both real Redis and patched fakeredis.
 
 *   **Current Development Priorities (Focusing on Proxy Pool Needs):**
     *   [ ] **Resource Prioritization:** Implement priority-based allocation in `RedisAllocator`, likely using Redis Sorted Sets (`ZSET`) for the free pool. *(New - High Priority)*

redis_allocator-0.6.1/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ['setuptools>=42']
+build-backend = 'setuptools.build_meta'
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = "0.6.1"
+tag_format = "v$version"
+
+[tool.commitizen.version_files]
+"redis_allocator/_version.py" = { search = "__version__ = '", replace = "__version__ = '" }
+
+[tool.pytest.ini_options]
+# Opt-in markers for tests that are slow, flaky, or need external services.
+# Default `pytest` invocation excludes them; CI runs only the fast unit suite.
+# Run them explicitly with:
+#     pytest -m concurrency           # multi-thread fakeredis race tests
+#     pytest -m fuzz                  # randomised single-thread sequences
+#     pytest -m "concurrency or fuzz"
+markers = [
+    "concurrency: tests that drive the allocator from multiple threads (fakeredis)",
+    "fuzz: random-sequence exploratory tests (may exercise lupa edge cases)",
+    "stress: long-running stress tests requiring external Redis (Docker)",
+    "benchmark: performance assertions (constant-time complexity, etc.)",
+]
+addopts = "-m 'not concurrency and not fuzz and not stress and not benchmark'"

redis_allocator-0.6.1/redis_allocator/_version.py

@@ -0,0 +1 @@
+__version__ = '0.6.1'

{redis_allocator-0.5.2 → redis_allocator-0.6.1}/redis_allocator/allocator.py

@@ -17,23 +17,32 @@ Key features:
 4. Support for an updater to refresh the pool's keys periodically
 5. Policy-based control of allocation behavior through RedisAllocatorPolicy
 """
+import random
 import atexit
 import logging
 import weakref
 import contextlib
 from abc import ABC, abstractmethod
-from typing import Any, Callable
+from typing import Any, Callable, Optional, TypeVar, Generic, Sequence, Iterable
 from functools import cached_property
 from threading import current_thread
 from concurrent.futures import ThreadPoolExecutor
-from typing import (Optional, TypeVar, Generic,
-                    Sequence, Iterable)
 from redis import StrictRedis as Redis
 from cachetools import cached, TTLCache
 from .lock import RedisLockPool, Timeout
 
 logger = logging.getLogger(__name__)
 
+#: Sentinel written into the prev/next fields of a pool hash entry to mark
+#: the key as currently allocated. Pool keys equal to this string are
+#: rejected by ``RedisAllocator._validate_keys`` to avoid collision.
+ALLOCATED_SENTINEL = "#ALLOCATED"
+
+#: Separator between prev / next / expiry inside a pool hash value
+#: ("prev||next||expiry"). Pool keys containing this substring are rejected
+#: at the API boundary to avoid the encoding being mis-parsed.
+POOL_VALUE_SEP = "||"
+
 
 class RedisThreadHealthCheckPool(RedisLockPool):
     """A class that provides a simple interface for managing the health status of a thread.
@@ -412,8 +421,7 @@ class DefaultRedisAllocatorPolicy(RedisAllocatorPolicy[U]):
 
     def refresh_pool_all(self, allocator: 'RedisAllocator[U]'):
         allocator.clear()
-        for _ in range(len(self.updater.params)):
-            self.refresh_pool(allocator)
+        self.refresh_pool(allocator, n=len(self.updater.params))
 
     def malloc(self, allocator: 'RedisAllocator[U]', timeout: Timeout = 120,
                obj: Optional[U] = None, params: Optional[dict] = None,
@@ -469,7 +477,7 @@ class DefaultRedisAllocatorPolicy(RedisAllocatorPolicy[U]):
             # If we got here, we acquired the lock, so we can update the pool
             self.refresh_pool(allocator)
 
-    def refresh_pool(self, allocator: 'RedisAllocator[U]'):
+    def refresh_pool(self, allocator: 'RedisAllocator[U]', shuffle=True, n=1):
         """Refresh the allocation pool using the updater.
 
         Args:
@@ -478,12 +486,17 @@ class DefaultRedisAllocatorPolicy(RedisAllocatorPolicy[U]):
         if self.updater is None:
             return
 
-        keys = self.updater()
+        keys = []
+        for _ in range(n):
+            keys.extend(self.updater())
 
         if len(keys) == 0:
             logger.warning("No keys to update to the pool")
             return
 
+        if shuffle:
+            random.shuffle(keys)
+
         # Update the pool based on the number of keys
         if len(self.updater) == 1:
             allocator.assign(keys, timeout=self.expiry_duration)
@@ -617,14 +630,14 @@ class RedisAllocator(RedisLockPool, Generic[U]):
                 return "", "", -1
             end
             value = tostring(value)
-            local prev, next, expiry = string.match(value, "(.*)||(.*)||(.*)")
+            local prev, next, expiry = string.match(value, "(.*){POOL_VALUE_SEP}(.*){POOL_VALUE_SEP}(.*)")
             return prev, next, tonumber(expiry)
         end
         local function join_pool_value(prev, next, expiry)
             if expiry == nil then
                 expiry = -1
             end
-            return tostring(prev) .. "||" .. tostring(next) .. "||" .. tostring(expiry)
+            return tostring(prev) .. "{POOL_VALUE_SEP}" .. tostring(next) .. "{POOL_VALUE_SEP}" .. tostring(expiry)
         end
         local function timeout_to_expiry(timeout)
             if timeout == nil or timeout <= 0 then
@@ -669,8 +682,8 @@ class RedisAllocator(RedisLockPool, Generic[U]):
             local itemVal = redis.call("HGET", poolItemsKey, itemName)
             if itemVal then
                 local prev, next, expiry = split_pool_value(itemVal)
-                assert(prev == "#ALLOCATED" or prev == "", "item should be allocated or free")
-                assert(next == "" or next == "#ALLOCATED", "item should be the last item in the free list")
+                assert(prev == "{ALLOCATED_SENTINEL}" or prev == "", "item should be allocated or free")
+                assert(next == "" or next == "{ALLOCATED_SENTINEL}", "item should be the last item in the free list")
             end
             -- set the item points to the tail
             redis.call("HSET", poolItemsKey, itemName, join_pool_value(tail, "", expiry))
@@ -718,16 +731,32 @@ class RedisAllocator(RedisLockPool, Generic[U]):
             local headVal = redis.call("HGET", poolItemsKey, head)
             assert(headVal, "head value should not be nil")
             local headPrev, headNext, headExpiry = split_pool_value(headVal)
+            -- Promote headNext to head and stitch its prev to "" so a later
+            -- set_item_allocated cannot dereference the removed prev.
+            local function _advance_head_after_removal()
+                if headNext == "" then
+                    redis.call("SET", headKey, "")
+                    redis.call("SET", tailKey, "")
+                    return
+                end
+                local nextVal = redis.call("HGET", poolItemsKey, headNext)
+                if not nextVal then
+                    redis.call("SET", headKey, "")
+                    redis.call("SET", tailKey, "")
+                    return
+                end
+                local _, nNext, nExpiry = split_pool_value(nextVal)
+                redis.call("HSET", poolItemsKey, headNext, join_pool_value("", nNext, nExpiry))
+                redis.call("SET", headKey, headNext)
+            end
             -- Check if the head item has expired or is locked
             if is_expiry_invalid(headExpiry) then  -- the item has expired
                 redis.call("HDEL", poolItemsKey, head)
-                set_current_head(headNext)
-                -- set_item_head_nil(headNext)
+                _advance_head_after_removal()
                 return pop_from_head()
             elseif redis.call("EXISTS", key_str(head)) > 0 then  -- the item is locked
-                redis.call("HSET", poolItemsKey, head, join_pool_value("#ALLOCATED", "#ALLOCATED", headExpiry))
-                set_current_head(headNext)
-                -- set_item_head_nil(headNext)
+                redis.call("HSET", poolItemsKey, head, join_pool_value("{ALLOCATED_SENTINEL}", "{ALLOCATED_SENTINEL}", headExpiry))
+                _advance_head_after_removal()
                 return pop_from_head()
             elseif headNext == "" then  -- the item is the last in the free list
                 redis.call("SET", headKey, "")
@@ -739,7 +768,7 @@ class RedisAllocator(RedisLockPool, Generic[U]):
                 redis.call("HSET", poolItemsKey, headNext, join_pool_value("", nextNext, nextExpiry))
                 redis.call("SET", headKey, headNext)
             end
-            redis.call("HSET", poolItemsKey, head, join_pool_value("#ALLOCATED", "#ALLOCATED", headExpiry))
+            redis.call("HSET", poolItemsKey, head, join_pool_value("{ALLOCATED_SENTINEL}", "{ALLOCATED_SENTINEL}", headExpiry))
             return head, headExpiry
         end
 
@@ -749,8 +778,8 @@ class RedisAllocator(RedisLockPool, Generic[U]):
             end
             assert(val, "val should not be nil")
             local prev, next, expiry = split_pool_value(val)
-            if prev ~= "#ALLOCATED" then
-                assert(next ~= "#ALLOCATED", "next item should not be allocated")
+            if prev ~= "{ALLOCATED_SENTINEL}" then
+                assert(next ~= "{ALLOCATED_SENTINEL}", "next item should not be allocated")
                 if is_expiry_invalid(expiry) then
                     redis.call("HDEL", poolItemsKey, itemName)
                 end
@@ -770,14 +799,14 @@ class RedisAllocator(RedisLockPool, Generic[U]):
                 else
                     redis.call("SET", tailKey, prev)
                 end
-                redis.call("HSET", poolItemsKey, itemName, join_pool_value("#ALLOCATED", "#ALLOCATED", expiry))
+                redis.call("HSET", poolItemsKey, itemName, join_pool_value("{ALLOCATED_SENTINEL}", "{ALLOCATED_SENTINEL}", expiry))
                 -- If we removed the current head, update head pointer
                 -- local savedHead = redis.call("GET", headKey)
                 -- if savedHead == itemName then
                 --     redis.call("SET", headKey, next or "")
                 -- end
             else
-                assert(next == "#ALLOCATED", "next item should also be allocated")
+                assert(next == "{ALLOCATED_SENTINEL}", "next item should also be allocated")
             end
         end
 
@@ -791,14 +820,16 @@ class RedisAllocator(RedisLockPool, Generic[U]):
                 return
             end
             local locked = redis.call("EXISTS", key_str(itemName)) > 0
-            if prev == "#ALLOCATED" then
+            if prev == "{ALLOCATED_SENTINEL}" then
                 if not locked then
                     push_to_tail(itemName, expiry)
                 end
             else
-                -- if locked then
-                --     set_item_allocated(itemName, value)
-                -- end
+                -- Free entry with a residual lock: pull it out of the free
+                -- list so callers can't malloc a key that's still locked.
+                if locked then
+                    set_item_allocated(itemName, value)
+                end
             end
         end
 
@@ -825,7 +856,7 @@ class RedisAllocator(RedisLockPool, Generic[U]):
                     break  -- corrupted pointer
                 end
                 local _prev, nxt, _expiry = split_pool_value(val)
-                if nxt == "" or nxt == "#ALLOCATED" then
+                if nxt == "" or nxt == "{ALLOCATED_SENTINEL}" then
                     break -- reached tail or allocated marker
                 end
                 current = nxt
@@ -866,19 +897,71 @@ class RedisAllocator(RedisLockPool, Generic[U]):
                 local prev, next, _ = split_pool_value(val)
                 val = join_pool_value(prev, next, expiry)
                 redis.call("HSET", poolItemsKey, itemName, val)
-            else -- refresh the expiry timeout
+            else
+                -- New key: wipe any residual lock so the entry starts clean.
+                redis.call("DEL", key_str(itemName))
                 push_to_tail(itemName, expiry)
             end
         end''')
 
+    def _validate_keys(self, keys: Sequence[str]) -> None:
+        """Reject pool keys that would corrupt the on-disk encoding.
+
+        Pool keys are stored as values inside Redis hash entries of the form
+        ``"<prev>||<next>||<expiry>"``. Three key shapes break this encoding
+        or collide with internal sentinels and must be rejected at the
+        Python API boundary, before they reach the Lua scripts:
+
+        - **Empty string keys** collide with the sentinel used for "no head"
+          / "no tail" of an empty list (see ``pop_from_head`` / ``push_to_tail``
+          in ``_lua_required_string``). An entry whose name is ``""`` becomes
+          indistinguishable from "the list is empty", causing INV-1 violations.
+        - **Keys containing the ``||`` separator** are mis-parsed by
+          ``split_pool_value``'s greedy ``(.*)||(.*)||(.*)`` regex and cause
+          silent linked-list corruption (later operations crash on
+          ``next value should not be nil``).
+        - **Keys equal to the literal ``"#ALLOCATED"``** collide with the
+          allocated-state marker stored in the prev/next fields of the pool
+          hash value, breaking INV-3 (no half-allocated state).
+
+        Args:
+            keys: Sequence of user-supplied keys to validate.
+
+        Raises:
+            ValueError: If any key in ``keys`` violates one of the rules above.
+        """
+        for key in keys:
+            if not isinstance(key, str):
+                raise ValueError(
+                    f"pool key must be str, got {type(key).__name__}: {key!r:.80}"
+                )
+            if key == "":
+                raise ValueError("pool key cannot be empty (collides with empty-pointer sentinel)")
+            if POOL_VALUE_SEP in key:
+                raise ValueError(
+                    f"pool key cannot contain {POOL_VALUE_SEP!r} separator: {key!r:.80}"
+                )
+            if key == ALLOCATED_SENTINEL:
+                raise ValueError(f"pool key cannot equal {ALLOCATED_SENTINEL!r} (reserved as internal sentinel)")
+            if "\x00" in key:
+                raise ValueError(
+                    f"pool key cannot contain NUL byte: {key!r:.80}"
+                )
+
     def extend(self, keys: Optional[Sequence[str]] = None, timeout: int = -1):
         """Add new resources to the allocation pool.
 
         Args:
-            keys: Sequence of resource identifiers to add to the pool
+            keys: Sequence of resource identifiers to add to the pool. Each
+                key is validated by :meth:`_validate_keys` before being
+                inserted; invalid keys cause the entire batch to be rejected.
             timeout: Optional timeout in seconds for the pool items (-1 means no timeout)
+
+        Raises:
+            ValueError: If any key fails :meth:`_validate_keys`.
         """
         if keys is not None and len(keys) > 0:
+            self._validate_keys(keys)
             # Ensure timeout is integer for Lua script
             int_timeout = timeout if timeout is not None else -1
             self._extend_script(args=[int_timeout] + list(keys))
@@ -887,16 +970,21 @@ class RedisAllocator(RedisLockPool, Generic[U]):
     def _shrink_script(self):
         """Cached Lua script to remove keys from the pool.
 
-        Iterates through provided keys (ARGV[1...]).
-        For each key:
+        Iterates through provided keys (ARGV[1...]). Items not present in the
+        pool are silently skipped (no-op), so callers can safely ``shrink`` a
+        superset of currently-known keys.
+
+        For each key that does exist:
         1. Calls set_item_allocated() to remove it from the free list structure.
         2. Deletes the key entirely from the pool hash using HDEL.
         """
         return self.redis.register_script(f'''{self._lua_required_string}
         for i=1, #ARGV do
             local itemName = ARGV[i]
-            set_item_allocated(itemName)
-            redis.call("HDEL", poolItemsKey, itemName)
+            if redis.call("HEXISTS", poolItemsKey, itemName) > 0 then
+                set_item_allocated(itemName)
+                redis.call("HDEL", poolItemsKey, itemName)
+            end
         end''')
 
     def shrink(self, keys: Optional[Sequence[str]] = None):
@@ -942,6 +1030,10 @@ class RedisAllocator(RedisLockPool, Generic[U]):
         end
         for k, v in pairs(assignSet) do
             if v then
+                -- Same rationale as in _extend_script: wipe any residual
+                -- lock for this name before adding it as a fresh free node,
+                -- otherwise we may surface INV-4 (free + locked).
+                redis.call("DEL", key_str(k))
                 push_to_tail(k, expiry)
             end
         end
@@ -952,10 +1044,17 @@ class RedisAllocator(RedisLockPool, Generic[U]):
 
         Args:
             keys: Sequence of resource identifiers to assign to the pool,
-                 replacing any existing resources
+                 replacing any existing resources. Each key is validated by
+                 :meth:`_validate_keys` before being inserted; invalid keys
+                 cause the entire call to be rejected (the existing pool is
+                 left untouched).
             timeout: Optional timeout in seconds for the pool items (-1 means no timeout)
+
+        Raises:
+            ValueError: If any key fails :meth:`_validate_keys`.
         """
         if keys is not None and len(keys) > 0:
+            self._validate_keys(keys)
             self._assign_script(args=[timeout] + list(keys))
         else:
             self.clear()
@@ -1081,8 +1180,11 @@ class RedisAllocator(RedisLockPool, Generic[U]):
                     -- Cached key is valid (either not locked or in shared mode)
                     refresh_cache(cachedKey) -- Refresh the cache expiry
                     if shared == 0 then
-                        redis.call("SET", key_str(cachedKey), "1", "EX", timeout)
+                        -- Order matters: chain mutation must succeed before
+                        -- the lock SET, otherwise an aborted EVAL leaves a
+                        -- free entry with a lock.
                         set_item_allocated(cachedKey)
+                        redis.call("SET", key_str(cachedKey), "1", "EX", timeout)
                     end
                     return cachedKey
                 end
@@ -1177,12 +1279,14 @@ class RedisAllocator(RedisLockPool, Generic[U]):
     def _free_script(self):
         """Cached Lua script to free allocated keys.
 
-        Iterates through provided keys (ARGV[2...]).
-        For each key:
-        1. Deletes the corresponding lock key (`key_str(k)`) using DEL.
-           If the key existed (DEL returns 1), it proceeds.
-        2. Adds the key back to the tail of the free list using `push_to_tail()`
-           with the specified expiry (calculated from ARGV[1] timeout).
+        Iterates through ARGV[2...]. For each key:
+
+        1. ``DEL`` its lock key.
+        2. If the lock did exist AND the key is still a pool member
+           (``HEXISTS`` guard), push it back to the free list tail.
+
+        The ``HEXISTS`` guard ensures ``free_keys`` cannot re-insert a key
+        that ``assign``/``shrink`` has evicted from the pool.
         """
         return self.redis.register_script(f'''
         {self._lua_required_string}
@@ -1191,7 +1295,7 @@ class RedisAllocator(RedisLockPool, Generic[U]):
         for i=2, #ARGV do
             local k = ARGV[i]
             local deleted = redis.call('DEL', key_str(k))
-            if deleted > 0 then -- Only push back to pool if it was actually locked/deleted
+            if deleted > 0 and redis.call('HEXISTS', poolItemsKey, k) > 0 then
                 push_to_tail(k, expiry)
             end
         end