From 9e98b7fb0116df89c6e5f72b761ba8309a57a6f5 Mon Sep 17 00:00:00 2001 From: Imani Manyara Date: Tue, 10 Nov 2026 05:00:43 -0500 Subject: [PATCH 1/2] feat: cache raw per-scope bags in front of database layers (phase 3) Add CachingDriver and SettingsCache: each scope's rows are cached under a hashed key of connection, database, tenant, store, table and scope, and invalidated by replacing ULID generation tokens (scope, store, epoch) after every write commits, so a Cache::flexible() refresh can never restore an invalidated value. Misses are cached as empty bags; reads inside a transaction or while bootstrap skips the layer go to the database; a failing cache falls back and is logged. Add laranail::settings.warm and .clear-cache, clearCache()/warmCache() on a handle (manage_stores, audited), the cache.* config keys, a phpbench read benchmark (composer bench), and docs. Mutation testing now runs weekly and on dispatch only, not on pull requests. --- .gitattributes | 2 + .github/workflows/static-analysis.yml | 29 +- CHANGELOG.md | 25 ++ CONTRIBUTING.md | 3 +- README.md | 4 +- benchmarks/BenchOwner.php | 31 ++ benchmarks/ReadBench.php | 140 +++++++ composer.json | 5 +- config/settings.php | 20 + docs/architecture.md | 40 +- docs/configuration.md | 7 +- docs/recipes/warming-the-cache.md | 58 +++ docs/tools/caching.md | 113 ++++++ docs/tools/commands.md | 15 +- docs/tools/settings-api.md | 2 + phpbench.json | 13 + src/Actions/ClearCache.php | 60 +++ src/Actions/FlushScope.php | 7 +- src/Actions/PromoteStore.php | 3 + src/Actions/StoreActions.php | 8 +- src/Actions/WarmCache.php | 46 +++ src/Caching/SettingsCache.php | 352 +++++++++++++++++ src/Console/ClearCacheCommand.php | 48 +++ src/Console/WarmCacheCommand.php | 66 ++++ src/Contracts/Settings.php | 19 + src/Data/CacheTarget.php | 27 ++ src/Drivers/CachingDriver.php | 118 ++++++ src/Providers/SettingsServiceProvider.php | 67 +++- src/SettingsManager.php | 22 ++ src/Stores/Store.php | 51 +++ src/Stores/StoreRegistry.php | 22 +- src/Support/BagCodec.php | 123 ++++++ src/Testing/SettingsFake.php | 10 + tests/Feature/Database/CachingTest.php | 452 ++++++++++++++++++++++ tests/Feature/Database/HandlesTest.php | 8 +- tests/Feature/FakeTest.php | 10 + tests/Feature/SettingsCacheTest.php | 303 +++++++++++++++ tests/Unit/BagCodecTest.php | 66 ++++ tests/Unit/DocsConformanceTest.php | 4 +- 39 files changed, 2364 insertions(+), 35 deletions(-) create mode 100644 benchmarks/BenchOwner.php create mode 100644 benchmarks/ReadBench.php create mode 100644 docs/recipes/warming-the-cache.md create mode 100644 docs/tools/caching.md create mode 100644 phpbench.json create mode 100644 src/Actions/ClearCache.php create mode 100644 src/Actions/WarmCache.php create mode 100644 src/Caching/SettingsCache.php create mode 100644 src/Console/ClearCacheCommand.php create mode 100644 src/Console/WarmCacheCommand.php create mode 100644 src/Data/CacheTarget.php create mode 100644 src/Drivers/CachingDriver.php create mode 100644 src/Support/BagCodec.php create mode 100644 tests/Feature/Database/CachingTest.php create mode 100644 tests/Feature/SettingsCacheTest.php create mode 100644 tests/Unit/BagCodecTest.php diff --git a/.gitattributes b/.gitattributes index 0b0023f..916f761 100644 --- a/.gitattributes +++ b/.gitattributes @@ -4,6 +4,7 @@ # Keep the Composer dist lean: exclude dev-only paths from package archives. # Source, config, database (migration, factories, seeders), README, LICENSE, CHANGELOG and composer.json ship. /.github export-ignore +/benchmarks export-ignore /docs export-ignore /tests export-ignore /.editorconfig export-ignore @@ -13,6 +14,7 @@ /.gitleaks.toml export-ignore /CONTRIBUTING.md export-ignore /SECURITY.md export-ignore +/phpbench.json export-ignore /phpstan.neon export-ignore /phpunit.xml export-ignore /rector.php export-ignore diff --git a/.github/workflows/static-analysis.yml b/.github/workflows/static-analysis.yml index d4def25..e208e49 100644 --- a/.github/workflows/static-analysis.yml +++ b/.github/workflows/static-analysis.yml @@ -4,8 +4,12 @@ on: pull_request: branches: [main] workflow_dispatch: - # The whole-package mutation run (every src file) is weekly; pull requests mutate only - # the files they change, so they finish in minutes. + inputs: + paths: + description: Comma-separated src/ files to mutate (empty = everything) + required: false + default: '' + # The whole-package mutation run (every src file) is weekly; pull requests skip it. schedule: - cron: '23 6 * * 1' @@ -67,10 +71,12 @@ jobs: mutation: name: Mutation testing (Pest) + # Weekly and on dispatch only (owner decision, 2026-11-10): pull requests skip it to keep CI + # spend down. The scheduled run mutates the whole package and fails below 70 %. A dispatch + # with `paths` set mutates only those files. + if: github.event_name != 'pull_request' runs-on: ubuntu-latest - # A pull request mutates only the src/ files it changes; the weekly and dispatched runs - # mutate everything with a longer limit. - timeout-minutes: ${{ github.event_name == 'pull_request' && 15 || 60 }} + timeout-minutes: 60 steps: - name: Checkout @@ -103,16 +109,10 @@ jobs: - name: Choose what to mutate id: scope env: - BASE_SHA: ${{ github.event.pull_request.base.sha }} + INPUT_PATHS: ${{ github.event.inputs.paths }} run: | - if [ "${{ github.event_name }}" = "pull_request" ]; then - files=$(git diff --name-only --diff-filter=AMR "$BASE_SHA"...HEAD -- 'src/*.php' | paste -sd, -) - echo "paths=$files" >> "$GITHUB_OUTPUT" - echo "Mutating: ${files:-nothing (no src/ changes)}" - else - echo "paths=" >> "$GITHUB_OUTPUT" - echo "Mutating: everything" - fi + echo "paths=${INPUT_PATHS}" >> "$GITHUB_OUTPUT" + echo "Mutating: ${INPUT_PATHS:-everything}" - name: Mutation testing (minimum score 70) # Pest's own mutator, not Infection: Infection has no Pest adapter, reads Pest's @@ -123,7 +123,6 @@ jobs: # group `mutation-excluded`, which is what is excluded: under --parallel Pest honours # only the first --exclude-group, and a comma-separated list excludes nothing, so # `--exclude-group=matrix,shared-app` ran every test and raced on the shared config file. - if: github.event_name != 'pull_request' || steps.scope.outputs.paths != '' env: MUTATE_PATHS: ${{ steps.scope.outputs.paths }} run: | diff --git a/CHANGELOG.md b/CHANGELOG.md index dd47ffc..bfed228 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- The settings cache (design phase 3, §7.5): `Drivers\CachingDriver` puts each database layer + behind `Caching\SettingsCache`, which caches every scope's raw rows (a "bag", every locale, + misses as empty bags) keyed by a hashed, length-prefixed tuple of connection, database, tenant, + store, table and scope. Invalidation replaces ULID generation tokens (per scope, per store, and + a global epoch) on every write path: set, forget, lock, unlock, flush, owner deletion and + promotion, after the write's transaction commits. Past `cache.ttl` a bag is still answered for + `cache.stale` seconds through `Cache::flexible()` while it is refreshed; a refresh can never + restore an invalidated value. Reads inside an open transaction and while bootstrap mode skips + the layer go straight to the database. A failing cache store falls back to the database and is + logged. New keys `cache.enabled` (default `true`), `cache.store`, `cache.prefix`, `cache.ttl` + and `cache.stale`. +- `laranail::settings.warm` and `laranail::settings.clear-cache` (`--store=*`), and + `clearCache()` / `warmCache()` on a settings handle, through the new `Actions\WarmCache` and + `Actions\ClearCache`: gated by `manage_stores` when an actor is present and audited as a + `manage_stores` entry (`meta.operation` `cache.warm` / `cache.clear`). +- `Store::isCached()`, `forgetCached()`, `forgetCachedStore()` and `warmCache()`; + `Data\CacheTarget`; `Support\BagCodec`. +- A phpbench benchmark of one request's reads with and without the cache (`benchmarks/`, + `phpbench.json`, `composer bench`). + - Tenancy (`tenancy.mode`: `none`, `column`, `database`; recorded in the schema file). Column mode adds a `tenant` column to the values, categories and audit tables, leading their unique keys; every row is stamped with the current tenant and every query, the audit trail and the @@ -72,6 +92,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 `Store::requireDatabase()`, `CategoryRepository::of()`. Behaviour, messages and audit entries are unchanged. - `FindOrphans` finds orphaned owners' settings; `PruneOrphans` removes them. +- With caching on (the default), a store's database layer is a `CachingDriver` in front of the + `DatabaseDriver`; `->database()` still returns the `DatabaseDriver`. Rows changed past the API + (raw queries, `Models\Setting` saves) are not seen until `clear-cache` runs or the bag expires. +- `Contracts\Settings` gains `clearCache()` and `warmCache()`; `Actions\StoreActions` gains the + optional `warmCache` and `clearCache` actions. ### Deprecated diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4bdcc64..a41d643 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,9 +17,10 @@ Contributions are welcome via pull requests. |---|---| | `composer test` | the Pest suite (Arch, Unit, Feature) | | `composer test-coverage` | the suite with line coverage, failing below 90 % | -| `composer mutate` | Pest mutation testing of the whole package, failing below a 70 % score (slow; CI runs it weekly). For your change only: `vendor/bin/pest --mutate --path=src/Changed.php,src/Other.php --min=70`, which is what pull requests run | +| `composer mutate` | Pest mutation testing of the whole package, failing below a 70 % score (slow; CI runs it weekly, not on pull requests). For your change only: `vendor/bin/pest --mutate --path=src/Changed.php,src/Other.php --exclude-group=mutation-excluded --min=70` | | `composer lint` | Pint (shared laranail config), PHPStan at level max, Rector dry run; never changes files | | `composer composer-audit` | known-vulnerable dependencies | +| `composer bench` | the phpbench read benchmark (`benchmarks/`): one request's reads uncached, cold and warm. Run it before and after a change to the read path or the cache, and quote both | ## Guidelines diff --git a/README.md b/README.md index 3afe5c3..082cd91 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,7 @@ The hosted docs live at id); + } + + /** @return list */ + public function settingsParents(): array + { + return [new OwnerRef('team', (string) $this->team)]; + } +} diff --git a/benchmarks/ReadBench.php b/benchmarks/ReadBench.php new file mode 100644 index 0000000..5dfc858 --- /dev/null +++ b/benchmarks/ReadBench.php @@ -0,0 +1,140 @@ +boot(['enabled' => false]); + } + + public function setUpCached(): void + { + $this->boot(['enabled' => true, 'store' => 'array']); + } + + public function setUpCachedFile(): void + { + $this->boot(['enabled' => true, 'store' => 'file']); + } + + #[BeforeMethods('setUpUncached')] + public function benchUncached(): void + { + $this->request(); + } + + #[BeforeMethods('setUpCached')] + public function benchCold(): void + { + $this->app->forgetScopedInstances(); + $this->app->make(SettingsCache::class)->forgetAll(); + $this->request(); + } + + #[BeforeMethods('setUpCached')] + public function benchWarm(): void + { + $this->request(); + } + + #[BeforeMethods('setUpCachedFile')] + public function benchWarmFileStore(): void + { + $this->request(); + } + + /** One request: fresh scoped services, then every key read through the cascade. */ + private function request(): void + { + $this->app->forgetScopedInstances(); + $settings = $this->app->make(Settings::class)->for($this->owner); + + foreach (self::KEYS as $key) { + $settings->get($key); + } + } + + /** @param array $cache `laranail.settings.cache` */ + private function boot(array $cache): void + { + $directory = sys_get_temp_dir() . '/laranail-settings-bench-' . bin2hex(random_bytes(4)); + mkdir($directory); + touch($directory . '/database.sqlite'); + + $this->app = Testbench::create(options: ['extra' => [ + 'providers' => [PackageToolsServiceProvider::class, DbToolsServiceProvider::class, SettingsServiceProvider::class], + 'dont-discover' => ['*'], + ]]); + + $config = $this->app->make('config'); + $config->set('app.key', 'base64:' . base64_encode(random_bytes(32))); + $config->set('database.default', 'bench'); + $config->set('database.connections.bench', ['driver' => 'sqlite', 'database' => $directory . '/database.sqlite', 'prefix' => '', 'foreign_key_constraints' => true]); + $config->set('cache.stores.file.path', $directory . '/cache'); + $config->set('laranail.settings.schema.path', $directory . '/settings-schema.php'); + $config->set('laranail.settings.layers.shipped.path', $directory . '/none.php'); + $config->set('laranail.settings.stores.settings.layers', ['database']); + $config->set('laranail.settings.stores.settings.owners', ['owner', 'team']); + $config->set('laranail.settings.stores.settings.inherits', true); + $config->set('laranail.settings.audit.sinks', ['null']); + $config->set('laranail.settings.cache', $cache + ['prefix' => 'bench', 'ttl' => 3600, 'stale' => 300]); + + Artisan::call('migrate', ['--path' => dirname(__DIR__) . '/database/migrations', '--realpath' => true]); + + $settings = $this->app->make(Settings::class); + $this->owner = new BenchOwner(1, 7); + + foreach (self::KEYS as $index => $key) { + match ($index % 3) { + 0 => $settings->set($key, 'global-' . $index), + 1 => $settings->for(new OwnerRef('team', '7'))->set($key, 'team-' . $index), + default => $settings->for(new OwnerRef('owner', '1'))->set($key, 'owner-' . $index), + }; + } + + // Fill the cache once, so the warm subjects start warm. + $this->request(); + } +} diff --git a/composer.json b/composer.json index 394573b..943dc6a 100644 --- a/composer.json +++ b/composer.json @@ -48,6 +48,7 @@ "pestphp/pest": "^4.0", "pestphp/pest-plugin-arch": "^4.0", "pestphp/pest-plugin-laravel": "^4.0", + "phpbench/phpbench": "^1.4", "phpstan/phpstan": "^2.0", "rector/rector": "^2.5.8", "roave/security-advisories": "dev-latest" @@ -67,7 +68,8 @@ }, "autoload-dev": { "psr-4": { - "Simtabi\\Laranail\\Settings\\Tests\\": "tests/" + "Simtabi\\Laranail\\Settings\\Tests\\": "tests/", + "Simtabi\\Laranail\\Settings\\Benchmarks\\": "benchmarks/" } }, "scripts": { @@ -76,6 +78,7 @@ "test-coverage": "@test --coverage --min=90", "test-dirty": "@test --dirty --compact", "mutate": "vendor/bin/pest --mutate --everything --exclude-group=matrix --min=70", + "bench": "vendor/bin/phpbench run --report=settings", "lint": [ "@pint", "@phpstan", diff --git a/config/settings.php b/config/settings.php index c435dde..00d39b6 100644 --- a/config/settings.php +++ b/config/settings.php @@ -188,6 +188,26 @@ 'retry_on_conflict' => true, ], + /* + | The settings cache (database layers only; file layers are read directly). + | It holds each scope's raw rows (a "bag"), keyed by connection, database, + | tenant, store and scope, and is invalidated on every write by replacing a + | generation token, so a write is visible on the next read everywhere. + | `store` is a cache store from config/cache.php (null: the default one; + | it must exist, and a node-local store such as `array` or `file` is only + | right for a single server). `ttl` is how long a bag is fresh; for `stale` + | seconds after that it is still answered while it is refreshed in the + | background (Cache::flexible()); 0 turns that off. `prefix` starts every + | key, so two applications can share a cache store. + */ + 'cache' => [ + 'enabled' => env('LARANAIL_SETTINGS_CACHE', true), + 'store' => env('LARANAIL_SETTINGS_CACHE_STORE'), + 'prefix' => 'laranail-settings', + 'ttl' => 3600, + 'stale' => 300, + ], + /* | Events after which the schema readiness memo is forgotten, besides | migrations, queued jobs and Octane requests: tenant switches. db-tools has diff --git a/docs/architecture.md b/docs/architecture.md index db3ecda..7b797e8 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -22,8 +22,8 @@ How `laranail/settings` is shaped, and why. |---|---|---| | Entry points | resolve inputs and delegate; no work of their own | `SettingsManager`, `CategoryManager`, `AuditQuery`, the console commands, the facade | | Actions (`Actions/`) | one intent each, `handle()` only, final and readonly | `SetSetting`, `PromoteStore`, `SyncDefinitions`, `FindOrphans` | -| Services | the database, the files, a body of rules | `Database\AuditRepository`, `Database\DefinitionsRepository`, `Database\SchemaInspector`, `Database\CategoryRepository`, the drivers, `Stores\SettingWriter`, `Resolution\Resolver`, `Authorization\AccessGuard`, `Tenancy\TenantDiscriminators` | -| Support (`Support/`) | stateless logic shared by several classes | `AuditedTransaction`, `Translations`, `Json`, `DatabaseValues`, `ConfigValues`, `ValueEncoder` | +| Services | the database, the files, a body of rules | `Database\AuditRepository`, `Database\DefinitionsRepository`, `Database\SchemaInspector`, `Database\CategoryRepository`, the drivers, `Stores\SettingWriter`, `Resolution\Resolver`, `Authorization\AccessGuard`, `Tenancy\TenantDiscriminators`, `Caching\SettingsCache` | +| Support (`Support/`) | stateless logic shared by several classes | `AuditedTransaction`, `Translations`, `Json`, `DatabaseValues`, `ConfigValues`, `ValueEncoder`, `BagCodec` | An action never builds a query or reads the schema itself; it asks a repository, so the table, the tenant filter and the row format live in one place. A change and its audit entry always go @@ -145,6 +145,42 @@ hook of its own, so the defaults name the tenancy packages' own events (stancl/t `ForgotCurrentTenantEvent`) as strings: no dependency is added, and an event that never fires costs nothing. Another tenancy package adds its event to the list. +## Why cache raw bags? + +The cache holds each scope's raw rows (a "bag"), never resolved values. A resolved value depends +on every scope the cascade walked (owner, team, tenant, global), so caching it would make a write +to `team:7` stale in every user's entry that inherited from it, with no cheap way to find them +(G-32). A bag depends on one scope only: the write invalidates exactly one entry and every +inheriting user resolves the new value on the next read, in memory, from bags that are still +valid. Resolution stays a pure function of the bags, so `explain()` and the cascade behave the +same cached or not. + +Invalidation replaces a random generation token instead of deleting the entry, so a +stale-while-revalidate refresh started before a write can only land under a generation no reader +uses any more (R-23), and an evicted token cannot revive an old entry the way a restarted counter +could (R-41). The key hashes connection, database, tenant, store, table and scope as a +length-prefixed tuple, so neither a shared cache store nor a `:` inside a scope can make two +tenants or databases meet (G-37, R-63). While a transaction is open on a layer's connection the +layer bypasses the cache, so nothing uncommitted is ever cached. + +Measured with `composer bench` (phpbench 1.7, PHP 8.5.7, SQLite file database, 200 revolutions x +5 iterations per subject; one revolution is one request reading ten settings through +owner → team → global): + +| Subject | Mode time per request | vs. uncached | +|---|---|---| +| uncached (`cache.enabled` off) | 3.81 ms, 10 queries | — | +| cold (every bag invalidated first) | 2.22 ms, 1 query | 1.7x faster | +| warm, `array` store | 2.08 ms, 0 queries | 1.8x faster | +| warm, `file` store | 2.48 ms, 0 queries | 1.5x faster | + +Measured 2026-11-10 on a developer Mac. About 2 ms of every request is rebuilding the scoped +services, which all four pay alike. Without the cache each `get()` loads its scopes again (ten +queries for ten reads); with it, one request costs one query cold and none warm, so the gain is +the queries saved. On a local SQLite file a query is cheap, so against a database across a network +each saved query is a round trip and the gain is larger. A shared cache store (Redis) costs two +round trips per store on the first read of a request and none after it. + ## Why headless? The package ships no views, Blade components, Livewire, Filament or assets. A settings engine is consumed by many interfaces (an admin panel, a CLI, an API client, another package), and any UI bundled here would be the wrong one for most of them and would drag view dependencies into every host. Its surfaces are the PHP API, events, Artisan commands and, later, an opt-in JSON API; an admin UI is a separate companion package. An architecture test fails on any view, Blade, Livewire or Filament reference in `src/` and on a `resources/views` directory. diff --git a/docs/configuration.md b/docs/configuration.md index bd45f39..89d9f04 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -59,12 +59,17 @@ Every key in `config/laranail/settings.php`, read at `config('laranail.settings. | `audit.keep_days` | `365` | how long `prune-audit` keeps audit rows | | `logging.channel` | `null` | the application's default channel, a channel name, or `false` for off | | `logging.level` | `info` (`LARANAIL_SETTINGS_LOG_LEVEL`) | the lowest level written | +| `cache.enabled` | `true` (`LARANAIL_SETTINGS_CACHE`) | cache each database layer's per-scope bags | +| `cache.store` | `null` (`LARANAIL_SETTINGS_CACHE_STORE`) | a store from `config/cache.php`; null is the default store; share it between servers | +| `cache.prefix` | `laranail-settings` | the start of every cache key | +| `cache.ttl` | `3600` | seconds a cached bag is fresh (at least 1) | +| `cache.stale` | `300` | seconds after `ttl` a stale bag is still answered while it is refreshed (`Cache::flexible()`); `0` for none | Store names, keys, locales and owner aliases are validated, and a misconfiguration (an unknown driver, sink, verifier, resolver, level or ability included) raises `InvalidConfiguration` naming the config path on first use. The `password_confirmation` verifier also reads Laravel's own `auth.password_timeout`. Migration-time switches (`tenancy.mode` among them) are read by `install` and `make-store` and recorded in the schema file; after that the package reads the file, and `doctor` reports configuration that differs from it. See [Schema switches](tools/schema-switches.md). -Access, audit and logging are described in [Access control](tools/access-control.md) and [Audit and logging](tools/audit-and-logging.md); per-request changes in [Runtime configuration](tools/runtime-configuration.md). +The cache is described in [Caching](tools/caching.md). Access, audit and logging are described in [Access control](tools/access-control.md) and [Audit and logging](tools/audit-and-logging.md); per-request changes in [Runtime configuration](tools/runtime-configuration.md). ## Publishing diff --git a/docs/recipes/warming-the-cache.md b/docs/recipes/warming-the-cache.md new file mode 100644 index 0000000..4770eef --- /dev/null +++ b/docs/recipes/warming-the-cache.md @@ -0,0 +1,58 @@ +# Warm the cache after a deploy + +Load the global settings into the cache before traffic arrives, and reset it after changing rows by hand. + +## After a deploy + +Run the warm command once the new release's migrations have run: + +```bash +php artisan migrate --force +php artisan laranail::settings.warm +``` + +It loads the global scope of every cached store (one query per store when it is not cached +already, none when it is) and prints how many records each store holds: + +```text ++----------+----------------+ +| Store | Records cached | ++----------+----------------+ +| settings | 42 | ++----------+----------------+ +``` + +`--store=settings` (repeatable) warms only the named stores. Owners' settings are cached on their +first read; to warm one ahead of time, call `Settings::for($owner)->warmCache()`. + +## After changing rows past the API + +A raw query, a data migration or an Eloquent save on `Models\Setting` does not invalidate the +cache. Reset it, then warm it again: + +```bash +php artisan laranail::settings.clear-cache +php artisan laranail::settings.warm +``` + +`--store=settings` resets only the named stores. Either way only cached copies are reset, for +every tenant; stored values and the application's other cache entries are untouched. + +## In a tenant loop + +The warm command warms the central (no tenant) scope. With column-mode tenancy, warm each tenant +from inside its context: + +```php +use Simtabi\Laranail\Settings\Facades\Settings; + +Tenant::all()->runForEach(static function (): void { + Settings::asSystem('deploy warm-up')->warmCache(); +}); +``` + +See [Caching](../tools/caching.md) for how bags are keyed and invalidated. + +--- + +[← Docs index](../../README.md#documentation) diff --git a/docs/tools/caching.md b/docs/tools/caching.md new file mode 100644 index 0000000..5a3d0b6 --- /dev/null +++ b/docs/tools/caching.md @@ -0,0 +1,113 @@ +# Caching + +One cache sits in front of every database layer and holds each scope's raw rows, invalidated on every write. + +## What is cached + +Database layers only: `Drivers\CachingDriver` wraps each store's database layer when +`cache.enabled` is on (the default). File layers (`json`, `php`, `config`) are read directly; they +are already local and cheap. + +The unit is a **bag**: every row one scope (`global`, `user:42`, `team:7`) has in one store's +table, every locale included. Bags are raw records, never resolved values, so a write to +`team:7` invalidates exactly one bag and every user who inherits from team 7 sees the change on +their next read. A scope with no rows is cached as an empty bag, so a miss is cached too. + +A read through the cascade (owner, parents, global) costs, per distinct store in the chain: + +| State | Database queries | Cache calls | +|---|---|---| +| cold (bags not cached) | one, covering every scope the read needs from that store | two (tokens, then bags) and one write | +| warm (bags cached) | none | two | +| again in the same request | none | none (bags and tokens are held in memory for the request) | + +## Keys + +A bag's key is `::`. The first hash covers connection +name, database name, tenant, store, table and scope as a length-prefixed tuple, so +`a` + `b:c` and `a:b` + `c` never meet, and neither do two tenants or two databases that both +have a `global` scope (G-37). The tenant comes from the configured `TenantDiscriminator` in every +tenancy mode, `none` included. + +## Invalidation + +A bag's generation is three tokens: its scope's, its store's and a global epoch. Each token is a +random ULID, and invalidating replaces one: + +| Trigger | Token replaced | +|---|---| +| `set()`, `forget()`, `lock()`, `unlock()` | the written scope's (current tenant) | +| `flush()` and an owner model being deleted | the flushed scope's | +| `promote()` | the store's (every tenant) | +| `->for($owner)->clearCache()` | that owner's scope | +| `clearCache()`, `clear-cache --store=` | the store's (every tenant) | +| `laranail::settings.clear-cache` | the epoch (everything) | + +Nothing is deleted from the cache store, and the application's own cache entries are never +touched; entries under a replaced token simply stop being read and expire. Replacing a token +rather than deleting the bag is what makes stale-while-revalidate safe: a refresh computed before +a write lands under the old generation, where no reader looks any more. A random token also +survives eviction: an evicted token is replaced by a new random one and the next read misses, +where a counter would restart at zero and could revive an old entry. + +Writes inside a transaction invalidate when it commits, and not at all when it rolls back. While a +transaction is open on a layer's connection, that layer reads the database directly and caches +nothing, so a write's own transaction sees its uncommitted rows and nothing uncommitted reaches +the cache. + +> A row changed past the API (a raw query, a migration, an Eloquent `Models\Setting` save) does not +> invalidate anything. Run `laranail::settings.clear-cache`, or `clearCache()` on a handle, after +> such a change. + +## Stale-while-revalidate + +A bag is fresh for `cache.ttl` seconds. For `cache.stale` seconds after that, a read is still +answered from it while Laravel's `Cache::flexible()` refreshes it after the response. Set +`cache.stale` to `0` to turn that off; the bag then expires at `ttl`. + +## The cache store + +`cache.store` names a store from `config/cache.php`; null is the application's default store. Use +a store every server shares (Redis, Memcached, the database store) on more than one server: with +`array` or `file`, a write on one server leaves the other servers' bags stale until they expire. +`cache.prefix` begins every key, so two applications can share one store. + +A failing cache store never fails a read: the bag is read from the database and the failure is +written to the operational log (`logging.channel`) as a warning. A failed invalidation is logged +the same way, and leaves bags stale until they expire or the cache is cleared. + +## Octane and queues + +The cache service is bound `scoped`, so the bags and tokens it holds in memory last one request +or one queued job. Another process's write is seen on the next request or job; within one long +request, values read earlier are not re-read. + +## From PHP + +```php +use Simtabi\Laranail\Settings\Facades\Settings; + +Settings::clearCache(); // the default store, every tenant +Settings::store('user_settings')->clearCache(); // another store +Settings::for($team)->clearCache(); // one owner's cached values +Settings::warmCache(); // load the global scope now; returns the record count +Settings::for($user)->warmCache(); +``` + +Both need `manage_stores` when the handle carries an actor (and, with the default +`verification.abilities`, step-up verification), and both are audited as a `manage_stores` entry +whose `meta.operation` is `cache.clear` or `cache.warm`. They do nothing when caching is off. + +## Configuration + +| Key | Default | Purpose | +|---|---|---| +| `cache.enabled` | `true` (`LARANAIL_SETTINGS_CACHE`) | cache database layers | +| `cache.store` | `null` (`LARANAIL_SETTINGS_CACHE_STORE`) | a store from `config/cache.php`; null is the default store | +| `cache.prefix` | `laranail-settings` | the start of every key | +| `cache.ttl` | `3600` | seconds a bag is fresh (at least 1) | +| `cache.stale` | `300` | seconds after `ttl` a stale bag is answered while it is refreshed; `0` for none | + +--- + +[← Docs index](../../README.md#documentation) diff --git a/docs/tools/commands.md b/docs/tools/commands.md index 2d635d2..717d02c 100644 --- a/docs/tools/commands.md +++ b/docs/tools/commands.md @@ -1,6 +1,6 @@ # Commands -Eight Artisan commands, all named `laranail::settings.`. +Ten Artisan commands, all named `laranail::settings.`. ## The commands @@ -13,6 +13,8 @@ Eight Artisan commands, all named `laranail::settings.`. | `laranail::settings.sync-definitions` | copies code and config definitions into the definitions table as system rows | | `laranail::settings.prune-orphans [--dry-run]` | removes the settings of owners that no longer exist | | `laranail::settings.prune-audit [--days=]` | removes audit rows older than `audit.keep_days` | +| `laranail::settings.warm [--store=*]` | loads each cached store's global scope into the cache | +| `laranail::settings.clear-cache [--store=*]` | resets the cached settings of every store, or the named ones, for every tenant | Each one delegates to an action (`Actions\PromoteStore`, `Actions\PruneOrphans`, …) that the PHP API uses too, so the console and the API cannot behave differently. @@ -57,6 +59,17 @@ Lists, per store and alias, the owner scopes whose model no longer exists (soft- count as existing) and removes their rows. An alias with no model in the morph map is reported and left alone. Schedule it if you delete owners in bulk. +## `warm` and `clear-cache` + +`warm` loads the global scope of every store that has a cached database layer (one query per +store on a miss, none on a hit) and prints the record count per store. `clear-cache` replaces +generation tokens: with no option every bag goes, with `--store=` only those stores'. Neither +touches stored values or the application's other cache entries, and both do nothing when +`cache.enabled` is off. Both run as the system actor and are audited as a `manage_stores` entry +(`meta.operation` `cache.warm` or `cache.clear`); their actions, `Actions\WarmCache` and +`Actions\ClearCache`, need `manage_stores` when called with an actor. See +[Caching](caching.md) and [Warm the cache after a deploy](../recipes/warming-the-cache.md). + ## Pruning and access Both prune commands run as the system actor and are audited (a `prune` entry recording what was diff --git a/docs/tools/settings-api.md b/docs/tools/settings-api.md index ad5be11..df0fe2c 100644 --- a/docs/tools/settings-api.md +++ b/docs/tools/settings-api.md @@ -57,6 +57,8 @@ A stored `null` is an answer: `has()` is true and `get()` returns `null`, not th | `preload($owners)` | loads many owners' settings in one read per store; see [Database](database.md) | | `categories()` | the store's categories; see [Categories](categories.md) | | `promote(?PromotionRequest)` | moves runtime-file values into the database; returns a `PromotionReport` | +| `clearCache()` | resets the cached values of the handle's owner, or of its whole store; see [Caching](caching.md) | +| `warmCache()` | loads the handle's scope (owner or global) into the cache now; returns the record count | Writes raise `UnknownSetting` (strict store, no definition), `OwnerNotAllowed`, `LockedSetting`, `InvalidSettingValue`, `EncryptionUnavailable` or `StoreNotWritable`. A handle with an actor can also raise `AccessDenied` or `VerificationRequired`, any handle `ActorRequired` (when an actor is required) and `ApprovalUnavailable`. Every exception extends `SettingsException`. diff --git a/phpbench.json b/phpbench.json new file mode 100644 index 0000000..87ee6fd --- /dev/null +++ b/phpbench.json @@ -0,0 +1,13 @@ +{ + "$schema": "./vendor/phpbench/phpbench/phpbench.schema.json", + "runner.bootstrap": "vendor/autoload.php", + "runner.path": "benchmarks", + "runner.file_pattern": "*Bench.php", + "runner.php_config": {"memory_limit": "512M", "xdebug.mode": "off"}, + "report.generators": { + "settings": { + "extends": "aggregate", + "cols": ["subject", "revs", "its", "mem_peak", "mode", "rstdev"] + } + } +} diff --git a/src/Actions/ClearCache.php b/src/Actions/ClearCache.php new file mode 100644 index 0000000..4e438c7 --- /dev/null +++ b/src/Actions/ClearCache.php @@ -0,0 +1,60 @@ +name ?? $this->defaultStore, owner: $owner); + $this->access->authorize($actor, Ability::ManageStores, $subject); + + if (! $this->cache instanceof SettingsCache) { + return false; + } + + if (! $store instanceof Store) { + $this->cache->forgetAll(); + $target = 'all'; + } elseif (! $owner instanceof OwnerRef) { + $store->forgetCachedStore(); + $target = 'store'; + } else { + $store->forgetCached($owner->scope()); + $target = 'scope'; + } + + $this->access->auditor()->record(AuditAction::ManageStores, AuditOutcome::Allowed, $subject, $actor, meta: ['operation' => 'cache.clear', 'target' => $target]); + + return true; + } +} diff --git a/src/Actions/FlushScope.php b/src/Actions/FlushScope.php index e4f6097..632a7dd 100644 --- a/src/Actions/FlushScope.php +++ b/src/Actions/FlushScope.php @@ -22,7 +22,8 @@ /** * Remove every value an owner holds in a store, from every writable layer: needs `forget`. Used * when an owner is deleted (G-7) and by `prune-orphans`. The removal and its audit entry share - * one transaction on the store's connection. Returns how many rows went. + * one transaction on the store's connection; the scope's cached bag is forgotten when it commits. + * Returns how many rows went. */ final readonly class FlushScope { @@ -52,6 +53,10 @@ public function handle(Store $store, OwnerRef $owner, ?Actor $actor = null): int : $this->forgetEach($store, $layer->driver, $scope); } + // The rows went straight to the database, past the cache: forget the scope's bag + // once this transaction commits. + $store->forgetCached($scope); + $this->access->auditor()->record(AuditAction::Forget, AuditOutcome::Allowed, $subject, $actor, meta: ['flushed' => $removed]); $this->events->dispatch(new ScopeFlushed($store->name->value, $scope->value, $removed)); diff --git a/src/Actions/PromoteStore.php b/src/Actions/PromoteStore.php index 5b37dd4..129b68c 100644 --- a/src/Actions/PromoteStore.php +++ b/src/Actions/PromoteStore.php @@ -104,6 +104,9 @@ private function promote(Store $store, PromotionRequest $request, ?Actor $actor, ]], ); + // Promoted rows were written past the cache: reset the store's bags. + $store->forgetCachedStore(); + $archive = $request->from === null ? $runtime->archive($store->name, CarbonImmutable::now()) : null; $this->events->dispatch(new StorePromoted($store->name->value, count($promoted), count($skipped), $archive)); diff --git a/src/Actions/StoreActions.php b/src/Actions/StoreActions.php index 35712e5..4d10115 100644 --- a/src/Actions/StoreActions.php +++ b/src/Actions/StoreActions.php @@ -7,8 +7,10 @@ use Simtabi\Laranail\Settings\Actions\Categories\CategoryActions; /** - * The store-level actions a settings handle delegates to: categories, promotion and flushing an - * owner's values. Held together so a handle is built from one collaborator. + * The store-level actions a settings handle delegates to: categories, promotion, flushing an + * owner's values and warming or clearing the cache. Held together so a handle is built from one + * collaborator. The cache actions are optional so a bundle built before Phase 3 still builds; a + * handle without them refuses the cache calls. */ final readonly class StoreActions { @@ -16,5 +18,7 @@ public function __construct( public CategoryActions $categories, public PromoteStore $promote, public FlushScope $flush, + public ?WarmCache $warmCache = null, + public ?ClearCache $clearCache = null, ) {} } diff --git a/src/Actions/WarmCache.php b/src/Actions/WarmCache.php new file mode 100644 index 0000000..7d68559 --- /dev/null +++ b/src/Actions/WarmCache.php @@ -0,0 +1,46 @@ +name, owner: $owner); + $this->access->authorize($actor, Ability::ManageStores, $subject); + + if (! $store->isCached()) { + return 0; + } + + $records = $store->warmCache([Scope::of($owner)]); + + $this->access->auditor()->record(AuditAction::ManageStores, AuditOutcome::Allowed, $subject, $actor, meta: ['operation' => 'cache.warm', 'records' => $records]); + + return $records; + } +} diff --git a/src/Caching/SettingsCache.php b/src/Caching/SettingsCache.php new file mode 100644 index 0000000..ecf0eec --- /dev/null +++ b/src/Caching/SettingsCache.php @@ -0,0 +1,352 @@ + token key => token, read or written in this request */ + private array $tokens = []; + + /** @var array bag key => records, read in this request */ + private array $bags = []; + + /** + * @param int $ttl seconds a bag is fresh + * @param int $stale seconds after that a stale bag is still answered while it is refreshed + * @param (Closure(): ?string)|null $tenant the current tenant, null outside any tenant + * @param (Closure(string, Throwable): void)|null $onFailure told (operation, exception) when the cache fails + */ + public function __construct( + private readonly Repository $cache, + private readonly string $prefix = 'laranail-settings', + private readonly int $ttl = 3600, + private readonly int $stale = 300, + private readonly ?Closure $tenant = null, + private readonly ?Closure $onFailure = null, + private readonly BagCodec $codec = new BagCodec, + ) { + if ($prefix === '' || $ttl < 1 || $stale < 0) { + throw new InvalidConfiguration('laranail.settings.cache: `prefix` must be a non-empty string, `ttl` at least 1 and `stale` at least 0 (seconds).'); + } + } + + /** + * These scopes' records: from this request's memory, then the cache, and the rest from + * `$load` in **one** call, whose bags are then cached (an empty one included). + * + * @param list $scopes + * @param Closure(list): RecordSet $load reads scopes from the store itself + */ + public function load(CacheTarget $target, array $scopes, Closure $load): RecordSet + { + $scopes = $this->unique($scopes); + + if ($scopes === []) { + return new RecordSet; + } + + try { + [$keys, $found] = $this->lookup($target, $scopes, $load); + } catch (Throwable $exception) { + $this->failed('read', $exception); + + return $load($scopes); + } + + $missing = array_values(array_filter($scopes, static fn (Scope $scope): bool => ! isset($found[$scope->value]))); + + if ($missing !== []) { + $loaded = $load($missing); + + foreach ($missing as $scope) { + $found[$scope->value] = $this->only($loaded, $scope); + } + + $this->put(array_map(static fn (Scope $scope): string => $keys[$scope->value], $missing), array_map(static fn (Scope $scope): RecordSet => $found[$scope->value], $missing)); + } + + return new RecordSet(array_merge(...array_values(array_map(static fn (RecordSet $records): array => $records->all(), $found)))); + } + + /** Invalidate one scope's bag in one store, for the current tenant. */ + public function forgetScope(CacheTarget $target, Scope $scope): void + { + $this->rotate('scope', $this->scopeTokenKey($target, $this->currentTenant(), $scope), $this->lifetime()); + } + + /** Invalidate every bag of one store, for every tenant. */ + public function forgetStore(CacheTarget $target): void + { + $this->rotate('store', $this->storeTokenKey($target), null); + } + + /** Invalidate every bag this cache holds, for every store and tenant. */ + public function forgetAll(): void + { + $this->rotate('all', $this->epochKey(), null); + } + + /** The key one scope's bag is cached under right now (tokens included). */ + public function bagKey(CacheTarget $target, Scope $scope): string + { + $tenant = $this->currentTenant(); + + return $this->keyOf($target, $tenant, $scope, $this->tokensFor($target, $tenant, [$scope])[$scope->value]); + } + + /** + * The bag key of every scope, and the bags already cached (fresh, or stale and being + * refreshed), by scope. + * + * @param non-empty-list $scopes + * @param Closure(list): RecordSet $load + * + * @return array{array, array} + */ + private function lookup(CacheTarget $target, array $scopes, Closure $load): array + { + $tenant = $this->currentTenant(); + $tokens = $this->tokensFor($target, $tenant, $scopes); + $keys = []; + $found = []; + $pending = []; + + foreach ($scopes as $scope) { + $key = $keys[$scope->value] = $this->keyOf($target, $tenant, $scope, $tokens[$scope->value]); + + if (isset($this->bags[$key])) { + $found[$scope->value] = $this->bags[$key]; + } else { + $pending[$scope->value] = $scope; + } + } + + if ($pending === []) { + return [$keys, $found]; + } + + $entries = $this->cache->many(array_merge(...array_values(array_map( + static fn (Scope $scope): array => [$keys[$scope->value], Repository::FLEXIBLE_CREATED_KEY_PREFIX . $keys[$scope->value]], + $pending, + )))); + + foreach ($pending as $value => $scope) { + $key = $keys[$value]; + $created = $entries[Repository::FLEXIBLE_CREATED_KEY_PREFIX . $key] ?? null; + $entry = $entries[$key] ?? null; + + if (! is_int($created) || ! $this->codec->decode($entry) instanceof RecordSet) { + continue; + } + + // Past its fresh window: flexible() answers the stale bag and defers a refresh, which + // lands under this key's tokens (so never over a newer write). + if ($created + $this->ttl <= now()->getTimestamp()) { + $entry = $this->cache->flexible($key, [$this->ttl, $this->lifetime()], fn (): array => $this->codec->encode($this->only($load([$scope]), $scope))); + } + + $records = $this->codec->decode($entry); + + if ($records instanceof RecordSet) { + $found[$value] = $this->bags[$key] = $records; + } + } + + return [$keys, $found]; + } + + /** + * Cache freshly loaded bags in the shape flexible() reads (entry plus its creation time). + * + * @param list $keys + * @param list $bags + */ + private function put(array $keys, array $bags): void + { + $entries = []; + $now = now()->getTimestamp(); + + foreach ($keys as $index => $key) { + $this->bags[$key] = $bags[$index]; + $entries[$key] = $this->codec->encode($bags[$index]); + $entries[Repository::FLEXIBLE_CREATED_KEY_PREFIX . $key] = $now; + } + + try { + $this->cache->putMany($entries, $this->lifetime()); + } catch (Throwable $exception) { + $this->failed('write', $exception); + } + } + + /** + * The (epoch, store, scope) tokens of each scope, as one generation string per scope. Missing + * tokens are created; every token is read in one cache call. + * + * @param non-empty-list $scopes + * + * @return array scope => generation + */ + private function tokensFor(CacheTarget $target, string $tenant, array $scopes): array + { + $epoch = $this->epochKey(); + $store = $this->storeTokenKey($target); + $scopeKeys = []; + + foreach ($scopes as $scope) { + $scopeKeys[$scope->value] = $this->scopeTokenKey($target, $tenant, $scope); + } + + $wanted = array_values(array_filter([$epoch, $store, ...array_values($scopeKeys)], fn (string $key): bool => ! isset($this->tokens[$key]))); + + if ($wanted !== []) { + $read = $this->cache->many($wanted); + + foreach ($wanted as $key) { + $token = $read[$key] ?? null; + $this->tokens[$key] = is_string($token) && $token !== '' ? $token : $this->create($key, $key === $epoch || $key === $store ? null : $this->lifetime()); + } + } + + $generations = []; + + foreach ($scopeKeys as $value => $key) { + $generations[$value] = $this->tokens[$epoch] . '.' . $this->tokens[$store] . '.' . $this->tokens[$key]; + } + + return $generations; + } + + /** A new token for a key that had none; a concurrent reader that created one first wins. */ + private function create(string $key, ?int $seconds): string + { + $token = (string) Str::ulid(); + + if ($this->cache->add($key, $token, $seconds)) { + return $token; + } + + $winner = $this->cache->get($key); + + return is_string($winner) && $winner !== '' ? $winner : $token; + } + + private function rotate(string $operation, string $key, ?int $seconds): void + { + $token = (string) Str::ulid(); + $this->tokens[$key] = $token; + + try { + $seconds === null ? $this->cache->forever($key, $token) : $this->cache->put($key, $token, $seconds); + } catch (Throwable $exception) { + $this->failed('invalidate ' . $operation, $exception); + } + } + + private function keyOf(CacheTarget $target, string $tenant, Scope $scope, string $generation): string + { + return sprintf('%s:%s:%s', $this->prefix, $this->hash([...$target->parts(), $tenant, $scope->value]), hash('sha1', $generation)); + } + + private function epochKey(): string + { + return $this->prefix . ':epoch'; + } + + /** Per store and database, not per tenant: a store reset reaches every tenant's bags. */ + private function storeTokenKey(CacheTarget $target): string + { + return $this->prefix . ':store:' . $this->hash($target->parts()); + } + + private function scopeTokenKey(CacheTarget $target, string $tenant, Scope $scope): string + { + return $this->prefix . ':scope:' . $this->hash([...$target->parts(), $tenant, $scope->value]); + } + + /** + * A length-prefixed tuple, hashed: `a` + `b:c` and `a:b` + `c` stay different (R-63). + * + * @param list $parts + */ + private function hash(array $parts): string + { + return hash('sha1', implode('', array_map(static fn (string $part): string => strlen($part) . ':' . $part, $parts))); + } + + private function currentTenant(): string + { + return ($this->tenant instanceof Closure ? ($this->tenant)() : null) ?? ''; + } + + /** Seconds a bag (and a scope token) is kept: fresh plus stale. */ + private function lifetime(): int + { + return $this->ttl + $this->stale; + } + + private function only(RecordSet $records, Scope $scope): RecordSet + { + return new RecordSet(array_filter($records->all(), static fn (Record $record): bool => $record->scope->equals($scope))); + } + + /** + * @param list $scopes + * + * @return list + */ + private function unique(array $scopes): array + { + $unique = []; + + foreach ($scopes as $scope) { + $unique[$scope->value] = $scope; + } + + return array_values($unique); + } + + private function failed(string $operation, Throwable $exception): void + { + if ($this->onFailure instanceof Closure) { + ($this->onFailure)($operation, $exception); + } + } +} diff --git a/src/Console/ClearCacheCommand.php b/src/Console/ClearCacheCommand.php new file mode 100644 index 0000000..2702bae --- /dev/null +++ b/src/Console/ClearCacheCommand.php @@ -0,0 +1,48 @@ + $names */ + $names = $this->option('store'); + $cleared = $names === [] + ? $clear->handle(actor: $actor) + : array_all($names, static fn (string $name): bool => $clear->handle($registry->get(new StoreName($name)), actor: $actor)); + } catch (SettingsException $exception) { + $this->error($exception->getMessage()); + + return self::FAILURE; + } + + $this->info($cleared ? sprintf('Settings cache reset (%s).', $names === [] ? 'every store' : implode(', ', $names)) : 'Caching is off; nothing to reset.'); + + return self::SUCCESS; + } +} diff --git a/src/Console/WarmCacheCommand.php b/src/Console/WarmCacheCommand.php new file mode 100644 index 0000000..df8e959 --- /dev/null +++ b/src/Console/WarmCacheCommand.php @@ -0,0 +1,66 @@ +stores($registry); + $rows = []; + + foreach ($stores as $store) { + if ($store->isCached()) { + $rows[] = [$store->name->value, $warm->handle($store, actor: Actor::system('laranail::settings.warm'))]; + } + } + } catch (SettingsException $exception) { + $this->error($exception->getMessage()); + + return self::FAILURE; + } + + if ($rows === []) { + $this->info('No store is cached (caching is off, or no store has a database layer); nothing to warm.'); + + return self::SUCCESS; + } + + $this->table(['Store', 'Records cached'], $rows); + + return self::SUCCESS; + } + + /** @return list */ + private function stores(StoreRegistry $registry): array + { + /** @var list $names */ + $names = $this->option('store'); + + return $names === [] + ? array_values($registry->all()) + : array_map(static fn (string $name): Store => $registry->get(new StoreName($name)), $names); + } +} diff --git a/src/Contracts/Settings.php b/src/Contracts/Settings.php index ac247cd..c9817e2 100644 --- a/src/Contracts/Settings.php +++ b/src/Contracts/Settings.php @@ -145,6 +145,25 @@ public function unlock(string $key): void; */ public function flush(): void; + /** + * Reset the cached settings this handle names (design §7.5): with `for($owner)`, that owner's + * cached values in its store; otherwise every cached value of the handle's store, for every + * tenant. Stored values are untouched. Needs `manage_stores` when the handle carries an actor. + * Does nothing when caching is off. + * + * @throws AccessDenied + */ + public function clearCache(): void; + + /** + * Load this handle's scope (its owner's, or the global scope) into the cache now, so the + * first read costs no query. Needs `manage_stores` when the handle carries an actor. Returns + * how many records were cached (0 when the store is not cached). + * + * @throws AccessDenied + */ + public function warmCache(): int; + /** * Load the settings of many owners now, one read per store, so reading each of them later in * the request costs no further query (eager loading, G-9). Includes the global scope and the diff --git a/src/Data/CacheTarget.php b/src/Data/CacheTarget.php new file mode 100644 index 0000000..771e198 --- /dev/null +++ b/src/Data/CacheTarget.php @@ -0,0 +1,27 @@ + the components that name the store's rows, in key order */ + public function parts(): array + { + return [$this->connection, $this->database, $this->store->value, $this->table]; + } +} diff --git a/src/Drivers/CachingDriver.php b/src/Drivers/CachingDriver.php new file mode 100644 index 0000000..d169035 --- /dev/null +++ b/src/Drivers/CachingDriver.php @@ -0,0 +1,118 @@ +inner; + } + + public function database(): DatabaseDriver + { + return $this->inner->database(); + } + + public function isActive(): bool + { + return $this->inner->isActive(); + } + + public function isWritable(): bool + { + return $this->inner->isWritable(); + } + + public function load(StoreName $store, array $scopes): RecordSet + { + if (! $this->inner->isActive() || $this->inner->database()->connection()->transactionLevel() > 0) { + return $this->inner->load($store, $scopes); + } + + return $this->cache->load($this->target($store), $scopes, fn (array $missing): RecordSet => $this->inner->load($store, $missing)); + } + + public function put(StoreName $store, Record $record): void + { + $this->inner->put($store, $record); + $this->forgetScope($store, $record->scope); + } + + public function forget(StoreName $store, Scope $scope, Key $key, Locale $locale): void + { + $this->inner->forget($store, $scope, $key, $locale); + $this->forgetScope($store, $scope); + } + + /** Invalidate one scope's bag, once the surrounding transaction (if any) commits. */ + public function forgetScope(StoreName $store, Scope $scope): void + { + $this->afterCommit(fn () => $this->cache->forgetScope($this->target($store), $scope)); + } + + /** Invalidate every bag of the store, once the surrounding transaction (if any) commits. */ + public function forgetStore(StoreName $store): void + { + $this->afterCommit(fn () => $this->cache->forgetStore($this->target($store))); + } + + /** + * Run an invalidation when the layer's connection commits: straight away outside a + * transaction, never for a transaction that rolls back (nothing changed). + * + * @param callable(): void $invalidate + */ + private function afterCommit(callable $invalidate): void + { + $connection = $this->inner->database()->connection(); + + if ($connection->transactionLevel() > 0) { + $connection->afterCommit($invalidate); + + return; + } + + $invalidate(); + } + + private function target(StoreName $store): CacheTarget + { + $database = $this->inner->database(); + + return new CacheTarget($database->connectionName(), (string) $database->connection()->getDatabaseName(), $store, $database->tableFor($store)); + } +} diff --git a/src/Providers/SettingsServiceProvider.php b/src/Providers/SettingsServiceProvider.php index 3ed4f1f..ae349c0 100644 --- a/src/Providers/SettingsServiceProvider.php +++ b/src/Providers/SettingsServiceProvider.php @@ -6,10 +6,12 @@ use Closure; use Override; +use Throwable; use Psr\Log\LogLevel; use Psr\Log\NullLogger; use Carbon\CarbonImmutable; use Illuminate\Http\Request; +use InvalidArgumentException; use Illuminate\Log\LogManager; use Illuminate\Filesystem\Filesystem; use Simtabi\Laranail\Settings\Data\Key; @@ -31,8 +33,10 @@ use Illuminate\Database\Events\MigrationsEnded; use Illuminate\Contracts\Foundation\Application; use Simtabi\Laranail\Settings\Actions\MakeStore; +use Simtabi\Laranail\Settings\Actions\WarmCache; use Simtabi\Laranail\Settings\Enums\AuditAction; use Illuminate\Contracts\Cache\Factory as Caches; +use Simtabi\Laranail\Settings\Actions\ClearCache; use Simtabi\Laranail\Settings\Actions\FlushScope; use Simtabi\Laranail\Settings\Actions\PruneAudit; use Simtabi\Laranail\Settings\Actions\QueryAudit; @@ -47,6 +51,7 @@ use Simtabi\Laranail\Settings\Events\LayerSkipped; use Simtabi\Laranail\Settings\Models\ModelContext; use Simtabi\Laranail\Settings\Resolution\Resolver; +use Illuminate\Cache\Repository as CacheRepository; use Simtabi\Laranail\Settings\Actions\PromoteStore; use Simtabi\Laranail\Settings\Actions\PruneOrphans; use Simtabi\Laranail\Settings\Actions\StoreActions; @@ -60,6 +65,7 @@ use Illuminate\Contracts\Encryption\StringEncrypter; use Illuminate\Database\ConnectionResolverInterface; use Illuminate\Database\Eloquent\Relations\Relation; +use Simtabi\Laranail\Settings\Caching\SettingsCache; use Simtabi\Laranail\Settings\Console\DoctorCommand; use Simtabi\Laranail\Settings\Drivers\DriverFactory; use Simtabi\Laranail\Settings\Support\ValuePipeline; @@ -73,12 +79,14 @@ use Simtabi\Laranail\Settings\Audit\DatabaseAuditSink; use Simtabi\Laranail\Settings\Contracts\ActorResolver; use Simtabi\Laranail\Settings\Console\MakeStoreCommand; +use Simtabi\Laranail\Settings\Console\WarmCacheCommand; use Simtabi\Laranail\Settings\Contracts\ReadinessProbe; use Simtabi\Laranail\Settings\Contracts\ValueEncrypter; use Simtabi\Laranail\Settings\Contracts\ValueValidator; use Simtabi\Laranail\Settings\Support\RecordSerializer; use Simtabi\Laranail\Settings\Actions\FindForeignTables; use Simtabi\Laranail\Settings\Authorization\AccessGuard; +use Simtabi\Laranail\Settings\Console\ClearCacheCommand; use Simtabi\Laranail\Settings\Console\PruneAuditCommand; use Simtabi\Laranail\Settings\Logging\OperationalLogger; use Simtabi\Laranail\Settings\Verification\NullVerifier; @@ -139,7 +147,7 @@ public function configurePackage(Package $package): void ->hasPackageSeeders(AutoSeederDefinition::make('laranail/settings:defaults') ->seeders([DefaultCategoriesSeeder::class]) ->options(['disable_foreign_key_checks' => false, 'fire_events' => true])) - ->hasCommands([PromoteCommand::class, PruneOrphansCommand::class, PruneAuditCommand::class, MakeStoreCommand::class, DoctorCommand::class, SyncDefinitionsCommand::class]) + ->hasCommands([PromoteCommand::class, PruneOrphansCommand::class, PruneAuditCommand::class, MakeStoreCommand::class, DoctorCommand::class, SyncDefinitionsCommand::class, WarmCacheCommand::class, ClearCacheCommand::class]) ->hasInstallCommand(static function (InstallCommand $command): void { $command ->startWith(static function (InstallCommand $command): void { @@ -267,6 +275,7 @@ static function (string $change) use ($app): void { onLayerSkipped: static function (string $store, string $layer, string $reason) use ($app): void { $app->make(Dispatcher::class)->dispatch(new LayerSkipped($store, $layer, $reason)); }, + cache: self::cacheEnabled($app) ? $app->make(SettingsCache::class) : null, )); $this->app->singleton(ValuePipeline::class); @@ -293,6 +302,7 @@ static function (Store $store, Key $key, Scope $scope) use ($app): void { )); $this->registerAccess(); + $this->registerCache(); $this->app->scoped(SettingActions::class, static fn (Application $app): SettingActions => SettingActions::using( $app->make(SettingWriter::class), @@ -316,9 +326,18 @@ static function (Store $store, Key $key, Scope $scope) use ($app): void { ?? $app->make(DatabaseDefinitions::class)->find($store, $key), ), $flush, + new WarmCache($access), + new ClearCache( + $access, + self::cacheEnabled($app) ? $app->make(SettingsCache::class) : null, + new StoreName(self::string($app, 'laranail.settings.default', 'settings')), + ), ); }); + $this->app->scoped(WarmCache::class, static fn (Application $app): WarmCache => $app->make(StoreActions::class)->warmCache ?? new WarmCache($app->make(AccessGuard::class))); + $this->app->scoped(ClearCache::class, static fn (Application $app): ClearCache => $app->make(StoreActions::class)->clearCache ?? new ClearCache($app->make(AccessGuard::class), null)); + $this->app->scoped(DatabaseDefinitions::class, static fn (Application $app): DatabaseDefinitions => new DatabaseDefinitions( $app->make(CasterRegistry::class), $app->make(ValueEncoder::class), @@ -376,6 +395,12 @@ static function (Store $store, Key $key, Scope $scope) use ($app): void { )); } + /** `cache.enabled`: on unless set to a false value. */ + private static function cacheEnabled(Application $app): bool + { + return filter_var($app->make(Repository::class)->get('laranail.settings.cache.enabled', true), FILTER_VALIDATE_BOOL, FILTER_NULL_ON_FAILURE) ?? true; + } + /** * Install refuses to publish migrations over a table of the same name that is not this * package's (D-4): rename the package's tables with `tables.prefix` or `stores..table`. @@ -517,6 +542,46 @@ private static function config(Application $app): ConfigValues return new ConfigValues($app->make(Repository::class)); } + /** + * The settings cache (§7.5), built on first use, never at boot: the configured cache store + * (null for the application's default), keyed per tenant, reporting cache failures to the + * operational log. Scoped, so the bags it holds in memory last one request or job. + */ + private function registerCache(): void + { + $this->app->scoped(SettingsCache::class, static function (Application $app): SettingsCache { + $name = $app->make(Repository::class)->get('laranail.settings.cache.store'); + + if ($name !== null && (! is_string($name) || $name === '')) { + throw new InvalidConfiguration('laranail.settings.cache.store: a cache store name, or null for the default store.'); + } + + try { + $cache = $app->make(Caches::class)->store($name); + } catch (InvalidArgumentException $exception) { + throw new InvalidConfiguration(sprintf('laranail.settings.cache.store: %s', $exception->getMessage()), $exception->getCode(), previous: $exception); + } + + if (! $cache instanceof CacheRepository) { + throw new InvalidConfiguration(sprintf('laranail.settings.cache.store: [%s] is not a Laravel cache repository.', get_debug_type($cache))); + } + + return new SettingsCache( + $cache, + self::string($app, 'laranail.settings.cache.prefix', 'laranail-settings'), + self::integer($app, 'laranail.settings.cache.ttl', 3600), + self::integer($app, 'laranail.settings.cache.stale', 300), + static fn (): ?string => $app->make(TenantDiscriminator::class)->current(), + static function (string $operation, Throwable $exception) use ($app): void { + $app->make(OperationalLogger::class)->warning(sprintf('laranail/settings: the settings cache failed (%s): %s. Reads fall back to the database; a failed invalidation leaves bags stale until they expire or clear-cache runs.', $operation, $exception->getMessage()), [ + 'operation' => $operation, + 'exception' => $exception::class, + ]); + }, + ); + }); + } + /** * Tenancy (Amendment B): who the current tenant is, and the context the Eloquent models read * it from. `tenancy.discriminator`: `auto` (stancl/tenancy, then spatie/laravel-multitenancy, diff --git a/src/SettingsManager.php b/src/SettingsManager.php index 91bed78..9f9daea 100644 --- a/src/SettingsManager.php +++ b/src/SettingsManager.php @@ -19,7 +19,9 @@ use Illuminate\Contracts\Auth\Authenticatable; use Simtabi\Laranail\Settings\Data\Definition; use Simtabi\Laranail\Settings\Audit\AuditQuery; +use Simtabi\Laranail\Settings\Actions\WarmCache; use Simtabi\Laranail\Settings\Data\SettingWrite; +use Simtabi\Laranail\Settings\Actions\ClearCache; use Simtabi\Laranail\Settings\Actions\QueryAudit; use Simtabi\Laranail\Settings\Contracts\Settable; use Simtabi\Laranail\Settings\Contracts\Settings; @@ -263,6 +265,16 @@ public function flush(): void } } + public function clearCache(): void + { + $this->clearCacheAction()->handle($this->targetStore(), $this->owner, $this->actingAs); + } + + public function warmCache(): int + { + return $this->warmCacheAction()->handle($this->targetStore(), $this->owner, $this->actingAs); + } + public function preload(iterable $owners): void { $groups = []; @@ -313,6 +325,16 @@ private function storeActions(): StoreActions return $this->storeActions ?? throw new LogicException('This settings handle was built without store actions; resolve Settings from the container.'); } + private function clearCacheAction(): ClearCache + { + return $this->storeActions()->clearCache ?? throw new LogicException('This settings handle was built without the cache actions; resolve Settings from the container.'); + } + + private function warmCacheAction(): WarmCache + { + return $this->storeActions()->warmCache ?? throw new LogicException('This settings handle was built without the cache actions; resolve Settings from the container.'); + } + private function scope(): Scope { return Scope::of($this->owner); diff --git a/src/Stores/Store.php b/src/Stores/Store.php index 3746ca8..617b5de 100644 --- a/src/Stores/Store.php +++ b/src/Stores/Store.php @@ -9,6 +9,7 @@ use Simtabi\Laranail\Settings\Data\RecordSet; use Simtabi\Laranail\Settings\Data\StoreName; use Simtabi\Laranail\Settings\Enums\StoreMode; +use Simtabi\Laranail\Settings\Drivers\CachingDriver; use Simtabi\Laranail\Settings\Drivers\DatabaseDriver; use Simtabi\Laranail\Settings\Contracts\DatabaseBacked; use Simtabi\Laranail\Settings\Exceptions\StoreNotWritable; @@ -108,6 +109,50 @@ public function writableLayer(): Layer throw new StoreNotWritable(sprintf('Store [%s] has no writable layer.', $this->name)); } + /** Whether any layer of this store is read through the settings cache. */ + public function isCached(): bool + { + return array_any($this->layers, fn (Layer $layer): bool => $layer->driver instanceof CachingDriver); + } + + /** + * Forget one scope's cached bag in every cached layer (after the surrounding transaction + * commits), for writes that reach the database without passing through the cache. + */ + public function forgetCached(Scope $scope): void + { + foreach ($this->cachedLayers() as $driver) { + $driver->forgetScope($this->name, $scope); + } + } + + /** Forget every cached bag of this store, for every tenant. */ + public function forgetCachedStore(): void + { + foreach ($this->cachedLayers() as $driver) { + $driver->forgetStore($this->name); + } + } + + /** + * Load these scopes into the cache of every active cached layer (one read per layer on a + * miss, none on a hit); returns how many records the cached layers hold for them. + * + * @param list $scopes + */ + public function warmCache(array $scopes): int + { + $records = 0; + + foreach ($this->cachedLayers() as $driver) { + if ($driver->isActive()) { + $records += $driver->load($this->name, $scopes)->count(); + } + } + + return $records; + } + /** * Every layer's records for these scopes, in layer order: one read per layer. * @@ -125,4 +170,10 @@ public function load(array $scopes): array return $loaded; } + + /** @return list */ + private function cachedLayers(): array + { + return array_values(array_filter(array_map(static fn (Layer $layer): ?CachingDriver => $layer->driver instanceof CachingDriver ? $layer->driver : null, $this->layers))); + } } diff --git a/src/Stores/StoreRegistry.php b/src/Stores/StoreRegistry.php index 5059175..e6805a9 100644 --- a/src/Stores/StoreRegistry.php +++ b/src/Stores/StoreRegistry.php @@ -13,9 +13,12 @@ use Simtabi\Laranail\Settings\Database\SchemaNames; use Simtabi\Laranail\Settings\Database\StoreSchema; use Simtabi\Laranail\Settings\Support\ConfigValues; +use Simtabi\Laranail\Settings\Caching\SettingsCache; +use Simtabi\Laranail\Settings\Drivers\CachingDriver; use Simtabi\Laranail\Settings\Drivers\DriverFactory; use Simtabi\Laranail\Settings\Drivers\DatabaseDriver; use Simtabi\Laranail\Settings\Exceptions\UnknownStore; +use Simtabi\Laranail\Settings\Contracts\DatabaseBacked; use Simtabi\Laranail\Settings\Exceptions\OwnerNotAllowed; use Simtabi\Laranail\Settings\Contracts\BootstrapEvidence; use Simtabi\Laranail\Settings\Drivers\BootstrapGatedDriver; @@ -49,12 +52,13 @@ public function __construct( private readonly ?RuntimeConfiguration $runtime = null, private readonly ?BootstrapEvidence $evidence = null, private readonly ?Closure $onLayerSkipped = null, + private readonly ?SettingsCache $cache = null, ) {} /** A copy whose every layer is replaced by one driver (used by the fake). */ public function withEveryLayer(Driver $driver): self { - return new self($this->drivers, $this->default, $this->storeConfig, $this->layerConfig, $driver, $this->runtime, $this->evidence, $this->onLayerSkipped); + return new self($this->drivers, $this->default, $this->storeConfig, $this->layerConfig, $driver, $this->runtime, $this->evidence, $this->onLayerSkipped, $this->cache); } /** @@ -187,12 +191,22 @@ private function build(): array } /** - * A layer built for one store: a database layer learns the store's table, and in a store in - * bootstrap mode it is put behind the bootstrap gate. + * A layer built for one store: a database layer learns the store's table, in a store in + * bootstrap mode it is put behind the bootstrap gate, and with caching on it is read through + * the settings cache (outside the gate, so a skipped layer is never cached). */ private function storeLayer(string $name, string $storePath, StoreName $store, ?string $table, bool $bootstrap): Layer { - $layer = $this->layer($name, $storePath, $table === null ? [] : ['table' => $table]); + $layer = $this->gatedLayer($this->layer($name, $storePath, $table === null ? [] : ['table' => $table]), $store, $bootstrap); + + return $this->cache instanceof SettingsCache && $layer->driver instanceof DatabaseBacked + ? new Layer($layer->name, new CachingDriver($layer->driver, $this->cache), $layer->type) + : $layer; + } + + private function gatedLayer(Layer $layer, StoreName $store, bool $bootstrap): Layer + { + $name = $layer->name; if (! $bootstrap || ! $layer->driver instanceof DatabaseDriver) { return $layer; diff --git a/src/Support/BagCodec.php b/src/Support/BagCodec.php new file mode 100644 index 0000000..fc511ef --- /dev/null +++ b/src/Support/BagCodec.php @@ -0,0 +1,123 @@ +>} */ + public function encode(RecordSet $records): array + { + return ['v' => self::VERSION, 'r' => array_map(static fn (Record $record): array => [ + 's' => $record->scope->value, + 'k' => $record->key->value, + 'l' => $record->locale->value, + 'p' => $record->payload, + 't' => $record->type, + 'e' => $record->encrypted, + 'x' => $record->locked, + 'n' => $record->version, + 'w' => $record->writtenAt?->toIso8601String(), + 'g' => $record->group, + 'c' => $record->category, + 'u' => $record->public, + ], $records->all())]; + } + + /** The records an entry holds, or null when it is not an entry this release wrote. */ + public function decode(mixed $entry): ?RecordSet + { + if (! is_array($entry) || ($entry['v'] ?? null) !== self::VERSION || ! is_array($entry['r'] ?? null)) { + return null; + } + + $records = []; + + foreach ($entry['r'] as $row) { + $record = is_array($row) ? $this->record($row) : null; + + if (! $record instanceof Record) { + return null; + } + + $records[] = $record; + } + + return new RecordSet($records); + } + + /** @param array $row */ + private function record(array $row): ?Record + { + $scope = is_string($row['s'] ?? null) ? Scope::fromString($row['s']) : null; + $payload = $row['p'] ?? null; + $written = $row['w'] ?? null; + + if (! $scope instanceof Scope || ! is_string($row['k'] ?? null) || ! is_string($row['l'] ?? null) || ! is_int($row['n'] ?? null) + || ($payload !== null && ! is_string($payload)) || ($written !== null && ! is_string($written)) + || ! $this->nullableStrings($row, ['t', 'g', 'c']) || ! $this->booleans($row, ['e', 'x', 'u'])) { + return null; + } + + try { + return new Record( + scope: $scope, + key: new Key($row['k']), + locale: new Locale($row['l']), + payload: $payload, + type: $this->nullableString($row['t']), + encrypted: $row['e'] === true, + locked: $row['x'] === true, + version: $row['n'], + writtenAt: $written === null ? null : CarbonImmutable::parse($written), + group: $this->nullableString($row['g']), + category: $this->nullableString($row['c']), + public: $row['u'] === true, + ); + } catch (Throwable) { + return null; + } + } + + /** + * @param array $row + * @param list $fields + */ + private function nullableStrings(array $row, array $fields): bool + { + return array_all($fields, static fn (string $field): bool => array_key_exists($field, $row) && ($row[$field] === null || is_string($row[$field]))); + } + + /** + * @param array $row + * @param list $fields + */ + private function booleans(array $row, array $fields): bool + { + return array_all($fields, static fn (string $field): bool => is_bool($row[$field] ?? null)); + } + + private function nullableString(mixed $value): ?string + { + return is_string($value) ? $value : null; + } +} diff --git a/src/Testing/SettingsFake.php b/src/Testing/SettingsFake.php index e7a8307..45f1841 100644 --- a/src/Testing/SettingsFake.php +++ b/src/Testing/SettingsFake.php @@ -162,6 +162,16 @@ public function flush(): void $this->inner->flush(); } + public function clearCache(): void + { + $this->inner->clearCache(); + } + + public function warmCache(): int + { + return $this->inner->warmCache(); + } + public function preload(iterable $owners): void { $this->inner->preload($owners); diff --git a/tests/Feature/Database/CachingTest.php b/tests/Feature/Database/CachingTest.php new file mode 100644 index 0000000..4bd38c8 --- /dev/null +++ b/tests/Feature/Database/CachingTest.php @@ -0,0 +1,452 @@ +forgetScopedInstances(); +} + +/** Run a callback and return how many queries it sent to the default connection. */ +function queriesDuring(Closure $callback): int +{ + DB::flushQueryLog(); + DB::enableQueryLog(); + $callback(); + $count = count(DB::getQueryLog()); + DB::disableQueryLog(); + + return $count; +} + +/** The cached default store's database layer. */ +function cachedLayer(): CachingDriver +{ + $driver = app(StoreRegistry::class)->default()->layers[0]->driver; + assert($driver instanceof CachingDriver); + + return $driver; +} + +function defaultTarget(): CacheTarget +{ + $database = cachedLayer()->database(); + $store = new StoreName('settings'); + + return new CacheTarget($database->connectionName(), (string) $database->connection()->getDatabaseName(), $store, $database->tableFor($store)); +} + +beforeEach(function (): void { + useDatabase([ + 'stores.settings.owners' => ['owner'], + 'stores.settings.inherits' => true, + 'stores.teams' => ['layers' => ['database'], 'owners' => ['team']], + ], stores: ['teams']); + + Schema::create('owners', static function (Blueprint $table): void { + $table->bigIncrements('id'); + $table->unsignedBigInteger('team_id')->nullable(); + }); + + Relation::morphMap(['owner' => SettingsOwner::class], false); +}); + +afterEach(function (): void { + Relation::morphMap([], false); +}); + +it('caches each database layer behind the settings cache, and only database layers', function (): void { + $layers = app(StoreRegistry::class)->default()->layers; + + expect($layers[0]->driver)->toBeInstanceOf(CachingDriver::class) + ->and($layers[1]->driver)->toBeInstanceOf(JsonDriver::class) + ->and(app(StoreRegistry::class)->default()->isCached())->toBeTrue(); +}); + +it('reads a cold chain with one query per distinct store, and a warm one with none', function (): void { + $owner = SettingsOwner::query()->create(['team_id' => 7]); + settings()->for(new OwnerRef('team', 7))->set('ui.density', 'compact'); + settings()->set('ui.theme', 'light'); + nextRequest(); + + // owner → team (teams store) → global (settings store): two distinct stores. + $cold = queriesDuring(static function () use ($owner): void { + expect($owner->settings()->get('ui.density'))->toBe('compact'); + }); + $sameRequest = queriesDuring(static function () use ($owner): void { + expect($owner->settings()->get('ui.theme'))->toBe('light'); + }); + nextRequest(); + $warm = queriesDuring(static function () use ($owner): void { + expect($owner->settings()->get('ui.density'))->toBe('compact') + ->and($owner->settings()->get('ui.theme'))->toBe('light') + ->and($owner->settings()->get('ui.missing'))->toBeNull(); + }); + + expect($cold)->toBe(2) + ->and($sameRequest)->toBe(0) + ->and($warm)->toBe(0); +}); + +it('caches a miss as an empty bag', function (): void { + expect(settings()->get('nothing.here'))->toBeNull(); + nextRequest(); + + expect(queriesDuring(static function (): void { + expect(settings()->get('nothing.here'))->toBeNull(); + }))->toBe(0); +}); + +it('makes every write path visible to the next request', function (string $path): void { + $owner = SettingsOwner::query()->create(); + $owner->settings()->set('ui.theme', 'dark'); + settings()->set('site.name', 'Acme'); + expect($owner->settings()->get('ui.theme'))->toBe('dark') + ->and(settings()->get('site.name'))->toBe('Acme'); + nextRequest(); + // Both bags are now cached; every path below must invalidate the one it changes. + expect($owner->settings()->get('ui.theme'))->toBe('dark'); + nextRequest(); + + match ($path) { + 'set' => $owner->settings()->set('ui.theme', 'light'), + 'forget' => $owner->settings()->forget('ui.theme'), + 'lock' => $owner->settings()->lock('ui.theme'), + 'unlock' => [$owner->settings()->lock('ui.theme'), nextRequest(), $owner->settings()->get('ui.theme'), $owner->settings()->unlock('ui.theme')], + 'flush' => $owner->settings()->flush(), + 'deleted' => $owner->delete(), + }; + nextRequest(); + + $handle = $owner->settings(); + + match ($path) { + 'set' => expect($handle->get('ui.theme'))->toBe('light'), + 'forget', 'flush' => expect($handle->get('ui.theme'))->toBeNull(), + 'deleted' => expect(settings()->for(new OwnerRef('owner', $owner->id))->get('ui.theme'))->toBeNull(), + 'lock' => expect(cachedLayer()->load(new StoreName('settings'), [Scope::forOwner(new OwnerRef('owner', $owner->id))])->all()[0]->locked)->toBeTrue(), + 'unlock' => expect(cachedLayer()->load(new StoreName('settings'), [Scope::forOwner(new OwnerRef('owner', $owner->id))])->all()[0]->locked)->toBeFalse(), + }; +})->with(['set', 'forget', 'lock', 'unlock', 'flush', 'deleted']); + +it('invalidates the store when values are promoted into it', function (): void { + expect(settings()->get('site.name'))->toBeNull(); + $runtime = app(StoreRegistry::class)->default()->layers[1]->driver; + assert($runtime instanceof JsonDriver); + $runtime->put(new StoreName('settings'), new Record(Scope::global(), new Key('site.name'), Locale::none(), '"Acme"')); + nextRequest(); + + settings()->promote(); + nextRequest(); + + expect(settings()->get('site.name'))->toBe('Acme') + ->and(settings()->explain('site.name')->lookup->layer())->toBe('database'); +}); + +it('keeps a write made past the API invisible until the cache is cleared', function (): void { + settings()->set('site.name', 'Acme'); + expect(settings()->get('site.name'))->toBe('Acme'); + DB::table('settings')->update(['value' => '"Changed"']); + nextRequest(); + + expect(settings()->get('site.name'))->toBe('Acme'); + + settings()->clearCache(); + nextRequest(); + + expect(settings()->get('site.name'))->toBe('Changed'); +}); + +it('reads its own uncommitted write inside a transaction and caches nothing a rollback undoes', function (): void { + settings()->set('site.name', 'Acme'); + expect(settings()->get('site.name'))->toBe('Acme'); + + DB::beginTransaction(); + settings()->set('site.name', 'Inside'); + expect(settings()->get('site.name'))->toBe('Inside'); + DB::rollBack(); + nextRequest(); + + expect(settings()->get('site.name'))->toBe('Acme'); + + DB::transaction(static fn () => settings()->set('site.name', 'Committed')); + nextRequest(); + + expect(settings()->get('site.name'))->toBe('Committed'); +}); + +it('keeps two connections apart even where every other key component is equal (G-37)', function (): void { + // A second in-memory SQLite connection: same database name (`:memory:`), store, table and + // scope as the default one under SQLite, so only the connection name tells them apart. + config()->set('database.connections.other', ['driver' => 'sqlite', 'database' => ':memory:', 'prefix' => '']); + $default = config('database.default'); + config()->set('database.default', 'other'); + useDatabase(['stores.settings.owners' => ['owner']]); + settings()->set('site.name', 'Other'); + + config()->set('database.default', $default); + app()->forgetInstance(DriverFactory::class); + nextRequest(); + settings()->set('site.name', 'Default'); + expect(settings()->get('site.name'))->toBe('Default'); + + // The same store's layer, pointed at the other connection. + config()->set('laranail.settings.layers.database.connection', 'other'); + app()->forgetInstance(DriverFactory::class); + nextRequest(); + + expect(settings()->get('site.name'))->toBe('Other'); +}); + +it('never answers one tenant from another tenant\'s bag', function (): void { + useDatabase(['tenancy.mode' => 'column']); + $tenant = new class + { + public ?string $id = 'a'; + }; + app()->instance(TenantDiscriminator::class, new ClosureTenantDiscriminator(static fn (): ?string => $tenant->id)); + + settings()->set('site.name', 'Tenant A'); + $tenant->id = 'b'; + settings()->set('site.name', 'Tenant B'); + $tenant->id = 'a'; + expect(settings()->get('site.name'))->toBe('Tenant A'); + $tenant->id = 'b'; + expect(settings()->get('site.name'))->toBe('Tenant B'); + + // Once cached, the database is not asked again, and still neither tenant sees the other. + $queries = queriesDuring(static function () use ($tenant): void { + $tenant->id = 'a'; + expect(settings()->get('site.name'))->toBe('Tenant A'); + $tenant->id = 'b'; + expect(settings()->get('site.name'))->toBe('Tenant B'); + }); + + expect($queries)->toBe(0); +}); + +it('serves a stale bag while it refreshes, and a refresh can never restore an invalidated value', function (): void { + settings()->set('site.name', 'Acme'); + expect(settings()->get('site.name'))->toBe('Acme'); + DB::table('settings')->update(['value' => '"Changed directly"']); + + // Past the fresh window (ttl 3600), inside the stale one (300): the stale bag is answered and + // a refresh is deferred. + $this->travel(3700)->seconds(); + nextRequest(); + $deferred = app(DeferredCallbackCollection::class); + $before = $deferred->count(); + + expect(settings()->get('site.name'))->toBe('Acme') + ->and($deferred->count())->toBe($before + 1); + + // A write lands before the deferred refresh runs; the refresh then writes under the old + // generation, where no reader looks any more. + settings()->set('site.name', 'Written'); + $deferred->invoke(); + nextRequest(); + + expect(settings()->get('site.name'))->toBe('Written'); +}); + +it('refreshes a stale bag in the background when nothing was written', function (): void { + settings()->set('site.name', 'Acme'); + expect(settings()->get('site.name'))->toBe('Acme'); + DB::table('settings')->update(['value' => '"Changed directly"']); + $this->travel(3700)->seconds(); + nextRequest(); + + expect(settings()->get('site.name'))->toBe('Acme'); + + app(DeferredCallbackCollection::class)->invoke(); + nextRequest(); + + expect(settings()->get('site.name'))->toBe('Changed directly'); +}); + +it('ignores a bag written late under a generation a write has replaced', function (): void { + settings()->set('site.name', 'Acme'); + $cache = app(SettingsCache::class); + $target = defaultTarget(); + $before = $cache->bagKey($target, Scope::global()); + + $cache->forgetScope($target, Scope::global()); + + expect($cache->bagKey($target, Scope::global()))->not->toBe($before); + + // A slow reader that computed the old bag stores it after the write. + Cache::store()->put($before, ['v' => 1, 'r' => []], 600); + nextRequest(); + + expect(settings()->get('site.name'))->toBe('Acme'); +}); + +it('expires a bag after its fresh and stale windows', function (): void { + settings()->set('site.name', 'Acme'); + expect(settings()->get('site.name'))->toBe('Acme'); + DB::table('settings')->update(['value' => '"Changed directly"']); + $this->travel(3901)->seconds(); + nextRequest(); + + expect(settings()->get('site.name'))->toBe('Changed directly'); +}); + +it('never caches a database layer that bootstrap mode is skipping', function (): void { + config()->set('laranail.settings.stores.settings.bootstrap', true); + config()->set('laranail.settings.bootstrap', true); + config()->set('database.connections.unmigrated', ['driver' => 'sqlite', 'database' => ':memory:', 'prefix' => '']); + config()->set('laranail.settings.layers.database.connection', 'unmigrated'); + app()->forgetInstance(DriverFactory::class); + nextRequest(); + + expect(settings()->get('site.name'))->toBeNull() + ->and(cachedLayer()->isActive())->toBeFalse() + ->and(cachedLayer()->isWritable())->toBeFalse() + ->and(cachedLayer()->uncached()->isActive())->toBeFalse() + ->and(app(StoreRegistry::class)->default()->warmCache([Scope::global()]))->toBe(0); +}); + +it('warms and clears per scope, per store and everywhere, gated by manage_stores and audited', function (): void { + settings()->set('site.name', 'Acme'); + nextRequest(); + + expect(settings()->warmCache())->toBe(1) + ->and(queriesDuring(static fn (): mixed => settings()->get('site.name')))->toBe(0); + + DB::table('settings')->update(['value' => '"Changed"']); + + // Another owner's bag, then another store: the global bag of `settings` survives both. + settings()->for(new OwnerRef('owner', 1))->clearCache(); + settings()->store('teams')->clearCache(); + nextRequest(); + expect(settings()->get('site.name'))->toBe('Acme'); + + settings()->clearCache(); + nextRequest(); + expect(settings()->get('site.name'))->toBe('Changed'); + + // An actor needs manage_stores (step-up verification switched off here). + config()->set('laranail.settings.verification.driver', 'none'); + nextRequest(); + $sink = auditInMemory(); + + expect(fn () => settings()->as(user())->clearCache())->toThrow(AccessDenied::class) + ->and(fn (): int => settings()->as(user())->warmCache())->toThrow(AccessDenied::class); + + allowGates(Ability::ManageStores); + settings()->as(user())->clearCache(); + expect(settings()->as(user())->warmCache())->toBe(1); + + $allowed = array_values(array_filter($sink->entries(), static fn (AuditEntry $entry): bool => $entry->outcome === AuditOutcome::Allowed && $entry->action === AuditAction::ManageStores)); + $denied = array_values(array_filter($sink->entries(), static fn (AuditEntry $entry): bool => $entry->outcome === AuditOutcome::Denied)); + + expect(array_map(static fn (AuditEntry $entry): mixed => $entry->meta['operation'] ?? null, $allowed))->toBe(['cache.clear', 'cache.warm']) + ->and(array_map(static fn (AuditEntry $entry): AuditAction => $entry->action, $allowed))->toBe([AuditAction::ManageStores, AuditAction::ManageStores]) + ->and($allowed[0]->meta['target'] ?? null)->toBe('store') + ->and($allowed[1]->meta['records'] ?? null)->toBe(1) + ->and($denied)->toHaveCount(2); +}); + +it('warms and clears from the console', function (): void { + settings()->set('site.name', 'Acme'); + nextRequest(); + + $this->artisan('laranail::settings.warm') + ->expectsTable(['Store', 'Records cached'], [['settings', 1], ['teams', 0]]) + ->assertSuccessful(); + expect(queriesDuring(static fn (): mixed => settings()->get('site.name')))->toBe(0); + + DB::table('settings')->update(['value' => '"Changed"']); + $this->artisan('laranail::settings.clear-cache', ['--store' => ['teams']]) + ->expectsOutputToContain('Settings cache reset (teams).') + ->assertSuccessful(); + nextRequest(); + expect(settings()->get('site.name'))->toBe('Acme'); + + $this->artisan('laranail::settings.clear-cache') + ->expectsOutputToContain('Settings cache reset (every store).') + ->assertSuccessful(); + nextRequest(); + expect(settings()->get('site.name'))->toBe('Changed'); + + $this->artisan('laranail::settings.warm', ['--store' => ['teams']])->assertSuccessful(); + $this->artisan('laranail::settings.warm', ['--store' => ['missing']])->assertFailed(); + $this->artisan('laranail::settings.clear-cache', ['--store' => ['missing']])->assertFailed(); +}); + +it('reads straight from the database when caching is off', function (): void { + config()->set('laranail.settings.cache.enabled', false); + nextRequest(); + settings()->set('site.name', 'Acme'); + expect(settings()->get('site.name'))->toBe('Acme') + ->and(app(StoreRegistry::class)->default()->layers[0]->driver)->not->toBeInstanceOf(CachingDriver::class) + ->and(app(StoreRegistry::class)->default()->isCached())->toBeFalse() + ->and(settings()->warmCache())->toBe(0); + + settings()->clearCache(); + + $this->artisan('laranail::settings.warm')->expectsOutputToContain('nothing to warm')->assertSuccessful(); + $this->artisan('laranail::settings.clear-cache')->expectsOutputToContain('Caching is off')->assertSuccessful(); + + DB::table('settings')->update(['value' => '"Changed"']); + + expect(settings()->get('site.name'))->toBe('Changed'); +}); + +it('loads every scope of a read in one query and caches each bag on its own', function (): void { + $records = app(StoreRegistry::class)->default()->layers[0]->driver->load(new StoreName('settings'), []); + expect($records)->toBeInstanceOf(RecordSet::class)->and($records->count())->toBe(0); + + settings()->set('site.name', 'Acme'); + settings()->for(new OwnerRef('owner', 1))->set('ui.theme', 'dark'); + nextRequest(); + $scopes = [Scope::global(), Scope::forOwner(new OwnerRef('owner', 1)), Scope::forOwner(new OwnerRef('owner', 2)), Scope::global()]; + + $cold = queriesDuring(static function () use ($scopes): void { + expect(cachedLayer()->load(new StoreName('settings'), $scopes)->count())->toBe(2); + }); + nextRequest(); + $warm = queriesDuring(static function (): void { + expect(cachedLayer()->load(new StoreName('settings'), [Scope::forOwner(new OwnerRef('owner', 2))])->count())->toBe(0); + }); + + expect($cold)->toBe(1)->and($warm)->toBe(0); +}); diff --git a/tests/Feature/Database/HandlesTest.php b/tests/Feature/Database/HandlesTest.php index 25d079f..eeb869e 100644 --- a/tests/Feature/Database/HandlesTest.php +++ b/tests/Feature/Database/HandlesTest.php @@ -14,8 +14,8 @@ use Simtabi\Laranail\Settings\Data\PromotionReport; use Simtabi\Laranail\Settings\Stores\StoreRegistry; use Simtabi\Laranail\Settings\Data\PromotionRequest; +use Simtabi\Laranail\Settings\Drivers\CachingDriver; use Simtabi\Laranail\Settings\Drivers\DriverFactory; -use Simtabi\Laranail\Settings\Drivers\DatabaseDriver; use Simtabi\Laranail\Settings\Exceptions\DriverFailure; use Simtabi\Laranail\Settings\Exceptions\StoreNotWritable; use Simtabi\Laranail\Settings\Stores\InstallationEvidence; @@ -64,8 +64,10 @@ app()->forgetInstance(DriverFactory::class); app()->forgetScopedInstances(); - $layer = app(StoreRegistry::class)->default()->layers[0]->driver; - assert($layer instanceof DatabaseDriver); + // With caching on the layer is the cache in front of the database driver. + $cached = app(StoreRegistry::class)->default()->layers[0]->driver; + assert($cached instanceof CachingDriver); + $layer = $cached->database(); $gate = new BootstrapGatedDriver($layer, new StoreName('settings'), new InstallationEvidence(true)); $store = new StoreName('settings'); diff --git a/tests/Feature/FakeTest.php b/tests/Feature/FakeTest.php index 2653be9..50193a2 100644 --- a/tests/Feature/FakeTest.php +++ b/tests/Feature/FakeTest.php @@ -110,3 +110,13 @@ expect(fn (): array => $fake->audit()->get())->toThrow(DriverUnavailable::class); }); + +it('forwards the cache calls, which have nothing to cache over in-memory layers', function (): void { + $fake = Settings::fake(); + Settings::set('site.name', 'Acme'); + + $fake->clearCache(); + + expect($fake->warmCache())->toBe(0) + ->and(Settings::get('site.name'))->toBe('Acme'); +}); diff --git a/tests/Feature/SettingsCacheTest.php b/tests/Feature/SettingsCacheTest.php new file mode 100644 index 0000000..bfe57a5 --- /dev/null +++ b/tests/Feature/SettingsCacheTest.php @@ -0,0 +1,303 @@ +> $calls + */ +function countingLoader(array &$calls): Closure +{ + return static function (array $scopes) use (&$calls): RecordSet { + $calls[] = array_map(static fn (Scope $scope): string => $scope->value, $scopes); + + return new RecordSet(array_map(static fn (Scope $scope): Record => new Record($scope, new Key('a'), Locale::none(), '"' . $scope->value . '"'), $scopes)); + }; +} + +/** A cache store whose every operation fails, as an unreachable Redis would. */ +function brokenCache(): Repository +{ + return new Repository(new class extends ArrayStore + { + public function get($key): mixed + { + throw new RuntimeException('cache down'); + } + + public function many(array $keys): array + { + throw new RuntimeException('cache down'); + } + + public function put($key, $value, $seconds): bool + { + throw new RuntimeException('cache down'); + } + + public function putMany(array $values, $seconds): bool + { + throw new RuntimeException('cache down'); + } + + public function forever($key, $value): bool + { + throw new RuntimeException('cache down'); + } + }); +} + +it('asks the database once for every missing scope, then not at all', function (): void { + $calls = []; + $cache = new SettingsCache(new Repository(new ArrayStore)); + $owner = Scope::forOwner(new OwnerRef('user', '1')); + + $first = $cache->load(cacheTarget(), [Scope::global(), $owner, Scope::global()], countingLoader($calls)); + $again = $cache->load(cacheTarget(), [$owner, Scope::global()], countingLoader($calls)); + + expect($calls)->toBe([['global', 'user:1']]) + ->and($first->count())->toBe(2) + ->and($again->count())->toBe(2) + ->and($cache->load(cacheTarget(), [], countingLoader($calls))->count())->toBe(0); +}); + +it('shares bags across requests through the cache store, not the request memory', function (): void { + $calls = []; + $store = new Repository(new ArrayStore); + + new SettingsCache($store)->load(cacheTarget(), [Scope::global()], countingLoader($calls)); + new SettingsCache($store)->load(cacheTarget(), [Scope::global()], countingLoader($calls)); + + expect($calls)->toBe([['global']]); +}); + +it('invalidates a scope, a store or everything with one token each', function (): void { + $calls = []; + $store = new Repository(new ArrayStore); + $owner = Scope::forOwner(new OwnerRef('user', '1')); + $load = static function (SettingsCache $cache, array $scopes) use (&$calls): void { + $cache->load(cacheTarget(), $scopes, countingLoader($calls)); + }; + $writer = new SettingsCache($store); + $load($writer, [Scope::global(), $owner]); + + $writer->forgetScope(cacheTarget(), $owner); + $load(new SettingsCache($store), [Scope::global(), $owner]); + + $writer->forgetStore(cacheTarget()); + $load(new SettingsCache($store), [Scope::global(), $owner]); + // Another store's bags are not touched by a store reset. + new SettingsCache($store)->load(new CacheTarget('mysql', 'app', new StoreName('teams'), 'teams'), [Scope::global()], countingLoader($calls)); + $writer->forgetStore(cacheTarget()); + new SettingsCache($store)->load(new CacheTarget('mysql', 'app', new StoreName('teams'), 'teams'), [Scope::global()], countingLoader($calls)); + + $writer->forgetAll(); + new SettingsCache($store)->load(new CacheTarget('mysql', 'app', new StoreName('teams'), 'teams'), [Scope::global()], countingLoader($calls)); + + expect($calls)->toBe([['global', 'user:1'], ['user:1'], ['global', 'user:1'], ['global'], ['global']]); +}); + +it('keys every component apart, including a split that a plain join would collide on (R-63, G-37)', function (): void { + $cache = new SettingsCache(new Repository(new ArrayStore)); + $keys = [ + $cache->bagKey(cacheTarget('a', 'b:c'), Scope::global()), + $cache->bagKey(cacheTarget('a:b', 'c'), Scope::global()), + $cache->bagKey(cacheTarget('a', 'bc'), Scope::global()), + $cache->bagKey(cacheTarget('mysql', 'app'), Scope::global()), + $cache->bagKey(cacheTarget('pgsql', 'app'), Scope::global()), + $cache->bagKey(cacheTarget('mysql', 'other'), Scope::global()), + $cache->bagKey(cacheTarget('mysql', 'app'), Scope::forOwner(new OwnerRef('user', '1'))), + ]; + + expect(array_unique($keys))->toHaveCount(count($keys)) + ->and($keys[0])->toStartWith('laranail-settings:') + ->and($cache->bagKey(cacheTarget('mysql', 'app'), Scope::global()))->toBe($keys[3]); +}); + +it('keys the tenant into every bag', function (): void { + $tenant = new class + { + public ?string $id = 'a'; + }; + $calls = []; + $cache = new SettingsCache(new Repository(new ArrayStore), tenant: static fn (): ?string => $tenant->id); + + $a = $cache->bagKey(cacheTarget(), Scope::global()); + $cache->load(cacheTarget(), [Scope::global()], countingLoader($calls)); + $tenant->id = 'b'; + $b = $cache->bagKey(cacheTarget(), Scope::global()); + $cache->load(cacheTarget(), [Scope::global()], countingLoader($calls)); + $tenant->id = null; + + expect($a)->not->toBe($b) + ->and($cache->bagKey(cacheTarget(), Scope::global()))->not->toBe($a) + ->and($calls)->toHaveCount(2); +}); + +it('uses the configured prefix and key lifetimes', function (): void { + $store = new Repository(new ArrayStore); + $calls = []; + $cache = new SettingsCache($store, prefix: 'acme', ttl: 10, stale: 0); + $cache->load(cacheTarget(), [Scope::global()], countingLoader($calls)); + $key = $cache->bagKey(cacheTarget(), Scope::global()); + + expect($key)->toStartWith('acme:') + ->and($store->get($key))->toBeArray(); + + $this->travel(11)->seconds(); + + expect($store->get($key))->toBeNull(); +}); + +it('reads from the database and reports it when the cache fails', function (): void { + $calls = []; + $failures = []; + $cache = new SettingsCache(brokenCache(), onFailure: static function (string $operation, Throwable $exception) use (&$failures): void { + $failures[] = $operation . ': ' . $exception->getMessage(); + }); + + $records = $cache->load(cacheTarget(), [Scope::global()], countingLoader($calls)); + $cache->forgetScope(cacheTarget(), Scope::global()); + $cache->forgetAll(); + + expect($records->count())->toBe(1) + ->and($calls)->toBe([['global']]) + ->and($failures)->toBe(['read: cache down', 'invalidate scope: cache down', 'invalidate all: cache down']); +}); + +it('reports a failed write of fresh bags and still answers them', function (): void { + $calls = []; + $failures = []; + $store = new Repository(new class extends ArrayStore + { + public function putMany(array $values, $seconds): bool + { + throw new RuntimeException('full'); + } + }); + $cache = new SettingsCache($store, onFailure: static function (string $operation) use (&$failures): void { + $failures[] = $operation; + }); + + expect($cache->load(cacheTarget(), [Scope::global()], countingLoader($calls))->count())->toBe(1) + ->and($failures)->toBe(['write']); + + // Silent without a reporter. + expect(new SettingsCache(brokenCache())->load(cacheTarget(), [Scope::global()], countingLoader($calls))->count())->toBe(1); +}); + +it('lets the first of two concurrent readers create a missing token', function (): void { + $store = new Repository(new class extends ArrayStore + { + /** Another reader created every token a moment earlier. */ + public function add(string $key, mixed $value, int $seconds): bool + { + $this->put($key, 'WINNER', $seconds); + + return false; + } + }); + $epoch = new SettingsCache($store); + $calls = []; + $epoch->load(cacheTarget(), [Scope::global()], countingLoader($calls)); + + expect($store->get('laranail-settings:epoch'))->not->toBeNull(); +}); + +it('refuses an empty prefix, a ttl under a second and a negative stale window', function (array $arguments): void { + expect(fn (): SettingsCache => new SettingsCache(new Repository(new ArrayStore), ...$arguments))->toThrow(InvalidConfiguration::class, 'laranail.settings.cache'); +})->with([ + 'empty prefix' => [['prefix' => '']], + 'zero ttl' => [['ttl' => 0]], + 'negative stale' => [['stale' => -1]], +]); + +it('refuses a cache store that does not exist or is misnamed', function (mixed $store): void { + config()->set('laranail.settings.cache.store', $store); + app()->forgetScopedInstances(); + + expect(fn () => app(SettingsCache::class))->toThrow(InvalidConfiguration::class, 'laranail.settings.cache.store'); +})->with([ + 'unknown' => ['nowhere'], + 'empty' => [''], + 'number' => [5], +]); + +it('builds on the configured store, prefix and windows', function (): void { + config()->set('laranail.settings.cache', ['enabled' => true, 'store' => 'array', 'prefix' => 'acme-settings', 'ttl' => 60, 'stale' => 5]); + app()->forgetScopedInstances(); + $calls = []; + $cache = app(SettingsCache::class); + $cache->load(cacheTarget(), [Scope::global()], countingLoader($calls)); + + expect($cache->bagKey(cacheTarget(), Scope::global()))->toStartWith('acme-settings:'); +}); + +it('refuses a cache store that is not a Laravel cache repository', function (): void { + app()->instance(CacheFactory::class, new class implements CacheFactory + { + public function store($name = null): CacheContract + { + return Mockery::mock(CacheContract::class); + } + }); + app()->forgetScopedInstances(); + + expect(fn () => app(SettingsCache::class))->toThrow(InvalidConfiguration::class, 'is not a Laravel cache repository'); +}); + +it('reports a failing cache to the operational log', function (): void { + $logger = new class extends AbstractLogger + { + /** @var list}> */ + public array $records = []; + + public function log($level, Stringable|string $message, array $context = []): void + { + $this->records[] = [(string) $level, (string) $message, $context]; + } + }; + config()->set('cache.stores.broken', ['driver' => 'broken']); + config()->set('laranail.settings.cache.store', 'broken'); + Cache::extend('broken', static fn (): Repository => brokenCache()); + app()->forgetScopedInstances(); + settings()->configuration()->logTo($logger); + $calls = []; + + app(SettingsCache::class)->load(cacheTarget(), [Scope::global()], countingLoader($calls)); + $failure = array_values(array_filter($logger->records, static fn (array $record): bool => str_contains($record[1], 'settings cache failed'))); + + expect($calls)->toBe([['global']]) + ->and($failure)->toHaveCount(1) + ->and($failure[0][0])->toBe('warning') + ->and($failure[0][1])->toContain('(read): cache down') + ->and($failure[0][2])->toBe(['operation' => 'read', 'exception' => RuntimeException::class]); +}); diff --git a/tests/Unit/BagCodecTest.php b/tests/Unit/BagCodecTest.php new file mode 100644 index 0000000..39b64cc --- /dev/null +++ b/tests/Unit/BagCodecTest.php @@ -0,0 +1,66 @@ +decode($codec->encode(new RecordSet([$record, $plain]))); + + expect($decoded)->toBeInstanceOf(RecordSet::class) + ->and($decoded?->all())->toEqual([$record, $plain]) + ->and($codec->encode(new RecordSet))->toBe(['v' => BagCodec::VERSION, 'r' => []]) + ->and($codec->decode($codec->encode(new RecordSet))?->count())->toBe(0); +}); + +it('reads anything it did not write as no entry, never as an empty bag', function (mixed $entry): void { + expect((new BagCodec)->decode($entry))->toBeNull(); +})->with([ + 'null' => [null], + 'a string' => ['bag'], + 'no version' => [['r' => []]], + 'another version' => [['v' => 2, 'r' => []]], + 'no records' => [['v' => 1]], + 'a scalar row' => [['v' => 1, 'r' => ['row']]], + 'a bad scope' => [['v' => 1, 'r' => [['s' => 'Not A Scope', 'k' => 'a', 'l' => '', 'p' => null, 't' => null, 'e' => false, 'x' => false, 'n' => 1, 'w' => null, 'g' => null, 'c' => null, 'u' => false]]]], + 'a bad key' => [['v' => 1, 'r' => [['s' => 'global', 'k' => '', 'l' => '', 'p' => null, 't' => null, 'e' => false, 'x' => false, 'n' => 1, 'w' => null, 'g' => null, 'c' => null, 'u' => false]]]], + 'a string version' => [['v' => 1, 'r' => [['s' => 'global', 'k' => 'a', 'l' => '', 'p' => null, 't' => null, 'e' => false, 'x' => false, 'n' => '1', 'w' => null, 'g' => null, 'c' => null, 'u' => false]]]], + 'a numeric payload' => [['v' => 1, 'r' => [['s' => 'global', 'k' => 'a', 'l' => '', 'p' => 1, 't' => null, 'e' => false, 'x' => false, 'n' => 1, 'w' => null, 'g' => null, 'c' => null, 'u' => false]]]], + 'a numeric date' => [['v' => 1, 'r' => [['s' => 'global', 'k' => 'a', 'l' => '', 'p' => null, 't' => null, 'e' => false, 'x' => false, 'n' => 1, 'w' => 5, 'g' => null, 'c' => null, 'u' => false]]]], + 'a bad date' => [['v' => 1, 'r' => [['s' => 'global', 'k' => 'a', 'l' => '', 'p' => null, 't' => null, 'e' => false, 'x' => false, 'n' => 1, 'w' => 'not a date', 'g' => null, 'c' => null, 'u' => false]]]], + 'a missing type' => [['v' => 1, 'r' => [['s' => 'global', 'k' => 'a', 'l' => '', 'p' => null, 'e' => false, 'x' => false, 'n' => 1, 'w' => null, 'g' => null, 'c' => null, 'u' => false]]]], + 'a numeric group' => [['v' => 1, 'r' => [['s' => 'global', 'k' => 'a', 'l' => '', 'p' => null, 't' => null, 'e' => false, 'x' => false, 'n' => 1, 'w' => null, 'g' => 1, 'c' => null, 'u' => false]]]], + 'a string flag' => [['v' => 1, 'r' => [['s' => 'global', 'k' => 'a', 'l' => '', 'p' => null, 't' => null, 'e' => 'yes', 'x' => false, 'n' => 1, 'w' => null, 'g' => null, 'c' => null, 'u' => false]]]], + 'a missing flag' => [['v' => 1, 'r' => [['s' => 'global', 'k' => 'a', 'l' => '', 'p' => null, 't' => null, 'e' => false, 'x' => false, 'n' => 1, 'w' => null, 'g' => null, 'c' => null]]]], + 'a numeric locale' => [['v' => 1, 'r' => [['s' => 'global', 'k' => 'a', 'l' => 1, 'p' => null, 't' => null, 'e' => false, 'x' => false, 'n' => 1, 'w' => null, 'g' => null, 'c' => null, 'u' => false]]]], +]); + +it('lists a cache target\'s parts in key order', function (): void { + expect(new CacheTarget('mysql', 'app', new StoreName('settings'), 'settings')->parts())->toBe(['mysql', 'app', 'settings', 'settings']); +}); diff --git a/tests/Unit/DocsConformanceTest.php b/tests/Unit/DocsConformanceTest.php index a8373d1..5b0ab27 100644 --- a/tests/Unit/DocsConformanceTest.php +++ b/tests/Unit/DocsConformanceTest.php @@ -6,10 +6,10 @@ uses(AssertsDocsConformance::class); -// Floor = the 21 pages shipped today (5 guides, 12 reference, 4 recipes). Raise it as pages +// Floor = the 26 pages shipped today (5 guides, 15 reference, 6 recipes). Raise it as pages // are added; a glob that suddenly matches fewer has broken rather than found a clean tree. it('conforms to the org docs standard', function (): void { - $this->assertDocsConformToStandard(dirname(__DIR__, 2), 24); + $this->assertDocsConformToStandard(dirname(__DIR__, 2), 26); expect(true)->toBeTrue(); }); From 9d2ca0270ad853d4070756d672866c6664bf4202 Mon Sep 17 00:00:00 2001 From: Imani Manyara Date: Tue, 10 Nov 2026 05:09:31 -0500 Subject: [PATCH 2/2] build: install phpbench apart from the package phpbench requires doctrine/annotations, which Packagist marks abandoned, so composer audit failed. phpbench now installs into tools/phpbench/ on the first composer bench, and the package's own dependency tree and audit stay clean. --- .gitattributes | 1 + CHANGELOG.md | 3 ++- CONTRIBUTING.md | 2 +- composer.json | 6 ++++-- phpbench.json | 2 +- tools/phpbench/.gitignore | 2 ++ tools/phpbench/composer.json | 12 ++++++++++++ 7 files changed, 23 insertions(+), 5 deletions(-) create mode 100644 tools/phpbench/.gitignore create mode 100644 tools/phpbench/composer.json diff --git a/.gitattributes b/.gitattributes index 916f761..1bb2920 100644 --- a/.gitattributes +++ b/.gitattributes @@ -15,6 +15,7 @@ /CONTRIBUTING.md export-ignore /SECURITY.md export-ignore /phpbench.json export-ignore +/tools export-ignore /phpstan.neon export-ignore /phpunit.xml export-ignore /rector.php export-ignore diff --git a/CHANGELOG.md b/CHANGELOG.md index bfed228..2cab254 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,7 +27,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `Store::isCached()`, `forgetCached()`, `forgetCachedStore()` and `warmCache()`; `Data\CacheTarget`; `Support\BagCodec`. - A phpbench benchmark of one request's reads with and without the cache (`benchmarks/`, - `phpbench.json`, `composer bench`). + `phpbench.json`, `composer bench`). phpbench installs into `tools/phpbench/`, outside the + package's dependencies. - Tenancy (`tenancy.mode`: `none`, `column`, `database`; recorded in the schema file). Column mode adds a `tenant` column to the values, categories and audit tables, leading their unique diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a41d643..cda4f15 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,7 @@ Contributions are welcome via pull requests. | `composer mutate` | Pest mutation testing of the whole package, failing below a 70 % score (slow; CI runs it weekly, not on pull requests). For your change only: `vendor/bin/pest --mutate --path=src/Changed.php,src/Other.php --exclude-group=mutation-excluded --min=70` | | `composer lint` | Pint (shared laranail config), PHPStan at level max, Rector dry run; never changes files | | `composer composer-audit` | known-vulnerable dependencies | -| `composer bench` | the phpbench read benchmark (`benchmarks/`): one request's reads uncached, cold and warm. Run it before and after a change to the read path or the cache, and quote both | +| `composer bench` | the phpbench read benchmark (`benchmarks/`): one request's reads uncached, cold and warm. Run it before and after a change to the read path or the cache, and quote both. phpbench installs into `tools/phpbench/` on first run, apart from the package, because it depends on the abandoned `doctrine/annotations` | ## Guidelines diff --git a/composer.json b/composer.json index 943dc6a..44b7d4e 100644 --- a/composer.json +++ b/composer.json @@ -48,7 +48,6 @@ "pestphp/pest": "^4.0", "pestphp/pest-plugin-arch": "^4.0", "pestphp/pest-plugin-laravel": "^4.0", - "phpbench/phpbench": "^1.4", "phpstan/phpstan": "^2.0", "rector/rector": "^2.5.8", "roave/security-advisories": "dev-latest" @@ -78,7 +77,10 @@ "test-coverage": "@test --coverage --min=90", "test-dirty": "@test --dirty --compact", "mutate": "vendor/bin/pest --mutate --everything --exclude-group=matrix --min=70", - "bench": "vendor/bin/phpbench run --report=settings", + "bench": [ + "@composer --working-dir=tools/phpbench update --no-interaction --no-progress --quiet", + "tools/phpbench/vendor/bin/phpbench run --config=phpbench.json --report=settings" + ], "lint": [ "@pint", "@phpstan", diff --git a/phpbench.json b/phpbench.json index 87ee6fd..34bf487 100644 --- a/phpbench.json +++ b/phpbench.json @@ -1,5 +1,5 @@ { - "$schema": "./vendor/phpbench/phpbench/phpbench.schema.json", + "$schema": "./tools/phpbench/vendor/phpbench/phpbench/phpbench.schema.json", "runner.bootstrap": "vendor/autoload.php", "runner.path": "benchmarks", "runner.file_pattern": "*Bench.php", diff --git a/tools/phpbench/.gitignore b/tools/phpbench/.gitignore new file mode 100644 index 0000000..4fbb073 --- /dev/null +++ b/tools/phpbench/.gitignore @@ -0,0 +1,2 @@ +/vendor/ +/composer.lock diff --git a/tools/phpbench/composer.json b/tools/phpbench/composer.json new file mode 100644 index 0000000..6f09d63 --- /dev/null +++ b/tools/phpbench/composer.json @@ -0,0 +1,12 @@ +{ + "name": "laranail/settings-phpbench", + "description": "phpbench for laranail/settings' benchmarks, installed apart from the package so its dependencies (doctrine/annotations, abandoned) never enter the package's tree or its composer audit.", + "type": "project", + "license": "MIT", + "require": { + "phpbench/phpbench": "^1.4" + }, + "config": { + "sort-packages": true + } +}