redis-allocator 0.6.0__tar.gz → 0.7.0__tar.gz

{redis_allocator-0.6.0/redis_allocator.egg-info → redis_allocator-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redis-allocator
-Version: 0.6.0
+Version: 0.7.0
 Summary: Redis-based resource allocation system.
 Home-page: https://github.com/invoker-bot/RedisAllocator-python
 Author: Invoker Bot
@@ -21,11 +21,11 @@ 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
-Requires-Dist: sphinx>=7.0.0; extra == "docs"
+Requires-Dist: sphinx<9.0.0,>=7.0.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
 Requires-Dist: sphinx-git>=11.0.0; extra == "docs"
 Requires-Dist: sphinxcontrib-mermaid>=0.7.1; extra == "docs"
@@ -33,10 +33,10 @@ 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"
+Requires-Dist: sphinx<9.0.0,>=7.0.0; extra == "dev"
 Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "dev"
 Requires-Dist: sphinx-git>=11.0.0; extra == "dev"
 Requires-Dist: sphinxcontrib-mermaid>=0.7.1; extra == "dev"
@@ -91,6 +91,17 @@ 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.
+- **`malloc()` and `malloc_key()` return `None` when no resource is available.** Check the return value before using it; an empty pool is not represented as a wrapper with `key=None`.
+- **Prefer `with allocator.malloc(...) as allocation:` or `allocation.release()` for object allocations.** `release()` closes the wrapped object and returns the key to the pool. Plain `close()` only closes the wrapped object and leaves allocation ownership unchanged for callers that manage `free()` manually.
+- **`assign()` / `shrink()` / `clear()` are not namespace scrubbers.** `assign()` and `shrink()` remove pool membership but intentionally leave lock keys for removed members; `clear()` deletes the pool hash/head/tail only. This avoids write amplification and wildcard scans, but an evicted permanent lock becomes a permanent orphan. To recover a known orphan, call `free_keys(key)`, reintroduce that same key with `extend([key])` or `assign([... key ...])`, or delete `<prefix>|<suffix>:<key>` directly. Reintroducing unrelated keys, `clear()`, and `gc()` do not remove orphan locks outside the pool.
+- **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/).
@@ -218,15 +229,13 @@ if key:
 # Allocate a resource with object (returns a RedisAllocatorObject)
 allocated_obj = allocator.malloc(timeout=120)
 if allocated_obj:
-    try:
+    with allocated_obj:
         # The key is available as a property
         print(f"Allocated resource: {allocated_obj.key}")
         
         # Update the resource's lock timeout
         allocated_obj.update(timeout=60)
-    finally:
-        # Free the resource when done
-        allocator.free(allocated_obj)
+    # Leaving the with block calls allocated_obj.release().
 
 # Using soft binding (associates a name with a resource)
 allocator.update_soft_bind("worker-1", "resource-1")
@@ -452,7 +461,7 @@ result = task_queue.query(
     id="task-123",
     name="example-task",
     params={"input": "data"},
-    timeout=300,  # Optional timeout in seconds
+    timeout=300,  # End-to-end wait timeout in seconds for remote execution
     policy=TaskExecutePolicy.Auto,  # Execution policy
     once=False  # Whether to delete the result after getting it
 )
@@ -487,6 +496,106 @@ 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 after allocation can leave a lock behind. If the resource is still present in pool metadata, the lock either expires naturally or is reconciled by GC; if the resource is later evicted by `assign()` / `shrink()` / `clear()`, the lock becomes an orphan outside GC scope and expires only by TTL unless it is permanent.
+
+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.
+
+#### Atomic Operation Boundaries
+
+Allocator state transitions are written as single Redis Lua scripts. Redis runs each script atomically on the server event loop, so concurrent processes cannot observe a half-updated free-list node, lock key, or soft-binding update. This guarantee depends on using one Redis instance; Redis Cluster is out of scope because the allocator mutates multiple related keys in one script.
+
+| Operation | Atomic boundary | Notes |
+|---|---|---|
+| `malloc_key()` | One Lua EVAL | Checks soft binding, pops/rotates the free-list head, marks the item allocated, creates the lock key, and refreshes binding state together. |
+| `free_keys()` | One Lua EVAL | Deletes lock keys and returns still-present pool members to the free-list tail together. Unknown or evicted keys are no-ops. |
+| `extend()` / `shrink()` / `assign()` | One Lua EVAL per call | Batch updates are atomic as a batch. `assign()` and `shrink()` intentionally preserve lock keys for evicted members; `extend()` / `assign()` delete a residual lock only when that same key is newly added to the pool. |
+| `clear()` | One Lua EVAL | Deletes the pool hash plus head/tail pointers only; it does not scan or delete per-resource lock keys. |
+| `gc()` | One Lua EVAL per pass | Incrementally reconciles up to the requested scan count and saves the scan cursor. |
+| `malloc()` / `RedisAllocatorObject.release()` | Wrapper around atomic calls | `malloc()` wraps `malloc_key()` after the atomic allocation; `release()` wraps `free_keys()` after closing the local object. |
+
+Multi-process coordination is provided by those atomic scripts plus lock TTLs and GC. A process killed after allocation may leave a lock behind; pool-member locks either expire naturally or are reconciled by GC. Orphan locks whose key is no longer in the pool are outside GC scope. Permanent locks (`timeout <= 0`) are never reclaimed automatically and must be released explicitly with `free_keys(key)`, by reintroducing that same key with `extend([key])` or `assign([... key ...])`, or by deleting `<prefix>|<suffix>:<key>` directly.
+
+### Operation Complexity
+
+The hot path is designed to avoid scanning the whole pool. Use `malloc_key()` / `free_keys()` for high-frequency allocation, use `extend()` for incremental pool refreshes, and reserve `assign()` for lower-frequency wholesale replacement.
+
+| Operation | Time complexity | Space / Redis writes | Recommended use |
+|---|---:|---|---|
+| `malloc_key()` | Amortized `O(1)`; worst-case `O(k)` when skipping `k` expired or locked head entries | Constant extra metadata writes | Hot path allocation. |
+| `free_keys(n)` | `O(n)` | Constant writes per released key | Hot path release; single-key free is `O(1)`. |
+| `extend(n)` | `O(n)`, independent of existing pool size | Constant writes per supplied key | Incremental pool additions or expiry refresh. |
+| `shrink(n)` | `O(n)` | Constant writes per supplied key | Remove known resources. |
+| `assign(n)` | `O(current_pool_size + n)` | Rewrites membership for removed/new keys | Low-frequency full replacement. |
+| `gc(count)` | Approximately `O(count)` per pass | Bounded by scanned entries | Periodic incremental repair/reclaim. |
+
+`k` in `malloc_key()` is the number of stale head entries cleaned during that allocation. Those entries are removed or marked allocated as they are skipped, so the cost is paid once and amortizes over later calls.
+
+## 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               # operation-complexity assertions for allocator commands
+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. The fakeredis `pytest -m benchmark` suite enforces scaling ratios across pool sizes from 10 to 5000 keys for `malloc_key() + free_keys()`, batched `free_keys(n)`, `extend(n)`, `shrink(n)`, and `gc(count)`. It covers `assign(n)` across 10 to 1000 keys because fakeredis/lupa is unreliable with 5000+ Lua ARGV on Windows; the real Redis script covers `assign(n)` through 5000. The benchmark asserts operation cost follows the documented complexity table instead of silently regressing to full-pool scans. 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 same operation-complexity benchmark against a real Redis container for cross-checking and exits non-zero when a contract fails.
+
+## Live Diagnostics
+
+`redis-allocator` includes an observer-only diagnostics API and local dashboard for inspecting live allocator state under multi-process load.
+
+Python API:
+
+```python
+from redis import Redis
+from redis_allocator import RedisAllocatorDiagnostics
+
+redis = Redis.from_url("redis://localhost:6379/0", decode_responses=True)
+diagnostics = RedisAllocatorDiagnostics(redis, prefix="myapp", suffix="allocator")
+snapshot = diagnostics.snapshot()
+print(snapshot.to_json(indent=2))
+```
+
+One-shot JSON:
+
+```bash
+redis-allocator-diagnose --redis-url redis://localhost:6379/0 --prefix myapp --suffix allocator --json
+```
+
+Live dashboard:
+
+```bash
+redis-allocator-diagnose --redis-url redis://localhost:6379/0 --prefix myapp --suffix allocator --interval 1 --port 8765
+```
+
+The diagnostics collector reads pool structure and per-pool-key lock state atomically with one Lua script. Advisory metrics such as Redis memory, commandstats, slowlog, soft bindings, and orphan locks are sampled separately. V1 never mutates allocator state and does not repair corruption. Orphan-lock samples are reporting only: clean a known orphan with `free_keys(key)`, by reintroducing the same key through `extend()` / `assign()`, or with a precise Redis `DEL`; `clear()` and `gc()` do not repair orphan locks outside the pool.
+
+Use `sample_limit` to bound returned examples and `scan_limit` to cap advisory keyspace scans during dashboard refreshes. When a scan is capped, the JSON marks that section as `truncated`.
+
 ## Roadmap
 
 *   **Core Focus & Recently Completed:**
@@ -497,6 +606,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.0 → redis_allocator-0.7.0}/README.md

@@ -36,6 +36,17 @@ 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.
+- **`malloc()` and `malloc_key()` return `None` when no resource is available.** Check the return value before using it; an empty pool is not represented as a wrapper with `key=None`.
+- **Prefer `with allocator.malloc(...) as allocation:` or `allocation.release()` for object allocations.** `release()` closes the wrapped object and returns the key to the pool. Plain `close()` only closes the wrapped object and leaves allocation ownership unchanged for callers that manage `free()` manually.
+- **`assign()` / `shrink()` / `clear()` are not namespace scrubbers.** `assign()` and `shrink()` remove pool membership but intentionally leave lock keys for removed members; `clear()` deletes the pool hash/head/tail only. This avoids write amplification and wildcard scans, but an evicted permanent lock becomes a permanent orphan. To recover a known orphan, call `free_keys(key)`, reintroduce that same key with `extend([key])` or `assign([... key ...])`, or delete `<prefix>|<suffix>:<key>` directly. Reintroducing unrelated keys, `clear()`, and `gc()` do not remove orphan locks outside the pool.
+- **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/).
@@ -163,15 +174,13 @@ if key:
 # Allocate a resource with object (returns a RedisAllocatorObject)
 allocated_obj = allocator.malloc(timeout=120)
 if allocated_obj:
-    try:
+    with allocated_obj:
         # The key is available as a property
         print(f"Allocated resource: {allocated_obj.key}")
         
         # Update the resource's lock timeout
         allocated_obj.update(timeout=60)
-    finally:
-        # Free the resource when done
-        allocator.free(allocated_obj)
+    # Leaving the with block calls allocated_obj.release().
 
 # Using soft binding (associates a name with a resource)
 allocator.update_soft_bind("worker-1", "resource-1")
@@ -397,7 +406,7 @@ result = task_queue.query(
     id="task-123",
     name="example-task",
     params={"input": "data"},
-    timeout=300,  # Optional timeout in seconds
+    timeout=300,  # End-to-end wait timeout in seconds for remote execution
     policy=TaskExecutePolicy.Auto,  # Execution policy
     once=False  # Whether to delete the result after getting it
 )
@@ -432,6 +441,106 @@ 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 after allocation can leave a lock behind. If the resource is still present in pool metadata, the lock either expires naturally or is reconciled by GC; if the resource is later evicted by `assign()` / `shrink()` / `clear()`, the lock becomes an orphan outside GC scope and expires only by TTL unless it is permanent.
+
+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.
+
+#### Atomic Operation Boundaries
+
+Allocator state transitions are written as single Redis Lua scripts. Redis runs each script atomically on the server event loop, so concurrent processes cannot observe a half-updated free-list node, lock key, or soft-binding update. This guarantee depends on using one Redis instance; Redis Cluster is out of scope because the allocator mutates multiple related keys in one script.
+
+| Operation | Atomic boundary | Notes |
+|---|---|---|
+| `malloc_key()` | One Lua EVAL | Checks soft binding, pops/rotates the free-list head, marks the item allocated, creates the lock key, and refreshes binding state together. |
+| `free_keys()` | One Lua EVAL | Deletes lock keys and returns still-present pool members to the free-list tail together. Unknown or evicted keys are no-ops. |
+| `extend()` / `shrink()` / `assign()` | One Lua EVAL per call | Batch updates are atomic as a batch. `assign()` and `shrink()` intentionally preserve lock keys for evicted members; `extend()` / `assign()` delete a residual lock only when that same key is newly added to the pool. |
+| `clear()` | One Lua EVAL | Deletes the pool hash plus head/tail pointers only; it does not scan or delete per-resource lock keys. |
+| `gc()` | One Lua EVAL per pass | Incrementally reconciles up to the requested scan count and saves the scan cursor. |
+| `malloc()` / `RedisAllocatorObject.release()` | Wrapper around atomic calls | `malloc()` wraps `malloc_key()` after the atomic allocation; `release()` wraps `free_keys()` after closing the local object. |
+
+Multi-process coordination is provided by those atomic scripts plus lock TTLs and GC. A process killed after allocation may leave a lock behind; pool-member locks either expire naturally or are reconciled by GC. Orphan locks whose key is no longer in the pool are outside GC scope. Permanent locks (`timeout <= 0`) are never reclaimed automatically and must be released explicitly with `free_keys(key)`, by reintroducing that same key with `extend([key])` or `assign([... key ...])`, or by deleting `<prefix>|<suffix>:<key>` directly.
+
+### Operation Complexity
+
+The hot path is designed to avoid scanning the whole pool. Use `malloc_key()` / `free_keys()` for high-frequency allocation, use `extend()` for incremental pool refreshes, and reserve `assign()` for lower-frequency wholesale replacement.
+
+| Operation | Time complexity | Space / Redis writes | Recommended use |
+|---|---:|---|---|
+| `malloc_key()` | Amortized `O(1)`; worst-case `O(k)` when skipping `k` expired or locked head entries | Constant extra metadata writes | Hot path allocation. |
+| `free_keys(n)` | `O(n)` | Constant writes per released key | Hot path release; single-key free is `O(1)`. |
+| `extend(n)` | `O(n)`, independent of existing pool size | Constant writes per supplied key | Incremental pool additions or expiry refresh. |
+| `shrink(n)` | `O(n)` | Constant writes per supplied key | Remove known resources. |
+| `assign(n)` | `O(current_pool_size + n)` | Rewrites membership for removed/new keys | Low-frequency full replacement. |
+| `gc(count)` | Approximately `O(count)` per pass | Bounded by scanned entries | Periodic incremental repair/reclaim. |
+
+`k` in `malloc_key()` is the number of stale head entries cleaned during that allocation. Those entries are removed or marked allocated as they are skipped, so the cost is paid once and amortizes over later calls.
+
+## 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               # operation-complexity assertions for allocator commands
+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. The fakeredis `pytest -m benchmark` suite enforces scaling ratios across pool sizes from 10 to 5000 keys for `malloc_key() + free_keys()`, batched `free_keys(n)`, `extend(n)`, `shrink(n)`, and `gc(count)`. It covers `assign(n)` across 10 to 1000 keys because fakeredis/lupa is unreliable with 5000+ Lua ARGV on Windows; the real Redis script covers `assign(n)` through 5000. The benchmark asserts operation cost follows the documented complexity table instead of silently regressing to full-pool scans. 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 same operation-complexity benchmark against a real Redis container for cross-checking and exits non-zero when a contract fails.
+
+## Live Diagnostics
+
+`redis-allocator` includes an observer-only diagnostics API and local dashboard for inspecting live allocator state under multi-process load.
+
+Python API:
+
+```python
+from redis import Redis
+from redis_allocator import RedisAllocatorDiagnostics
+
+redis = Redis.from_url("redis://localhost:6379/0", decode_responses=True)
+diagnostics = RedisAllocatorDiagnostics(redis, prefix="myapp", suffix="allocator")
+snapshot = diagnostics.snapshot()
+print(snapshot.to_json(indent=2))
+```
+
+One-shot JSON:
+
+```bash
+redis-allocator-diagnose --redis-url redis://localhost:6379/0 --prefix myapp --suffix allocator --json
+```
+
+Live dashboard:
+
+```bash
+redis-allocator-diagnose --redis-url redis://localhost:6379/0 --prefix myapp --suffix allocator --interval 1 --port 8765
+```
+
+The diagnostics collector reads pool structure and per-pool-key lock state atomically with one Lua script. Advisory metrics such as Redis memory, commandstats, slowlog, soft bindings, and orphan locks are sampled separately. V1 never mutates allocator state and does not repair corruption. Orphan-lock samples are reporting only: clean a known orphan with `free_keys(key)`, by reintroducing the same key through `extend()` / `assign()`, or with a precise Redis `DEL`; `clear()` and `gc()` do not repair orphan locks outside the pool.
+
+Use `sample_limit` to bound returned examples and `scan_limit` to cap advisory keyspace scans during dashboard refreshes. When a scan is capped, the JSON marks that section as `truncated`.
+
 ## Roadmap
 
 *   **Core Focus & Recently Completed:**
@@ -442,6 +551,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.7.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ['setuptools>=42']
+build-backend = 'setuptools.build_meta'
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = "0.7.0"
+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 benchmark             # allocator operation-complexity contracts
+#     pytest -m "concurrency or fuzz or benchmark"
+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.0 → redis_allocator-0.7.0}/redis_allocator/__init__.py

@@ -9,6 +9,7 @@ from redis_allocator.lock import (RedisLock, RedisLockPool, LockStatus,
                                   BaseLock, BaseLockPool, ThreadLock, ThreadLockPool)
 from redis_allocator.task_queue import TaskExecutePolicy, RedisTask, RedisTaskQueue
 from redis_allocator.allocator import RedisAllocator, RedisAllocatorObject, RedisAllocatorUpdater, RedisAllocatorPolicy, DefaultRedisAllocatorPolicy
+from redis_allocator.diagnostics import RedisAllocatorDiagnostics
 
 
 __version__ = '0.0.1'
@@ -29,4 +30,5 @@ __all__ = [
     'RedisAllocatorUpdater',
     'RedisAllocatorPolicy',
     'DefaultRedisAllocatorPolicy',
+    'RedisAllocatorDiagnostics',
 ]

redis_allocator-0.7.0/redis_allocator/_version.py

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