V3

CHANGELOG.md

@@ -7,7 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-## [Unreleased]
+## [3.0.0] — 2026-07-09
+
+### Added
+
+- **Atomic cache spaces for Redis Cluster:** declare `$normCacheSpaces`, select one with `->space()`, and run cache operations in one hash slot.
+- **Space-targeted flushing:** use `NormCache::flushAll('space')` or `php artisan normcache:flush --space=...`.
+- **Cache-space coverage:** relations, pivot data, and table dependencies participate in cache-space invalidation.
+
+### Changed
+
+- **BREAKING:** model-declared cache spaces replace the `cluster` and `slotting` configuration. Run `php artisan normcache:flush` before deploying.
+- `dependsOnTables()` supports named cache spaces.
+
+### Fixed
+
+- Cache isolation across declared spaces and database connections, including `Model::on()` queries and writes.
+- Repeated `dependsOn()` calls no longer discard previously declared model dependencies.
+- Stale cache entries are not written when a cache rebuild races an invalidating write.
+- Table-dependency invalidation remains visible across application workers.
+- Eloquent observers see invalidated cache state while a model is being saved.
 
 ---
 

composer.json

@@ -47,6 +47,7 @@
     },
     "scripts": {
         "test": "vendor/bin/phpunit",
+        "test:cluster": "REDIS_CLUSTER=true REDIS_PORT=7010 vendor/bin/phpunit",
         "lint": "vendor/bin/pint --test",
         "format": "vendor/bin/pint",
         "analyse": "vendor/bin/phpstan analyse --memory-limit=512M"

config/normcache.php

@@ -4,7 +4,7 @@
     // Redis connection from config/database.php.
     'connection' => env('NORMCACHE_CONNECTION', 'cache'),
 
-    // Master switch; false bypasses the cache.
+    // Boot-time master switch; false bypasses the cache.
     'enabled' => env('NORMCACHE_ENABLED', true),
 
     // Model attribute payload TTL (seconds).
@@ -16,10 +16,6 @@
     // Prefix every NormCache key. Useful when sharing a Redis database.
     'key_prefix' => env('NORMCACHE_PREFIX', ''),
 
-    // false keeps all keys in {nc}, preserving cross-model Lua atomicity on Cluster.
-    // true slots by model/table, spreading load but limiting atomic operations to each slot.
-    'slotting' => (bool) env('NORMCACHE_SLOTTING', false),
-
     // Debounce automatic version bumps on write-heavy models; 0 bumps immediately (seconds).
     'cooldown' => (int) env('NORMCACHE_COOLDOWN', 0),
 
@@ -32,9 +28,6 @@
     // Wake tokens pushed when a cache build releases. Raise for high same-key concurrency.
     'stampede_wake_tokens' => (int) env('NORMCACHE_STAMPEDE_WAKE_TOKENS', 64),
 
-    // Use Redis Cluster-safe command paths when the configured Redis connection is clustered.
-    'cluster' => (bool) env('NORMCACHE_CLUSTER', false),
-
     // Dispatch cache hit, miss, and bypass events. Enable only if something consumes them.
     'events' => (bool) env('NORMCACHE_EVENTS', false),
 
@@ -46,4 +39,17 @@
 
     // Register the Laravel Debugbar collector for local cache inspection.
     'debugbar' => env('NORMCACHE_DEBUGBAR', false),
+    // Redis Cluster sharding via model-declared cache spaces.
+    'spaces' => [
+        // Max spaces per model. Writes bump one version key per space.
+        'max_per_model' => 16,
+
+        // Cross-space dependency handling: 'bypass' or 'throw'.
+        'cross_space_behavior' => env('NORMCACHE_CROSS_SPACE_BEHAVIOR', 'bypass'),
+
+        // Optional space => hash-tag override. Default: content => {nc:content}.
+        'placement' => [
+            // 'catalog' => ['hash_tag' => 'nc:catalog'],
+        ],
+    ],
 ];

docker-compose.yml

@@ -0,0 +1,20 @@
+# Local Redis for the test suite.
+#   redis          — single node on 6379 (default `composer test`)
+#   redis-cluster  — 6-node cluster (3 masters + 3 replicas) on 7010-7015,
+#                    matching REDIS_CLUSTER_NODES in phpunit.xml (`composer test:cluster`)
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    command: ["redis-server", "--save", "", "--appendonly", "no"]
+
+  redis-cluster:
+    image: grokzen/redis-cluster:7.0.10
+    environment:
+      IP: 0.0.0.0
+      INITIAL_PORT: 7010
+      MASTERS: 3
+      SLAVES_PER_MASTER: 1
+    ports:
+      - "7010-7015:7010-7015"

phpstan.neon

@@ -15,6 +15,9 @@ parameters:
         -
             identifier: argument.type
             path: src/Support/RedisStore.php
+        -
+            identifier: argument.type
+            path: src/Support/RedisScanner.php
         -
             identifier: trait.unused
             path: src/Traits/Cacheable.php

src/Cache/ExecutionEngine.php

@@ -11,42 +11,6 @@
 
 final class ExecutionEngine
 {
-    /**
-     * @param  callable(): ResultCacheResult  $fetch
-     * @param  callable(): (ResultCacheResult|null)  $waitForBuild
-     * @param  callable(ResultCacheResult): array{Collection, mixed}  $onMiss
-     * @param  callable(mixed, ResultCacheResult): void  $onStore
-     * @param  callable(ResultCacheResult): Collection  $onHit
-     * @param  callable(): Collection  $onBuild
-     */
-    public function runResult(
-        callable $fetch,
-        callable $waitForBuild,
-        callable $onMiss,
-        callable $onStore,
-        callable $onHit,
-        callable $onBuild,
-    ): Collection {
-        $result = $fetch();
-
-        if ($result->status === CacheStatus::Building) {
-            $result = $waitForBuild();
-
-            if ($result === null) {
-                return $onBuild();
-            }
-        }
-
-        if ($result->status === CacheStatus::Hit) {
-            return $onHit($result);
-        }
-
-        [$models, $payload] = $onMiss($result);
-        $onStore($payload, $result);
-
-        return $models;
-    }
-
     /**
      * @param  callable(): PivotCacheResult  $fetch
      * @param  callable(): (PivotCacheResult|null)  $waitForBuild
@@ -119,47 +83,15 @@ public function runScalar(
     }
 
     /**
-     * @param  callable(): QueryCacheResult  $fetch
-     * @param  callable(): (QueryCacheResult|null)  $waitForBuild
-     * @param  callable(): Collection  $onBuild
-     * @param  callable(QueryCacheResult): Collection  $onMiss
-     * @param  callable(QueryCacheResult): Collection  $onHit
-     */
-    public function runNormalized(
-        callable $fetch,
-        callable $waitForBuild,
-        callable $onBuild,
-        callable $onMiss,
-        callable $onHit,
-    ): Collection {
-        $result = $fetch();
-
-        if ($result->status === CacheStatus::Building) {
-            $result = $waitForBuild();
-
-            if ($result === null) {
-                return $onBuild();
-            }
-        }
-
-        if ($result->status === CacheStatus::Miss) {
-            return $onMiss($result);
-        }
-
-        return $onHit($result);
-    }
-
-    /**
-     * Same control flow as {@see self::runNormalized()}, kept as a separate method so call
-     * sites get ThroughCacheResult-typed callables instead of QueryCacheResult.
+     * @template TResult of QueryCacheResult|ThroughCacheResult
      *
-     * @param  callable(): ThroughCacheResult  $fetch
-     * @param  callable(): (ThroughCacheResult|null)  $waitForBuild
+     * @param  callable(): TResult  $fetch
+     * @param  callable(): (TResult|null)  $waitForBuild
      * @param  callable(): Collection  $onBuild
-     * @param  callable(ThroughCacheResult): Collection  $onMiss
-     * @param  callable(ThroughCacheResult): Collection  $onHit
+     * @param  callable(TResult): Collection  $onMiss
+     * @param  callable(TResult): Collection  $onHit
      */
-    public function runThrough(
+    public function runNormalized(
         callable $fetch,
         callable $waitForBuild,
         callable $onBuild,

src/Cache/ModelCacheRepository.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace NormCache\Cache;
+
+use NormCache\Support\CacheKeyBuilder;
+use NormCache\Support\RedisStore;
+use NormCache\Values\BuildHandle;
+use NormCache\Values\CacheConfig;
+use NormCache\Values\CacheSpace;
+
+final class ModelCacheRepository
+{
+    public function __construct(
+        private readonly RedisStore $store,
+        private readonly CacheKeyBuilder $keys,
+        private readonly VersionTracker $versions,
+        private readonly CacheConfig $config,
+    ) {}
+
+    public function store(
+        string $modelClass,
+        array $modelAttrs,
+        ?CacheSpace $space = null,
+        ?string $connection = null,
+    ): void {
+        $space ??= $this->keys->activeSpace();
+        $modelVersion = $this->versions->currentVersion($modelClass, $space, $connection);
+
+        $this->storeForVersion($modelClass, $modelAttrs, $modelVersion, $space, $connection);
+    }
+
+    public function storeForBuild(
+        string $modelClass,
+        array $modelAttrs,
+        BuildHandle $build,
+        ?CacheSpace $space = null,
+        ?string $connection = null,
+    ): void {
+        $classKey = $this->keys->classKey($modelClass, $connection);
+        $index = array_search($this->keys->verKey($classKey, $space), $build->versionKeys, true);
+
+        if ($index === false || !isset($build->expectedVersions[$index])) {
+            return;
+        }
+
+        $this->storeForVersion($modelClass, $modelAttrs, (int) $build->expectedVersions[$index], $space, $connection);
+    }
+
+    public function storeForVersion(
+        string $modelClass,
+        array $modelAttrs,
+        int $expectedVersion,
+        ?CacheSpace $space = null,
+        ?string $connection = null,
+    ): void {
+        if (empty($modelAttrs)) {
+            return;
+        }
+
+        $classKey = $this->keys->classKey($modelClass, $connection);
+        $attrsByKey = [];
+
+        foreach ($modelAttrs as $id => $attrs) {
+            $attrsByKey[$this->keys->modelPrefix($classKey, $expectedVersion, $space) . $id] = $attrs;
+        }
+
+        $this->store->setManyIfVersion(
+            $attrsByKey,
+            $this->config->ttl,
+            $this->keys->verKey($classKey, $space),
+            $expectedVersion,
+        );
+    }
+}