diff --git a/.github/workflows/static-analysis.yml b/.github/workflows/static-analysis.yml index fd416d3..ca01a3c 100644 --- a/.github/workflows/static-analysis.yml +++ b/.github/workflows/static-analysis.yml @@ -4,6 +4,10 @@ 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. + schedule: + - cron: '23 6 * * 1' permissions: contents: read @@ -64,28 +68,64 @@ jobs: mutation: name: Mutation testing (Pest) runs-on: ubuntu-latest - # About 2,800 mutations since phase 2; sequential runs took over 20 minutes. - timeout-minutes: 45 + # 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 }} steps: - name: Checkout uses: actions/checkout@v7 + with: + fetch-depth: 0 - name: Setup PHP uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0 with: php-version: '8.5' extensions: dom, curl, libxml, mbstring, zip, fileinfo, pdo, sqlite3, pdo_sqlite - # Pest mutation testing needs a coverage driver. - coverage: xdebug + # Pest mutation testing needs a coverage driver; PCOV is several times faster than Xdebug. + coverage: pcov - name: Install dependencies run: composer update --prefer-stable --no-interaction --no-progress + # Pest caches each mutant's result by the code and tests it depends on; restoring it means + # a re-run (a fix pushed to the same pull request) only tests what changed. + - name: Restore the mutation cache + uses: actions/cache@v6 + with: + path: /tmp/pest-mutate-cache + key: pest-mutate-${{ github.head_ref || github.ref_name }}-${{ github.sha }} + restore-keys: | + pest-mutate-${{ github.head_ref || github.ref_name }}- + pest-mutate-main- + + - name: Choose what to mutate + id: scope + env: + BASE_SHA: ${{ github.event.pull_request.base.sha }} + 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 + - name: Mutation testing (minimum score 70) # Pest's own mutator, not Infection: Infection has no Pest adapter, reads Pest's # version as PHPUnit's, writes a config PHPUnit 12 rejects, and cannot map Pest's - # generated test classes to its JUnit report. - # --parallel: each worker gets its own faked disk (Storage::fake appends the - # ParallelTesting token), so the runtime JSON files never collide. - run: vendor/bin/pest --mutate --everything --parallel --min=70 + # generated test classes to its JUnit report. The schema matrix (group `matrix`) + # covers almost every line, so it is left out, and group `shared-app` writes into the + # testbench application every process shares; the Tests workflow runs both. + if: github.event_name != 'pull_request' || steps.scope.outputs.paths != '' + env: + MUTATE_PATHS: ${{ steps.scope.outputs.paths }} + run: | + if [ -n "$MUTATE_PATHS" ]; then + vendor/bin/pest --mutate --path="$MUTATE_PATHS" --parallel --processes=8 --exclude-group=matrix,shared-app --ignore-min-score-on-zero-mutations --min=70 + else + vendor/bin/pest --mutate --everything --parallel --processes=8 --exclude-group=matrix,shared-app --min=70 + fi diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 575c5c1..646d703 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -78,3 +78,30 @@ jobs: - name: Run the database group run: vendor/bin/pest --group=database + + # §13: the full product of the schema switches (576 shapes) on SQLite, weekly and on demand. + # Pull requests run the pairwise set (10 shapes) inside the jobs above. + matrix-full: + name: Schema switches · full product + if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' + runs-on: ubuntu-latest + timeout-minutes: 20 + env: + LARANAIL_SETTINGS_MATRIX: full + COMPOSER_AUTH: '{"github-oauth": {"github.com": "${{ secrets.GITHUB_TOKEN }}"}}' + steps: + - uses: actions/checkout@v7 + + - name: Setup PHP 8.4 + uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0 + with: + php-version: '8.4' + extensions: dom, curl, libxml, mbstring, zip, fileinfo, pdo, sqlite3, pdo_sqlite + coverage: none + tools: composer:v2 + + - name: Install dependencies + run: composer update --prefer-dist --no-interaction --no-progress + + - name: Run the full switch matrix + run: vendor/bin/pest --group=matrix diff --git a/2026_11_09_165225_create_settings_user_settings_table.php b/2026_11_09_165225_create_settings_user_settings_table.php deleted file mode 100644 index 8dc3132..0000000 --- a/2026_11_09_165225_create_settings_user_settings_table.php +++ /dev/null @@ -1,111 +0,0 @@ -pinnedConnection !== null) { - return $this->pinnedConnection; - } - - foreach ((array) config("laranail.settings.stores.{$this->store}.layers", []) as $layer) { - if (is_string($layer) && config("laranail.settings.layers.{$layer}.driver") === 'database') { - $connection = config("laranail.settings.layers.{$layer}.connection"); - - return is_string($connection) ? $connection : null; - } - } - - return null; - } - - public function up(): void - { - $name = $this->table(); - $categories = $this->categories(); - $index = substr($name, 0, 40); - $binary = match (Schema::getConnection()->getDriverName()) { - 'mysql', 'mariadb' => 'utf8mb4_bin', - 'pgsql' => 'C', - default => null, - }; - - Schema::create($name, static function (Blueprint $table) use ($binary, $categories, $index): void { - $collate = static function (Illuminate\Database\Schema\ColumnDefinition $column) use ($binary): Illuminate\Database\Schema\ColumnDefinition { - return $binary === null ? $column : $column->collation($binary); - }; - - $table->bigIncrements('id'); - $table->string('settable_type', 64)->nullable(); - $table->string('settable_id', 36)->nullable(); - $collate($table->string('scope', 128)); - $table->unsignedBigInteger('category_id')->nullable(); - $table->string('category_store', 64)->nullable(); - $table->string('group', 64); - $collate($table->string('key', 191)); - $collate($table->string('slug', 191)->nullable()); - $table->char('uid', 26)->nullable(); - $collate($table->string('locale', 16)->default('')); - $table->longText('value')->nullable(); - $table->string('type', 64)->nullable(); - $table->text('label')->nullable(); - $table->text('description')->nullable(); - $table->boolean('is_encrypted')->default(false); - $table->boolean('is_locked')->default(false); - $table->boolean('is_public')->default(false); - $table->boolean('autoload')->default(true); - $table->unsignedInteger('sort_order')->default(0); - $table->json('meta')->nullable(); - $table->unsignedInteger('version')->default(1); - $table->timestamps(); - - $table->unique(['scope', 'key', 'locale'], $index . '_identity_unique'); - $table->unique('uid', $index . '_uid_unique'); - $table->index('slug', $index . '_slug_index'); - $table->index(['settable_type', 'settable_id'], $index . '_settable_index'); - $table->index('category_id', $index . '_category_index'); - $table->index(['autoload', 'scope'], $index . '_autoload_index'); - $table->foreign(['category_id', 'category_store'], $index . '_category_foreign') - ->references(['id', 'store'])->on($categories)->nullOnDelete(); - }); - } - - public function down(): void - { - Schema::dropIfExists($this->table()); - } - - private function table(): string - { - $table = config("laranail.settings.stores.{$this->store}.table"); - - return config('laranail.settings.tables.prefix', '') . (is_string($table) ? $table : $this->store); - } - - private function categories(): string - { - $table = config('laranail.settings.tables.categories', 'settings_categories'); - - return config('laranail.settings.tables.prefix', '') . (is_string($table) ? $table : 'settings_categories'); - } -}; diff --git a/CHANGELOG.md b/CHANGELOG.md index cae9bff..e3879db 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Schema switches (design phase 2b, §4.0): `identity.mode` (`slug_uid`, `slug_per_row`, + `uid_only`), `ids.type` (`bigint`, `uuid`, `ulid`; follows `laranail.db-tools.id_type` unless + set) with matching category keys, `ids.owner_key` (`string`, `typed`), `stores..mode` + (`polymorphic`, `dedicated` with an `owner_id` foreign key, `owner.*` and a polymorphic + `fallback` store for global values), `stores..soft_deletes` (forget trashes; the next + write restores through the version check, never as a conflict) and `categories.soft_deletes`, + `translations.mode` (`lang`, `json`; `NewCategory` `translations`, `Category::$titles` and + `titleIn()`), and `tables.definitions`. New enums `IdentityMode`, `IdType`, `OwnerKeyType`, + `StoreMode`, `TranslationsMode`. +- The schema-shape file (`database/settings-schema.php`, `schema.path`): `install` records the + shape its migrations produce and `make-store` adds its store; the migrations and the runtime + read the record, not live configuration (`SchemaShape`, `StoreSchema`, + `SchemaShapeRepository`). +- `doctor` drift detection: configuration against the schema file, the file's shape version + against this release, unrecorded database stores, and the live tables against the recorded + shape (missing or unexpected columns, wrong `id` type). `doctor --fix` syncs definitions. +- The optional `settings_definitions` table (D-6, `definitions.table`) with its migration, + `laranail::settings.sync-definitions` (code and config definitions as `is_system` rows; stale + ones removed; runtime rows never touched; gated by `manage_definitions`, audited), and the + `database` definition source for keys no code covers, with rules filtered through + `definitions.allowed_rules`. `definitions.sources` selects `code`, `config` and `database`. +- `$settings->audit()`: an immutable audit query (`for()`, `global()`, `store()`, `key()`, + `action()`, `outcome()`, `since()`, `until()`, then `get()`, `cursor()` or `paginate()` returning + an `AuditPage`), gated by `view_audit`; `Actions\QueryAudit`, `Data\AuditFilter`. +- A plain `set()` retries once after a concurrent change, re-reading the row under a row lock + (`writes.retry_on_conflict`, default on; logged). `SettingWrite::$expectedVersion` makes a + write conditional on a version and is never retried (`SettingWriter::setExpecting()`). +- The `prune` ability (and audit action): `Actions\PruneOrphans` and `Actions\PruneAudit` need it + when called with an actor, and both prunes are audited. +- `readiness.flush_on`: schema readiness is forgotten on tenancy events (stancl/tenancy and + spatie/laravel-multitenancy by default), since db-tools has no tenant hook of its own. +- The §13 switch matrix: a pairwise set of 10 shapes covering all 141 value pairs (both + asserted) on SQLite, MySQL and PostgreSQL, and the full 576-shape product weekly + (`LARANAIL_SETTINGS_MATRIX=full`, CI job `matrix-full`). + +### Changed + +- The migration stubs read the recorded schema shape (or configuration, when nothing is + recorded) instead of individual config keys, and run on the store's recorded connection. +- `laranail::settings.install` publishes a fourth migration (`create_settings_definitions_table`, + a no-op while the table is off), records the schema file and syncs definitions. +- `laranail::settings.prune-audit` now writes an audit entry for the prune itself. +- The `Settings` contract gains `audit()`. A third-party implementation of the contract must add + it (pre-1.0; `SettingsManager` and the fake implement it). + - The database layer (design phase 2, default schema): the `database` driver (`DriverType::Database`) over the query builder, with version-checked writes that raise `ConcurrentModification`, inserts in a savepoint, and database errors surfaced as diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6596ef2..4bdcc64 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ 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, failing below a 70 % score | +| `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 lint` | Pint (shared laranail config), PHPStan at level max, Rector dry run; never changes files | | `composer composer-audit` | known-vulnerable dependencies | diff --git a/README.md b/README.md index bcb6b12..da2809e 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,8 @@ The hosted docs live at pinnedConnection !== null) { - return $this->pinnedConnection; - } - - foreach ((array) config("laranail.settings.stores.{$this->store}.layers", []) as $layer) { - if (is_string($layer) && config("laranail.settings.layers.{$layer}.driver") === 'database') { - $connection = config("laranail.settings.layers.{$layer}.connection"); - - return is_string($connection) ? $connection : null; - } - } - - return null; - } - - public function up(): void - { - $name = $this->table(); - $categories = $this->categories(); - $index = substr($name, 0, 40); - $binary = match (Schema::getConnection()->getDriverName()) { - 'mysql', 'mariadb' => 'utf8mb4_bin', - 'pgsql' => 'C', - default => null, - }; - - Schema::create($name, static function (Blueprint $table) use ($binary, $categories, $index): void { - $collate = static function (Illuminate\Database\Schema\ColumnDefinition $column) use ($binary): Illuminate\Database\Schema\ColumnDefinition { - return $binary === null ? $column : $column->collation($binary); - }; - - $table->bigIncrements('id'); - $table->string('settable_type', 64)->nullable(); - $table->string('settable_id', 36)->nullable(); - $collate($table->string('scope', 128)); - $table->unsignedBigInteger('category_id')->nullable(); - $table->string('category_store', 64)->nullable(); - $table->string('group', 64); - $collate($table->string('key', 191)); - $collate($table->string('slug', 191)->nullable()); - $table->char('uid', 26)->nullable(); - $collate($table->string('locale', 16)->default('')); - $table->longText('value')->nullable(); - $table->string('type', 64)->nullable(); - $table->text('label')->nullable(); - $table->text('description')->nullable(); - $table->boolean('is_encrypted')->default(false); - $table->boolean('is_locked')->default(false); - $table->boolean('is_public')->default(false); - $table->boolean('autoload')->default(true); - $table->unsignedInteger('sort_order')->default(0); - $table->json('meta')->nullable(); - $table->unsignedInteger('version')->default(1); - $table->timestamps(); - - $table->unique(['scope', 'key', 'locale'], $index . '_identity_unique'); - $table->unique('uid', $index . '_uid_unique'); - $table->index('slug', $index . '_slug_index'); - $table->index(['settable_type', 'settable_id'], $index . '_settable_index'); - $table->index('category_id', $index . '_category_index'); - $table->index(['autoload', 'scope'], $index . '_autoload_index'); - $table->foreign(['category_id', 'category_store'], $index . '_category_foreign') - ->references(['id', 'store'])->on($categories)->nullOnDelete(); - }); - } - - public function down(): void - { - Schema::dropIfExists($this->table()); - } - - private function table(): string - { - $table = config("laranail.settings.stores.{$this->store}.table"); - - return config('laranail.settings.tables.prefix', '') . (is_string($table) ? $table : $this->store); - } - - private function categories(): string - { - $table = config('laranail.settings.tables.categories', 'settings_categories'); - - return config('laranail.settings.tables.prefix', '') . (is_string($table) ? $table : 'settings_categories'); - } -}; diff --git a/composer.json b/composer.json index 367d79a..67fae89 100644 --- a/composer.json +++ b/composer.json @@ -71,7 +71,7 @@ "test": "vendor/bin/pest --colors=always", "test-coverage": "@test --coverage --min=90", "test-dirty": "@test --dirty --compact", - "mutate": "vendor/bin/pest --mutate --everything --min=70", + "mutate": "vendor/bin/pest --mutate --everything --exclude-group=matrix --min=70", "lint": [ "@pint", "@phpstan", diff --git a/config/settings.php b/config/settings.php index 868df98..b6a094a 100644 --- a/config/settings.php +++ b/config/settings.php @@ -37,15 +37,32 @@ | name). `bootstrap` lets the database layer be skipped while, and only | while, the application is being installed (see `bootstrap` below); | otherwise an unreachable database raises DriverUnavailable. + | + | Schema switches per store (migration-time, recorded in the schema file): + | `mode` is `polymorphic` (settable_type/settable_id, any listed alias, plus + | global rows) or `dedicated` (one owner alias, a non-null `owner_id` foreign + | key to `owner.table`, owner rows only; its global values come from + | `fallback`, default the default store). `soft_deletes` keeps forgotten rows + | as trashed and restores them on the next write. + | + | 'user_settings' => [ + | 'layers' => ['database'], + | 'owners' => ['user'], + | 'mode' => 'dedicated', + | 'owner' => ['table' => 'users', 'key' => 'id', 'type' => null], + | 'soft_deletes' => false, + | ], */ 'stores' => [ 'settings' => [ - 'layers' => ['database', 'runtime', 'shipped'], - 'owners' => [], - 'strict' => false, - 'inherits' => false, - 'locks' => ['overridable' => false], - 'bootstrap' => false, + 'layers' => ['database', 'runtime', 'shipped'], + 'owners' => [], + 'strict' => false, + 'inherits' => false, + 'locks' => ['overridable' => false], + 'bootstrap' => false, + 'mode' => 'polymorphic', + 'soft_deletes' => false, ], ], @@ -63,9 +80,77 @@ | name that is not this package's. */ 'tables' => [ - 'prefix' => env('LARANAIL_SETTINGS_TABLE_PREFIX', ''), - 'categories' => 'settings_categories', - 'audit' => 'settings_audit', + 'prefix' => env('LARANAIL_SETTINGS_TABLE_PREFIX', ''), + 'categories' => 'settings_categories', + 'audit' => 'settings_audit', + 'definitions' => 'settings_definitions', + ], + + /* + |-------------------------------------------------------------------------- + | Schema switches (migration-time) + |-------------------------------------------------------------------------- + | + | Read by `install` and `make-store`, which record the shape they produce + | in the schema file (`schema.path`, default database/settings-schema.php). + | The package then reads that file, not these keys, so changing a switch + | after migrating changes nothing until a migration says so; `doctor` + | reports the drift. The defaults are the recommended shape. + | + | identity.mode: `slug_uid` (a slug shared by a key's rows and a ULID per + | row), `slug_per_row` (a unique sha1 slug per row, no uid) or `uid_only`. + | ids.type: `bigint`, `uuid` or `ulid`; null follows laranail.db-tools.id_type. + | ids.owner_key: `string` (settable_id as string(36)) or `typed` (typed like + | laranail.db-tools.id_type, for owners that share one key type). + | translations.mode: `lang` (titles, labels and descriptions as text) or + | `json` (per-locale JSON maps). + | categories.soft_deletes: categories are trashed, and restored when the slug + | is created again. + */ + 'schema' => [ + 'path' => env('LARANAIL_SETTINGS_SCHEMA_PATH'), + ], + + 'identity' => [ + 'mode' => 'slug_uid', + ], + + 'ids' => [ + 'type' => null, + 'owner_key' => 'string', + ], + + 'translations' => [ + 'mode' => 'lang', + ], + + 'categories' => [ + 'soft_deletes' => false, + ], + + /* + | Writes. `retry_on_conflict` retries a plain set() once when another writer + | changed the row between the read and the write (re-reading it under a row + | lock where the database supports one). A write that names the version it + | expects is never retried. + */ + 'writes' => [ + 'retry_on_conflict' => true, + ], + + /* + | Events after which the schema readiness memo is forgotten, besides + | migrations, queued jobs and Octane requests: tenant switches. db-tools has + | no tenant hook of its own, so the tenancy packages' events are listened to + | by name (no dependency is added; an event that never fires costs nothing). + */ + 'readiness' => [ + 'flush_on' => [ + 'Stancl\\Tenancy\\Events\\TenancyInitialized', + 'Stancl\\Tenancy\\Events\\TenancyEnded', + 'Spatie\\Multitenancy\\Events\\MadeTenantCurrentEvent', + 'Spatie\\Multitenancy\\Events\\ForgotCurrentTenantEvent', + ], ], /* @@ -95,8 +180,18 @@ | public, locked, localised, inherits, overridable_by, precedence, | label, description, category, group, store. Definitions can also be | registered in code through DefinitionRegistry::define(). + | + | Three names are options, not keys (D-6): `table` creates the optional + | settings_definitions table (migration-time), `sources` lists where + | definitions come from, merged in order, later wins per field (`code`, + | `config`, `database`; `database` is read only when the table exists), + | and `allowed_rules` filters the rules of database definitions. */ - 'definitions' => [], + 'definitions' => [ + 'table' => false, + 'sources' => ['code', 'config', 'database'], + 'allowed_rules' => ['required', 'nullable', 'string', 'integer', 'numeric', 'boolean', 'array', 'email', 'url', 'in', 'not_in', 'min', 'max', 'between', 'size', 'regex', 'date', 'alpha', 'alpha_dash', 'alpha_num'], + ], /* |-------------------------------------------------------------------------- @@ -149,6 +244,7 @@ 'manage_categories' => 'settings.manage_categories', 'manage_definitions' => 'settings.manage_definitions', 'manage_stores' => 'settings.manage_stores', + 'prune' => 'settings.prune', ], ], diff --git a/database/migrations/create_settings_audit_table.php.stub b/database/migrations/create_settings_audit_table.php.stub index b644f80..d00d500 100644 --- a/database/migrations/create_settings_audit_table.php.stub +++ b/database/migrations/create_settings_audit_table.php.stub @@ -5,12 +5,15 @@ declare(strict_types=1); use Illuminate\Support\Facades\Schema; use Illuminate\Database\Schema\Blueprint; use Illuminate\Database\Migrations\Migration; +use Simtabi\Laranail\Settings\Data\StoreName; +use Simtabi\Laranail\Settings\Database\SchemaShapeRepository; /* * laranail/settings: the audit trail (design §16.8). It records actions and denials, who, when, * through which channel and which versions, and has no value column: an audit trail must never * become a second copy of the secrets it watches. * + * Table name and connection come from the recorded schema file (or configuration). * Runs on the connection of the default store's database layer. `laranail::settings.make-store` * pins another connection by rewriting the $pinnedConnection line below. */ @@ -24,24 +27,16 @@ return new class extends Migration return $this->pinnedConnection; } - $store = config('laranail.settings.default', 'settings'); + $default = config('laranail.settings.default', 'settings'); - foreach ((array) config("laranail.settings.stores.{$store}.layers", []) as $layer) { - if (is_string($layer) && config("laranail.settings.layers.{$layer}.driver") === 'database') { - $connection = config("laranail.settings.layers.{$layer}.connection"); - - return is_string($connection) ? $connection : null; - } - } - - return null; + return $this->shape()->store(new StoreName(is_string($default) ? $default : 'settings'))->connection; } public function up(): void { $name = $this->table(); - Schema::create($name, static function (Blueprint $table) use ($name): void { + Schema::connection($this->getConnection())->create($name, static function (Blueprint $table) use ($name): void { $table->char('id', 26)->primary(); $table->timestamp('occurred_at'); $table->string('action', 32); @@ -71,13 +66,16 @@ return new class extends Migration public function down(): void { - Schema::dropIfExists($this->table()); + Schema::connection($this->getConnection())->dropIfExists($this->table()); } private function table(): string { - $table = config('laranail.settings.tables.audit', 'settings_audit'); + return $this->shape()->names->audit(); + } - return config('laranail.settings.tables.prefix', '') . (is_string($table) ? $table : 'settings_audit'); + private function shape(): Simtabi\Laranail\Settings\Database\SchemaShape + { + return app(SchemaShapeRepository::class)->current(); } }; diff --git a/database/migrations/create_settings_categories_table.php.stub b/database/migrations/create_settings_categories_table.php.stub index 30a55ab..cbadaa5 100644 --- a/database/migrations/create_settings_categories_table.php.stub +++ b/database/migrations/create_settings_categories_table.php.stub @@ -5,12 +5,19 @@ declare(strict_types=1); use Illuminate\Support\Facades\Schema; use Illuminate\Database\Schema\Blueprint; use Illuminate\Database\Migrations\Migration; +use Simtabi\Laranail\Settings\Enums\IdType; +use Simtabi\Laranail\Settings\Data\StoreName; +use Simtabi\Laranail\Settings\Enums\TranslationsMode; +use Simtabi\Laranail\Settings\Database\SchemaShapeRepository; /* * laranail/settings: categories (nested by parent_id), shared by every store on this connection. * `store` is the logical store name; `unique(id, store)` lets a store's values table point at a * category of its own store only, through a composite foreign key. * + * The shape comes from the recorded schema file (or configuration): the key type (D-5), JSON + * titles (D-8) and soft deletes (D-9, `categories.soft_deletes`). + * * Runs on the connection of the default store's database layer. `laranail::settings.make-store` * pins another connection by rewriting the $pinnedConnection line below. */ @@ -24,36 +31,62 @@ return new class extends Migration return $this->pinnedConnection; } - $store = config('laranail.settings.default', 'settings'); - - foreach ((array) config("laranail.settings.stores.{$store}.layers", []) as $layer) { - if (is_string($layer) && config("laranail.settings.layers.{$layer}.driver") === 'database') { - $connection = config("laranail.settings.layers.{$layer}.connection"); - - return is_string($connection) ? $connection : null; - } - } + $default = config('laranail.settings.default', 'settings'); - return null; + return $this->shape()->store(new StoreName(is_string($default) ? $default : 'settings'))->connection; } public function up(): void { - $name = $this->table(); + $shape = $this->shape(); + $name = $shape->names->categories(); + + Schema::connection($this->getConnection())->create($name, static function (Blueprint $table) use ($name, $shape): void { + match ($shape->ids) { + IdType::Bigint => $table->bigIncrements('id'), + IdType::Uuid => $table->char('id', 36), + IdType::Ulid => $table->char('id', 26), + }; + + // An explicit command, not the fluent ->primary(): Laravel appends fluent indexes after + // every other command, so PostgreSQL would see the parent_id foreign key below before + // the key it references and refuse it (SQLSTATE 42830). + if ($shape->ids !== IdType::Bigint) { + $table->primary('id'); + } - Schema::create($name, static function (Blueprint $table) use ($name): void { - $table->bigIncrements('id'); $table->string('store', 64); - $table->unsignedBigInteger('parent_id')->nullable(); - $table->string('title'); + + match ($shape->ids) { + IdType::Bigint => $table->unsignedBigInteger('parent_id')->nullable(), + IdType::Uuid => $table->char('parent_id', 36)->nullable(), + IdType::Ulid => $table->char('parent_id', 26)->nullable(), + }; + + if ($shape->translations === TranslationsMode::Json) { + $table->json('title'); + } else { + $table->string('title'); + } + $table->string('slug', 128); - $table->text('description')->nullable(); + + if ($shape->translations === TranslationsMode::Json) { + $table->json('description')->nullable(); + } else { + $table->text('description')->nullable(); + } + $table->string('icon')->nullable(); $table->unsignedInteger('sort_order')->default(0); $table->boolean('is_system')->default(false); $table->json('meta')->nullable(); $table->timestamps(); + if ($shape->categoriesSoftDeletes) { + $table->timestamp('deleted_at')->nullable(); + } + $table->unique(['store', 'slug'], $name . '_store_slug_unique'); $table->unique(['id', 'store'], $name . '_id_store_unique'); $table->index('parent_id', $name . '_parent_index'); @@ -63,13 +96,11 @@ return new class extends Migration public function down(): void { - Schema::dropIfExists($this->table()); + Schema::connection($this->getConnection())->dropIfExists($this->shape()->names->categories()); } - private function table(): string + private function shape(): Simtabi\Laranail\Settings\Database\SchemaShape { - $table = config('laranail.settings.tables.categories', 'settings_categories'); - - return config('laranail.settings.tables.prefix', '') . (is_string($table) ? $table : 'settings_categories'); + return app(SchemaShapeRepository::class)->current(); } }; diff --git a/database/migrations/create_settings_definitions_table.php.stub b/database/migrations/create_settings_definitions_table.php.stub new file mode 100644 index 0000000..d76e13c --- /dev/null +++ b/database/migrations/create_settings_definitions_table.php.stub @@ -0,0 +1,103 @@ +pinnedConnection !== null) { + return $this->pinnedConnection; + } + + $default = config('laranail.settings.default', 'settings'); + + return $this->shape()->store(new StoreName(is_string($default) ? $default : 'settings'))->connection; + } + + public function up(): void + { + $shape = $this->shape(); + + if (! $shape->definitionsTable) { + return; + } + + $name = $shape->names->definitions(); + $categories = $shape->names->categories(); + + Schema::connection($this->getConnection())->create($name, static function (Blueprint $table) use ($categories, $name, $shape): void { + match ($shape->ids) { + IdType::Bigint => $table->bigIncrements('id'), + IdType::Uuid => $table->char('id', 36)->primary(), + IdType::Ulid => $table->char('id', 26)->primary(), + }; + + $table->string('store', 64); + $table->string('slug', 191); + $table->string('key', 191); + $table->string('group', 64); + + match ($shape->ids) { + IdType::Bigint => $table->unsignedBigInteger('category_id')->nullable(), + IdType::Uuid => $table->char('category_id', 36)->nullable(), + IdType::Ulid => $table->char('category_id', 26)->nullable(), + }; + + $table->string('type', 64)->nullable(); + $table->longText('default')->nullable(); + + if ($shape->translations === TranslationsMode::Json) { + $table->json('label')->nullable(); + $table->json('description')->nullable(); + } else { + $table->text('label')->nullable(); + $table->text('description')->nullable(); + } + + $table->json('rules')->nullable(); + $table->boolean('is_encrypted')->default(false); + $table->boolean('is_public')->default(false); + $table->boolean('is_locked')->default(false); + $table->boolean('autoload')->default(true); + $table->boolean('inherits')->nullable(); + $table->json('overridable_by')->nullable(); + $table->boolean('is_system')->default(false); + $table->json('meta')->nullable(); + $table->timestamps(); + + $table->unique(['store', 'key'], $name . '_store_key_unique'); + $table->unique(['store', 'slug'], $name . '_store_slug_unique'); + $table->index('category_id', $name . '_category_index'); + $table->foreign('category_id', $name . '_category_foreign')->references('id')->on($categories)->nullOnDelete(); + }); + } + + public function down(): void + { + Schema::connection($this->getConnection())->dropIfExists($this->shape()->names->definitions()); + } + + private function shape(): Simtabi\Laranail\Settings\Database\SchemaShape + { + return app(SchemaShapeRepository::class)->current(); + } +}; diff --git a/database/migrations/create_settings_table.php.stub b/database/migrations/create_settings_table.php.stub index 1d547d2..635d01b 100644 --- a/database/migrations/create_settings_table.php.stub +++ b/database/migrations/create_settings_table.php.stub @@ -5,13 +5,24 @@ declare(strict_types=1); use Illuminate\Support\Facades\Schema; use Illuminate\Database\Schema\Blueprint; use Illuminate\Database\Migrations\Migration; +use Illuminate\Database\Schema\ColumnDefinition; +use Simtabi\Laranail\Settings\Enums\IdType; +use Simtabi\Laranail\Settings\Data\StoreName; +use Simtabi\Laranail\Settings\Enums\IdentityMode; +use Simtabi\Laranail\Settings\Enums\OwnerKeyType; +use Simtabi\Laranail\Settings\Enums\TranslationsMode; +use Simtabi\Laranail\Settings\Database\SchemaShapeRepository; /* - * laranail/settings: the values table of one store, in the default shape: polymorphic owners, - * identity mode slug_uid, bigint ids, a string owner key. Identity is (scope, key, locale); the - * three columns are binary-collated so `Theme` and `theme` or `pt_BR` and `pt_br` cannot become - * one row on MySQL only (G-38). Column types are explicit so db-tools' blueprint macros cannot - * retype them. + * laranail/settings: the values table of one store. Identity is (scope, key, locale); the three + * columns are binary-collated so `Theme` and `theme` or `pt_BR` and `pt_br` cannot become one row + * on MySQL only (G-38). Column types are explicit so db-tools' blueprint macros cannot retype + * them. + * + * The shape comes from the recorded schema file (database/settings-schema.php, written by + * `install` and `make-store`), or from configuration when nothing is recorded: identity mode + * (D-1), key type and owner key (D-5), polymorphic or dedicated owners (D-3), soft deletes (D-9) + * and JSON labels (D-8). * * `laranail::settings.make-store` copies this file for another store by rewriting the $store * (and, with --connection, the $pinnedConnection) line below. @@ -24,52 +35,70 @@ return new class extends Migration public function getConnection(): ?string { - if ($this->pinnedConnection !== null) { - return $this->pinnedConnection; - } - - foreach ((array) config("laranail.settings.stores.{$this->store}.layers", []) as $layer) { - if (is_string($layer) && config("laranail.settings.layers.{$layer}.driver") === 'database') { - $connection = config("laranail.settings.layers.{$layer}.connection"); - - return is_string($connection) ? $connection : null; - } - } - - return null; + return $this->pinnedConnection ?? $this->shape()->store(new StoreName($this->store))->connection; } public function up(): void { - $name = $this->table(); - $categories = $this->categories(); + $shape = $this->shape(); + $store = $shape->store(new StoreName($this->store)); + $name = $shape->names->store($store->name, $store->table); + $categories = $shape->names->categories(); $index = substr($name, 0, 40); - $binary = match (Schema::getConnection()->getDriverName()) { + $binary = match (Schema::connection($this->getConnection())->getConnection()->getDriverName()) { 'mysql', 'mariadb' => 'utf8mb4_bin', 'pgsql' => 'C', default => null, }; - Schema::create($name, static function (Blueprint $table) use ($binary, $categories, $index): void { - $collate = static function (Illuminate\Database\Schema\ColumnDefinition $column) use ($binary): Illuminate\Database\Schema\ColumnDefinition { - return $binary === null ? $column : $column->collation($binary); + Schema::connection($this->getConnection())->create($name, static function (Blueprint $table) use ($binary, $categories, $index, $shape, $store): void { + $collate = static fn (ColumnDefinition $column): ColumnDefinition => $binary === null ? $column : $column->collation($binary); + $key = static fn (string $column, IdType $type): ColumnDefinition => match ($type) { + IdType::Bigint => $table->unsignedBigInteger($column), + IdType::Uuid => $table->char($column, 36), + IdType::Ulid => $table->char($column, 26), + }; + + match ($shape->ids) { + IdType::Bigint => $table->bigIncrements('id'), + default => $key('id', $shape->ids)->primary(), }; - $table->bigIncrements('id'); - $table->string('settable_type', 64)->nullable(); - $table->string('settable_id', 36)->nullable(); + if ($store->isDedicated()) { + $key('owner_id', $store->ownerKeyType); + } else { + $table->string('settable_type', 64)->nullable(); + $shape->ownerKey === OwnerKeyType::Typed + ? $key('settable_id', $shape->ownerKeyType)->nullable() + : $table->string('settable_id', 36)->nullable(); + } + $collate($table->string('scope', 128)); - $table->unsignedBigInteger('category_id')->nullable(); + $key('category_id', $shape->ids)->nullable(); $table->string('category_store', 64)->nullable(); $table->string('group', 64); $collate($table->string('key', 191)); - $collate($table->string('slug', 191)->nullable()); - $table->char('uid', 26)->nullable(); + + if ($shape->identity->hasSlug()) { + $collate($table->string('slug', $shape->identity === IdentityMode::SlugPerRow ? 40 : 191)->nullable()); + } + + if ($shape->identity->hasUid()) { + $table->char('uid', 26)->nullable(); + } + $collate($table->string('locale', 16)->default('')); $table->longText('value')->nullable(); $table->string('type', 64)->nullable(); - $table->text('label')->nullable(); - $table->text('description')->nullable(); + + if ($shape->translations === TranslationsMode::Json) { + $table->json('label')->nullable(); + $table->json('description')->nullable(); + } else { + $table->text('label')->nullable(); + $table->text('description')->nullable(); + } + $table->boolean('is_encrypted')->default(false); $table->boolean('is_locked')->default(false); $table->boolean('is_public')->default(false); @@ -79,10 +108,30 @@ return new class extends Migration $table->unsignedInteger('version')->default(1); $table->timestamps(); + if ($store->softDeletes) { + $table->timestamp('deleted_at')->nullable(); + } + $table->unique(['scope', 'key', 'locale'], $index . '_identity_unique'); - $table->unique('uid', $index . '_uid_unique'); - $table->index('slug', $index . '_slug_index'); - $table->index(['settable_type', 'settable_id'], $index . '_settable_index'); + + if ($shape->identity->hasUid()) { + $table->unique('uid', $index . '_uid_unique'); + } + + match ($shape->identity) { + IdentityMode::SlugPerRow => $table->unique('slug', $index . '_slug_unique'), + IdentityMode::SlugUid => $table->index('slug', $index . '_slug_index'), + IdentityMode::UidOnly => null, + }; + + if ($store->isDedicated()) { + $table->index('owner_id', $index . '_owner_index'); + $table->foreign('owner_id', $index . '_owner_foreign') + ->references($store->ownerKey)->on((string) $store->ownerTable)->cascadeOnDelete(); + } else { + $table->index(['settable_type', 'settable_id'], $index . '_settable_index'); + } + $table->index('category_id', $index . '_category_index'); $table->index(['autoload', 'scope'], $index . '_autoload_index'); $table->foreign(['category_id', 'category_store'], $index . '_category_foreign') @@ -92,20 +141,14 @@ return new class extends Migration public function down(): void { - Schema::dropIfExists($this->table()); - } + $shape = $this->shape(); + $store = $shape->store(new StoreName($this->store)); - private function table(): string - { - $table = config("laranail.settings.stores.{$this->store}.table"); - - return config('laranail.settings.tables.prefix', '') . (is_string($table) ? $table : $this->store); + Schema::connection($this->getConnection())->dropIfExists($shape->names->store($store->name, $store->table)); } - private function categories(): string + private function shape(): Simtabi\Laranail\Settings\Database\SchemaShape { - $table = config('laranail.settings.tables.categories', 'settings_categories'); - - return config('laranail.settings.tables.prefix', '') . (is_string($table) ? $table : 'settings_categories'); + return app(SchemaShapeRepository::class)->current(); } }; diff --git a/docs/architecture.md b/docs/architecture.md index b5fa148..6119b7f 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -65,6 +65,45 @@ The package is used from controllers, jobs, commands and other packages, and it Every write is one `final` action (`Actions\SetSetting`, …) that authorizes, writes and audits. The PHP API delegates to it today; console commands and the REST API will delegate to the same actions, so the rules cannot drift between channels. +## Why are the table shapes switches, and why are they recorded? + +The owner's standing rule is that where several styles are reasonable, all are supported through +configuration with the recommended one as the default. Identity columns, key types, owner +columns, soft deletes, JSON translations and the definitions table each have applications that +need the other value (uuid-keyed estates, a users table that should cascade, an admin UI that +edits definitions), so they are switches (see [Schema switches](tools/schema-switches.md)). + +A switch decides a column, so it is migration-time, and the package must not trust configuration +for it afterwards: flipping `soft_deletes` on after migrating would make every read filter on a +`deleted_at` column that does not exist. So `install` and `make-store` record the shape they +produce in a schema file the application commits, the runtime and the migrations read that file, +and `doctor` reports any drift between configuration, the file and the database. A later +`make-store` keeps the file's key type, so a new table's `category_id` can never disagree with the +categories key it points at. + +Every combination is a shape the suite has to keep working. A pairwise set (every pair of switch +values meets at least once, asserted along with the number of shapes) runs on every pull request +on SQLite, MySQL and PostgreSQL, and the full product weekly. + +## Why does a plain set retry once, and an expected-version write never? + +A plain `set()` means "make it this value"; losing a race to another writer between the read and +the write is not the caller's concern, so the write re-reads the row under a row lock (a plain +re-read under MySQL's REPEATABLE READ would see the old snapshot) and tries once more +(`writes.retry_on_conflict`). A write that names the version it expects (the REST API's +`If-Match`) is the caller asking to be told about the race, so it is never retried. + +## Why is schema readiness flushed on tenancy events by name? + +laranail/db-tools memoises schema readiness in a singleton, which outlives a request under Octane +and a tenant under a tenancy package: a tenant whose database is migrated would keep the previous +tenant's answer. The package forgets the memo after migrations, at the start of every queued job +and Octane request, and on each event in `readiness.flush_on`. db-tools exposes no tenant-switch +hook of its own, so the defaults name the tenancy packages' own events (stancl/tenancy's +`TenancyInitialized` / `TenancyEnded`, spatie/laravel-multitenancy's `MadeTenantCurrentEvent` / +`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 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 6375c80..fc6f3a5 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -18,19 +18,35 @@ Every key in `config/laranail/settings.php`, read at `config('laranail.settings. | `tables.prefix` | `''` (`LARANAIL_SETTINGS_TABLE_PREFIX`) | put in front of every package table, `[a-z0-9_]`, at most 32 characters | | `tables.categories` | `settings_categories` | the categories table, one per connection | | `tables.audit` | `settings_audit` | the audit table, one per connection | +| `tables.definitions` | `settings_definitions` | the optional definitions table | +| `stores..mode` | `polymorphic` | `dedicated`: one owner alias, an `owner_id` foreign key to `owner.table`, owner rows only (migration-time) | +| `stores..owner` | — | dedicated stores: `table`, `key` (`id`), `type` (`bigint`/`uuid`/`ulid`; null follows db-tools) | +| `stores..fallback` | the default store | dedicated stores: the polymorphic store that holds their global values | +| `stores..soft_deletes` | `false` | trash forgotten rows and restore them on the next write (migration-time) | +| `schema.path` | `database/settings-schema.php` (`LARANAIL_SETTINGS_SCHEMA_PATH`) | where the recorded schema shape lives | +| `identity.mode` | `slug_uid` | `slug_uid`, `slug_per_row` or `uid_only` (migration-time) | +| `ids.type` | `null` | `bigint`, `uuid` or `ulid`; null follows `laranail.db-tools.id_type` (migration-time) | +| `ids.owner_key` | `string` | `typed` types `settable_id` like the owners' keys (migration-time) | +| `translations.mode` | `lang` | `json` stores titles, labels and descriptions per locale (migration-time) | +| `categories.soft_deletes` | `false` | trash deleted categories and restore them when the slug is created again (migration-time) | +| `writes.retry_on_conflict` | `true` | retry a plain `set()` once after a concurrent change | +| `readiness.flush_on` | the stancl and spatie tenancy events | events after which schema readiness is re-checked | | `layers..driver` | — | `database`, `json`, `php`, `config`, `array`, or a custom driver | | `layers..connection` | `null` (`LARANAIL_SETTINGS_DB_CONNECTION` for `database`) | database driver: the connection; null is the default one | | `layers..writable` | `true` | set `false` for a read-only layer | | `layers..disk` | `local` (`LARANAIL_SETTINGS_RUNTIME_DISK`) | JSON driver: a private filesystem disk | | `layers..path` | — | JSON: a path on the disk containing `{store}`; PHP: a path from the application root | | `layers..prefix` | — | config driver: the config prefix to read | -| `definitions` | `[]` | `key => attributes`; see [Definitions](tools/definitions.md) | +| `definitions` | options only | `key => attributes`; see [Definitions](tools/definitions.md). `table`, `sources` and `allowed_rules` are options, not keys | +| `definitions.table` | `false` | create the optional definitions table (migration-time) | +| `definitions.sources` | `code`, `config`, `database` | where definitions come from; `database` is read only when the table exists | +| `definitions.allowed_rules` | common rule names | the rules a definitions-table row may use | | `authentication.resolver` | `guard` (`LARANAIL_SETTINGS_ACTOR_RESOLVER`) | how `asCurrentActor()` finds the actor: `guard`, `sanctum` or a class | | `authentication.guards` | `[]` | guards tried in order; empty means the default guard | | `authorization.driver` | `gate` (`LARANAIL_SETTINGS_AUTHORIZER`) | `gate`, `permissions`, a class, or a list tried in order | | `authorization.undefined` | `deny` | decides an ability nobody defined: `deny` or `allow` | | `authorization.require_actor` | `false` (`LARANAIL_SETTINGS_REQUIRE_ACTOR`) | refuse calls without an actor; `asSystem()` still works | -| `authorization.permissions` | `settings.` for each ability | permission names for the `permissions` driver; `{ability}`, `{store}`, `{key}` | +| `authorization.permissions` | `settings.` for each ability, `prune` included | permission names for the `permissions` driver; `{ability}`, `{store}`, `{key}` | | `verification.driver` | `password_confirmation` (`LARANAIL_SETTINGS_VERIFIER`) | `password_confirmation`, `actor`, `none` or a class | | `verification.abilities` | `override_lock`, `rollback`, `import`, `manage_stores` | abilities that always need step-up verification | | `verification.ttl` | `900` | seconds an actor's `verifiedAt` stays fresh for the `actor` driver | @@ -41,6 +57,8 @@ Every key in `config/laranail/settings.php`, read at `config('laranail.settings. 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 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). ## Publishing diff --git a/docs/tools/audit-and-logging.md b/docs/tools/audit-and-logging.md index 427b426..e633db6 100644 --- a/docs/tools/audit-and-logging.md +++ b/docs/tools/audit-and-logging.md @@ -57,10 +57,16 @@ both survive the refusal. The table has no value column. Every connection a store uses has its own audit table; `make-store --connection` generates it. +## Querying the trail + +`$settings->audit()->for($user)->since(now()->subWeek())->get()` reads entries back, gated by +`view_audit`; see [Audit queries](audit-queries.md). + ## Retention `laranail::settings.prune-audit` deletes rows older than `audit.keep_days` (365 by default), or -`--days`. Schedule it: +`--days`, and audits the prune itself; its action needs `prune` when called with an actor. +Schedule it: ```php Schedule::command('laranail::settings.prune-audit')->weekly(); diff --git a/docs/tools/audit-queries.md b/docs/tools/audit-queries.md new file mode 100644 index 0000000..9844701 --- /dev/null +++ b/docs/tools/audit-queries.md @@ -0,0 +1,50 @@ +# Audit queries + +`$settings->audit()` reads the audit trail from PHP: an immutable query narrowed by owner, store, key, action, outcome and time, gated by `view_audit`. + +## Querying + +```php +use Simtabi\Laranail\Settings\Enums\AuditAction; +use Simtabi\Laranail\Settings\Enums\AuditOutcome; + +$entries = $settings->as($admin)->audit() + ->for($user) // a Settable or OwnerRef: that owner's scope + ->key('mail.from_address') + ->action(AuditAction::Update) + ->outcome(AuditOutcome::Allowed) + ->since(now()->subWeek()) + ->until(now()) + ->get(); // list, newest first +``` + +`->store('billing')` narrows to one store and reads the audit table on that store's connection +(the default store's otherwise); a handle built with `store()` starts narrowed to it. `->global()` +keeps entries about global values only. `get(100)` limits the result. + +## Large trails + +```php +foreach ($settings->audit()->since($from)->cursor() as $entry) { … } // LazyCollection, streamed + +$page = $settings->audit()->paginate(50); // AuditPage +$next = $settings->audit()->paginate(50, $page->nextCursor); +``` + +An `AuditPage` holds `entries`, `perPage`, `nextCursor` and `previousCursor` (opaque strings, null +at either end) and `hasMore()`. + +## Access + +With an actor on the handle, every run needs `view_audit` (checked against the filtered store, +key and owner); a denial is itself audited. Without an actor the call is trusted, unless +`authorization.require_actor` is on. Entries never carry a value, encrypted or not, so there is +nothing to redact. + +A store without an active database layer audits to the log, which cannot be queried: +`audit()` raises `DriverUnavailable` for it. The action behind the query is +`Actions\QueryAudit`, which the REST API will share. + +--- + +[← Docs index](../../README.md#documentation) diff --git a/docs/tools/commands.md b/docs/tools/commands.md index ea685e6..fd38f28 100644 --- a/docs/tools/commands.md +++ b/docs/tools/commands.md @@ -1,15 +1,16 @@ # Commands -Seven Artisan commands, all named `laranail::settings.`. +Eight Artisan commands, all named `laranail::settings.`. ## The commands | Command | Does | |---|---| -| `laranail::settings.install` | publishes the config and the migrations; refuses to run over a foreign table of the same name | -| `laranail::settings.make-store {store} [--owner=*] [--connection=]` | writes a new store's migration and prints its configuration entry | +| `laranail::settings.install` | publishes the config and the migrations, records the schema file, syncs definitions once the table exists; refuses to run over a foreign table of the same name | +| `laranail::settings.make-store {store} [--owner=*] [--connection=]` | writes a new store's migration, records it in the schema file and prints its configuration entry | | `laranail::settings.promote [store] [--force] [--from=]` | copies values written before install from the runtime file into the database | -| `laranail::settings.doctor [--json]` | checks readiness, schema drift and rows the database cannot guard | +| `laranail::settings.doctor [--json] [--fix]` | checks readiness, schema drift against the schema file and rows the database cannot guard; `--fix` syncs definitions first | +| `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` | @@ -33,8 +34,9 @@ For every store with a database layer: | Check | Fails when | |---|---| +| schema file | the file is older than this release's shape version, or a database store has no entry (warns when there is no file, or when configuration differs from it) | | readiness | the connection does not answer or the table is missing (a warning in bootstrap mode) | -| schema | a column this release uses is missing: publish and run the latest migrations | +| schema | a column the recorded shape uses is missing, or `id` has the wrong type (warns on a column the shape does not have) | | scopes | a scope names a class instead of a morph alias (fails) or an alias the store does not list (warns) | | categories | a row points at a category of another store | @@ -47,6 +49,12 @@ 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. +## Pruning and access + +Both prune commands run as the system actor and are audited (a `prune` entry recording what was +removed). Their actions, `Actions\PruneOrphans` and `Actions\PruneAudit`, need the `prune` +ability when called with an actor; pruning orphans also needs `forget` for each owner it flushes. + --- [← Docs index](../../README.md#documentation) diff --git a/docs/tools/database.md b/docs/tools/database.md index 6c2ad66..9f705a5 100644 --- a/docs/tools/database.md +++ b/docs/tools/database.md @@ -9,12 +9,16 @@ The `database` driver keeps a store's values in a table, through the query build | `settings` (each store's own, `stores..table`) | one row per (scope, key, locale) | | `settings_categories` | categories of every store on the connection | | `settings_audit` | the audit trail of every store on the connection | +| `settings_definitions` | optional (`definitions.table`): definitions synced from code and edited at runtime | `tables.prefix` goes in front of all of them. Every connection a store uses has its own categories and audit tables, so a store's foreign keys and transactions never cross connections. The values table, in the default shape (polymorphic owners, identity mode `slug_uid`, bigint ids, -string owner key): +string owner key). Every other shape is a [schema switch](schema-switches.md): `uuid` / `ulid` +keys, `slug_per_row` or `uid_only` identity, typed owner keys, dedicated stores with an `owner_id` +foreign key, soft deletes, JSON labels, and the optional `settings_definitions` table. The +package reads the shape recorded in `database/settings-schema.php`, not live configuration. | Column | Notes | |---|---| @@ -48,9 +52,14 @@ Each store is then read once for the whole list, and reading each owner afterwar ## Writes and concurrency A write updates the row at the version it read. If no row is at that version, it inserts; a row -at another version makes the insert hit the unique index, and the write fails with -`ConcurrentModification`. Re-read and try again. The write, its events and its audit row share -one transaction on the store's connection. +at another version makes the insert hit the unique index, which is a concurrent change. A plain +`set()` then re-reads the row under a row lock and retries once (`writes.retry_on_conflict`, +on by default; the retry is logged); a second conflict, or any conflict on a write that names the +version it expects (`SettingWrite::$expectedVersion`), raises `ConcurrentModification`. The write, +its events and its audit row share one transaction on the store's connection. + +With soft deletes a write to a trashed key restores the row through the same version check; see +[Schema switches](schema-switches.md#soft-deletes). ## Failures diff --git a/docs/tools/schema-switches.md b/docs/tools/schema-switches.md new file mode 100644 index 0000000..07c63e3 --- /dev/null +++ b/docs/tools/schema-switches.md @@ -0,0 +1,128 @@ +# Schema switches + +Seven schema switches choose the shape of the package's tables at migration time; the defaults are the recommended shape, and the package then reads the recorded shape, never live configuration. + +## The switches + +| Switch | Values (default first) | Effect | +|---|---|---| +| `identity.mode` | `slug_uid`, `slug_per_row`, `uid_only` | which identity columns a values row has besides (scope, key, locale) | +| `ids.type` | `null` (follows `laranail.db-tools.id_type`), `bigint`, `uuid`, `ulid` | the key of every package table and of every foreign key to one | +| `ids.owner_key` | `string`, `typed` | `settable_id` as `string(36)`, or typed like the owners' keys | +| `stores..mode` | `polymorphic`, `dedicated` | `settable_type` / `settable_id`, or a non-null `owner_id` foreign key to one owner table | +| `stores..soft_deletes` | `false`, `true` | forgotten rows are trashed, and restored by the next write | +| `translations.mode` | `lang`, `json` | titles, labels and descriptions as text, or as per-locale JSON maps | +| `definitions.table` | `false`, `true` | creates the optional `settings_definitions` table | + +`categories.soft_deletes` (default `false`) gives categories the same trash-and-restore rule. +`tables.prefix` and the table names (`tables.categories`, `tables.audit`, `tables.definitions`, +`stores..table`) are recorded with the switches and honoured everywhere, including the +check that refuses to install over a table that is not the package's. + +## Identity modes + +| Mode | `slug` | `uid` | +|---|---|---| +| `slug_uid` | the key with `.` replaced by `-`, shared by every row of the key, indexed | a ULID per row, unique | +| `slug_per_row` | `sha1(scope|key|locale)`, unique per row | none | +| `uid_only` | none | a ULID per row, unique | + +## Keys and owner keys + +With `uuid` or `ulid` the package generates every key itself (`Str::orderedUuid()`, +`Str::ulid()`); `category_id`, `parent_id` and the definitions table's `category_id` take the same +type, so the composite foreign key from a values table to its store's categories always matches. + +`ids.owner_key = typed` types `settable_id` like `laranail.db-tools.id_type` (the key type of the +application's models). A write for an owner id of another shape (`user:abc` against bigint keys) +raises `OwnerNotAllowed`. The package itself never queries by `settable_id`: every read goes +through `scope`, so the owner key type never meets the column type (G-26). + +## Dedicated stores + +```php +'stores' => [ + 'settings' => ['layers' => ['database', 'runtime', 'shipped'], 'owners' => ['team']], + 'user_settings' => [ + 'layers' => ['database'], + 'owners' => ['user'], // exactly one alias + 'mode' => 'dedicated', + 'owner' => ['table' => 'users', 'key' => 'id', 'type' => null], // type: bigint, uuid, ulid; null follows db-tools + 'fallback' => 'settings', // default: the default store + 'inherits' => true, + ], +], +``` + +A dedicated store's `owner_id` is a foreign key to the owner table with `cascadeOnDelete`, so +deleting a user removes its settings in the database itself. It holds owner rows only: a global +write raises `OwnerNotAllowed` naming the fallback store, and the global step of the cascade, and +a read with no owner, read the fallback store. The fallback must be a configured polymorphic +store; a dedicated store without exactly one owner alias or an owner table is refused when the +store registry is built. + +## Soft deletes + +With `stores..soft_deletes`, `forget()` and `flush()` set `deleted_at`; reads, lock checks +and orphan pruning skip trashed rows. The next write to a trashed key restores that row through +the same version check as any update: the writer continues the trashed row's version, the update +clears `deleted_at` and resets `is_locked`, labels, `meta` and the category to the new write. So +the unique index never collides, a restore is never read as a conflict, and a forgotten lock +never comes back. `lock()` on a trashed key restores the row as a value-less lock. + +Under `categories.soft_deletes`, deleting a category trashes it (its children move to the top +level and its settings lose the link, as before), and creating the same slug again restores the +row with the same id. + +## JSON translations + +Under `translations.mode = json`, a category's title is stored as a JSON map with `""` for the +title that applies to any locale: + +```php +$settings->categories()->create(new NewCategory('mail', 'Mail', translations: ['fr' => 'Courrier'])); +$settings->categories()->get('mail')->titleIn('fr_CA'); // "Courrier" (locale, then language, then "") +``` + +Labels and descriptions in the definitions table are stored the same way. Under `lang`, titles are +plain text or translation keys and `translations` is ignored. + +## The definitions table + +`definitions.table = true` creates `settings_definitions` (§4.4 of the design). Code and config +definitions are copied in as read-only `is_system` rows by +`laranail::settings.sync-definitions` (also run by `install` once the table exists, and by +`doctor --fix`), so UIs can list them; system rows nothing defines any more are removed. + +Other rows are definitions edited at runtime. They answer only for keys no code or config +definition covers, so a row can never loosen a coded setting, and a row sharing a coded key is +reported as a conflict and left alone. A row's rules are filtered through +`definitions.allowed_rules` (no `exists`, `unique` or rule classes), its type must be a +registered caster alias, and an encrypted definition's default is never copied into the table. +`definitions.sources` (`code`, `config`, `database`) turns the config map or the table off. + +## The schema file + +`install` writes `database/settings-schema.php` (or `schema.path`): a `shape_version`, the +switches, the table names and one entry per database store. `make-store` adds its store's entry. +The migrations and the runtime read this file, not configuration, so changing a switch after +migrating changes nothing until a migration does. Commit it. An existing record always wins: +recording again only adds stores that are new. + +`doctor` reports drift three ways: configuration against the file (a warning naming each +difference), the file's `shape_version` against this release (a release that adds columns raises +it; an older file means an upgrade migration was never published), and the live tables against +the file (a missing column fails, a column the shape does not have warns, an `id` of the wrong +type fails). A database store with no entry in the file fails. + +## Keeping the switches tested + +`tests/Feature/Database/SchemaMatrixTest.php` builds a pairwise set of shapes (every pair of +switch values meets in at least one; 10 shapes covering all 141 pairs, both counts asserted) and +runs each end to end, finishing with `doctor`. It runs on SQLite with the suite and on MySQL and +PostgreSQL in the `database` group; `LARANAIL_SETTINGS_MATRIX=full` runs all 576 shapes, which +the weekly CI job does. + +--- + +[← Docs index](../../README.md#documentation) diff --git a/src/Actions/DiagnoseSettings.php b/src/Actions/DiagnoseSettings.php index ea2a4ec..3f9f842 100644 --- a/src/Actions/DiagnoseSettings.php +++ b/src/Actions/DiagnoseSettings.php @@ -7,11 +7,15 @@ use Throwable; use Illuminate\Database\Query\Builder; use Simtabi\Laranail\Settings\Data\Scope; +use Simtabi\Laranail\Settings\Enums\IdType; use Simtabi\Laranail\Settings\Stores\Store; use Simtabi\Laranail\Settings\Diagnostics\Finding; +use Simtabi\Laranail\Settings\Database\SchemaShape; use Simtabi\Laranail\Settings\Stores\StoreRegistry; use Simtabi\Laranail\Settings\Drivers\DatabaseDriver; use Simtabi\Laranail\Settings\Contracts\DatabaseBacked; +use Simtabi\Laranail\Settings\Exceptions\SettingsException; +use Simtabi\Laranail\Settings\Database\SchemaShapeRepository; use Simtabi\Laranail\Package\Tools\Services\Doctor\DoctorResult; /** @@ -19,24 +23,33 @@ * connection answers and the tables exist), schema drift (columns this release reads that the * tables lack), scopes naming a class instead of a morph alias or an alias the store does not * list (G-6, G-30), and rows whose category belongs to another store (G-33). Read-only. + * + * Schema drift is three comparisons (§4.0): the schema file against the configuration (a switch + * changed after migrating changes nothing until a migration does), the file's shape version + * against this release's (an upgrade migration that was never published), and the live tables + * against the recorded shape (missing columns fail; columns the shape does not have, such as + * `deleted_at` on a store without soft deletes, warn). */ final readonly class DiagnoseSettings { - /** The columns this release reads and writes, per table. */ - private const array VALUES_COLUMNS = ['id', 'settable_type', 'settable_id', 'scope', 'category_id', 'category_store', 'group', 'key', 'slug', 'uid', 'locale', 'value', 'type', 'is_encrypted', 'is_locked', 'is_public', 'autoload', 'sort_order', 'meta', 'version', 'created_at', 'updated_at']; + /** The values-table columns every shape has; the rest depend on the switches. */ + private const array VALUES_COLUMNS = ['id', 'scope', 'category_id', 'category_store', 'group', 'key', 'locale', 'value', 'type', 'label', 'description', 'is_encrypted', 'is_locked', 'is_public', 'autoload', 'sort_order', 'meta', 'version', 'created_at', 'updated_at']; private const array CATEGORY_COLUMNS = ['id', 'store', 'parent_id', 'title', 'slug', 'description', 'icon', 'sort_order', 'is_system', 'meta', 'created_at', 'updated_at']; + private const array DEFINITION_COLUMNS = ['id', 'store', 'slug', 'key', 'group', 'category_id', 'type', 'default', 'label', 'description', 'rules', 'is_encrypted', 'is_public', 'is_locked', 'autoload', 'inherits', 'overridable_by', 'is_system', 'meta', 'created_at', 'updated_at']; + private const array AUDIT_COLUMNS = ['id', 'occurred_at', 'action', 'outcome', 'store', 'scope', 'key', 'locale', 'version_from', 'version_to', 'change_request', 'actor_type', 'actor_alias', 'actor_id', 'channel', 'ip', 'user_agent', 'request_id', 'reason', 'meta']; public function __construct( private StoreRegistry $stores, + private ?SchemaShapeRepository $shapes = null, ) {} /** @return list */ public function handle(): array { - $findings = []; + $findings = $this->shapes instanceof SchemaShapeRepository ? $this->schemaFile($this->shapes) : []; foreach ($this->stores->all() as $name => $store) { $database = $this->databaseOf($store); @@ -75,15 +88,68 @@ private function databaseOf(Store $store): ?DatabaseDriver return null; } + /** + * The schema file against the configuration and against this release. + * + * @return list + */ + private function schemaFile(SchemaShapeRepository $shapes): array + { + $name = 'schema file'; + $description = 'The recorded schema matches the configuration and this release'; + + try { + $recorded = $shapes->recorded(); + $configured = $shapes->configured(); + } catch (SettingsException $exception) { + return [new Finding($name, $description, DoctorResult::fail($exception->getMessage()))]; + } + + if (! $recorded instanceof SchemaShape) { + return [new Finding($name, $description, DoctorResult::warn(sprintf('No schema file at [%s]; the shape is read from configuration. Run laranail::settings.install to record it.', $shapes->path())))]; + } + + $findings = []; + + if ($recorded->version < SchemaShape::VERSION) { + $findings[] = new Finding('schema version', 'The schema is at this release\'s shape version', DoctorResult::fail(sprintf('The schema file is at shape version %d; this release needs %d. Publish and run the upgrade migrations, then record the new version.', $recorded->version, SchemaShape::VERSION))); + } + + foreach ($this->stores->all() as $storeName => $store) { + if ($store->hasDatabaseLayer() && ! $recorded->hasStore($store->name)) { + $findings[] = new Finding("{$storeName}: recorded", 'The store is in the schema file', DoctorResult::fail(sprintf('Store [%s] has a database layer but no entry in the schema file: run laranail::settings.make-store %s.', $storeName, $storeName))); + } + } + + $differences = array_values(array_filter( + $configured->differencesFrom($recorded), + static fn (string $line): bool => ! str_starts_with($line, 'stores.') || array_any(array_keys($recorded->stores), static fn (string $store): bool => str_starts_with($line, "stores.{$store}.")), + )); + + $findings[] = new Finding($name, $description, $differences === [] + ? DoctorResult::pass('The configuration matches the recorded schema.') + : DoctorResult::warn('The configuration differs from the recorded schema (the recorded one is in force; a migration is needed to change it): ' . implode('; ', $differences), ['differences' => $differences])); + + return $findings; + } + private function drift(Store $store, DatabaseDriver $database): Finding { + $shape = $database->shape(); + $schema = $shape->store($store->name); $missing = []; + $unexpected = []; + $expected = [ + $database->tableFor($store->name) => [...self::VALUES_COLUMNS, ...$this->switchColumns($shape, $schema->isDedicated(), $schema->softDeletes)], + $shape->names->categories() => [...self::CATEGORY_COLUMNS, ...($shape->categoriesSoftDeletes ? ['deleted_at'] : [])], + $shape->names->audit() => self::AUDIT_COLUMNS, + ]; + + if ($shape->definitionsTable) { + $expected[$shape->names->definitions()] = self::DEFINITION_COLUMNS; + } - foreach ([ - $database->tableFor($store->name) => self::VALUES_COLUMNS, - $database->names()->categories() => self::CATEGORY_COLUMNS, - $database->names()->audit() => self::AUDIT_COLUMNS, - ] as $table => $columns) { + foreach ($expected as $table => $columns) { try { $present = $database->connection()->getSchemaBuilder()->getColumnListing($table); } catch (Throwable) { @@ -93,11 +159,58 @@ private function drift(Store $store, DatabaseDriver $database): Finding foreach (array_diff($columns, $present) as $column) { $missing[] = $table . '.' . $column; } + + foreach (array_diff(array_intersect($present, ['deleted_at', 'slug', 'uid', 'settable_type', 'settable_id', 'owner_id']), $columns) as $column) { + $unexpected[] = $table . '.' . $column; + } + } + + $idType = $this->idTypeDrift($database, $database->tableFor($store->name), $shape->ids); + + if ($missing !== []) { + return new Finding("{$store->name}: schema", 'The tables have every column the recorded schema uses', DoctorResult::fail('Missing columns (publish and run the latest migrations): ' . implode(', ', $missing), ['missing' => $missing])); + } + + if ($idType !== null) { + return new Finding("{$store->name}: schema", 'The tables have every column the recorded schema uses', DoctorResult::fail($idType)); } - return new Finding("{$store->name}: schema", 'The tables have every column this release uses', $missing === [] + return new Finding("{$store->name}: schema", 'The tables have every column the recorded schema uses', $unexpected === [] ? DoctorResult::pass('No schema drift.') - : DoctorResult::fail('Missing columns (publish and run the latest migrations): ' . implode(', ', $missing), ['missing' => $missing])); + : DoctorResult::warn('Columns the recorded schema does not have (a switch changed without a migration?): ' . implode(', ', $unexpected), ['unexpected' => $unexpected])); + } + + /** @return list the values-table columns the switches add */ + private function switchColumns(SchemaShape $shape, bool $dedicated, bool $softDeletes): array + { + return [ + ...($dedicated ? ['owner_id'] : ['settable_type', 'settable_id']), + ...($shape->identity->hasSlug() ? ['slug'] : []), + ...($shape->identity->hasUid() ? ['uid'] : []), + ...($softDeletes ? ['deleted_at'] : []), + ]; + } + + /** A message when the table's `id` column is not of the recorded key type, else null. */ + private function idTypeDrift(DatabaseDriver $database, string $table, IdType $type): ?string + { + try { + $columns = $database->connection()->getSchemaBuilder()->getColumns($table); + } catch (Throwable) { + return null; + } + + foreach ($columns as $column) { + if (($column['name'] ?? null) !== 'id') { + continue; + } + + $integer = str_contains(strtolower((string) ($column['type_name'] ?? '')), 'int'); + + return $integer === ($type === IdType::Bigint) ? null : sprintf('Table [%s] has an id of type [%s], but the recorded key type is [%s].', $table, $column['type_name'] ?? '?', $type->value); + } + + return null; } private function scopes(Store $store, DatabaseDriver $database): Finding diff --git a/src/Actions/MakeStore.php b/src/Actions/MakeStore.php index ca39521..9ac6654 100644 --- a/src/Actions/MakeStore.php +++ b/src/Actions/MakeStore.php @@ -9,6 +9,8 @@ use Simtabi\Laranail\Settings\Data\OwnerRef; use Simtabi\Laranail\Settings\Data\StoreName; use Simtabi\Laranail\Settings\Data\GeneratedStore; +use Simtabi\Laranail\Settings\Database\StoreSchema; +use Simtabi\Laranail\Settings\Database\SchemaShapeRepository; use Simtabi\Laranail\Settings\Exceptions\InvalidConfiguration; /** @@ -16,6 +18,11 @@ * from the package's stub with the store name filled in, plus the categories and audit tables * when the store lives on a connection of its own (each connection keeps its own). Returns the * files written and the configuration entry to add by hand. + * + * The store's shape (mode, soft deletes, owner table) is recorded in the schema file (§4.0): + * taken from its configuration entry when it has one, else the default polymorphic shape on the + * given connection. The file's switches (key type, identity, translations) are kept, so the new + * table's `category_id` always matches the categories key it points at. */ final readonly class MakeStore { @@ -27,6 +34,7 @@ public function __construct( private Filesystem $files, private string $stubs, private string $migrations, + private ?SchemaShapeRepository $shapes = null, ) {} /** @@ -65,6 +73,10 @@ public function handle(StoreName $store, ?string $connection = null, array $owne self::CONNECTION_LINE => $pinned, ]); + if ($this->shapes instanceof SchemaShapeRepository) { + $this->shapes->recordStore($this->shapes->configured()->stores[$store->value] ?? new StoreSchema($store, connection: $connection)); + } + return new GeneratedStore($store, $written, $this->config($store, $connection, $owners)); } diff --git a/src/Actions/PruneAudit.php b/src/Actions/PruneAudit.php index 211dff4..5d31607 100644 --- a/src/Actions/PruneAudit.php +++ b/src/Actions/PruneAudit.php @@ -5,26 +5,42 @@ namespace Simtabi\Laranail\Settings\Actions; use Carbon\CarbonImmutable; +use Simtabi\Laranail\Settings\Data\Actor; +use Simtabi\Laranail\Settings\Data\Subject; +use Simtabi\Laranail\Settings\Enums\Ability; +use Simtabi\Laranail\Settings\Enums\AuditAction; +use Simtabi\Laranail\Settings\Enums\AuditOutcome; use Simtabi\Laranail\Settings\Stores\StoreRegistry; use Simtabi\Laranail\Settings\Drivers\DatabaseDriver; +use Simtabi\Laranail\Settings\Authorization\AccessGuard; use Simtabi\Laranail\Settings\Exceptions\InvalidConfiguration; /** * Delete audit rows older than `audit.keep_days` from the audit table of every connection a - * store uses. Returns the number of rows removed. + * store uses. Returns the number of rows removed. With an actor it needs `prune` (checked + * against the default store); the prune itself is audited, so the trail records who shortened + * it. */ final readonly class PruneAudit { + private AccessGuard $access; + public function __construct( private StoreRegistry $stores, - ) {} + ?AccessGuard $access = null, + ) { + $this->access = $access ?? AccessGuard::closed(); + } - public function handle(int $keepDays): int + public function handle(int $keepDays, ?Actor $actor = null): int { if ($keepDays < 1) { throw new InvalidConfiguration(sprintf('laranail.settings.audit.keep_days: [%d] must be at least 1.', $keepDays)); } + $subject = new Subject($this->stores->default()->name); + $this->access->authorize($actor, Ability::Prune, $subject); + $cutoff = CarbonImmutable::now()->subDays($keepDays); $removed = 0; $seen = []; @@ -44,6 +60,8 @@ public function handle(int $keepDays): int ->delete()); } + $this->access->auditor()->record(AuditAction::Prune, AuditOutcome::Allowed, $subject, $actor, meta: ['target' => 'audit', 'keep_days' => $keepDays, 'removed' => $removed]); + return $removed; } } diff --git a/src/Actions/PruneOrphans.php b/src/Actions/PruneOrphans.php index 9d02824..0127bec 100644 --- a/src/Actions/PruneOrphans.php +++ b/src/Actions/PruneOrphans.php @@ -7,10 +7,15 @@ use Closure; use Illuminate\Database\Eloquent\Model; use Simtabi\Laranail\Settings\Data\Actor; +use Simtabi\Laranail\Settings\Data\Subject; use Simtabi\Laranail\Settings\Stores\Store; use Simtabi\Laranail\Settings\Data\OwnerRef; +use Simtabi\Laranail\Settings\Enums\Ability; +use Simtabi\Laranail\Settings\Enums\AuditAction; +use Simtabi\Laranail\Settings\Enums\AuditOutcome; use Simtabi\Laranail\Settings\Stores\StoreRegistry; use Simtabi\Laranail\Settings\Drivers\DatabaseDriver; +use Simtabi\Laranail\Settings\Authorization\AccessGuard; /** * Find, and remove, the settings of owners that no longer exist (G-7): rows left by bulk @@ -18,15 +23,23 @@ * in the database layer and asks the aliased model which ids still exist, soft-deleted ones * included (a soft-deleted owner keeps its settings for a restore). An alias with no model in * the morph map is reported, never guessed at. + * + * Removing needs `prune` when an actor is present (and, per owner, the `forget` that flushing + * needs); the run is audited as one `prune` entry besides the per-owner `forget` entries. */ final readonly class PruneOrphans { + private AccessGuard $access; + /** @param Closure(string): ?string $models the model class of a morph alias (the morph map) */ public function __construct( private StoreRegistry $stores, private FlushScope $flush, private Closure $models, - ) {} + ?AccessGuard $access = null, + ) { + $this->access = $access ?? AccessGuard::closed(); + } /** * The orphaned owners per store, and the aliases no model answers for. @@ -70,16 +83,22 @@ public function find(): array */ public function handle(?Actor $actor = null): int { + $subject = new Subject($this->stores->default()->name); + $this->access->authorize($actor, Ability::Prune, $subject); $removed = 0; + $flushed = 0; foreach ($this->find()['orphans'] as $name => $owners) { $store = $this->stores->all()[$name]; foreach ($owners as $owner) { $removed += $this->flush->handle($store, $owner, $actor); + $flushed++; } } + $this->access->auditor()->record(AuditAction::Prune, AuditOutcome::Allowed, $subject, $actor, meta: ['target' => 'orphans', 'owners' => $flushed, 'removed' => $removed]); + return $removed; } diff --git a/src/Actions/QueryAudit.php b/src/Actions/QueryAudit.php new file mode 100644 index 0000000..a9d1f94 --- /dev/null +++ b/src/Actions/QueryAudit.php @@ -0,0 +1,176 @@ + */ + public function get(AuditFilter $filter, ?Actor $actor = null, ?int $limit = null): array + { + $query = $this->query($filter, $actor); + + if ($limit !== null) { + $query->limit(max(1, $limit)); + } + + return array_values(array_map(fn (object $row): AuditEntry => $this->entry((array) $row), $query->get()->all())); + } + + /** @return LazyCollection streamed in chunks, for large trails */ + public function cursor(AuditFilter $filter, ?Actor $actor = null): LazyCollection + { + return $this->query($filter, $actor)->cursor()->map(fn (object $row): AuditEntry => $this->entry((array) $row)); + } + + /** One page, newest first; pass the page's `nextCursor` back for the next one. */ + public function paginate(AuditFilter $filter, ?Actor $actor = null, int $perPage = 50, ?string $cursor = null): AuditPage + { + $page = $this->query($filter, $actor)->cursorPaginate(max(1, $perPage), ['*'], 'cursor', $cursor === null ? null : Cursor::fromEncoded($cursor)); + + return new AuditPage( + array_values(array_map(fn (mixed $row): AuditEntry => $this->entry(is_object($row) ? (array) $row : []), $page->items())), + max(1, $perPage), + $page->nextCursor()?->encode(), + $page->previousCursor()?->encode(), + ); + } + + private function query(AuditFilter $filter, ?Actor $actor): Builder + { + $store = $filter->store instanceof StoreName ? $this->stores->get($filter->store) : $this->stores->default(); + + $this->access->authorize($actor, Ability::ViewAudit, new Subject( + $store->name, + key: $filter->key, + owner: ! $filter->scope instanceof Scope || $filter->scope->isGlobal() ? null : new OwnerRef(...explode(':', $filter->scope->value, 2)), + )); + + $database = $store->database() ?? $this->stores->default()->database(); + + if (! $database instanceof DatabaseDriver) { + throw new DriverUnavailable(sprintf('Store [%s] has no active database layer, so its audit trail went to the log and cannot be queried.', $store->name)); + } + + $query = $database->connection()->table($database->names()->audit()); + + if ($filter->store instanceof StoreName) { + $query->where('store', $filter->store->value); + } + + foreach (['scope' => $filter->scope?->value, 'key' => $filter->key?->value, 'action' => $filter->action?->value, 'outcome' => $filter->outcome?->value] as $column => $value) { + if ($value !== null) { + $query->where($column, $value); + } + } + + if ($filter->since instanceof CarbonImmutable) { + $query->where('occurred_at', '>=', $filter->since); + } + + if ($filter->until instanceof CarbonImmutable) { + $query->where('occurred_at', '<=', $filter->until); + } + + return $query->orderByDesc('occurred_at')->orderByDesc('id'); + } + + /** @param array $row */ + private function entry(array $row): AuditEntry + { + $text = static fn (string $column): ?string => is_string($row[$column] ?? null) ? $row[$column] : null; + $number = static fn (string $column): ?int => is_numeric($row[$column] ?? null) ? (int) $row[$column] : null; + $id = $text('id'); + $occurred = $text('occurred_at'); + $action = AuditAction::tryFrom($text('action') ?? ''); + $outcome = AuditOutcome::tryFrom($text('outcome') ?? ''); + $actorType = ActorType::tryFrom($text('actor_type') ?? ''); + $channel = Channel::tryFrom($text('channel') ?? ''); + + if ($id === null || $occurred === null || ! $action instanceof AuditAction || ! $outcome instanceof AuditOutcome || ! $actorType instanceof ActorType || ! $channel instanceof Channel) { + throw new DriverFailure(sprintf('Audit row [%s] is malformed.', $id ?? '?')); + } + + return new AuditEntry( + id: $id, + occurredAt: CarbonImmutable::parse($occurred), + action: $action, + outcome: $outcome, + store: $text('store'), + scope: $text('scope'), + key: $text('key'), + locale: $text('locale'), + versionFrom: $number('version_from'), + versionTo: $number('version_to'), + actorType: $actorType, + actorAlias: $text('actor_alias'), + actorId: $text('actor_id'), + channel: $channel, + ip: $text('ip'), + userAgent: $text('user_agent'), + requestId: $text('request_id'), + reason: $text('reason'), + meta: $this->meta($text('meta')), + ); + } + + /** @return array */ + private function meta(?string $json): array + { + if ($json === null) { + return []; + } + + try { + $decoded = json_decode($json, true, 4, JSON_THROW_ON_ERROR); + } catch (JsonException) { + return []; + } + + $meta = []; + + foreach (is_array($decoded) ? $decoded : [] as $key => $value) { + if (is_scalar($value) || $value === null) { + $meta[(string) $key] = $value; + } + } + + return $meta; + } +} diff --git a/src/Actions/SetSetting.php b/src/Actions/SetSetting.php index fecdff7..3cbe720 100644 --- a/src/Actions/SetSetting.php +++ b/src/Actions/SetSetting.php @@ -11,7 +11,8 @@ /** * Store a value: needs `update` (and `override_lock` over a locked row the store lets be - * overridden). Shared by the PHP API and, later, the console and REST channels. + * overridden). Shared by the PHP API and, later, the console and REST channels. A write naming + * the version it expects is checked against it and never retried. */ final readonly class SetSetting { @@ -25,9 +26,11 @@ public function handle(SettingWrite $write, ?Actor $actor = null): void $target = $write->target; $this->guard->run(Ability::Update, $target, $actor, respectsLocks: true, write: function (bool $override) use ($target, $write): array { - $after = $override - ? $this->writer->setOverridingLock($target->store, $target->key, $target->locale, $target->owner, $target->definition, $write->value) - : $this->writer->set($target->store, $target->key, $target->locale, $target->owner, $target->definition, $write->value); + $after = match (true) { + $write->expectedVersion !== null => $this->writer->setExpecting($target->store, $target->key, $target->locale, $target->owner, $target->definition, $write->value, $write->expectedVersion, $override), + $override => $this->writer->setOverridingLock($target->store, $target->key, $target->locale, $target->owner, $target->definition, $write->value), + default => $this->writer->set($target->store, $target->key, $target->locale, $target->owner, $target->definition, $write->value), + }; return [$after->version > 1 ? $after->version - 1 : null, $after->version]; }); diff --git a/src/Actions/SyncDefinitions.php b/src/Actions/SyncDefinitions.php new file mode 100644 index 0000000..93ff0ab --- /dev/null +++ b/src/Actions/SyncDefinitions.php @@ -0,0 +1,166 @@ +, skipped: list} + */ +final readonly class SyncDefinitions +{ + public function __construct( + private StoreRegistry $stores, + private DefinitionRegistry $definitions, + private ValueEncoder $encoder, + private AccessGuard $access, + ) {} + + /** @return SyncReport */ + public function handle(?Actor $actor = null): array + { + $subject = new Subject($this->stores->default()->name); + $this->access->authorize($actor, Ability::ManageDefinitions, $subject); + + $report = ['synced' => 0, 'removed' => 0, 'conflicts' => [], 'skipped' => []]; + $byStore = []; + + foreach ($this->definitions->all() as $definition) { + $byStore[$definition->store->value][] = $definition; + } + + foreach ($this->stores->all() as $name => $store) { + $database = $store->database(); + + if (! $database instanceof DatabaseDriver || ! $database->shape()->definitionsTable) { + $report['skipped'][] = $name; + + continue; + } + + $result = $database->attempt($store->name, fn (): array => $database->transaction(fn (): array => $this->sync($store, $database, $byStore[$name] ?? []), $store->name)); + $report['synced'] += $result['synced']; + $report['removed'] += $result['removed']; + $report['conflicts'] = [...$report['conflicts'], ...$result['conflicts']]; + } + + $this->access->auditor()->record(AuditAction::ManageDefinitions, AuditOutcome::Allowed, $subject, $actor, meta: [ + 'sync' => true, + 'synced' => $report['synced'], + 'removed' => $report['removed'], + 'conflicts' => count($report['conflicts']), + ]); + + return $report; + } + + /** + * @param list $definitions + * + * @return array{synced: int, removed: int, conflicts: list} + */ + private function sync(Store $store, DatabaseDriver $database, array $definitions): array + { + $table = static fn () => $database->connection()->table($database->names()->definitions())->where('store', $store->name->value); + $now = CarbonImmutable::now(); + $json = $database->shape()->translations === TranslationsMode::Json; + $synced = 0; + $conflicts = []; + $keys = []; + + foreach ($definitions as $definition) { + $keys[] = $definition->key->value; + $row = $table()->where('key', $definition->key->value)->first(['is_system']); + + if ($row !== null && ! in_array($row->is_system ?? false, [true, 1, '1'], true)) { + $conflicts[] = $store->name->value . '.' . $definition->key->value; + + continue; + } + + $columns = $this->columns($database, $store, $definition, $json) + ['updated_at' => $now]; + + if ($row === null) { + $table()->insert($columns + DatabaseDriver::newId($database->shape()->ids) + [ + 'store' => $store->name->value, + 'key' => $definition->key->value, + 'is_system' => true, + 'created_at' => $now, + ]); + } else { + $table()->where('key', $definition->key->value)->update($columns); + } + + $synced++; + } + + $removed = $table()->where('is_system', true)->whereNotIn('key', $keys === [] ? [''] : $keys)->delete(); + + return ['synced' => $synced, 'removed' => $removed, 'conflicts' => $conflicts]; + } + + /** @return array */ + private function columns(DatabaseDriver $database, Store $store, Definition $definition, bool $json): array + { + $category = $definition->category === null ? null : $database->connection()->table($database->names()->categories()) + ->where('store', $store->name->value) + ->where('slug', $definition->category) + ->value('id'); + + return [ + 'slug' => $definition->key->slug(), + 'group' => $definition->group(), + 'category_id' => is_int($category) || is_string($category) ? $category : null, + 'type' => $definition->type, + // An encrypted setting's default stays in code: the table must not hold a readable copy. + 'default' => $definition->hasDefault && ! $definition->encrypted ? $this->encoder->encode($definition->key, $definition->default) : null, + 'label' => $this->text($definition->label, $json), + 'description' => $this->text($definition->description, $json), + 'rules' => $this->encode($definition->rules), + 'is_encrypted' => $definition->encrypted, + 'is_public' => $definition->public, + 'is_locked' => $definition->locked, + 'inherits' => $definition->inherits, + 'overridable_by' => $this->encode($definition->overridableBy), + ]; + } + + private function text(?string $text, bool $json): ?string + { + return $text === null || ! $json ? $text : $this->encode(['' => $text]); + } + + /** @param array $value */ + private function encode(array $value): string + { + try { + return json_encode($value, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES); + } catch (JsonException $exception) { + throw new DriverFailure('A definition could not be encoded for the definitions table.', 0, $exception); + } + } +} diff --git a/src/Audit/AuditQuery.php b/src/Audit/AuditQuery.php new file mode 100644 index 0000000..3a0f99b --- /dev/null +++ b/src/Audit/AuditQuery.php @@ -0,0 +1,110 @@ +audit()`: an immutable query over the audit trail. Each condition returns a new + * query; `get()`, `cursor()` and `paginate()` run it through {@see QueryAudit}, which checks + * `view_audit` for the handle's actor. Entries hold actions and identifiers, never values. + * + * $settings->as($admin)->audit()->for($user)->key('mail.from_address') + * ->action(AuditAction::Update)->since(now()->subWeek())->get(); + */ +final readonly class AuditQuery +{ + public function __construct( + private QueryAudit $action, + private ?Actor $actor = null, + private AuditFilter $filter = new AuditFilter, + ) {} + + /** Entries about one owner (its scope); the store is not narrowed by this. */ + public function for(Settable|OwnerRef $owner): self + { + $ref = $owner instanceof Settable ? $owner->settingsOwner() : $owner; + + return $this->with($this->filter->with(scope: $ref->scope())); + } + + /** Entries about global values only. */ + public function global(): self + { + return $this->with($this->filter->with(scope: Scope::global())); + } + + public function store(string $name): self + { + return $this->with($this->filter->with(store: new StoreName($name))); + } + + public function key(string $key): self + { + return $this->with($this->filter->with(key: new Key($key))); + } + + public function action(AuditAction $action): self + { + return $this->with($this->filter->with(action: $action)); + } + + public function outcome(AuditOutcome $outcome): self + { + return $this->with($this->filter->with(outcome: $outcome)); + } + + public function since(DateTimeInterface $moment): self + { + return $this->with($this->filter->with(since: CarbonImmutable::instance($moment))); + } + + public function until(DateTimeInterface $moment): self + { + return $this->with($this->filter->with(until: CarbonImmutable::instance($moment))); + } + + public function filter(): AuditFilter + { + return $this->filter; + } + + /** @return list newest first */ + public function get(?int $limit = null): array + { + return $this->action->get($this->filter, $this->actor, $limit); + } + + /** @return LazyCollection */ + public function cursor(): LazyCollection + { + return $this->action->cursor($this->filter, $this->actor); + } + + /** One page; pass its `nextCursor` back for the next. */ + public function paginate(int $perPage = 50, ?string $cursor = null): AuditPage + { + return $this->action->paginate($this->filter, $this->actor, $perPage, $cursor); + } + + private function with(AuditFilter $filter): self + { + return new self($this->action, $this->actor, $filter); + } +} diff --git a/src/Console/DoctorCommand.php b/src/Console/DoctorCommand.php index f03a5af..e50a618 100644 --- a/src/Console/DoctorCommand.php +++ b/src/Console/DoctorCommand.php @@ -4,27 +4,44 @@ namespace Simtabi\Laranail\Settings\Console; +use Simtabi\Laranail\Settings\Data\Actor; use Simtabi\Laranail\Console\Tools\Commands\Command; +use Simtabi\Laranail\Settings\Actions\SyncDefinitions; use Simtabi\Laranail\Settings\Actions\DiagnoseSettings; +use Simtabi\Laranail\Settings\Exceptions\SettingsException; use Simtabi\Laranail\Package\Tools\Services\Doctor\DoctorReporter; use Simtabi\Laranail\Console\Tools\Commands\Concerns\SupportsNamespacedNames; /** * `laranail::settings.doctor`: per database store, whether it is ready, whether its tables have * drifted from what this release uses, and whether any rows break the rules the database cannot - * enforce (class-name scopes, unlisted aliases, cross-store categories). Exits non-zero on a - * failure, so it can gate a deploy. + * enforce (class-name scopes, unlisted aliases, cross-store categories), and drift between the + * configuration, the recorded schema file and the database. Exits non-zero on a failure, so it + * can gate a deploy. `--fix` first refreshes the definitions table's system rows. */ final class DoctorCommand extends Command { use SupportsNamespacedNames; - protected $signature = 'laranail::settings.doctor {--json : Emit the report as JSON}'; + protected $signature = 'laranail::settings.doctor + {--json : Emit the report as JSON} + {--fix : Refresh the definitions table from code and config first}'; protected $description = 'Check the settings stores: readiness, schema drift and data the database cannot guard'; - public function handle(DiagnoseSettings $diagnose): int + public function handle(DiagnoseSettings $diagnose, SyncDefinitions $sync): int { + if ($this->option('fix') === true) { + try { + $report = $sync->handle(Actor::system('laranail::settings.doctor')); + $this->info(sprintf('Synced %d definition(s); removed %d stale system row(s).', $report['synced'], $report['removed'])); + } catch (SettingsException $exception) { + $this->error($exception->getMessage()); + + return self::FAILURE; + } + } + return DoctorReporter::render($this, $diagnose->handle(), $this->option('json') === true); } } diff --git a/src/Console/PruneAuditCommand.php b/src/Console/PruneAuditCommand.php index 83eb4ac..5e3cf67 100644 --- a/src/Console/PruneAuditCommand.php +++ b/src/Console/PruneAuditCommand.php @@ -4,6 +4,7 @@ namespace Simtabi\Laranail\Settings\Console; +use Simtabi\Laranail\Settings\Data\Actor; use Illuminate\Contracts\Config\Repository; use Simtabi\Laranail\Settings\Actions\PruneAudit; use Simtabi\Laranail\Console\Tools\Commands\Command; @@ -32,7 +33,7 @@ public function handle(PruneAudit $prune, Repository $config): int } try { - $removed = $prune->handle((int) $days); + $removed = $prune->handle((int) $days, Actor::system('laranail::settings.prune-audit')); } catch (SettingsException $exception) { $this->error($exception->getMessage()); diff --git a/src/Console/SyncDefinitionsCommand.php b/src/Console/SyncDefinitionsCommand.php new file mode 100644 index 0000000..8493fd8 --- /dev/null +++ b/src/Console/SyncDefinitionsCommand.php @@ -0,0 +1,48 @@ +handle(Actor::system('laranail::settings.sync-definitions')); + } catch (SettingsException $exception) { + $this->error($exception->getMessage()); + + return self::FAILURE; + } + + foreach ($report['skipped'] as $store) { + $this->line(sprintf('Store [%s] skipped: no active database layer, or the definitions table is off.', $store)); + } + + foreach ($report['conflicts'] as $key) { + $this->warn(sprintf('[%s] is defined in code and edited in the table; code wins, the row was left alone.', $key)); + } + + $this->info(sprintf('Synced %d definition(s); removed %d stale system row(s).', $report['synced'], $report['removed'])); + + return self::SUCCESS; + } +} diff --git a/src/Contracts/Settings.php b/src/Contracts/Settings.php index 024e8e0..ac247cd 100644 --- a/src/Contracts/Settings.php +++ b/src/Contracts/Settings.php @@ -9,6 +9,7 @@ use Simtabi\Laranail\Settings\Data\Lookup; use Simtabi\Laranail\Settings\Data\OwnerRef; use Illuminate\Contracts\Auth\Authenticatable; +use Simtabi\Laranail\Settings\Audit\AuditQuery; use Simtabi\Laranail\Settings\Data\PromotionReport; use Simtabi\Laranail\Settings\Data\PromotionRequest; use Simtabi\Laranail\Settings\Resolution\Explanation; @@ -165,4 +166,11 @@ public function categories(): CategoryManager; * @throws StoreNotWritable when the store has no active database layer */ public function promote(?PromotionRequest $request = null): PromotionReport; + + /** + * Query the audit trail (§16.8): `->for($owner)`, `->store()`, `->key()`, `->action()`, + * `->outcome()`, `->since()`, `->until()`, then `->get()`, `->cursor()` or `->paginate()`. + * Needs `view_audit` when the handle carries an actor. Entries never hold values. + */ + public function audit(): AuditQuery; } diff --git a/src/Data/AuditFilter.php b/src/Data/AuditFilter.php new file mode 100644 index 0000000..69e24e5 --- /dev/null +++ b/src/Data/AuditFilter.php @@ -0,0 +1,47 @@ +store, + $scope ?? $this->scope, + $key ?? $this->key, + $action ?? $this->action, + $outcome ?? $this->outcome, + $since ?? $this->since, + $until ?? $this->until, + ); + } +} diff --git a/src/Data/AuditPage.php b/src/Data/AuditPage.php new file mode 100644 index 0000000..bc2e81f --- /dev/null +++ b/src/Data/AuditPage.php @@ -0,0 +1,25 @@ + $entries */ + public function __construct( + public array $entries, + public int $perPage, + public ?string $nextCursor = null, + public ?string $previousCursor = null, + ) {} + + public function hasMore(): bool + { + return $this->nextCursor !== null; + } +} diff --git a/src/Data/Category.php b/src/Data/Category.php index 37edff8..732c00e 100644 --- a/src/Data/Category.php +++ b/src/Data/Category.php @@ -6,9 +6,12 @@ /** * One category of one store, as stored. `parent` is the parent's slug (categories nest, D-11). + * `titles` holds the title per locale under `translations.mode = json` (D-8), with `''` for the + * title that applies to any locale; under `lang` it holds only that entry. */ final readonly class Category { + /** @param array $titles locale => title */ public function __construct( public int|string $id, public StoreName $store, @@ -19,5 +22,15 @@ public function __construct( public ?string $icon = null, public int $sortOrder = 0, public bool $system = false, + public array $titles = [], ) {} + + /** The title in a locale: that locale, then its language, then the title for any locale. */ + public function titleIn(string $locale): string + { + $locale = new Locale($locale)->value; + $language = explode('_', $locale)[0]; + + return $this->titles[$locale] ?? $this->titles[$language] ?? $this->title; + } } diff --git a/src/Data/NewCategory.php b/src/Data/NewCategory.php index cebe3d1..698bb0b 100644 --- a/src/Data/NewCategory.php +++ b/src/Data/NewCategory.php @@ -8,7 +8,9 @@ /** * The input for creating a category: slug and title, optionally a parent (by slug), a - * description, an icon name and a sort position. + * description, an icon name, a sort position and, for `translations.mode = json` (D-8), the + * title per locale. Under `lang` the translations are ignored: the title is plain text or a + * translation key. */ final readonly class NewCategory { @@ -16,6 +18,10 @@ public ?CategorySlug $parent; + /** @var array locale => title, normalised */ + public array $translations; + + /** @param array $translations locale => title (json translations mode) */ public function __construct( string $slug, public string $title, @@ -23,6 +29,7 @@ public function __construct( public ?string $description = null, public ?string $icon = null, public int $sortOrder = 0, + array $translations = [], ) { if (trim($title) === '' || mb_strlen($title) > 255) { throw new InvalidIdentifier(sprintf('Category [%s] needs a title of 1-255 characters.', $slug)); @@ -32,6 +39,17 @@ public function __construct( throw new InvalidIdentifier(sprintf('Category [%s]: the sort order cannot be negative.', $slug)); } + $normalised = []; + + foreach ($translations as $locale => $text) { + if (! is_string($text) || trim($text) === '' || mb_strlen($text) > 255) { + throw new InvalidIdentifier(sprintf('Category [%s] needs a title of 1-255 characters in locale [%s].', $slug, $locale)); + } + + $normalised[new Locale((string) $locale)->value] = $text; + } + + $this->translations = $normalised; $this->slug = new CategorySlug($slug); $this->parent = $parent === null ? null : new CategorySlug($parent); } diff --git a/src/Data/SettingWrite.php b/src/Data/SettingWrite.php index 82053a4..142737e 100644 --- a/src/Data/SettingWrite.php +++ b/src/Data/SettingWrite.php @@ -6,12 +6,14 @@ /** * The input of {@see \Simtabi\Laranail\Settings\Actions\SetSetting}: a target and the value to - * store there. + * store there. `expectedVersion`, when set, makes the write conditional on the row still being + * at that version (0: no row yet), as a REST `If-Match` will; such a write is never retried. */ final readonly class SettingWrite { public function __construct( public SettingTarget $target, public mixed $value, + public ?int $expectedVersion = null, ) {} } diff --git a/src/Database/CategoryRepository.php b/src/Database/CategoryRepository.php index 4797298..b37bf52 100644 --- a/src/Database/CategoryRepository.php +++ b/src/Database/CategoryRepository.php @@ -4,6 +4,7 @@ namespace Simtabi\Laranail\Settings\Database; +use JsonException; use Carbon\CarbonImmutable; use Illuminate\Database\Query\Builder; use Simtabi\Laranail\Settings\Data\Category; @@ -11,6 +12,7 @@ use Simtabi\Laranail\Settings\Data\NewCategory; use Simtabi\Laranail\Settings\Data\CategorySlug; use Simtabi\Laranail\Settings\Drivers\DatabaseDriver; +use Simtabi\Laranail\Settings\Enums\TranslationsMode; use Simtabi\Laranail\Settings\Exceptions\CategoryCycle; use Simtabi\Laranail\Settings\Exceptions\DriverFailure; use Simtabi\Laranail\Settings\Exceptions\UnknownCategory; @@ -20,6 +22,11 @@ * The categories of one store, in the categories table on the store's connection. Every lookup is * by (store, slug), so a store can never reach another store's category by accident; naming one * that exists only in another store raises {@see CategoryStoreMismatch} (G-33). + * + * The recorded schema shape decides the rest: generated uuid / ulid keys (D-5), titles as + * per-locale JSON (D-8), and soft deletes (`categories.soft_deletes`), under which a deleted + * category is trashed and creating its slug again restores that row, so `unique(store, slug)` + * never collides. */ final readonly class CategoryRepository { @@ -60,12 +67,13 @@ public function all(): array id: $this->id($row['id'] ?? null), store: $this->store, slug: new CategorySlug($this->string($row['slug'] ?? null)), - title: $this->string($row['title'] ?? null), + title: $this->text($this->string($row['title'] ?? null)), parent: isset($row['parent_id'], $slugs[$this->id($row['parent_id'])]) ? new CategorySlug($slugs[$this->id($row['parent_id'])]) : null, - description: is_string($row['description'] ?? null) ? $row['description'] : null, + description: is_string($row['description'] ?? null) ? $this->text($row['description']) : null, icon: is_string($row['icon'] ?? null) ? $row['icon'] : null, sortOrder: is_numeric($row['sort_order'] ?? null) ? (int) $row['sort_order'] : 0, system: in_array($row['is_system'] ?? false, [true, 1, '1'], true), + titles: $this->texts($this->string($row['title'] ?? null)), ), $rows)); } @@ -77,18 +85,29 @@ public function create(NewCategory $category): Category { $parent = $category->parent instanceof CategorySlug ? $this->idOf($category->parent) : null; $now = CarbonImmutable::now(); - - $this->database->attempt($this->store, fn (): bool => $this->table()->insert([ - 'store' => $this->store->value, + $columns = [ 'parent_id' => $parent, - 'title' => $category->title, - 'slug' => $category->slug->value, - 'description' => $category->description, + 'title' => $this->encode($category->title, $category->translations), + 'description' => $category->description === null ? null : $this->encode($category->description), 'icon' => $category->icon, 'sort_order' => $category->sortOrder, 'is_system' => false, - 'created_at' => $now, 'updated_at' => $now, + ]; + + // A trashed category of the same slug is restored, not duplicated. + if ($this->softDeletes() && $this->database->attempt($this->store, fn (): int => $this->table() + ->where('store', $this->store->value) + ->where('slug', $category->slug->value) + ->whereNotNull('deleted_at') + ->update($columns + ['deleted_at' => null, 'meta' => null])) > 0) { + return $this->get($category->slug); + } + + $this->database->attempt($this->store, fn (): bool => $this->table()->insert($columns + DatabaseDriver::newId($this->database->shape()->ids) + [ + 'store' => $this->store->value, + 'slug' => $category->slug->value, + 'created_at' => $now, ])); return $this->get($category->slug); @@ -97,7 +116,7 @@ public function create(NewCategory $category): Category /** @throws UnknownCategory */ public function rename(CategorySlug $slug, string $title): void { - $this->update($slug, ['title' => $title]); + $this->update($slug, ['title' => $this->encode($title, $this->get($slug)->titles)]); } /** @@ -123,6 +142,7 @@ public function move(CategorySlug $slug, ?CategorySlug $parent): void /** * Delete a category. Its children move to the top level and settings in it lose their * category, explicitly as well as through the foreign keys (SQLite may not enforce them). + * With soft deletes the row is trashed rather than removed. * * @throws UnknownCategory */ @@ -136,7 +156,9 @@ public function delete(CategorySlug $slug, string $valuesTable): void ->where('category_id', $id) ->where('category_store', $this->store->value) ->update(['category_id' => null, 'category_store' => null]); - $this->query()->where('id', $id)->delete(); + $this->softDeletes() + ? $this->query()->where('id', $id)->update(['deleted_at' => CarbonImmutable::now(), 'parent_id' => null]) + : $this->query()->where('id', $id)->delete(); }); } @@ -198,16 +220,83 @@ private function idOf(CategorySlug $slug): int|string private function unknown(CategorySlug $slug): UnknownCategory|CategoryStoreMismatch { - $elsewhere = $this->database->attempt($this->store, fn (): mixed => $this->table()->where('slug', $slug->value)->value('store')); + $elsewhere = $this->database->attempt($this->store, fn (): mixed => $this->live($this->table())->where('slug', $slug->value)->value('store')); return is_string($elsewhere) ? new CategoryStoreMismatch(sprintf('Category [%s] belongs to store [%s], not [%s].', $slug, $elsewhere, $this->store)) : new UnknownCategory(sprintf('Store [%s] has no category [%s].', $this->store, $slug)); } + /** This store's live (not trashed) categories. */ private function query(): Builder { - return $this->table()->where('store', $this->store->value); + return $this->live($this->table()->where('store', $this->store->value)); + } + + private function live(Builder $query): Builder + { + return $this->softDeletes() ? $query->whereNull('deleted_at') : $query; + } + + private function softDeletes(): bool + { + return $this->database->shape()->categoriesSoftDeletes; + } + + private function json(): bool + { + return $this->database->shape()->translations === TranslationsMode::Json; + } + + /** + * A title or description as the column holds it: the text itself, or (json mode) a JSON map + * of locale to text with `''` for the text that applies to any locale. + * + * @param array $translations + */ + private function encode(string $text, array $translations = []): string + { + if (! $this->json()) { + return $text; + } + + try { + return json_encode(['' => $text] + $translations, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES); + } catch (JsonException $exception) { + throw new DriverFailure('A category title could not be encoded.', 0, $exception); + } + } + + /** The text for any locale. */ + private function text(string $stored): string + { + $texts = $this->texts($stored); + + return $texts[''] ?? (string) reset($texts); + } + + /** @return array locale => text */ + private function texts(string $stored): array + { + if (! $this->json()) { + return ['' => $stored]; + } + + $decoded = json_decode($stored, true); + + if (! is_array($decoded) || $decoded === []) { + return ['' => $stored]; + } + + $texts = []; + + foreach ($decoded as $locale => $text) { + if (is_string($text)) { + $texts[(string) $locale] = $text; + } + } + + return $texts === [] ? ['' => $stored] : $texts; } private function table(): Builder diff --git a/src/Database/SchemaNames.php b/src/Database/SchemaNames.php index fc5b598..8302c29 100644 --- a/src/Database/SchemaNames.php +++ b/src/Database/SchemaNames.php @@ -9,7 +9,7 @@ /** * The package's table names: `tables.prefix` (D-4) prepended to `tables.categories`, - * `tables.audit` and each store's values table (`stores..table`, default the store name). + * `tables.audit`, `tables.definitions` and each store's values table (`stores..table`, default the store name). * Every name is validated, because it is interpolated into SQL identifiers. */ final readonly class SchemaNames @@ -18,6 +18,7 @@ public function __construct( public string $prefix = '', private string $categories = 'settings_categories', private string $audit = 'settings_audit', + private string $definitions = 'settings_definitions', ) { if (preg_match('/^[a-z0-9_]{0,32}$/', $prefix) !== 1) { throw new InvalidConfiguration(sprintf('laranail.settings.tables.prefix: [%s] must be [a-z0-9_], at most 32 characters.', $prefix)); @@ -25,6 +26,7 @@ public function __construct( self::assertTable($categories, 'laranail.settings.tables.categories'); self::assertTable($audit, 'laranail.settings.tables.audit'); + self::assertTable($definitions, 'laranail.settings.tables.definitions'); } /** @param array $tables `laranail.settings.tables` */ @@ -34,6 +36,7 @@ public static function fromConfig(array $tables): self self::string($tables, 'prefix', ''), self::string($tables, 'categories', 'settings_categories'), self::string($tables, 'audit', 'settings_audit'), + self::string($tables, 'definitions', 'settings_definitions'), ); } @@ -54,6 +57,18 @@ public function audit(): string return $this->prefix . $this->audit; } + /** The optional definitions table (D-6). */ + public function definitions(): string + { + return $this->prefix . $this->definitions; + } + + /** @return array{prefix: string, categories: string, audit: string, definitions: string} the unprefixed names */ + public function toArray(): array + { + return ['prefix' => $this->prefix, 'categories' => $this->categories, 'audit' => $this->audit, 'definitions' => $this->definitions]; + } + /** A store's values table: its configured table, or its name, after the prefix. */ public function store(StoreName $store, ?string $configured = null): string { diff --git a/src/Database/SchemaShape.php b/src/Database/SchemaShape.php new file mode 100644 index 0000000..945f836 --- /dev/null +++ b/src/Database/SchemaShape.php @@ -0,0 +1,333 @@ + $stores database stores, by name */ + public function __construct( + public int $version = self::VERSION, + public IdentityMode $identity = IdentityMode::SlugUid, + public IdType $ids = IdType::Bigint, + public OwnerKeyType $ownerKey = OwnerKeyType::String, + public IdType $ownerKeyType = IdType::Bigint, + public TranslationsMode $translations = TranslationsMode::Lang, + public bool $categoriesSoftDeletes = false, + public bool $definitionsTable = false, + public SchemaNames $names = new SchemaNames, + public array $stores = [], + ) {} + + /** + * The shape the current configuration describes. + * + * @param array $settings `laranail.settings` + * @param mixed $dbToolsIdType `laranail.db-tools.id_type`, which `ids.type` follows unless set + */ + public static function fromConfig(array $settings, mixed $dbToolsIdType = null): self + { + $ids = self::section($settings, 'ids'); + $followed = is_string($dbToolsIdType) ? IdType::parse($dbToolsIdType) : null; + $type = $ids['type'] ?? null; + $idType = $type === null ? ($followed ?? IdType::Bigint) : (is_string($type) ? IdType::parse($type) : null); + + if (! $idType instanceof IdType) { + throw new InvalidConfiguration('laranail.settings.ids.type: use bigint, uuid or ulid (or leave it null to follow laranail.db-tools.id_type).'); + } + + $ownerKey = self::enum($ids, 'owner_key', OwnerKeyType::String, OwnerKeyType::tryFrom(...), 'laranail.settings.ids.owner_key: use [string] or [typed].'); + $identity = self::enum(self::section($settings, 'identity'), 'mode', IdentityMode::SlugUid, IdentityMode::tryFrom(...), 'laranail.settings.identity.mode: use slug_uid, slug_per_row or uid_only.'); + $translations = self::enum(self::section($settings, 'translations'), 'mode', TranslationsMode::Lang, TranslationsMode::tryFrom(...), 'laranail.settings.translations.mode: use [lang] or [json].'); + $categories = self::section($settings, 'categories'); + $definitions = $settings['definitions'] ?? []; + + if (! is_bool($categories['soft_deletes'] ?? false)) { + throw new InvalidConfiguration('laranail.settings.categories.soft_deletes: true or false.'); + } + + $definitionsTable = is_array($definitions) ? ($definitions['table'] ?? false) : false; + + if (! is_bool($definitionsTable)) { + throw new InvalidConfiguration('laranail.settings.definitions.table: true or false.'); + } + + $default = $settings['default'] ?? 'settings'; + $default = new StoreName(is_string($default) ? $default : 'settings'); + + return new self( + self::VERSION, + $identity, + $idType, + $ownerKey, + $followed ?? IdType::Bigint, + $translations, + $categories['soft_deletes'] ?? false, + $definitionsTable, + SchemaNames::fromConfig(self::section($settings, 'tables')), + self::storesFromConfig($settings, $followed ?? IdType::Bigint, $default), + ); + } + + /** + * Read a recorded schema file. + * + * @param array $data what the file returns + */ + public static function fromArray(array $data): self + { + $version = $data['shape_version'] ?? null; + + if (! is_int($version) || $version < 1) { + throw new InvalidConfiguration('Schema file: `shape_version` must be a positive integer.'); + } + + $switches = self::section($data, 'switches'); + $tables = self::section($data, 'tables'); + $stores = []; + + foreach (self::section($data, 'stores') as $name => $entry) { + if (! is_array($entry)) { + throw new InvalidConfiguration(sprintf('Schema file: store [%s] must be an array.', $name)); + } + + $stores[(string) $name] = StoreSchema::fromArray(new StoreName((string) $name), $entry); + } + + $invalid = static fn (string $switch): InvalidConfiguration => new InvalidConfiguration(sprintf('Schema file: switch [%s] has an unknown value.', $switch)); + + return new self( + $version, + IdentityMode::tryFrom(self::text($switches, 'identity', 'slug_uid')) ?? throw $invalid('identity'), + IdType::parse(self::text($switches, 'ids', 'bigint')) ?? throw $invalid('ids'), + OwnerKeyType::tryFrom(self::text($switches, 'owner_key', 'string')) ?? throw $invalid('owner_key'), + IdType::parse(self::text($switches, 'owner_key_type', 'bigint')) ?? throw $invalid('owner_key_type'), + TranslationsMode::tryFrom(self::text($switches, 'translations', 'lang')) ?? throw $invalid('translations'), + ($switches['categories_soft_deletes'] ?? false) === true, + ($switches['definitions_table'] ?? false) === true, + SchemaNames::fromConfig($tables), + $stores, + ); + } + + /** @return array what the schema file returns */ + public function toArray(): array + { + $stores = []; + + foreach ($this->stores as $name => $store) { + $stores[$name] = $store->toArray(); + } + + ksort($stores); + + return [ + 'shape_version' => $this->version, + 'switches' => [ + 'identity' => $this->identity->value, + 'ids' => $this->ids->value, + 'owner_key' => $this->ownerKey->value, + 'owner_key_type' => $this->ownerKeyType->value, + 'translations' => $this->translations->value, + 'categories_soft_deletes' => $this->categoriesSoftDeletes, + 'definitions_table' => $this->definitionsTable, + ], + 'tables' => $this->names->toArray(), + 'stores' => $stores, + ]; + } + + /** The recorded entry of a store, or the default shape for a store not recorded. */ + public function store(StoreName $name): StoreSchema + { + return $this->stores[$name->value] ?? new StoreSchema($name); + } + + public function hasStore(StoreName $name): bool + { + return isset($this->stores[$name->value]); + } + + /** A copy with one more store entry (an existing entry is kept: it describes a table already created). */ + public function withStore(StoreSchema $store): self + { + if ($this->hasStore($store->name)) { + return $this; + } + + return new self($this->version, $this->identity, $this->ids, $this->ownerKey, $this->ownerKeyType, $this->translations, $this->categoriesSoftDeletes, $this->definitionsTable, $this->names, [...$this->stores, $store->name->value => $store]); + } + + /** + * Every difference from another shape, one line each (`identity: slug_uid → uid_only`). + * + * @return list + */ + public function differencesFrom(self $other): array + { + $differences = []; + $mine = self::flatten($this->toArray()); + $theirs = self::flatten($other->toArray()); + + foreach (array_unique([...array_keys($theirs), ...array_keys($mine)]) as $path) { + if ($path === 'shape_version') { + continue; + } + + $from = $theirs[$path] ?? null; + $to = $mine[$path] ?? null; + + if ($from !== $to) { + $differences[] = sprintf('%s: %s → %s', $path, $this->show($from), $this->show($to)); + } + } + + return $differences; + } + + /** + * @param array $settings + * + * @return array the stores with a database layer + */ + private static function storesFromConfig(array $settings, IdType $ownerKeyType, StoreName $default): array + { + $layers = self::section($settings, 'layers'); + $stores = []; + + foreach (self::section($settings, 'stores') as $name => $config) { + if (! is_array($config)) { + continue; + } + + $database = null; + + foreach ((array) ($config['layers'] ?? []) as $layer) { + $layerConfig = is_string($layer) ? ($layers[$layer] ?? null) : null; + + if (is_array($layerConfig) && ($layerConfig['driver'] ?? null) === 'database') { + $database = $layerConfig; + + break; + } + } + + if ($database === null) { + continue; + } + + try { + $storeName = new StoreName((string) $name); + } catch (InvalidIdentifier $exception) { + throw new InvalidConfiguration(sprintf('laranail.settings.stores.%s: %s', $name, $exception->getMessage()), 0, $exception); + } + + $connection = $database['connection'] ?? null; + $stores[$storeName->value] = StoreSchema::fromConfig($storeName, $config, is_string($connection) ? $connection : null, $ownerKeyType, $default); + } + + foreach ($stores as $store) { + if ($store->fallback instanceof StoreName && ($stores[$store->fallback->value] ?? null)?->mode === StoreMode::Dedicated) { + throw new InvalidConfiguration(sprintf('laranail.settings.stores.%s.fallback: [%s] is dedicated too, so it has no global rows either.', $store->name, $store->fallback)); + } + } + + return $stores; + } + + /** + * @template T of \BackedEnum + * + * @param array $section + * @param T $default + * @param callable(string): (T|null) $parse + * + * @return T + */ + private static function enum(array $section, string $key, BackedEnum $default, callable $parse, string $message): BackedEnum + { + $value = $section[$key] ?? null; + + if ($value === null) { + return $default; + } + + return (is_string($value) ? $parse($value) : null) ?? throw new InvalidConfiguration($message); + } + + /** + * @param array $data + * + * @return array + */ + private static function section(array $data, string $key): array + { + $value = $data[$key] ?? []; + + return is_array($value) ? $value : throw new InvalidConfiguration(sprintf('laranail.settings.%s: an array is required.', $key)); + } + + /** @param array $data */ + private static function text(array $data, string $key, string $default): string + { + $value = $data[$key] ?? $default; + + return is_string($value) ? $value : $default; + } + + /** + * @param array $data + * + * @return array + */ + private static function flatten(array $data, string $prefix = ''): array + { + $flat = []; + + foreach ($data as $key => $value) { + $path = $prefix === '' ? (string) $key : $prefix . '.' . $key; + + if (is_array($value)) { + $flat += self::flatten($value, $path); + } else { + $flat[$path] = $value; + } + } + + return $flat; + } + + private function show(mixed $value): string + { + return match (true) { + $value === null => 'none', + is_bool($value) => $value ? 'true' : 'false', + is_scalar($value) => (string) $value, + default => get_debug_type($value), + }; + } +} diff --git a/src/Database/SchemaShapeRepository.php b/src/Database/SchemaShapeRepository.php new file mode 100644 index 0000000..68057fb --- /dev/null +++ b/src/Database/SchemaShapeRepository.php @@ -0,0 +1,149 @@ +path; + } + + public function exists(): bool + { + return $this->files->isFile($this->path); + } + + /** + * The recorded shape, or null when nothing is recorded yet. + * + * @throws InvalidConfiguration when the file does not return a valid shape + */ + public function recorded(): ?SchemaShape + { + if (! $this->exists()) { + return null; + } + + try { + $data = $this->files->getRequire($this->path); + } catch (Throwable $exception) { + throw new InvalidConfiguration(sprintf('The schema file [%s] could not be read: %s', $this->path, $exception->getMessage()), 0, $exception); + } + + return is_array($data) + ? SchemaShape::fromArray($data) + : throw new InvalidConfiguration(sprintf('The schema file [%s] must return an array.', $this->path)); + } + + /** The shape the current configuration describes. */ + public function configured(): SchemaShape + { + return ($this->configured)(); + } + + /** What the runtime and the migrations use: the recorded shape, else the configured one. */ + public function current(): SchemaShape + { + return $this->current ??= $this->recorded() ?? $this->configured(); + } + + /** + * Record the configured shape. Anything already recorded wins: its switches and its stores + * describe tables that may already exist, so only stores new to the file are added. + */ + public function record(): SchemaShape + { + $recorded = $this->recorded(); + $configured = $this->configured(); + $shape = $recorded ?? $configured; + + foreach ($configured->stores as $store) { + $shape = $shape->withStore($store); + } + + $this->write($shape); + + return $shape; + } + + /** Record one more store (make-store); the rest of the file is kept as it is. */ + public function recordStore(StoreSchema $store): SchemaShape + { + $shape = ($this->recorded() ?? $this->configured())->withStore($store); + $this->write($shape); + + return $shape; + } + + public function write(SchemaShape $shape): void + { + $this->files->ensureDirectoryExists(dirname($this->path)); + $this->files->put($this->path, $this->render($shape)); + $this->current = $shape; + } + + private function render(SchemaShape $shape): string + { + return <<export($shape->toArray(), 0)}; + + PHP; + } + + /** var_export with short arrays and stable indentation. */ + private function export(mixed $value, int $depth): string + { + if (! is_array($value)) { + return var_export($value, true); + } + + if ($value === []) { + return '[]'; + } + + $indent = str_repeat(' ', $depth + 1); + $lines = []; + + foreach ($value as $key => $item) { + $lines[] = $indent . var_export($key, true) . ' => ' . $this->export($item, $depth + 1) . ','; + } + + return "[\n" . implode("\n", $lines) . "\n" . str_repeat(' ', $depth) . ']'; + } +} diff --git a/src/Database/StoreSchema.php b/src/Database/StoreSchema.php new file mode 100644 index 0000000..4925fca --- /dev/null +++ b/src/Database/StoreSchema.php @@ -0,0 +1,166 @@ +` entry. `$connection` is the store's database + * layer connection (resolved by the caller from its layers); `$ownerKeyType` is the owner + * key type when the entry does not set one (laranail.db-tools.id_type). + * + * @param array $config + */ + public static function fromConfig(StoreName $name, array $config, ?string $connection, IdType $ownerKeyType, StoreName $default): self + { + $path = 'laranail.settings.stores.' . $name->value; + $mode = $config['mode'] ?? StoreMode::Polymorphic->value; + $mode = is_string($mode) ? StoreMode::tryFrom($mode) : null; + + if (! $mode instanceof StoreMode) { + throw new InvalidConfiguration($path . '.mode: use [polymorphic] or [dedicated].'); + } + + $softDeletes = $config['soft_deletes'] ?? false; + + if (! is_bool($softDeletes)) { + throw new InvalidConfiguration($path . '.soft_deletes: true or false.'); + } + + $table = $config['table'] ?? null; + + if ($table !== null && ! is_string($table)) { + throw new InvalidConfiguration($path . '.table: a table name is required.'); + } + + if ($mode === StoreMode::Polymorphic) { + return new self($name, $mode, $softDeletes, $table, $connection); + } + + $owners = $config['owners'] ?? []; + + if (! is_array($owners) || count($owners) !== 1 || ! is_string($owners[array_key_first($owners)])) { + throw new InvalidConfiguration($path . '.owners: a dedicated store holds exactly one owner alias.'); + } + + $owner = $config['owner'] ?? []; + + if (! is_array($owner) || ! is_string($owner['table'] ?? null)) { + throw new InvalidConfiguration($path . '.owner.table: a dedicated store names the table its owners live in.'); + } + + $key = $owner['key'] ?? 'id'; + $type = $owner['type'] ?? null; + $parsedType = is_string($type) ? IdType::parse($type) : $ownerKeyType; + + if (! is_string($key) || ! $parsedType instanceof IdType) { + throw new InvalidConfiguration($path . '.owner: `key` is a column name and `type` one of bigint, uuid, ulid.'); + } + + $fallback = $config['fallback'] ?? $default->value; + + try { + $fallbackName = new StoreName(is_string($fallback) ? $fallback : ''); + } catch (InvalidIdentifier $exception) { + throw new InvalidConfiguration($path . '.fallback: ' . $exception->getMessage(), 0, $exception); + } + + if ($fallbackName->value === $name->value) { + throw new InvalidConfiguration($path . '.fallback: a dedicated store has no global rows, so its fallback must be another store.'); + } + + return new self($name, $mode, $softDeletes, $table, $connection, $owners[array_key_first($owners)], $owner['table'], $key, $parsedType, $fallbackName); + } + + /** @param array $entry one entry of the schema file's `stores` */ + public static function fromArray(StoreName $name, array $entry): self + { + $mode = StoreMode::tryFrom(self::text($entry, 'mode') ?? 'polymorphic') + ?? throw new InvalidConfiguration(sprintf('Schema file: store [%s] has an unknown mode.', $name)); + $fallback = self::text($entry, 'fallback'); + + return new self( + $name, + $mode, + ($entry['soft_deletes'] ?? false) === true, + self::text($entry, 'table'), + self::text($entry, 'connection'), + self::text($entry, 'owner_alias'), + self::text($entry, 'owner_table'), + self::text($entry, 'owner_key') ?? 'id', + IdType::parse(self::text($entry, 'owner_key_type') ?? 'bigint') ?? IdType::Bigint, + $fallback === null ? null : new StoreName($fallback), + ); + } + + /** @return array the entry written to the schema file */ + public function toArray(): array + { + return [ + 'mode' => $this->mode->value, + 'soft_deletes' => $this->softDeletes, + 'table' => $this->table, + 'connection' => $this->connection, + 'owner_alias' => $this->ownerAlias, + 'owner_table' => $this->ownerTable, + 'owner_key' => $this->mode === StoreMode::Dedicated ? $this->ownerKey : null, + 'owner_key_type' => $this->mode === StoreMode::Dedicated ? $this->ownerKeyType->value : null, + 'fallback' => $this->fallback?->value, + ]; + } + + public function isDedicated(): bool + { + return $this->mode === StoreMode::Dedicated; + } + + /** @param array $entry */ + private static function text(array $entry, string $key): ?string + { + $value = $entry[$key] ?? null; + + return is_string($value) && $value !== '' ? $value : null; + } +} diff --git a/src/Definitions/DatabaseDefinitions.php b/src/Definitions/DatabaseDefinitions.php new file mode 100644 index 0000000..8d00f05 --- /dev/null +++ b/src/Definitions/DatabaseDefinitions.php @@ -0,0 +1,149 @@ +> */ + private array $loaded = []; + + /** @param list $allowedRules rule names a stored rule may use */ + public function __construct( + private readonly CasterRegistry $casters, + private readonly ValueEncoder $encoder, + private readonly array $allowedRules, + private readonly bool $enabled = true, + ) {} + + /** A label as text: itself, or (json mode) the entry for any locale, else the first one. */ + public static function localised(?string $stored, bool $json): ?string + { + if ($stored === null || ! $json) { + return $stored; + } + + $decoded = json_decode($stored, true); + + if (! is_array($decoded)) { + return $stored; + } + + $text = $decoded[''] ?? reset($decoded); + + return is_string($text) ? $text : null; + } + + public function find(Store $store, Key $key): ?Definition + { + if (! $this->enabled) { + return null; + } + + $database = $store->database(); + + if (! $database instanceof DatabaseDriver || ! $database->shape()->definitionsTable) { + return null; + } + + return ($this->loaded[$store->name->value] ??= $this->load($store, $database))[$key->value] ?? null; + } + + /** @return array */ + private function load(Store $store, DatabaseDriver $database): array + { + $names = $database->names(); + $rows = $database->attempt($store->name, static fn (): array => $database->connection() + ->table($names->definitions() . ' as d') + ->leftJoin($names->categories() . ' as c', 'c.id', '=', 'd.category_id') + ->where('d.store', $store->name->value) + ->where('d.is_system', false) + ->get(['d.*', 'c.slug as category_slug']) + ->map(static fn (object $row): array => (array) $row) + ->all()); + $json = $database->shape()->translations === TranslationsMode::Json; + $definitions = []; + + foreach ($rows as $row) { + $definition = $this->definition($store, $row, $json); + $definitions[$definition->key->value] = $definition; + } + + return $definitions; + } + + /** @param array $row */ + private function definition(Store $store, array $row, bool $json): Definition + { + $text = static fn (string $column): ?string => is_string($row[$column] ?? null) && $row[$column] !== '' ? $row[$column] : null; + $flag = static fn (string $column): bool => in_array($row[$column] ?? false, [true, 1, '1'], true); + $key = new Key($text('key') ?? throw new InvalidDefinition('A definitions row has no key.')); + $type = $text('type'); + + if ($type !== null && ! $this->casters->has($type)) { + throw new InvalidDefinition(sprintf('Definitions table: setting [%s] uses unknown type [%s]; register a caster for it.', $key, $type)); + } + + $default = $text('default'); + $inherits = $row['inherits'] ?? null; + + return new Definition( + store: $store->name, + key: $key, + type: $type, + default: $default === null ? null : $this->encoder->decode($key, $default), + hasDefault: $default !== null, + rules: $this->rules($text('rules')), + encrypted: $flag('is_encrypted'), + public: $flag('is_public'), + locked: $flag('is_locked'), + inherits: $inherits === null ? null : in_array($inherits, [true, 1, '1'], true), + overridableBy: $this->strings($text('overridable_by')), + label: self::localised($text('label'), $json), + description: self::localised($text('description'), $json), + category: $text('category_slug'), + group: $text('group'), + ); + } + + /** @return list the stored rules whose name is allowed */ + private function rules(?string $json): array + { + return array_values(array_filter( + $this->strings($json), + fn (string $rule): bool => in_array(explode(':', $rule, 2)[0], $this->allowedRules, true), + )); + } + + /** @return list */ + private function strings(?string $json): array + { + $decoded = $json === null ? null : json_decode($json, true); + + return is_array($decoded) ? array_values(array_filter($decoded, is_string(...))) : []; + } +} diff --git a/src/Definitions/DefinitionRegistry.php b/src/Definitions/DefinitionRegistry.php index 74370aa..9691b7d 100644 --- a/src/Definitions/DefinitionRegistry.php +++ b/src/Definitions/DefinitionRegistry.php @@ -17,6 +17,9 @@ */ final class DefinitionRegistry { + /** Names under `laranail.settings.definitions` that are options (D-6), not setting keys. */ + public const array OPTIONS = ['table', 'sources', 'allowed_rules']; + /** @var array */ private array $definitions = []; @@ -52,6 +55,19 @@ public function find(StoreName $store, Key $key): ?Definition return $this->definitions[$this->index($store, $key)] ?? null; } + /** + * Every definition registered in code and config, in registration order (the definitions + * table sync copies them as `is_system` rows). + * + * @return list + */ + public function all(): array + { + $this->loadConfigured(); + + return array_values($this->definitions); + } + private function loadConfigured(): void { if ($this->configLoaded) { @@ -61,6 +77,10 @@ private function loadConfigured(): void $this->configLoaded = true; foreach ($this->configured as $key => $attributes) { + if (in_array($key, self::OPTIONS, true)) { + continue; + } + if (! is_array($attributes)) { throw new InvalidDefinition(sprintf('laranail.settings.definitions.%s: an array of attributes is required.', $key)); } diff --git a/src/Drivers/DatabaseDriver.php b/src/Drivers/DatabaseDriver.php index 0403fd9..7649809 100644 --- a/src/Drivers/DatabaseDriver.php +++ b/src/Drivers/DatabaseDriver.php @@ -15,14 +15,20 @@ use Simtabi\Laranail\Settings\Data\Scope; use Simtabi\Laranail\Settings\Data\Locale; use Simtabi\Laranail\Settings\Data\Record; +use Simtabi\Laranail\Settings\Enums\IdType; use Simtabi\Laranail\Settings\Data\OwnerRef; use Simtabi\Laranail\Settings\Data\RecordSet; use Simtabi\Laranail\Settings\Data\StoreName; +use Simtabi\Laranail\Settings\Enums\IdentityMode; +use Simtabi\Laranail\Settings\Enums\OwnerKeyType; use Simtabi\Laranail\Settings\Database\SchemaNames; +use Simtabi\Laranail\Settings\Database\SchemaShape; +use Simtabi\Laranail\Settings\Database\StoreSchema; use Illuminate\Database\ConnectionResolverInterface; use Simtabi\Laranail\Settings\Contracts\DatabaseBacked; use Simtabi\Laranail\Settings\Contracts\ReadinessProbe; use Simtabi\Laranail\Settings\Exceptions\DriverFailure; +use Simtabi\Laranail\Settings\Exceptions\OwnerNotAllowed; use Simtabi\Laranail\Settings\Exceptions\StoreNotWritable; use Illuminate\Database\UniqueConstraintViolationException; use Simtabi\Laranail\Settings\Exceptions\DriverUnavailable; @@ -40,6 +46,12 @@ * first write) does not abort the surrounding transaction on Postgres. Either conflict raises * {@see ConcurrentModification}. Database errors surface as {@see DriverUnavailable} when the * connection or table is gone, {@see DriverFailure} otherwise, never as PDO exceptions. + * + * The table's shape (identity columns, key type, owner columns, soft deletes) is read from the + * recorded {@see SchemaShape}, never from live configuration (§4.0). With soft deletes a forget + * trashes the row, reads skip trashed rows, and the next write to that identity restores the + * row through the same version check (so a restore is never read as a conflict and the unique + * index never collides). */ final readonly class DatabaseDriver implements DatabaseBacked { @@ -48,6 +60,7 @@ /** * @param ?string $table the store's configured table (`stores..table`); null uses the store name * @param Closure(): ReadinessProbe $probe resolved only after a database error + * @param (Closure(): SchemaShape)|null $shape the recorded schema shape; null is the default shape over $names */ public function __construct( private ConnectionResolverInterface $db, @@ -56,8 +69,38 @@ public function __construct( private ?string $table, private bool $writable, private Closure $probe, + private ?Closure $shape = null, ) {} + /** + * A new primary key for a table keyed by this type: none for bigint (the database assigns + * it), a time-ordered UUID or a ULID otherwise. + * + * @return array{id?: string} + */ + public static function newId(IdType $type): array + { + return match ($type) { + IdType::Bigint => [], + IdType::Uuid => ['id' => (string) Str::orderedUuid()], + IdType::Ulid => ['id' => (string) Str::ulid()], + }; + } + + /** The recorded schema shape the table was created with. */ + public function shape(): SchemaShape + { + $shape = $this->shape instanceof Closure ? ($this->shape)() : null; + + return $shape instanceof SchemaShape ? $shape : new SchemaShape(names: $this->names); + } + + /** One store's recorded entry: mode, soft deletes, owner table. */ + public function schemaOf(StoreName $store): StoreSchema + { + return $this->shape()->store($store); + } + public function database(): self { return $this; @@ -81,12 +124,14 @@ public function connectionName(): string public function tableFor(StoreName $store): string { - return $this->names->store($store, $this->table); + $shape = $this->shape(); + + return $shape->names->store($store, $shape->hasStore($store) ? $shape->store($store)->table : $this->table); } public function names(): SchemaNames { - return $this->names; + return $this->shape()->names; } public function connection(): Connection @@ -118,7 +163,7 @@ public function load(StoreName $store, array $scopes): RecordSet $records = []; foreach (array_chunk($values, 500) as $chunk) { - foreach ($this->table($store)->whereIn('scope', $chunk)->get(self::COLUMNS) as $row) { + foreach ($this->live($store)->whereIn('scope', $chunk)->get(self::COLUMNS) as $row) { $records[] = $this->record((array) $row); } } @@ -129,8 +174,9 @@ public function load(StoreName $store, array $scopes): RecordSet /** * Store a record whose version is one above the version the writer read: an update checked - * against that version; failing that, an insert. A row at any other version makes the insert - * hit the unique index, which is a concurrent change. + * against that version; with soft deletes, failing that, a restore of the trashed row at that + * version; failing that, an insert. A row at any other version makes the insert hit the + * unique index, which is a concurrent change. * * @throws ConcurrentModification */ @@ -143,9 +189,23 @@ public function put(StoreName $store, Record $record): void $now = $record->writtenAt ?? CarbonImmutable::now(); $columns = $this->columns($store, $record) + ['version' => $record->version, 'updated_at' => $now]; $expected = $record->version - 1; + $softDeletes = $this->schemaOf($store)->softDeletes; // Versions start at 1, so a first write (expected 0) has no row to update. - if ($expected > 0 && $this->identity($this->table($store), $record->scope, $record->key, $record->locale)->where('version', $expected)->update($columns) > 0) { + if ($expected > 0 && $this->live($store)->where('scope', $record->scope->value)->where('key', $record->key->value)->where('locale', $record->locale->value)->where('version', $expected)->update($columns) > 0) { + return; + } + + // A trashed row at the expected version: restore it as a fresh write, so no flag, + // label or category of the forgotten row comes back with it. + if ($expected > 0 && $softDeletes && $this->trashed($store)->where('scope', $record->scope->value)->where('key', $record->key->value)->where('locale', $record->locale->value)->where('version', $expected)->update($columns + [ + 'deleted_at' => null, + 'label' => null, + 'description' => null, + 'meta' => null, + 'autoload' => true, + 'sort_order' => 0, + ]) > 0) { return; } @@ -154,12 +214,10 @@ public function put(StoreName $store, Record $record): void try { // A savepoint: on Postgres a unique violation would otherwise abort the // whole surrounding transaction, not just this statement. - $this->connection()->transaction(fn (): bool => $this->table($store)->insert($columns + [ + $this->connection()->transaction(fn (): bool => $this->table($store)->insert($columns + $this->identityColumns($record) + [ 'scope' => $record->scope->value, 'key' => $record->key->value, 'locale' => $record->locale->value, - 'slug' => $record->key->slug(), - 'uid' => (string) Str::ulid(), 'autoload' => true, 'sort_order' => 0, 'created_at' => $now, @@ -171,11 +229,42 @@ public function put(StoreName $store, Record $record): void }); } + /** + * The version of the trashed row of this identity (0 when there is none, or the store keeps + * no trashed rows), so a write over it continues its version rather than colliding. + */ + public function trashedVersion(StoreName $store, Scope $scope, Key $key, Locale $locale): int + { + if (! $this->schemaOf($store)->softDeletes) { + return 0; + } + + $version = $this->attempt($store, fn (): mixed => $this->identity($this->trashed($store), $scope, $key, $locale)->value('version')); + + return is_numeric($version) ? (int) $version : 0; + } + + /** + * The live row of one identity read under a row lock (`SELECT … FOR UPDATE` where the + * database has one), for retrying a write after a conflict: a plain re-read under MySQL's + * REPEATABLE READ would see the old snapshot. + */ + public function lockedFind(StoreName $store, Scope $scope, Key $key, Locale $locale): ?Record + { + return $this->attempt($store, function () use ($store, $scope, $key, $locale): ?Record { + $row = $this->identity($this->live($store), $scope, $key, $locale)->lockForUpdate()->first(self::COLUMNS); + + return $row === null ? null : $this->record((array) $row); + }); + } + public function forget(StoreName $store, Scope $scope, Key $key, Locale $locale): void { $this->assertWritable($store); - $this->attempt($store, fn (): int => $this->identity($this->table($store), $scope, $key, $locale)->delete()); + $this->attempt($store, fn (): int => $this->schemaOf($store)->softDeletes + ? $this->identity($this->live($store), $scope, $key, $locale)->update(['deleted_at' => CarbonImmutable::now()]) + : $this->identity($this->table($store), $scope, $key, $locale)->delete()); } /** Remove every row of one scope; returns how many went. */ @@ -183,19 +272,22 @@ public function flushScope(StoreName $store, Scope $scope): int { $this->assertWritable($store); - return $this->attempt($store, fn (): int => $this->table($store)->where('scope', $scope->value)->delete()); + return $this->attempt($store, fn (): int => $this->schemaOf($store)->softDeletes + ? $this->live($store)->where('scope', $scope->value)->update(['deleted_at' => CarbonImmutable::now()]) + : $this->table($store)->where('scope', $scope->value)->delete()); } /** - * Every distinct owner scope of one alias in this store (`alias:`), for orphan pruning. - * A range on the binary-collated column rather than LIKE, whose `_` would match any character. + * Every distinct owner scope of one alias in this store (`alias:`) with live rows, for + * orphan pruning. A range on the binary-collated column rather than LIKE, whose `_` would + * match any character. * * @return list */ public function scopesOf(StoreName $store, string $alias): array { return $this->attempt($store, fn (): array => array_values(array_filter( - $this->table($store) + $this->live($store) ->where('scope', '>=', $alias . ':') ->where('scope', '<', $alias . ';') ->distinct() @@ -317,6 +409,19 @@ private function table(StoreName $store): Builder return $this->connection()->table($this->tableFor($store)); } + /** Rows that are not trashed (every row, without soft deletes). */ + private function live(StoreName $store): Builder + { + $query = $this->table($store); + + return $this->schemaOf($store)->softDeletes ? $query->whereNull('deleted_at') : $query; + } + + private function trashed(StoreName $store): Builder + { + return $this->table($store)->whereNotNull('deleted_at'); + } + private function identity(Builder $query, Scope $scope, Key $key, Locale $locale): Builder { return $query->where('scope', $scope->value)->where('key', $key->value)->where('locale', $locale->value); @@ -331,12 +436,9 @@ private function columns(StoreName $store, Record $record): array throw new InvalidSettingValue(sprintf('Setting [%s]: the group [%s] is longer than 64 characters; give the definition a shorter group.', $record->key, $group)); } - [$type, $id] = $this->owner($record->scope); $category = $this->categoryId($store, $record); - return [ - 'settable_type' => $type, - 'settable_id' => $id, + return $this->ownerColumns($store, $record->scope) + [ 'category_id' => $category, 'category_store' => $category === null ? null : $store->value, 'group' => $group, @@ -348,16 +450,66 @@ private function columns(StoreName $store, Record $record): array ]; } - /** @return array{?string, ?string} the morph alias and id of an owner scope, nulls for global */ - private function owner(Scope $scope): array + /** + * The owner columns of a row, per the store's mode: `settable_type` / `settable_id` (typed per + * `ids.owner_key`) in a polymorphic store, `owner_id` in a dedicated one, which holds owner + * rows only. + * + * @return array + * + * @throws OwnerNotAllowed + */ + private function ownerColumns(StoreName $store, Scope $scope): array { - if ($scope->isGlobal()) { - return [null, null]; + $schema = $this->schemaOf($store); + [$alias, $id] = $scope->isGlobal() ? [null, null] : explode(':', $scope->value, 2); + + if (! $schema->isDedicated()) { + $shape = $this->shape(); + + return [ + 'settable_type' => $alias, + 'settable_id' => $id === null || $shape->ownerKey === OwnerKeyType::String ? $id : $this->typedKey($store, $id, $shape->ownerKeyType), + ]; } - [$alias, $id] = explode(':', $scope->value, 2); + if ($alias === null || $id === null) { + throw new OwnerNotAllowed(sprintf('Store [%s] is dedicated to owner [%s] and holds no global values; write those to store [%s].', $store, $schema->ownerAlias, $schema->fallback)); + } + + if ($alias !== $schema->ownerAlias) { + throw new OwnerNotAllowed(sprintf('Store [%s] is dedicated to owner [%s], not [%s].', $store, $schema->ownerAlias, $alias)); + } + + return ['owner_id' => $this->typedKey($store, $id, $schema->ownerKeyType)]; + } - return [$alias, $id]; + /** An owner id as the typed column holds it: an integer for bigint keys. */ + private function typedKey(StoreName $store, string $id, IdType $type): int|string + { + return match ($type) { + IdType::Bigint => ctype_digit($id) ? (int) $id : throw new OwnerNotAllowed(sprintf('Store [%s] types owner keys as bigint; [%s] is not one.', $store, $id)), + IdType::Uuid => strlen($id) === 36 ? $id : throw new OwnerNotAllowed(sprintf('Store [%s] types owner keys as uuid; [%s] is not one.', $store, $id)), + IdType::Ulid => strlen($id) === 26 ? $id : throw new OwnerNotAllowed(sprintf('Store [%s] types owner keys as ulid; [%s] is not one.', $store, $id)), + }; + } + + /** + * The columns only an insert sets: a generated primary key (uuid, ulid) and the identity + * columns of the identity mode (D-1). + * + * @return array + */ + private function identityColumns(Record $record): array + { + $shape = $this->shape(); + $columns = self::newId($shape->ids); + + return $columns + match ($shape->identity) { + IdentityMode::SlugUid => ['slug' => $record->key->slug(), 'uid' => (string) Str::ulid()], + IdentityMode::SlugPerRow => ['slug' => sha1($record->scope->value . '|' . $record->key->value . '|' . $record->locale->value)], + IdentityMode::UidOnly => ['uid' => (string) Str::ulid()], + }; } /** @@ -372,7 +524,12 @@ private function categoryId(StoreName $store, Record $record): int|string|null return null; } - $categories = $this->connection()->table($this->names->categories())->where('slug', $record->category); + $categories = $this->connection()->table($this->names()->categories())->where('slug', $record->category); + + if ($this->shape()->categoriesSoftDeletes) { + $categories->whereNull('deleted_at'); + } + $id = (clone $categories)->where('store', $store->value)->value('id'); if (is_int($id) || is_string($id)) { diff --git a/src/Drivers/DriverFactory.php b/src/Drivers/DriverFactory.php index 8621d06..f37fcb9 100644 --- a/src/Drivers/DriverFactory.php +++ b/src/Drivers/DriverFactory.php @@ -10,6 +10,7 @@ use Simtabi\Laranail\Settings\Data\LayerConfig; use Simtabi\Laranail\Settings\Enums\DriverType; use Simtabi\Laranail\Settings\Database\SchemaNames; +use Simtabi\Laranail\Settings\Database\SchemaShape; use Illuminate\Database\ConnectionResolverInterface; use Illuminate\Contracts\Filesystem\Factory as Disks; use Simtabi\Laranail\Settings\Contracts\ReadinessProbe; @@ -35,6 +36,7 @@ public function __construct( private readonly ?ConnectionResolverInterface $db = null, private readonly SchemaNames $names = new SchemaNames, private readonly ?Closure $probe = null, + private readonly ?Closure $shape = null, ) {} /** @param Closure(LayerConfig): Driver $factory */ @@ -91,7 +93,8 @@ public function make(LayerConfig $layer): Driver /** * The database layer. `connection` is optional (null = the default connection); `table` is - * set by the store registry from `stores..table`. Nothing connects here. + * set by the store registry from `stores..table`. The driver reads the recorded schema + * shape through `$shape` on use. Nothing connects here. */ private function database(LayerConfig $layer): DatabaseDriver { @@ -113,7 +116,10 @@ private function database(LayerConfig $layer): DatabaseDriver /** @var Closure(): ReadinessProbe $probe */ $probe = $this->probe; - return new DatabaseDriver($this->db, $connection, $this->names, $table, $layer->writable, $probe); + /** @var (Closure(): SchemaShape)|null $shape */ + $shape = $this->shape; + + return new DatabaseDriver($this->db, $connection, $this->names, $table, $layer->writable, $probe, $shape); } private function json(LayerConfig $layer): JsonDriver diff --git a/src/Enums/Ability.php b/src/Enums/Ability.php index 707d79c..8f2a29d 100644 --- a/src/Enums/Ability.php +++ b/src/Enums/Ability.php @@ -68,6 +68,9 @@ enum Ability: string implements Enumerator #[Label('Manage stores')] case ManageStores = 'manage_stores'; + #[Label('Prune orphans and old audit entries')] + case Prune = 'prune'; + /** The gate the gate authorizer asks for this ability. */ public function gateName(): string { diff --git a/src/Enums/AuditAction.php b/src/Enums/AuditAction.php index 94e39ac..2b0732d 100644 --- a/src/Enums/AuditAction.php +++ b/src/Enums/AuditAction.php @@ -66,6 +66,9 @@ enum AuditAction: string implements Enumerator #[Label('Manage stores')] case ManageStores = 'manage_stores'; + #[Label('Prune orphans and old audit entries')] + case Prune = 'prune'; + #[Label('Configure')] case Configure = 'configure'; diff --git a/src/Enums/IdType.php b/src/Enums/IdType.php new file mode 100644 index 0000000..b75dab9 --- /dev/null +++ b/src/Enums/IdType.php @@ -0,0 +1,39 @@ +.mode`). + */ +enum StoreMode: string implements Enumerator +{ + use HasEnumeratorBehavior; + + #[Label('Polymorphic')] + #[Description('settable_type and settable_id: any listed owner alias, plus global rows. The default.')] + case Polymorphic = 'polymorphic'; + + #[Label('Dedicated')] + #[Description('A non-null owner_id foreign key to one owner table; owner rows only, the global value lives in the fallback store.')] + case Dedicated = 'dedicated'; +} diff --git a/src/Enums/TranslationsMode.php b/src/Enums/TranslationsMode.php new file mode 100644 index 0000000..2aa038c --- /dev/null +++ b/src/Enums/TranslationsMode.php @@ -0,0 +1,27 @@ + $owners) * @method static CategoryManager categories() * @method static PromotionReport promote(?PromotionRequest $request = null) + * @method static AuditQuery audit() * * @see SettingsContract */ @@ -95,6 +98,7 @@ public static function fake(): SettingsFake access: $access, runtime: $app->make(RuntimeConfiguration::class), storeActions: $app->make(StoreActions::class), + auditQuery: new QueryAudit($stores, $access), ), $log); self::swap($fake); diff --git a/src/Providers/SettingsServiceProvider.php b/src/Providers/SettingsServiceProvider.php index 2e68b7e..3c2bff8 100644 --- a/src/Providers/SettingsServiceProvider.php +++ b/src/Providers/SettingsServiceProvider.php @@ -14,6 +14,8 @@ use Illuminate\Filesystem\Filesystem; use Simtabi\Laranail\Settings\Data\Key; use Illuminate\Contracts\Session\Session; +use Simtabi\Laranail\Settings\Data\Actor; +use Simtabi\Laranail\Settings\Data\Scope; use Illuminate\Contracts\Auth\Access\Gate; use Illuminate\Queue\Events\JobProcessing; use Illuminate\Contracts\Config\Repository; @@ -32,6 +34,8 @@ use Simtabi\Laranail\Settings\Enums\AuditAction; use Illuminate\Contracts\Cache\Factory as Caches; use Simtabi\Laranail\Settings\Actions\FlushScope; +use Simtabi\Laranail\Settings\Actions\PruneAudit; +use Simtabi\Laranail\Settings\Actions\QueryAudit; use Simtabi\Laranail\Settings\Audit\LogAuditSink; use Simtabi\Laranail\Settings\Contracts\Settings; use Simtabi\Laranail\Settings\Contracts\Verifier; @@ -46,6 +50,7 @@ use Simtabi\Laranail\Settings\Actions\StoreActions; use Simtabi\Laranail\Settings\Contracts\Authorizer; use Simtabi\Laranail\Settings\Database\SchemaNames; +use Simtabi\Laranail\Settings\Database\SchemaShape; use Simtabi\Laranail\Settings\Stores\SettingWriter; use Simtabi\Laranail\Settings\Stores\StoreRegistry; use Simtabi\Laranail\Settings\Support\ValueEncoder; @@ -61,6 +66,7 @@ use Simtabi\Laranail\Settings\Casting\CasterRegistry; use Simtabi\Laranail\Settings\Console\PromoteCommand; use Simtabi\Laranail\Settings\Drivers\ReadOnlyValues; +use Simtabi\Laranail\Settings\Actions\SyncDefinitions; use Simtabi\Laranail\Settings\Audit\DatabaseAuditSink; use Simtabi\Laranail\Settings\Contracts\ActorResolver; use Simtabi\Laranail\Settings\Console\MakeStoreCommand; @@ -78,11 +84,15 @@ use Simtabi\Laranail\Settings\Stores\InstallationEvidence; use Simtabi\Laranail\Package\Tools\Commands\InstallCommand; use Simtabi\Laranail\Settings\Authorization\GateAuthorizer; +use Simtabi\Laranail\Settings\Exceptions\SettingsException; use Simtabi\Laranail\Settings\Authorization\ChainAuthorizer; use Simtabi\Laranail\Settings\Database\SchemaReadinessProbe; use Simtabi\Laranail\Settings\Support\LaravelValueEncrypter; use Simtabi\Laranail\Settings\Support\LaravelValueValidator; +use Simtabi\Laranail\Settings\Console\SyncDefinitionsCommand; +use Simtabi\Laranail\Settings\Database\SchemaShapeRepository; use Simtabi\Laranail\Settings\Definitions\DefinitionRegistry; +use Simtabi\Laranail\Settings\Definitions\DatabaseDefinitions; use Simtabi\Laranail\Settings\Exceptions\InvalidConfiguration; use Simtabi\Laranail\Settings\Authentication\GuardActorResolver; use Simtabi\Laranail\Settings\Actions\Categories\CategoryActions; @@ -115,15 +125,19 @@ public function configurePackage(Package $package): void ->name('laranail/settings') ->setPublishTagId('settings') ->hasConfigFile('settings') - ->hasMigrations(['create_settings_categories_table', 'create_settings_table', 'create_settings_audit_table']) - ->hasCommands([PromoteCommand::class, PruneOrphansCommand::class, PruneAuditCommand::class, MakeStoreCommand::class, DoctorCommand::class]) + ->hasMigrations(['create_settings_categories_table', 'create_settings_table', 'create_settings_audit_table', 'create_settings_definitions_table']) + ->hasCommands([PromoteCommand::class, PruneOrphansCommand::class, PruneAuditCommand::class, MakeStoreCommand::class, DoctorCommand::class, SyncDefinitionsCommand::class]) ->hasInstallCommand(static function (InstallCommand $command): void { $command ->startWith(static function (InstallCommand $command): void { self::refuseForeignTables($command); + self::recordSchema($command); }) ->publishConfigFile() - ->publishMigrations(); + ->publishMigrations() + ->endWith(static function (InstallCommand $command): void { + self::syncDefinitions($command); + }); }); } @@ -141,6 +155,11 @@ public function packageBooted(): void $events->listen(MigrationsEnded::class, $flush); $events->listen(JobProcessing::class, $flush); $events->listen('Laravel\\Octane\\Events\\RequestReceived', $flush); + + // Tenant switches (db-tools has no hook of its own): the tenancy packages' events, by name. + foreach (self::strings($app, 'laranail.settings.readiness.flush_on') as $event) { + $events->listen($event, $flush); + } } #[Override] @@ -159,7 +178,7 @@ public function packageRegistered(): void $this->app->singleton(DefinitionRegistry::class, static fn (Application $app): DefinitionRegistry => new DefinitionRegistry( new StoreName(self::string($app, 'laranail.settings.default', 'settings')), $app->make(CasterRegistry::class), - self::array($app, 'laranail.settings.definitions'), + in_array('config', self::definitionSources($app), true) ? self::array($app, 'laranail.settings.definitions') : [], )); $this->app->singleton(ReadinessProbe::class, static fn (Application $app): ReadinessProbe => new SchemaReadinessProbe( @@ -175,8 +194,23 @@ public function packageRegistered(): void $app->make(ConnectionResolverInterface::class), SchemaNames::fromConfig(self::array($app, 'laranail.settings.tables')), static fn (): ReadinessProbe => $app->make(ReadinessProbe::class), + static fn (): SchemaShape => $app->make(SchemaShapeRepository::class)->current(), )); + // The recorded schema shape (§4.0). Scoped: read once per request or job, never at boot. + $this->app->scoped(SchemaShapeRepository::class, static function (Application $app): SchemaShapeRepository { + $path = $app->make(Repository::class)->get('laranail.settings.schema.path'); + + return new SchemaShapeRepository( + $app->make(Filesystem::class), + is_string($path) && $path !== '' ? $path : $app->databasePath('settings-schema.php'), + static fn (): SchemaShape => SchemaShape::fromConfig( + self::array($app, 'laranail.settings'), + $app->make(Repository::class)->get('laranail.db-tools.id_type'), + ), + ); + }); + // Evidence that the application is being installed: the operator's flag, or // laranail/installer-headless (suggested, so class_exists-guarded) reporting an install // in progress. Read on first use, never at boot. @@ -231,6 +265,14 @@ static function (string $change) use ($app): void { $app->make(ValuePipeline::class), $app->make(Dispatcher::class), self::clock(), + $app->make(Repository::class)->get('laranail.settings.writes.retry_on_conflict', true) !== false, + static function (Store $store, Key $key, Scope $scope) use ($app): void { + $app->make(OperationalLogger::class)->info(sprintf('laranail/settings retried a write of [%s] in store [%s] for scope [%s] after a concurrent change.', $key, $store->name, $scope), [ + 'store' => $store->name->value, + 'key' => $key->value, + 'scope' => $scope->value, + ]); + }, )); $this->registerAccess(); @@ -253,22 +295,49 @@ static function (string $change) use ($app): void { $events, $app->make(Caches::class), static fn (Store $store, Key $key): ?Definition => $app->make(RuntimeConfiguration::class)->findDefinition($store->name, $key) - ?? $app->make(DefinitionRegistry::class)->find($store->name, $key), + ?? $app->make(DefinitionRegistry::class)->find($store->name, $key) + ?? $app->make(DatabaseDefinitions::class)->find($store, $key), ), $flush, ); }); + $this->app->scoped(DatabaseDefinitions::class, static fn (Application $app): DatabaseDefinitions => new DatabaseDefinitions( + $app->make(CasterRegistry::class), + $app->make(ValueEncoder::class), + self::strings($app, 'laranail.settings.definitions.allowed_rules'), + in_array('database', self::definitionSources($app), true), + )); + + $this->app->scoped(SyncDefinitions::class, static fn (Application $app): SyncDefinitions => new SyncDefinitions( + $app->make(StoreRegistry::class), + $app->make(DefinitionRegistry::class), + $app->make(ValueEncoder::class), + $app->make(AccessGuard::class), + )); + + $this->app->scoped(QueryAudit::class, static fn (Application $app): QueryAudit => new QueryAudit( + $app->make(StoreRegistry::class), + $app->make(AccessGuard::class), + )); + $this->app->scoped(PruneOrphans::class, static fn (Application $app): PruneOrphans => new PruneOrphans( $app->make(StoreRegistry::class), $app->make(StoreActions::class)->flush, static fn (string $alias): ?string => Relation::getMorphedModel($alias), + $app->make(AccessGuard::class), + )); + + $this->app->scoped(PruneAudit::class, static fn (Application $app): PruneAudit => new PruneAudit( + $app->make(StoreRegistry::class), + $app->make(AccessGuard::class), )); $this->app->bind(MakeStore::class, static fn (Application $app): MakeStore => new MakeStore( $app->make(Filesystem::class), dirname(__DIR__, 2) . '/database/migrations', $app->databasePath('migrations'), + $app->make(SchemaShapeRepository::class), )); $this->app->scoped(Settings::class, static fn (Application $app): Settings => new SettingsManager( @@ -280,6 +349,8 @@ static function (string $change) use ($app): void { access: $app->make(AccessGuard::class), runtime: $app->make(RuntimeConfiguration::class), storeActions: $app->make(StoreActions::class), + auditQuery: $app->make(QueryAudit::class), + databaseDefinitions: $app->make(DatabaseDefinitions::class), )); } @@ -299,6 +370,53 @@ private static function refuseForeignTables(InstallCommand $command): void } } + /** + * `definitions.sources` (D-6): which of `code`, `config` and `database` are read. Code + * definitions are registered by packages and the application in code and are always read. + * + * @return list + */ + private static function definitionSources(Application $app): array + { + $sources = $app->make(Repository::class)->get('laranail.settings.definitions.sources', ['code', 'config', 'database']); + + $names = is_array($sources) ? array_values(array_filter($sources, is_string(...))) : null; + + if ($names === null || count($names) !== count($sources) || array_diff($names, ['code', 'config', 'database']) !== []) { + throw new InvalidConfiguration('laranail.settings.definitions.sources: a list of code, config and database.'); + } + + return $names; + } + + /** + * Record the schema the published migrations will produce (§4.0), so the runtime reads that + * record rather than live configuration. An existing record is kept and only new stores are + * added to it. + */ + private static function recordSchema(InstallCommand $command): void + { + $shapes = $command->getLaravel()->make(SchemaShapeRepository::class); + $shapes->record(); + $command->info('Recorded the settings schema in ' . $shapes->path()); + } + + /** Copy code and config definitions into the definitions table, when it exists already. */ + private static function syncDefinitions(InstallCommand $command): void + { + try { + $report = $command->getLaravel()->make(SyncDefinitions::class)->handle(Actor::system('laranail::settings.install')); + } catch (SettingsException) { + $command->comment('Definitions were not synced (run the migrations, then laranail::settings.sync-definitions).'); + + return; + } + + if ($report['synced'] > 0) { + $command->info(sprintf('Synced %d definition(s) into the definitions table.', $report['synced'])); + } + } + private static function authorizer(Application $app, mixed $driver, string $path): Authorizer { return match ($driver) { diff --git a/src/Resolution/Resolver.php b/src/Resolution/Resolver.php index d17dbe8..c7085cf 100644 --- a/src/Resolution/Resolver.php +++ b/src/Resolution/Resolver.php @@ -21,6 +21,8 @@ * * owner → (if inheritance is allowed) each parent, in its own store → global → definition default * + * The global step reads the store itself, or a dedicated store's fallback store (§7.2). + * * At each step the store's layers are tried in order and the requested locale falls back to the * application's fallback locale and then to the unlocalised value. Absence moves on; a stored * null is an answer. Each store is read once per resolution, whatever the number of steps. @@ -95,8 +97,11 @@ public function resolve(Store $store, Key $key, Locale $locale, ?OwnerRef $owner */ private function plan(Store $store, ?OwnerRef $owner, array $parents, ?Definition $definition): array { + // A dedicated store has no global rows: its global step reads its fallback store. + $global = $this->stores->globalOf($store); + if (! $owner instanceof OwnerRef) { - return [[$store, Scope::global()]]; + return [[$global, Scope::global()]]; } $plan = [[$store, $owner->scope()]]; @@ -109,7 +114,7 @@ private function plan(Store $store, ?OwnerRef $owner, array $parents, ?Definitio $plan[] = [$this->stores->forOwner($parent->alias), $parent->scope()]; } - $plan[] = [$store, Scope::global()]; + $plan[] = [$global, Scope::global()]; return $plan; } diff --git a/src/SettingsManager.php b/src/SettingsManager.php index 43178cb..174ff61 100644 --- a/src/SettingsManager.php +++ b/src/SettingsManager.php @@ -18,7 +18,9 @@ use Simtabi\Laranail\Settings\Data\StoreName; use Illuminate\Contracts\Auth\Authenticatable; use Simtabi\Laranail\Settings\Data\Definition; +use Simtabi\Laranail\Settings\Audit\AuditQuery; use Simtabi\Laranail\Settings\Data\SettingWrite; +use Simtabi\Laranail\Settings\Actions\QueryAudit; use Simtabi\Laranail\Settings\Contracts\Settable; use Simtabi\Laranail\Settings\Contracts\Settings; use Simtabi\Laranail\Settings\Data\SettingTarget; @@ -37,6 +39,7 @@ use Simtabi\Laranail\Settings\Categories\CategoryManager; use Simtabi\Laranail\Settings\Exceptions\OwnerNotAllowed; use Simtabi\Laranail\Settings\Definitions\DefinitionRegistry; +use Simtabi\Laranail\Settings\Definitions\DatabaseDefinitions; use Simtabi\Laranail\Settings\Configuration\RuntimeConfiguration; /** @@ -71,6 +74,8 @@ public function __construct( private ?Actor $actingAs = null, private ?string $reason = null, private ?StoreActions $storeActions = null, + private ?QueryAudit $auditQuery = null, + private ?DatabaseDefinitions $databaseDefinitions = null, ) { $this->access = $access ?? AccessGuard::closed(); $this->actions = $actions ?? SettingActions::using($writer, $this->access); @@ -293,6 +298,16 @@ public function promote(?PromotionRequest $request = null): PromotionReport return $this->storeActions()->promote->handle($this->targetStore(), $request ?? new PromotionRequest, $this->actingAs); } + public function audit(): AuditQuery + { + $query = new AuditQuery( + $this->auditQuery ?? throw new LogicException('This settings handle was built without the audit query; resolve Settings from the container.'), + $this->actingAs, + ); + + return $this->storeName instanceof StoreName ? $query->store($this->storeName->value) : $query; + } + private function storeActions(): StoreActions { return $this->storeActions ?? throw new LogicException('This settings handle was built without store actions; resolve Settings from the container.'); @@ -365,10 +380,15 @@ private function activeLocale(): Locale return $this->selectedLocale ?? Locale::none(); } - /** A definition registered at runtime for this request wins over the shared registry. */ + /** + * A definition registered at runtime for this request wins over the shared registry (code and + * config); the definitions table answers only for keys neither covers (D-6). + */ private function definition(Store $store, Key $key): ?Definition { - return $this->runtime?->findDefinition($store->name, $key) ?? $this->definitions->find($store->name, $key); + return $this->runtime?->findDefinition($store->name, $key) + ?? $this->definitions->find($store->name, $key) + ?? $this->databaseDefinitions?->find($store, $key); } private function required(string $key): mixed @@ -407,6 +427,8 @@ private function with( $actor ?? $this->actingAs, $reason ?? $this->reason, $this->storeActions, + $this->auditQuery, + $this->databaseDefinitions, ); } } diff --git a/src/Stores/SettingWriter.php b/src/Stores/SettingWriter.php index e90b3da..8192c3a 100644 --- a/src/Stores/SettingWriter.php +++ b/src/Stores/SettingWriter.php @@ -16,25 +16,38 @@ use Simtabi\Laranail\Settings\Events\SettingSaved; use Simtabi\Laranail\Settings\Events\SettingSaving; use Simtabi\Laranail\Settings\Support\ValuePipeline; +use Simtabi\Laranail\Settings\Drivers\DatabaseDriver; use Simtabi\Laranail\Settings\Events\SettingForgotten; +use Simtabi\Laranail\Settings\Contracts\DatabaseBacked; use Simtabi\Laranail\Settings\Events\SettingForgetting; use Simtabi\Laranail\Settings\Exceptions\LockedSetting; use Simtabi\Laranail\Settings\Exceptions\UnknownSetting; use Simtabi\Laranail\Settings\Exceptions\OwnerNotAllowed; use Simtabi\Laranail\Settings\Exceptions\InvalidSettingValue; +use Simtabi\Laranail\Settings\Exceptions\ConcurrentModification; /** * Every write path: set, forget, lock, unlock. Checks run before anything is stored, in this * order: definition (strict stores) → owner allowed → lock and precedence → locale → value - * pipeline → the first writable layer, with the version continued from the existing record. + * pipeline → the first writable layer, with the version continued from the existing record + * (or from a trashed row, in a store with soft deletes, so the write restores it). + * + * A plain set that loses a race (another writer changed the row between the read and the + * write) is retried once when `writes.retry_on_conflict` is on, re-reading the row under a row + * lock; a write that names the version it expects is never retried. */ final readonly class SettingWriter { - /** @param Closure(): CarbonImmutable $clock */ + /** + * @param Closure(): CarbonImmutable $clock + * @param (Closure(Store, Key, Scope, ConcurrentModification): void)|null $onRetry told before a retry (logging) + */ public function __construct( private ValuePipeline $pipeline, private Dispatcher $events, private Closure $clock, + private bool $retryOnConflict = false, + private ?Closure $onRetry = null, ) {} /** Store a value and return the stored record. A locked row refuses it. */ @@ -43,6 +56,17 @@ public function set(Store $store, Key $key, Locale $locale, ?OwnerRef $owner, ?D return $this->write($store, $key, $locale, $owner, $definition, $value, overrideLock: false); } + /** + * Store a value only if this scope's row is still at `$expectedVersion` (0: no row yet). + * Anything else raises {@see ConcurrentModification}; it is never retried. + * + * @throws ConcurrentModification + */ + public function setExpecting(Store $store, Key $key, Locale $locale, ?OwnerRef $owner, ?Definition $definition, mixed $value, int $expectedVersion, bool $overrideLock = false): Record + { + return $this->write($store, $key, $locale, $owner, $definition, $value, $overrideLock, $expectedVersion); + } + /** * Store a value over a row lock. Only for a caller that has already established the right * to (an actor holding `override_lock` on a store whose locks are overridable); the lock @@ -87,14 +111,41 @@ public function unlock(Store $store, Key $key, Locale $locale, ?OwnerRef $owner, return $this->storeLock($store, $key, $locale, $owner, locked: false, definition: $definition); } - private function write(Store $store, Key $key, Locale $locale, ?OwnerRef $owner, ?Definition $definition, mixed $value, bool $overrideLock): Record + private function write(Store $store, Key $key, Locale $locale, ?OwnerRef $owner, ?Definition $definition, mixed $value, bool $overrideLock, ?int $expectedVersion = null): Record + { + $retries = $expectedVersion === null && $this->retryOnConflict ? 1 : 0; + + for ($attempt = 0; ; $attempt++) { + try { + return $this->writeOnce($store, $key, $locale, $owner, $definition, $value, $overrideLock, $expectedVersion, relocked: $attempt > 0); + } catch (ConcurrentModification $conflict) { + if ($attempt >= $retries) { + throw $conflict; + } + + if ($this->onRetry instanceof Closure) { + ($this->onRetry)($store, $key, $this->scope($owner), $conflict); + } + } + } + } + + private function writeOnce(Store $store, Key $key, Locale $locale, ?OwnerRef $owner, ?Definition $definition, mixed $value, bool $overrideLock, ?int $expectedVersion, bool $relocked): Record { $this->guard($store, $key, $locale, $owner, $definition, $overrideLock); $layer = $store->writableLayer(); $scope = $this->scope($owner); - $existing = $layer->driver->load($store->name, [$scope])->find($scope, $key, $locale); - $version = ($existing->version ?? 0) + 1; + $database = $this->database($layer); + $existing = $relocked && $database instanceof DatabaseDriver + ? $database->lockedFind($store->name, $scope, $key, $locale) + : $layer->driver->load($store->name, [$scope])->find($scope, $key, $locale); + + if ($expectedVersion !== null && ($existing->version ?? 0) !== $expectedVersion) { + throw new ConcurrentModification(sprintf('Setting [%s] in store [%s] for scope [%s] is at version %d, not the expected %d; re-read and retry.', $key, $store->name, $scope, $existing->version ?? 0, $expectedVersion)); + } + + $version = $this->baseVersion($layer, $store, $scope, $key, $locale, $existing) + 1; $record = new Record( scope: $scope, @@ -118,6 +169,24 @@ private function write(Store $store, Key $key, Locale $locale, ?OwnerRef $owner, return $record; } + /** + * The version a write continues: the live row's, else (soft deletes) the trashed row's, so + * the write restores it instead of colliding with it, else 0. + */ + private function baseVersion(Layer $layer, Store $store, Scope $scope, Key $key, Locale $locale, ?Record $existing): int + { + if ($existing instanceof Record) { + return $existing->version; + } + + return $this->database($layer)?->trashedVersion($store->name, $scope, $key, $locale) ?? 0; + } + + private function database(Layer $layer): ?DatabaseDriver + { + return $layer->driver instanceof DatabaseBacked && $layer->driver->isActive() ? $layer->driver->database() : null; + } + private function remove(Store $store, Key $key, Locale $locale, ?OwnerRef $owner, ?Definition $definition, bool $overrideLock): ?Record { $this->guard($store, $key, $locale, $owner, $definition, $overrideLock); @@ -144,7 +213,7 @@ private function storeLock(Store $store, Key $key, Locale $locale, ?OwnerRef $ow $layer = $store->writableLayer(); $scope = $this->scope($owner); $existing = $layer->driver->load($store->name, [$scope])->find($scope, $key, $locale) - ?? new Record($scope, $key, $locale, null, version: 0); + ?? new Record($scope, $key, $locale, null, version: $this->baseVersion($layer, $store, $scope, $key, $locale, null)); $record = new Record( $existing->scope, @@ -196,6 +265,10 @@ private function guard(Store $store, Key $key, Locale $locale, ?OwnerRef $owner, private function ownerAllowed(Store $store, ?OwnerRef $owner, ?Definition $definition): void { if (! $owner instanceof OwnerRef) { + if ($store->isDedicated()) { + throw new OwnerNotAllowed(sprintf('Store [%s] is dedicated to its owners and holds no global values; write those to store [%s].', $store->name, $store->fallback)); + } + return; } diff --git a/src/Stores/Store.php b/src/Stores/Store.php index dbba680..3e825c5 100644 --- a/src/Stores/Store.php +++ b/src/Stores/Store.php @@ -8,6 +8,7 @@ use Simtabi\Laranail\Settings\Data\Scope; use Simtabi\Laranail\Settings\Data\RecordSet; use Simtabi\Laranail\Settings\Data\StoreName; +use Simtabi\Laranail\Settings\Enums\StoreMode; use Simtabi\Laranail\Settings\Drivers\DatabaseDriver; use Simtabi\Laranail\Settings\Contracts\DatabaseBacked; use Simtabi\Laranail\Settings\Exceptions\StoreNotWritable; @@ -17,7 +18,8 @@ * `locksOverridable` (`locks.overridable`) lets an actor holding `override_lock` write a locked * setting; it is off by default, so a lock binds everyone. `bootstrap` lets the database layer be * skipped while the application is being installed (§7.4); `table` is the configured values - * table (`stores..table`), null for the store name. + * table (`stores..table`), null for the store name. A `dedicated` store (D-3) holds owner + * rows only; its global values are read from `fallback`. */ final readonly class Store { @@ -34,8 +36,15 @@ public function __construct( public bool $locksOverridable = false, public bool $bootstrap = false, public ?string $table = null, + public StoreMode $mode = StoreMode::Polymorphic, + public ?StoreName $fallback = null, ) {} + public function isDedicated(): bool + { + return $this->mode === StoreMode::Dedicated; + } + /** Whether any layer of this store is a database layer, whether or not it is active. */ public function hasDatabaseLayer(): bool { diff --git a/src/Stores/StoreRegistry.php b/src/Stores/StoreRegistry.php index a974680..63d361c 100644 --- a/src/Stores/StoreRegistry.php +++ b/src/Stores/StoreRegistry.php @@ -5,11 +5,13 @@ namespace Simtabi\Laranail\Settings\Stores; use Closure; +use Simtabi\Laranail\Settings\Enums\IdType; use Simtabi\Laranail\Settings\Data\StoreName; use Simtabi\Laranail\Settings\Contracts\Driver; use Simtabi\Laranail\Settings\Data\LayerConfig; use Simtabi\Laranail\Settings\Enums\DriverType; use Simtabi\Laranail\Settings\Database\SchemaNames; +use Simtabi\Laranail\Settings\Database\StoreSchema; use Simtabi\Laranail\Settings\Drivers\DriverFactory; use Simtabi\Laranail\Settings\Drivers\DatabaseDriver; use Simtabi\Laranail\Settings\Exceptions\UnknownStore; @@ -77,6 +79,12 @@ public function get(StoreName $name): Store return $this->all()[$name->value] ?? throw new UnknownStore(sprintf('Store [%s] is not configured in laranail.settings.stores.', $name)); } + /** Where a store's global values live: the store itself, or a dedicated store's fallback. */ + public function globalOf(Store $store): Store + { + return $store->fallback instanceof StoreName ? $this->get($store->fallback) : $store; + } + /** The one store whose owners include this alias. */ public function forOwner(string $alias): Store { @@ -148,6 +156,7 @@ private function build(): array } $bootstrap = ($config['bootstrap'] ?? false) === true; + $schema = StoreSchema::fromConfig($storeName, $config, null, IdType::Bigint, new StoreName($this->default)); $built[$storeName->value] = new Store( name: $storeName, @@ -158,6 +167,8 @@ private function build(): array locksOverridable: $this->locksOverridable($config['locks'] ?? [], $path . '.locks'), bootstrap: $bootstrap, table: $table, + mode: $schema->mode, + fallback: $schema->fallback, ); } @@ -165,6 +176,12 @@ private function build(): array throw new InvalidConfiguration(sprintf('laranail.settings.default: store [%s] is not configured.', $this->default)); } + foreach ($built as $store) { + if ($store->fallback instanceof StoreName && ($built[$store->fallback->value] ?? null)?->isDedicated() !== false) { + throw new InvalidConfiguration(sprintf('laranail.settings.stores.%s.fallback: [%s] must be a configured polymorphic store.', $store->name, $store->fallback)); + } + } + return $built; } diff --git a/src/Testing/SettingsFake.php b/src/Testing/SettingsFake.php index 05be6f4..e7a8307 100644 --- a/src/Testing/SettingsFake.php +++ b/src/Testing/SettingsFake.php @@ -12,6 +12,7 @@ use Simtabi\Laranail\Settings\Enums\Ability; use Illuminate\Contracts\Auth\Authenticatable; use Simtabi\Laranail\Settings\Data\AuditEntry; +use Simtabi\Laranail\Settings\Audit\AuditQuery; use Simtabi\Laranail\Settings\Enums\AuditAction; use Simtabi\Laranail\Settings\Contracts\Settable; use Simtabi\Laranail\Settings\Contracts\Settings; @@ -176,6 +177,11 @@ public function promote(?PromotionRequest $request = null): PromotionReport return $this->inner->promote($request); } + public function audit(): AuditQuery + { + return $this->inner->audit(); + } + public function assertSaved(string $key, mixed ...$value): void { $checksValue = $value !== []; diff --git a/tests/Arch/NoLiteralCredentialsTest.php b/tests/Arch/NoLiteralCredentialsTest.php index 7df8441..65144fe 100644 --- a/tests/Arch/NoLiteralCredentialsTest.php +++ b/tests/Arch/NoLiteralCredentialsTest.php @@ -8,7 +8,7 @@ // The floor is the number of PHP files under tests/ today. Raise it as the suite grows; a // scan that suddenly inspects fewer files has broken rather than found a clean tree. -const SETTINGS_TEST_FILE_FLOOR = 34; +const SETTINGS_TEST_FILE_FLOOR = 45; it('keeps literal credentials out of the tests', function (): void { $this->assertNoLiteralCredentialsIn([dirname(__DIR__)], minFiles: SETTINGS_TEST_FILE_FLOOR); diff --git a/tests/Feature/Database/AuditQueryTest.php b/tests/Feature/Database/AuditQueryTest.php new file mode 100644 index 0000000..0295b1a --- /dev/null +++ b/tests/Feature/Database/AuditQueryTest.php @@ -0,0 +1,98 @@ + ['user'], + 'stores.billing' => ['layers' => ['database']], + ], stores: ['billing']); +}); + +/** @param list $entries */ +function auditKeys(array $entries): array +{ + return array_map(static fn (AuditEntry $entry): string => $entry->action->value . ':' . ($entry->key ?? '-'), $entries); +} + +it('queries the audit trail by owner, store, key, action, outcome and time, newest first (§16.8)', function (): void { + $this->travelTo(now()->subDays(3)); + settings()->set('site.name', 'Old'); + $this->travelBack(); + settings()->set('site.name', 'Acme'); + settings()->for(new OwnerRef('user', 5))->set('theme', 'dark'); + settings()->for(new OwnerRef('user', 5))->lock('theme'); + settings()->store('billing')->set('currency', 'EUR'); + + expect(auditKeys(settings()->audit()->for(new OwnerRef('user', 5))->get()))->toBe(['lock:theme', 'update:theme']) + ->and(auditKeys(settings()->audit()->store('billing')->get()))->toBe(['update:currency']) + ->and(auditKeys(settings()->store('billing')->audit()->get()))->toBe(['update:currency']) + ->and(auditKeys(settings()->audit()->key('site.name')->since(now()->subDay())->get()))->toBe(['update:site.name']) + ->and(auditKeys(settings()->audit()->key('site.name')->until(now()->subDay())->get()))->toBe(['update:site.name']) + ->and(settings()->audit()->action(AuditAction::Lock)->outcome(AuditOutcome::Allowed)->get())->toHaveCount(1) + ->and(auditKeys(settings()->audit()->store('settings')->global()->get(1)))->toBe(['update:site.name']) + ->and(settings()->audit()->for(new OwnerRef('user', 5))->filter()->scope?->value)->toBe('user:5'); +}); + +it('streams and pages the trail, and maps every column back', function (): void { + foreach (range(1, 5) as $n) { + settings()->asSystem('batch')->set("k.n{$n}", $n); + } + + $first = settings()->audit()->paginate(2); + $second = settings()->audit()->paginate(2, $first->nextCursor); + $last = settings()->audit()->paginate(2, settings()->audit()->paginate(2, $second->nextCursor)->previousCursor); + $entry = settings()->audit()->cursor()->first(); + + expect($first->entries)->toHaveCount(2) + ->and($first->hasMore())->toBeTrue() + ->and($first->previousCursor)->toBeNull() + ->and($first->perPage)->toBe(2) + ->and($second->entries[0]->key)->not->toBe($first->entries[0]->key) + ->and($last->entries[0]->key)->toBe($second->entries[0]->key) + ->and(settings()->audit()->paginate(10)->hasMore())->toBeFalse() + ->and(settings()->audit()->cursor()->count())->toBe(5) + ->and($entry?->reason)->toBe('batch') + ->and($entry?->versionTo)->toBe(1) + ->and($entry?->actorType->value)->toBe('system'); +}); + +it('needs view_audit when an actor queries, and records the denial', function (): void { + settings()->set('site.name', 'Acme'); + + expect(fn (): array => settings()->as(user())->audit()->get())->toThrow(AccessDenied::class); + + allowGates(Ability::ViewAudit); + + expect(settings()->as(user())->audit()->outcome(AuditOutcome::Denied)->get()[0]->action)->toBe(AuditAction::ViewAudit); +}); + +it('cannot query a store whose trail is not in a database', function (): void { + config()->set('laranail.settings.stores.settings.layers', ['runtime']); + config()->set('laranail.settings.stores.billing.layers', ['runtime']); + app()->forgetScopedInstances(); + + expect(fn (): array => settings()->audit()->get())->toThrow(DriverUnavailable::class, 'cannot be queried'); +}); + +it('refuses a malformed audit row rather than inventing an entry, and ignores malformed meta', function (): void { + settings()->set('site.name', 'Acme'); + // Valid JSON that is not an object: a json column (MySQL, PostgreSQL) refuses text that is not JSON at all. + DB::table('settings_audit')->update(['meta' => json_encode('not an object')]); + + expect(settings()->audit()->get()[0]->meta)->toBe([]); + + DB::table('settings_audit')->update(['action' => 'teleport']); + + expect(fn (): array => settings()->audit()->get())->toThrow(DriverFailure::class, 'malformed'); +}); diff --git a/tests/Feature/Database/AuditTableTest.php b/tests/Feature/Database/AuditTableTest.php index 648a47e..3a4f12d 100644 --- a/tests/Feature/Database/AuditTableTest.php +++ b/tests/Feature/Database/AuditTableTest.php @@ -105,5 +105,7 @@ public function record(AuditEntry $entry): void $this->artisan('laranail::settings.prune-audit', ['--days' => '0'])->assertFailed(); $this->artisan('laranail::settings.prune-audit', ['--days' => 'soon'])->assertFailed(); - expect(DB::table('settings_audit')->count())->toBe(1); + // The kept row, plus the prune's own entry: the trail records who shortened it. + expect(DB::table('settings_audit')->count())->toBe(2) + ->and(DB::table('settings_audit')->where('action', 'prune')->value('actor_type'))->toBe('system'); }); diff --git a/tests/Feature/Database/CommandsTest.php b/tests/Feature/Database/CommandsTest.php index 6113ac3..3a61317 100644 --- a/tests/Feature/Database/CommandsTest.php +++ b/tests/Feature/Database/CommandsTest.php @@ -10,8 +10,13 @@ use Simtabi\Laranail\Settings\Data\StoreName; use Simtabi\Laranail\Settings\Actions\MakeStore; use Simtabi\Laranail\Settings\Exceptions\InvalidIdentifier; +use Simtabi\Laranail\Settings\Database\SchemaShapeRepository; use Simtabi\Laranail\Settings\Exceptions\InvalidConfiguration; +// Writes into the testbench application shared by every process (config/, database/), so it +// cannot run beside itself in parallel; the parallel mutation run leaves this group out. +pest()->group('shared-app'); + /** @return list */ function settingsMigrations(): array { @@ -28,7 +33,7 @@ function settingsMigrations(): array File::delete(config_path('laranail/settings.php')); }); -it('publishes the config and the three migrations on install', function (): void { +it('publishes the config and the four migrations on install, and records the schema', function (): void { config()->set('laranail.settings.stores.settings.layers', ['database', 'runtime', 'shipped']); $this->artisan('laranail::settings.install')->assertSuccessful(); @@ -36,7 +41,8 @@ function settingsMigrations(): array $names = array_map(static fn (string $path): string => preg_replace('/^\d{4}_\d{2}_\d{2}_\d{6}_/', '', basename($path)) ?? '', settingsMigrations()); sort($names); - expect($names)->toBe(['create_settings_audit_table.php', 'create_settings_categories_table.php', 'create_settings_table.php']); + expect($names)->toBe(['create_settings_audit_table.php', 'create_settings_categories_table.php', 'create_settings_definitions_table.php', 'create_settings_table.php']) + ->and(app(SchemaShapeRepository::class)->recorded()?->hasStore(new StoreName('settings')))->toBeTrue(); }); it('refuses to install over a table of the same name that is not its own (D-4)', function (): void { diff --git a/tests/Feature/Database/DedicatedStoreTest.php b/tests/Feature/Database/DedicatedStoreTest.php new file mode 100644 index 0000000..700d597 --- /dev/null +++ b/tests/Feature/Database/DedicatedStoreTest.php @@ -0,0 +1,84 @@ + ['team'], + 'stores.user_settings' => [ + 'layers' => ['database'], + 'owners' => ['user'], + 'mode' => 'dedicated', + 'owner' => ['table' => 'users'], + ] + $extra, + ], stores: ['user_settings'], ownerTables: ['users' => 'bigint']); + + DB::table('users')->insert([['id' => 1, 'name' => 'Ada'], ['id' => 2, 'name' => 'Grace']]); +} + +it('replaces settable_* with a non-null owner_id foreign key (D-3)', function (): void { + useDedicatedStore(); + + settings()->for(new OwnerRef('user', 1))->set('theme', 'dark'); + + expect(Schema::getColumnListing('user_settings'))->toContain('owner_id') + ->and(Schema::getColumnListing('user_settings'))->not->toContain('settable_type') + ->and((int) DB::table('user_settings')->value('owner_id'))->toBe(1) + ->and(DB::table('user_settings')->value('scope'))->toBe('user:1') + ->and(settings()->for(new OwnerRef('user', 1))->get('theme'))->toBe('dark') + ->and(collect(Schema::getForeignKeys('user_settings'))->pluck('foreign_table')->all())->toContain('users'); +}); + +it('holds owner rows only: a global write is refused and names the fallback store (D-3)', function (): void { + useDedicatedStore(); + + expect(fn () => settings()->store('user_settings')->set('theme', 'dark'))->toThrow(OwnerNotAllowed::class, 'store [settings]') + ->and(DB::table('user_settings')->count())->toBe(0); +}); + +it('reads its global value from the fallback store when owners inherit (§7.2)', function (): void { + useDedicatedStore(['inherits' => true]); + + settings()->set('theme', 'light'); + settings()->for(new OwnerRef('user', 2))->set('theme', 'dark'); + + expect(settings()->for(new OwnerRef('user', 1))->get('theme'))->toBe('light') + ->and(settings()->for(new OwnerRef('user', 2))->get('theme'))->toBe('dark') + ->and(settings()->store('user_settings')->get('theme'))->toBe('light') + ->and(settings()->for(new OwnerRef('user', 1))->explain('theme')->steps)->toContain('settings / global / (none) / database'); +}); + +it('removes an owner\'s rows with the owner, through the cascading foreign key', function (): void { + useDedicatedStore(); + settings()->for(new OwnerRef('user', 1))->set('theme', 'dark'); + + if (DB::getDriverName() === 'sqlite') { + DB::statement('PRAGMA foreign_keys = ON'); + } + + DB::table('users')->where('id', 1)->delete(); + + expect(DB::table('user_settings')->count())->toBe(0); +}); + +it('refuses a dedicated store without one owner alias, an owner table or a polymorphic fallback', function (array $store, string $message): void { + config()->set('laranail.settings.stores.user_settings', $store + ['layers' => ['runtime'], 'mode' => 'dedicated']); + + expect(fn () => app(StoreRegistry::class)->all())->toThrow(InvalidConfiguration::class, $message); +})->with([ + 'no owner alias' => [['owners' => [], 'owner' => ['table' => 'users']], 'exactly one owner alias'], + 'two owner aliases' => [['owners' => ['user', 'admin'], 'owner' => ['table' => 'users']], 'exactly one owner alias'], + 'no owner table' => [['owners' => ['user']], 'owner.table'], + 'itself as fallback' => [['owners' => ['user'], 'owner' => ['table' => 'users'], 'fallback' => 'user_settings'], 'must be another store'], + 'unknown fallback' => [['owners' => ['user'], 'owner' => ['table' => 'users'], 'fallback' => 'nowhere'], 'must be a configured polymorphic store'], + 'bad owner key type' => [['owners' => ['user'], 'owner' => ['table' => 'users', 'type' => 'serial']], '`type` one of'], + 'unknown mode' => [['mode' => 'shared'], 'use [polymorphic] or [dedicated]'], +]); diff --git a/tests/Feature/Database/DefinitionsTableTest.php b/tests/Feature/Database/DefinitionsTableTest.php new file mode 100644 index 0000000..6879a22 --- /dev/null +++ b/tests/Feature/Database/DefinitionsTableTest.php @@ -0,0 +1,171 @@ +insert($columns + [ + 'store' => 'settings', + 'slug' => str_replace('.', '-', $key), + 'key' => $key, + 'group' => explode('.', $key)[0], + 'is_system' => false, + 'created_at' => now(), + 'updated_at' => now(), + ]); +} + +it('syncs code and config definitions in as system rows and removes stale ones (D-6)', function (): void { + config()->set('laranail.settings.definitions', ['site.name' => ['type' => 'string', 'default' => 'Acme', 'label' => 'Site name']] + config('laranail.settings.definitions')); + useDatabase(['definitions.table' => true]); + settings()->categories()->create(new NewCategory('mail', 'Mail')); + app(DefinitionRegistry::class)->define('mail.password')->ofType('string')->withDefault(TestCredentials::password())->encrypted()->inCategory('mail')->register(); + DB::table('settings_definitions')->insert(['store' => 'settings', 'slug' => 'gone', 'key' => 'gone', 'group' => 'gone', 'is_system' => true, 'created_at' => now(), 'updated_at' => now()]); + + $report = app(SyncDefinitions::class)->handle(); + $password = DB::table('settings_definitions')->where('key', 'mail.password')->first(); + + expect($report)->toMatchArray(['synced' => 2, 'removed' => 1, 'conflicts' => []]) + ->and(DB::table('settings_definitions')->where('key', 'site.name')->value('label'))->toBe('Site name') + ->and(DB::table('settings_definitions')->where('key', 'site.name')->value('default'))->toBe('"Acme"') + ->and((bool) $password?->is_system)->toBeTrue() + ->and($password?->default)->toBeNull() + ->and($password?->category_id)->not->toBeNull(); + + // Idempotent. + expect(app(SyncDefinitions::class)->handle())->toMatchArray(['synced' => 2, 'removed' => 0]); +}); + +it('reports a runtime row that shares a key with code, and leaves it alone', function (): void { + useDatabase(['definitions.table' => true]); + app(DefinitionRegistry::class)->define('site.name')->ofType('string')->register(); + runtimeDefinition('site.name', ['label' => 'Edited']); + + expect(app(SyncDefinitions::class)->handle()['conflicts'])->toBe(['settings.site.name']) + ->and(DB::table('settings_definitions')->value('label'))->toBe('Edited'); +}); + +it('answers for keys no code covers from runtime rows, never from system rows', function (): void { + useDatabase(['definitions.table' => true]); + runtimeDefinition('billing.currency', ['type' => 'string', 'default' => '"EUR"', 'rules' => '["required","in:EUR,USD","exists:currencies,code"]', 'label' => 'Currency']); + DB::table('settings_definitions')->insert(['store' => 'settings', 'slug' => 'site-name', 'key' => 'site.name', 'group' => 'site', 'default' => '"Stale"', 'is_system' => true, 'created_at' => now(), 'updated_at' => now()]); + + expect(settings()->get('billing.currency'))->toBe('EUR') + ->and(settings()->has('site.name'))->toBeFalse() + ->and(fn () => settings()->set('billing.currency', 'GBP'))->toThrow(InvalidSettingValue::class); + + // `exists` is not an allowed rule, so it was dropped rather than run against a table. + settings()->set('billing.currency', 'USD'); + + expect(settings()->get('billing.currency'))->toBe('USD'); +}); + +it('never lets a table row loosen a coded definition', function (): void { + useDatabase(['definitions.table' => true]); + app(DefinitionRegistry::class)->define('mail.password')->ofType('string')->encrypted()->register(); + runtimeDefinition('mail.password', ['is_encrypted' => false, 'is_public' => true]); + + settings()->set('mail.password', TestCredentials::secret()); + + expect((bool) DB::table('settings')->value('is_encrypted'))->toBeTrue(); +}); + +it('refuses a row whose type is not a registered caster', function (): void { + useDatabase(['definitions.table' => true]); + runtimeDefinition('x.y', ['type' => 'App\\Evil']); + + expect(fn (): mixed => settings()->get('x.y'))->toThrow(InvalidDefinition::class, 'unknown type'); +}); + +it('reads JSON labels in json translations mode', function (): void { + useDatabase(['definitions.table' => true, 'translations.mode' => 'json']); + app(DefinitionRegistry::class)->define('site.name')->labelled('Site name')->register(); + runtimeDefinition('site.tagline', ['label' => '{"":"Tagline","fr":"Slogan"}', 'default' => '"Hi"']); + + app(SyncDefinitions::class)->handle(); + + expect(json_decode((string) DB::table('settings_definitions')->where('key', 'site.name')->value('label'), true))->toBe(['' => 'Site name']) + ->and(settings()->get('site.tagline'))->toBe('Hi'); +}); + +it('reads no table definitions when `database` is not a source, and validates sources', function (): void { + useDatabase(['definitions.table' => true, 'definitions.sources' => ['code', 'config']]); + runtimeDefinition('billing.currency', ['default' => '"EUR"']); + + expect(settings()->has('billing.currency'))->toBeFalse(); + + config()->set('laranail.settings.definitions.sources', ['code', 'yaml']); + app()->forgetScopedInstances(); + + expect(fn (): mixed => settings()->get('x'))->toThrow(InvalidConfiguration::class, 'definitions.sources'); +}); + +it('skips config definitions when `config` is not a source, and never reads option names as keys', function (): void { + config()->set('laranail.settings.definitions', ['site.name' => ['default' => 'Acme'], 'sources' => ['code'], 'table' => false]); + app()->forgetInstance(DefinitionRegistry::class); + app()->forgetScopedInstances(); + + expect(settings()->has('site.name'))->toBeFalse() + ->and(settings()->has('table'))->toBeFalse(); + + // Positive control: with `config` back, the same map answers, and `table` is still not a key. + config()->set('laranail.settings.definitions.sources', ['code', 'config']); + app()->forgetInstance(DefinitionRegistry::class); + app()->forgetScopedInstances(); + + expect(settings()->get('site.name'))->toBe('Acme') + ->and(settings()->has('table'))->toBeFalse(); +}); + +it('needs manage_definitions to sync with an actor, is audited, and runs from the command and doctor --fix', function (): void { + useDatabase(['definitions.table' => true]); + $audit = auditInMemory(); + + expect(fn () => app(SyncDefinitions::class)->handle(Actor::user(user())))->toThrow(AccessDenied::class); + + allowGates(Ability::ManageDefinitions); + app(SyncDefinitions::class)->handle(Actor::user(user())); + + expect(collect($audit->entries())->where('action', AuditAction::ManageDefinitions)->count())->toBe(2); + + $this->artisan('laranail::settings.sync-definitions')->expectsOutputToContain('Synced 0 definition(s)')->assertSuccessful(); + $this->artisan('laranail::settings.doctor', ['--fix' => true])->expectsOutputToContain('Synced 0 definition(s)'); +}); + +it('skips stores without the table when syncing', function (): void { + useDatabase(); + + expect(app(SyncDefinitions::class)->handle()['skipped'])->toBe(['settings']); +}); + +it('reports skipped stores and conflicts from the command, and fails when syncing fails', function (): void { + useDatabase(['definitions.table' => true, 'stores.files' => ['layers' => ['runtime']]]); + app(DefinitionRegistry::class)->define('site.name')->register(); + runtimeDefinition('site.name'); + + $this->artisan('laranail::settings.sync-definitions') + ->expectsOutputToContain('Store [files] skipped') + ->expectsOutputToContain('[settings.site.name] is defined in code and edited in the table') + ->assertSuccessful(); + + Schema::drop('settings_definitions'); + app()->forgetScopedInstances(); + + $this->artisan('laranail::settings.sync-definitions')->assertFailed(); + $this->artisan('laranail::settings.doctor', ['--fix' => true])->assertFailed(); +}); diff --git a/tests/Feature/Database/OwnersTest.php b/tests/Feature/Database/OwnersTest.php index cae69c5..913898f 100644 --- a/tests/Feature/Database/OwnersTest.php +++ b/tests/Feature/Database/OwnersTest.php @@ -5,8 +5,13 @@ use Illuminate\Support\Facades\DB; use Illuminate\Support\Facades\Schema; use Illuminate\Database\Schema\Blueprint; +use Simtabi\Laranail\Settings\Data\Actor; use Simtabi\Laranail\Settings\Data\OwnerRef; +use Simtabi\Laranail\Settings\Enums\Ability; +use Simtabi\Laranail\Settings\Actions\PruneAudit; +use Simtabi\Laranail\Settings\Actions\PruneOrphans; use Illuminate\Database\Eloquent\Relations\Relation; +use Simtabi\Laranail\Settings\Exceptions\AccessDenied; use Simtabi\Laranail\Settings\Exceptions\InvalidIdentifier; use Simtabi\Laranail\Settings\Tests\Fixtures\SettingsOwner; use Simtabi\Laranail\Settings\Tests\Fixtures\SoftDeletingOwner; @@ -119,3 +124,32 @@ expect(DB::table('settings')->pluck('scope')->sort()->values()->all())->toBe(['owner:' . $kept->id, 'soft:' . $trashed->id]); }); + +it('needs prune (and forget) to prune orphans with an actor, and audits the run', function (): void { + $gone = SettingsOwner::query()->create(); + $gone->settings()->set('ui.theme', 'dark'); + SettingsOwner::query()->whereKey($gone->id)->delete(); + $prune = app(PruneOrphans::class); + $actor = Actor::user(user()); + + expect(fn () => $prune->handle($actor))->toThrow(AccessDenied::class, 'prune') + ->and(DB::table('settings')->count())->toBe(1); + + allowGates(Ability::Prune, Ability::Forget); + + expect($prune->handle($actor))->toBe(1) + ->and(json_decode((string) DB::table('settings_audit')->where('action', 'prune')->where('outcome', 'allowed')->value('meta'), true))->toMatchArray(['owners' => 1]) + ->and(DB::table('settings_audit')->where('action', 'prune')->where('outcome', 'denied')->count())->toBe(1); +}); + +it('needs prune to prune the audit trail with an actor', function (): void { + $prune = app(PruneAudit::class); + $actor = Actor::user(user()); + + expect(fn () => $prune->handle(30, $actor))->toThrow(AccessDenied::class); + + allowGates(Ability::Prune); + + expect($prune->handle(30, $actor))->toBe(0) + ->and(DB::table('settings_audit')->where('action', 'prune')->where('actor_type', 'user')->where('outcome', 'allowed')->count())->toBe(1); +}); diff --git a/tests/Feature/Database/SchemaMatrixTest.php b/tests/Feature/Database/SchemaMatrixTest.php new file mode 100644 index 0000000..5add2fe --- /dev/null +++ b/tests/Feature/Database/SchemaMatrixTest.php @@ -0,0 +1,136 @@ +> */ +function switchFactors(): array +{ + return [ + 'identity' => ['slug_uid', 'slug_per_row', 'uid_only'], + 'ids' => ['bigint', 'uuid', 'ulid'], + 'owner_key' => ['string', 'typed'], + 'mode' => ['polymorphic', 'dedicated'], + 'soft_deletes' => [false, true], + 'translations' => ['lang', 'json'], + 'definitions_table' => [false, true], + 'categories_soft_deletes' => [false, true], + ]; +} + +/** @return list> */ +function switchShapes(): array +{ + return getenv('LARANAIL_SETTINGS_MATRIX') === 'full' ? Pairwise::product(switchFactors()) : Pairwise::rows(switchFactors()); +} + +it('covers every pair of switch values with a counted set of shapes', function (): void { + $shapes = switchShapes(); + $covered = []; + + foreach ($shapes as $shape) { + foreach (Pairwise::pairs($shape) as $pair) { + $covered[$pair] = true; + } + } + + $all = []; + + foreach (Pairwise::product(switchFactors()) as $row) { + foreach (Pairwise::pairs($row) as $pair) { + $all[$pair] = true; + } + } + + expect(count($shapes))->toBe(getenv('LARANAIL_SETTINGS_MATRIX') === 'full' ? 576 : 10) + ->and(count($all))->toBe(141) + ->and(array_diff_key($all, $covered))->toBe([]); +})->group('matrix'); + +it('runs every shape end to end and reports no drift', function (array $shape): void { + $dedicated = $shape['mode'] === 'dedicated'; + $ownerStore = $dedicated ? 'user_settings' : 'settings'; + + $config = [ + 'identity.mode' => $shape['identity'], + 'ids.type' => $shape['ids'], + 'ids.owner_key' => $shape['owner_key'], + 'translations.mode' => $shape['translations'], + 'definitions.table' => $shape['definitions_table'], + 'categories.soft_deletes' => $shape['categories_soft_deletes'], + 'stores.settings.owners' => $dedicated ? [] : ['user'], + 'stores.settings.soft_deletes' => $shape['soft_deletes'], + 'stores.settings.inherits' => true, + ]; + + if ($dedicated) { + $config['stores.user_settings'] = [ + 'layers' => ['database'], + 'owners' => ['user'], + 'mode' => 'dedicated', + 'owner' => ['table' => 'users', 'type' => 'bigint'], + 'soft_deletes' => $shape['soft_deletes'], + 'inherits' => true, + ]; + } + + useDatabase($config, stores: $dedicated ? ['user_settings'] : [], ownerTables: ['users' => 'bigint']); + app(SchemaShapeRepository::class)->record(); + DB::table('users')->insert(['id' => 1, 'name' => 'Ada']); + + $user = new OwnerRef('user', 1); + + // Categories: create with translations, delete, create again (restored when trashed). + $categories = settings()->categories(); + $mail = $categories->create(new NewCategory('mail', 'Mail', translations: ['fr' => 'Courrier'])); + $categories->delete('mail'); + $again = $categories->create(new NewCategory('mail', 'Email')); + app(DefinitionRegistry::class)->define('mail.host')->inCategory('mail')->labelled('Host')->register(); + + // Values: global, owner, category link, forget then set, lock and unlock. + settings()->set('mail.host', 'smtp.acme.test'); + settings()->set('site.name', 'Acme'); + settings()->for($user)->set('theme', 'dark'); + settings()->for($user)->forget('theme'); + settings()->for($user)->set('theme', 'light'); + settings()->for($user)->lock('theme'); + settings()->for($user)->unlock('theme'); + + if ($shape['definitions_table']) { + expect(app(SyncDefinitions::class)->handle()['synced'])->toBe(1); + } + + $exit = Artisan::call('laranail::settings.doctor', ['--json' => true]); + $report = Artisan::output(); + + expect(settings()->get('mail.host'))->toBe('smtp.acme.test') + ->and(settings()->for($user)->get('theme'))->toBe('light') + ->and(settings()->for($user)->get('site.name'))->toBe('Acme') + ->and(DB::table($ownerStore)->where('scope', 'user:1')->count())->toBe(1) + ->and((int) DB::table($ownerStore)->where('scope', 'user:1')->value('version'))->toBe($shape['soft_deletes'] ? 4 : 3) + ->and(DB::table('settings')->where('key', 'mail.host')->value('category_id'))->toBe($again->id) + ->and($again->id === $mail->id)->toBe($shape['categories_soft_deletes']) + ->and($report)->toContain('No schema drift.') + ->and($report)->toContain('The configuration matches the recorded schema.') + ->and($exit)->toBe(0); +})->with(fn (): array => array_map( + static fn (array $shape): array => [$shape], + array_combine(array_map(static fn (array $shape): string => implode(',', array_map(static fn (mixed $value): string => is_bool($value) ? ($value ? 'on' : 'off') : $value, $shape)), switchShapes()), switchShapes()), +))->group('matrix'); diff --git a/tests/Feature/Database/SchemaShapeTest.php b/tests/Feature/Database/SchemaShapeTest.php new file mode 100644 index 0000000..78e4cb5 --- /dev/null +++ b/tests/Feature/Database/SchemaShapeTest.php @@ -0,0 +1,165 @@ +group('shared-app'); + +function shapes(): SchemaShapeRepository +{ + return app(SchemaShapeRepository::class); +} + +/** The doctor's JSON report. */ +function doctorReport(): string +{ + Artisan::call('laranail::settings.doctor', ['--json' => true]); + + return Artisan::output(); +} + +it('records the configured shape in the schema file and reads it back', function (): void { + config()->set('laranail.settings.identity.mode', 'uid_only'); + config()->set('laranail.settings.stores.settings.layers', ['database']); + config()->set('laranail.settings.stores.settings.soft_deletes', true); + + $recorded = shapes()->record(); + app()->forgetScopedInstances(); + + expect(File::get(shapes()->path()))->toContain("'identity' => 'uid_only'") + ->and(shapes()->recorded()?->toArray())->toBe($recorded->toArray()) + ->and(shapes()->current()->store(new StoreName('settings'))->softDeletes)->toBeTrue(); +}); + +it('makes the runtime read the recorded shape, not config changed after migrating (§4.0)', function (): void { + useDatabase(); + shapes()->record(); + + config()->set('laranail.settings.identity.mode', 'uid_only'); + config()->set('laranail.settings.stores.settings.soft_deletes', true); + app()->forgetScopedInstances(); + + settings()->set('site.name', 'Acme'); + settings()->forget('site.name'); + + expect(DB::table('settings')->count())->toBe(0) + ->and(shapes()->current()->identity->value)->toBe('slug_uid'); +}); + +it('keeps recorded switches and stores and only adds new stores on record', function (): void { + config()->set('laranail.settings.stores.settings.layers', ['database']); + shapes()->record(); + + config()->set('laranail.settings.ids.type', 'uuid'); + config()->set('laranail.settings.stores.settings.soft_deletes', true); + config()->set('laranail.settings.stores.billing', ['layers' => ['database'], 'soft_deletes' => true]); + $shape = shapes()->record(); + + expect($shape->ids->value)->toBe('bigint') + ->and($shape->store(new StoreName('settings'))->softDeletes)->toBeFalse() + ->and($shape->store(new StoreName('billing'))->softDeletes)->toBeTrue(); +}); + +it('records the store make-store generates, from its configuration when it has one', function (): void { + config()->set('laranail.settings.stores.ledger', ['layers' => ['database'], 'soft_deletes' => true]); + + app(MakeStore::class)->handle(new StoreName('ledger')); + app(MakeStore::class)->handle(new StoreName('archive'), 'archive_db'); + + $recorded = shapes()->recorded(); + + expect($recorded?->store(new StoreName('ledger'))->softDeletes)->toBeTrue() + ->and($recorded?->store(new StoreName('archive'))->connection)->toBe('archive_db'); + + File::delete(glob(database_path('migrations') . '/*settings*.php') ?: []); +}); + +it('refuses a schema file that does not hold a shape', function (string $contents, string $message): void { + File::put(shapes()->path(), $contents); + + expect(fn (): ?SchemaShape => shapes()->recorded())->toThrow(InvalidConfiguration::class, $message); +})->with([ + 'not an array' => [' [' [" 1, 'switches' => ['identity' => 'nope']];", 'switch [identity]'], + 'unknown mode' => [" 1, 'stores' => ['settings' => ['mode' => 'nope']]];", 'unknown mode'], + 'store not array' => [" 1, 'stores' => ['settings' => 1]];", 'must be an array'], + 'broken PHP' => ['toContain('No schema file'); + + shapes()->record(); + + expect(doctorReport())->toContain('The configuration matches the recorded schema.'); +}); + +it('warns about configuration that drifted from the recorded schema', function (): void { + useDatabase(); + shapes()->record(); + config()->set('laranail.settings.translations.mode', 'json'); + config()->set('laranail.settings.stores.settings.soft_deletes', true); + app()->forgetScopedInstances(); + + $this->artisan('laranail::settings.doctor') + ->expectsOutputToContain('switches.translations: lang → json') + ->assertSuccessful(); + + expect(doctorReport())->toContain('stores.settings.soft_deletes: false'); +}); + +it('fails on an unrecorded database store, a missing column or a wrong id type', function (): void { + useDatabase(); + shapes()->write(new SchemaShape(stores: [])); + + expect(doctorReport())->toContain('has a database layer but no entry in the schema file'); + + $data = shapes()->configured()->toArray(); + $data['shape_version'] = 1; + File::put(shapes()->path(), ' 1] + $data, true) . ';'); + + expect(doctorReport())->not->toContain('no entry in the schema file'); + + // The recorded shape says soft deletes; the table has no deleted_at. + shapes()->write(shapes()->configured()->withStore(new StoreSchema(new StoreName('x')))); + $soft = shapes()->configured()->toArray(); + $soft['stores']['settings']['soft_deletes'] = true; + File::put(shapes()->path(), 'forgetScopedInstances(); + + expect(doctorReport())->toContain('settings.deleted_at'); + + // The recorded shape says ulid; the table has a bigint id. + $ulid = shapes()->configured()->toArray(); + $ulid['switches']['ids'] = 'ulid'; + File::put(shapes()->path(), 'forgetScopedInstances(); + + expect(doctorReport())->toContain('recorded key type is [ulid]'); +}); + +it('warns about columns the recorded shape does not have', function (): void { + useDatabase(['stores.settings.soft_deletes' => true]); + $plain = shapes()->configured()->toArray(); + $plain['stores']['settings']['soft_deletes'] = false; + File::put(shapes()->path(), 'forgetScopedInstances(); + + expect(Schema::hasColumn('settings', 'deleted_at'))->toBeTrue() + ->and(doctorReport())->toContain('Columns the recorded schema does not have'); +}); diff --git a/tests/Feature/Database/SchemaSwitchesTest.php b/tests/Feature/Database/SchemaSwitchesTest.php new file mode 100644 index 0000000..3f01798 --- /dev/null +++ b/tests/Feature/Database/SchemaSwitchesTest.php @@ -0,0 +1,167 @@ + ['user']]); + + settings()->set('mail.from_address', 'a@acme.test'); + settings()->for(new OwnerRef('user', 1))->set('mail.from_address', 'b@acme.test'); + + $rows = DB::table('settings')->orderBy('scope')->get(); + + expect($rows->pluck('slug')->unique()->all())->toBe(['mail-from_address']) + ->and($rows->pluck('uid')->unique())->toHaveCount(2); +}); + +it('gives each row a unique sha1 slug and no uid in slug_per_row mode (D-1)', function (): void { + useDatabase(['identity.mode' => 'slug_per_row', 'stores.settings.owners' => ['user']]); + + settings()->set('mail.from_address', 'a@acme.test'); + settings()->for(new OwnerRef('user', 1))->set('mail.from_address', 'b@acme.test'); + settings()->set('mail.from_address', 'c@acme.test'); + + expect(valueColumns())->not->toContain('uid') + ->and(DB::table('settings')->where('scope', 'global')->value('slug'))->toBe(sha1('global|mail.from_address|')) + ->and(DB::table('settings')->where('scope', 'user:1')->value('slug'))->toBe(sha1('user:1|mail.from_address|')) + ->and(settings()->get('mail.from_address'))->toBe('c@acme.test'); + + $unique = collect(Schema::getIndexes('settings'))->filter(static fn (array $index): bool => $index['unique'] && $index['columns'] === ['slug']); + + expect($unique)->toHaveCount(1); +}); + +it('keeps only a uid in uid_only mode (D-1)', function (): void { + useDatabase(['identity.mode' => 'uid_only']); + + settings()->set('site.name', 'Acme'); + + expect(valueColumns())->not->toContain('slug') + ->and(strlen((string) DB::table('settings')->value('uid')))->toBe(26) + ->and(settings()->get('site.name'))->toBe('Acme'); +}); + +it('keys every package table by uuid or ulid, with matching category keys (D-5)', function (string $type, int $length): void { + useDatabase(['ids.type' => $type, 'definitions.table' => true]); + + $category = settings()->categories()->create(new NewCategory('mail', 'Mail')); + settings()->configuration()->define('mail.host')->inCategory('mail')->register(); + settings()->set('mail.host', 'smtp.acme.test'); + + $row = DB::table('settings')->first(); + + expect(strlen((string) $category->id))->toBe($length) + ->and(strlen((string) $row?->id))->toBe($length) + ->and($row?->category_id)->toBe($category->id) + ->and(settings()->get('mail.host'))->toBe('smtp.acme.test'); +})->with([ + 'uuid' => ['uuid', 36], + 'ulid' => ['ulid', 26], +]); + +it('follows laranail.db-tools.id_type when ids.type is not set (D-5)', function (): void { + config()->set('laranail.db-tools.id_type', 'ULID'); + useDatabase(); + + settings()->set('site.name', 'Acme'); + + expect(app(SchemaShapeRepository::class)->current()->ids->value)->toBe('ulid') + ->and(strlen((string) DB::table('settings')->value('id')))->toBe(26); +}); + +it('refuses an ids.type it does not know', function (): void { + config()->set('laranail.settings.ids.type', 'serial'); + + expect(fn () => app(SchemaShapeRepository::class)->configured())->toThrow(InvalidConfiguration::class, 'laranail.settings.ids.type'); +}); + +it('types settable_id like the owners\' keys when ids.owner_key is typed (D-5)', function (): void { + useDatabase(['ids.owner_key' => 'typed', 'stores.settings.owners' => ['user']]); + + settings()->for(new OwnerRef('user', 42))->set('theme', 'dark'); + + expect((int) DB::table('settings')->value('settable_id'))->toBe(42) + ->and(settings()->for(new OwnerRef('user', 42))->get('theme'))->toBe('dark') + ->and(fn () => settings()->for(new OwnerRef('user', 'abc'))->set('theme', 'light'))->toThrow(OwnerNotAllowed::class, 'bigint'); +}); + +it('stores titles as per-locale JSON in json translations mode (D-8)', function (): void { + useDatabase(['translations.mode' => 'json']); + + $categories = settings()->categories(); + $categories->create(new NewCategory('mail', 'Mail', description: 'Outgoing mail', translations: ['fr' => 'Courrier', 'pt-br' => 'Correio'])); + $categories->rename('mail', 'Email'); + $mail = $categories->get('mail'); + $stored = json_decode((string) DB::table('settings_categories')->value('title'), true); + + expect($mail->title)->toBe('Email') + ->and($mail->titleIn('fr_CA'))->toBe('Courrier') + ->and($mail->titleIn('pt_BR'))->toBe('Correio') + ->and($mail->titleIn('de'))->toBe('Email') + ->and($mail->description)->toBe('Outgoing mail') + ->and($stored)->toMatchArray(['' => 'Email', 'fr' => 'Courrier', 'pt_BR' => 'Correio']); +}); + +it('keeps plain titles in lang mode, where translations are not stored', function (): void { + useDatabase(); + + $mail = settings()->categories()->create(new NewCategory('mail', 'settings.categories.mail', translations: ['fr' => 'Courrier'])); + + expect(DB::table('settings_categories')->value('title'))->toBe('settings.categories.mail') + ->and($mail->titles)->toBe(['' => 'settings.categories.mail']) + ->and(fn (): NewCategory => new NewCategory('x', 'X', translations: ['fr' => ' ']))->toThrow(InvalidIdentifier::class); +}); + +it('prefixes every table and honours each override, including the foreign-table check (D-4)', function (): void { + useDatabase([ + 'tables.prefix' => 'app_', + 'tables.categories' => 'setting_groups', + 'tables.audit' => 'setting_log', + 'tables.definitions' => 'setting_defs', + 'definitions.table' => true, + 'stores.settings.table' => 'preferences', + ]); + + settings()->categories()->create(new NewCategory('mail', 'Mail')); + settings()->set('site.name', 'Acme'); + + expect(Schema::hasTable('app_preferences'))->toBeTrue() + ->and(Schema::hasTable('app_setting_groups'))->toBeTrue() + ->and(Schema::hasTable('app_setting_log'))->toBeTrue() + ->and(Schema::hasTable('app_setting_defs'))->toBeTrue() + ->and(Schema::hasTable('settings'))->toBeFalse() + ->and(DB::table('app_preferences')->value('key'))->toBe('site.name') + ->and(app(FindForeignTables::class)->handle())->toBe([]); + + // A foreign table under a prefixed name is still refused. + Schema::drop('app_setting_log'); + Schema::create('app_setting_log', static function (Blueprint $table): void { + $table->id(); + $table->string('message'); + }); + + expect(app(FindForeignTables::class)->handle())->toBe([DB::getDefaultConnection() . '.app_setting_log']); +}); + +it('runs the definitions migration as a no-op while the table is off (D-6)', function (): void { + useDatabase(); + + expect(Schema::hasTable('settings_definitions'))->toBeFalse(); +}); diff --git a/tests/Feature/Database/SoftDeletesTest.php b/tests/Feature/Database/SoftDeletesTest.php new file mode 100644 index 0000000..e5379c2 --- /dev/null +++ b/tests/Feature/Database/SoftDeletesTest.php @@ -0,0 +1,109 @@ + true, 'stores.settings.owners' => ['user'], 'categories.soft_deletes' => true]); +}); + +it('trashes a forgotten row instead of deleting it, and reads past it (D-9)', function (): void { + settings()->set('site.name', 'Acme'); + settings()->forget('site.name'); + + expect(settings()->has('site.name'))->toBeFalse() + ->and(DB::table('settings')->count())->toBe(1) + ->and(DB::table('settings')->value('deleted_at'))->not->toBeNull(); +}); + +it('restores a trashed row on the next set, continuing its version, never as a conflict (D-9)', function (): void { + $audit = auditInMemory(); + settings()->set('site.name', 'One'); + settings()->set('site.name', 'Two'); + settings()->forget('site.name'); + + settings()->set('site.name', 'Three'); + $row = DB::table('settings')->first(); + + expect(settings()->get('site.name'))->toBe('Three') + ->and(DB::table('settings')->count())->toBe(1) + ->and($row?->deleted_at)->toBeNull() + ->and((int) $row?->version)->toBe(3) + ->and(collect($audit->entries())->where('action', AuditAction::Update)->last()?->versionTo)->toBe(3) + ->and(collect($audit->entries())->where('outcome', AuditOutcome::Failed))->toBeEmpty(); +}); + +it('does not bring back the lock or labels of the forgotten row', function (): void { + settings()->set('site.name', 'One'); + settings()->lock('site.name'); + DB::table('settings')->update(['label' => 'Stale', 'meta' => '{"x":1}']); + settings()->unlock('site.name'); + settings()->lock('site.name'); + DB::table('settings')->update(['deleted_at' => now()]); + + settings()->set('site.name', 'Two'); + $row = DB::table('settings')->first(); + + expect((bool) $row?->is_locked)->toBeFalse() + ->and($row?->label)->toBeNull() + ->and($row?->meta)->toBeNull() + ->and(settings()->get('site.name'))->toBe('Two'); +}); + +it('locks a trashed key by restoring its row as a value-less lock', function (): void { + settings()->set('site.name', 'One'); + settings()->forget('site.name'); + + settings()->lock('site.name'); + + expect(DB::table('settings')->count())->toBe(1) + ->and(DB::table('settings')->value('deleted_at'))->toBeNull() + ->and((int) DB::table('settings')->value('version'))->toBe(2) + ->and(settings()->has('site.name'))->toBeFalse(); +}); + +it('trashes a whole scope on flush, and does not list it as an owner any more', function (): void { + $owner = new OwnerRef('user', 7); + settings()->for($owner)->set('theme', 'dark'); + settings()->for($owner)->set('locale', 'fr'); + + settings()->for($owner)->flush(); + settings()->for($owner)->set('theme', 'light'); + + expect(DB::table('settings')->whereNotNull('deleted_at')->count())->toBe(1) + ->and(settings()->for($owner)->get('theme'))->toBe('light') + ->and(settings()->for($owner)->has('locale'))->toBeFalse(); +}); + +it('trashes a deleted category and restores it when its slug is created again', function (): void { + $categories = settings()->categories(); + $first = $categories->create(new NewCategory('mail', 'Mail')); + $categories->delete('mail'); + + expect(fn (): Category => $categories->get('mail'))->toThrow(UnknownCategory::class) + ->and(DB::table('settings_categories')->count())->toBe(1); + + $again = $categories->create(new NewCategory('mail', 'Email')); + + expect($again->id)->toBe($first->id) + ->and($again->title)->toBe('Email') + ->and(DB::table('settings_categories')->count())->toBe(1) + ->and(DB::table('settings_categories')->value('deleted_at'))->toBeNull(); +}); + +it('does not link a setting to a trashed category', function (): void { + settings()->categories()->create(new NewCategory('mail', 'Mail')); + settings()->categories()->delete('mail'); + settings()->configuration()->define('mail.host')->inCategory('mail')->register(); + + settings()->set('mail.host', 'smtp.acme.test'); + + expect(DB::table('settings')->value('category_id'))->toBeNull(); +}); diff --git a/tests/Feature/Database/WriteRetryTest.php b/tests/Feature/Database/WriteRetryTest.php new file mode 100644 index 0000000..8e14ca5 --- /dev/null +++ b/tests/Feature/Database/WriteRetryTest.php @@ -0,0 +1,105 @@ + $afterReads + */ +function interveneAfterReads(array $afterReads): void +{ + $reads = 0; + $busy = false; + + DB::listen(static function (QueryExecuted $query) use ($afterReads, &$reads, &$busy): void { + if ($busy || ! str_starts_with(strtolower($query->sql), 'select') || ! preg_match('/from [`"]settings[`"]/', $query->sql)) { + return; + } + + if (! in_array(++$reads, $afterReads, true)) { + return; + } + + $busy = true; + $version = (int) DB::table('settings')->where('key', 'site.name')->value('version'); + DB::table('settings')->where('key', 'site.name')->update(['value' => '"Theirs"', 'version' => $version + 1]); + $busy = false; + }); +} + +function target(): SettingTarget +{ + $store = app(StoreRegistry::class)->default(); + + return new SettingTarget($store, new Key('site.name'), Locale::none()); +} + +beforeEach(function (): void { + useDatabase(); + settings()->set('site.name', 'Ours'); +}); + +it('retries a plain set once after a concurrent change, and logs it', function (): void { + $logger = new class extends AbstractLogger + { + /** @var list */ + public array $messages = []; + + public function log($level, string|Stringable $message, array $context = []): void + { + $this->messages[] = (string) $message; + } + }; + settings()->configuration()->logTo($logger); + interveneAfterReads([2]); + + settings()->set('site.name', 'Mine'); + + expect(settings()->get('site.name'))->toBe('Mine') + ->and((int) DB::table('settings')->value('version'))->toBe(3) + ->and(array_filter($logger->messages, static fn (string $message): bool => str_contains($message, 'retried a write of [site.name]')))->toHaveCount(1); +}); + +it('gives up after one retry, rolling the whole write back', function (): void { + interveneAfterReads([2, 4]); + + expect(fn () => settings()->set('site.name', 'Mine'))->toThrow(ConcurrentModification::class) + ->and(settings()->get('site.name'))->toBe('Ours'); +}); + +it('does not retry when writes.retry_on_conflict is off', function (): void { + config()->set('laranail.settings.writes.retry_on_conflict', false); + app()->forgetInstance(SettingWriter::class); + app()->forgetScopedInstances(); + interveneAfterReads([2]); + + expect(fn () => settings()->set('site.name', 'Mine'))->toThrow(ConcurrentModification::class); +}); + +it('checks an explicit expected version and never retries it', function (): void { + $set = app(SettingActions::class)->set; + + expect(fn () => $set->handle(new SettingWrite(target(), 'Stale', expectedVersion: 7)))->toThrow(ConcurrentModification::class, 'not the expected 7'); + + $set->handle(new SettingWrite(target(), 'Mine', expectedVersion: 1)); + interveneAfterReads([2]); + + expect(settings()->get('site.name'))->toBe('Mine') + ->and(fn () => $set->handle(new SettingWrite(target(), 'Again', expectedVersion: 2)))->toThrow(ConcurrentModification::class); +}); diff --git a/tests/Feature/FakeTest.php b/tests/Feature/FakeTest.php index 5a7b605..2653be9 100644 --- a/tests/Feature/FakeTest.php +++ b/tests/Feature/FakeTest.php @@ -12,6 +12,7 @@ use Simtabi\Laranail\Settings\Enums\AuditAction; use Simtabi\Laranail\Settings\Enums\AuditOutcome; use Simtabi\Laranail\Settings\Tests\Fixtures\TestUser; +use Simtabi\Laranail\Settings\Exceptions\DriverUnavailable; use Simtabi\Laranail\Settings\Configuration\RuntimeConfiguration; use Simtabi\Laranail\Settings\Contracts\Settings as SettingsContract; @@ -103,3 +104,9 @@ ->and($fake->locale('fr')->get('n.int'))->toBe(3) ->and($fake->for(new OwnerRef('user', 1))->get('n.int'))->toBeNull(); }); + +it('has no database audit trail to query', function (): void { + $fake = Settings::fake(); + + expect(fn (): array => $fake->audit()->get())->toThrow(DriverUnavailable::class); +}); diff --git a/tests/Feature/InstallCommandTest.php b/tests/Feature/InstallCommandTest.php index aab0f91..8d698e2 100644 --- a/tests/Feature/InstallCommandTest.php +++ b/tests/Feature/InstallCommandTest.php @@ -4,6 +4,10 @@ use Illuminate\Support\Facades\File; +// Writes into the testbench application shared by every process (config/, database/), so it +// cannot run beside itself in parallel; the parallel mutation run leaves this group out. +pest()->group('shared-app'); + beforeEach(function (): void { File::delete(config_path('laranail/settings.php')); }); diff --git a/tests/Feature/ReadinessFlushTest.php b/tests/Feature/ReadinessFlushTest.php new file mode 100644 index 0000000..532b4d4 --- /dev/null +++ b/tests/Feature/ReadinessFlushTest.php @@ -0,0 +1,49 @@ +flushes++; + } + }; + app()->instance(ReadinessProbe::class, $probe); + + return $probe; +} + +it('forgets schema readiness when a tenancy package switches tenants, by event name (no dependency)', function (string $event): void { + $probe = countingProbe(); + + Event::dispatch($event); + + expect($probe->flushes)->toBe(1); +})->with([ + 'stancl initialized' => 'Stancl\Tenancy\Events\TenancyInitialized', + 'stancl ended' => 'Stancl\Tenancy\Events\TenancyEnded', + 'spatie current' => 'Spatie\Multitenancy\Events\MadeTenantCurrentEvent', + 'spatie forgot' => 'Spatie\Multitenancy\Events\ForgotCurrentTenantEvent', +]); + +it('does not flush on events nobody configured', function (): void { + $probe = countingProbe(); + + Event::dispatch('App\Events\SomethingElse'); + + expect($probe->flushes)->toBe(0); +}); diff --git a/tests/Pest.php b/tests/Pest.php index 12d57e3..be1f027 100644 --- a/tests/Pest.php +++ b/tests/Pest.php @@ -69,8 +69,9 @@ function auditInMemory(): InMemoryAuditSink * * @param array $config extra `laranail.settings.*` values, set before migrating * @param list $stores further stores whose values table to create (as make-store would) + * @param array $ownerTables tables to create first (name => bigint|uuid|ulid key), for dedicated stores */ -function useDatabase(array $config = [], array $stores = []): void +function useDatabase(array $config = [], array $stores = [], array $ownerTables = []): void { config()->set('laranail.settings.stores.settings.layers', ['database', 'runtime', 'shipped']); @@ -84,10 +85,28 @@ function useDatabase(array $config = [], array $stores = []): void $directory = sys_get_temp_dir() . '/laranail-settings-migrations-' . bin2hex(random_bytes(4)); mkdir($directory); - foreach (['create_settings_categories_table', 'create_settings_table', 'create_settings_audit_table'] as $index => $stub) { + foreach (['create_settings_categories_table', 'create_settings_table', 'create_settings_audit_table', 'create_settings_definitions_table'] as $index => $stub) { copy(dirname(__DIR__) . "/database/migrations/{$stub}.php.stub", sprintf('%s/2026_01_01_00000%d_%s.php', $directory, $index, $stub)); } + if ($ownerTables !== []) { + file_put_contents($directory . '/2025_01_01_000000_create_owner_tables.php', ' $type) { + Illuminate\Support\Facades\Schema::create($name, static function (Illuminate\Database\Schema\Blueprint $table) use ($type): void { + match ($type) { + "uuid" => $table->char("id", 36)->primary(), + "ulid" => $table->char("id", 26)->primary(), + default => $table->bigIncrements("id"), + }; + $table->string("name")->nullable(); + }); + } + } + };'); + } + foreach ($stores as $index => $store) { $source = (string) file_get_contents(__DIR__ . '/../database/migrations/create_settings_table.php.stub'); file_put_contents( diff --git a/tests/Support/Pairwise.php b/tests/Support/Pairwise.php new file mode 100644 index 0000000..f11cc39 --- /dev/null +++ b/tests/Support/Pairwise.php @@ -0,0 +1,108 @@ +> $factors + * + * @return list> + */ + public static function rows(array $factors): array + { + $product = self::product($factors); + $uncovered = []; + + foreach ($product as $row) { + foreach (self::pairs($row) as $pair) { + $uncovered[$pair] = true; + } + } + + $rows = []; + + while ($uncovered !== []) { + $best = null; + $bestCount = 0; + + foreach ($product as $row) { + $count = count(array_intersect_key(array_flip(self::pairs($row)), $uncovered)); + + if ($count > $bestCount) { + [$best, $bestCount] = [$row, $count]; + } + } + + if ($best === null) { + break; + } + + $rows[] = $best; + + foreach (self::pairs($best) as $pair) { + unset($uncovered[$pair]); + } + } + + return $rows; + } + + /** + * @param array> $factors + * + * @return list> + */ + public static function product(array $factors): array + { + $rows = [[]]; + + foreach ($factors as $name => $values) { + $next = []; + + foreach ($rows as $row) { + foreach ($values as $value) { + $next[] = $row + [$name => $value]; + } + } + + $rows = $next; + } + + return $rows; + } + + /** + * Every pair of (factor = value) in one row, as stable strings. + * + * @param array $row + * + * @return list + */ + public static function pairs(array $row): array + { + $cells = []; + + foreach ($row as $name => $value) { + $cells[] = $name . '=' . var_export($value, true); + } + + $pairs = []; + + foreach ($cells as $i => $a) { + foreach (array_slice($cells, $i + 1) as $b) { + $pairs[] = $a . '&' . $b; + } + } + + return $pairs; + } +} diff --git a/tests/TestCase.php b/tests/TestCase.php index d2e4ff4..3d67e49 100644 --- a/tests/TestCase.php +++ b/tests/TestCase.php @@ -21,6 +21,8 @@ protected function setUp(): void Storage::fake('local'); // No shipped file unless a test ships one. config()->set('laranail.settings.layers.shipped.path', '/nonexistent/laranail-settings-defaults.php'); + // The schema-shape file goes to a path of this test's own, never the skeleton's database/. + config()->set('laranail.settings.schema.path', sys_get_temp_dir() . '/laranail-settings-schema-' . bin2hex(random_bytes(6)) . '.php'); // File layers only unless a test asks for the database (useDatabase() in tests/Pest.php). config()->set('laranail.settings.stores.settings.layers', ['runtime', 'shipped']); } diff --git a/tests/Unit/AccessValuesTest.php b/tests/Unit/AccessValuesTest.php index 12afc28..de89229 100644 --- a/tests/Unit/AccessValuesTest.php +++ b/tests/Unit/AccessValuesTest.php @@ -32,7 +32,7 @@ function subjectFor(string $key = 'site.name'): Subject it('names each ability\'s gate and token ability, and knows the read abilities', function (): void { expect(Ability::Update->gateName())->toBe('laranail-settings.update') ->and(Ability::OverrideLock->tokenAbility())->toBe('settings:override_lock') - ->and(Ability::cases())->toHaveCount(17) + ->and(Ability::cases())->toHaveCount(18) ->and(array_values(array_map(static fn (Ability $ability): string => $ability->value, array_filter(Ability::cases(), static fn (Ability $ability): bool => $ability->isRead())))) ->toBe(['view', 'view_sensitive', 'view_history', 'view_audit']); }); @@ -42,7 +42,7 @@ function subjectFor(string $key = 'site.name'): Subject expect(AuditAction::fromAbility($ability)->value)->toBe($ability->value); } - expect(AuditAction::cases())->toHaveCount(18) + expect(AuditAction::cases())->toHaveCount(19) ->and(AuditAction::Configure->value)->toBe('configure'); }); diff --git a/tests/Unit/DocsConformanceTest.php b/tests/Unit/DocsConformanceTest.php index bdf3228..d06b116 100644 --- a/tests/Unit/DocsConformanceTest.php +++ b/tests/Unit/DocsConformanceTest.php @@ -6,10 +6,10 @@ uses(AssertsDocsConformance::class); -// Floor = the 19 pages shipped today (5 guides, 10 reference, 4 recipes). Raise it as pages +// Floor = the 21 pages shipped today (5 guides, 12 reference, 4 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), 19); + $this->assertDocsConformToStandard(dirname(__DIR__, 2), 21); expect(true)->toBeTrue(); }); diff --git a/tests/Unit/SchemaShapeTest.php b/tests/Unit/SchemaShapeTest.php new file mode 100644 index 0000000..80289fd --- /dev/null +++ b/tests/Unit/SchemaShapeTest.php @@ -0,0 +1,110 @@ + $extra */ +function settingsConfig(array $extra = []): array +{ + return array_replace_recursive([ + 'default' => 'settings', + 'stores' => ['settings' => ['layers' => ['database', 'runtime']], 'files' => ['layers' => ['runtime']]], + 'layers' => ['database' => ['driver' => 'database', 'connection' => 'tenant'], 'runtime' => ['driver' => 'json']], + ], $extra); +} + +it('derives the default shape from default configuration, with database stores only', function (): void { + $shape = SchemaShape::fromConfig(settingsConfig()); + + expect($shape->identity)->toBe(IdentityMode::SlugUid) + ->and($shape->ids)->toBe(IdType::Bigint) + ->and(array_keys($shape->stores))->toBe(['settings']) + ->and($shape->store(new StoreName('settings'))->connection)->toBe('tenant') + ->and($shape->store(new StoreName('files'))->mode)->toBe(StoreMode::Polymorphic) + ->and($shape->hasStore(new StoreName('files')))->toBeFalse(); +}); + +it('follows db-tools\' upper-case id type unless ids.type is set', function (): void { + expect(SchemaShape::fromConfig(settingsConfig(), 'UUID')->ids)->toBe(IdType::Uuid) + ->and(SchemaShape::fromConfig(settingsConfig(), 'UUID')->ownerKeyType)->toBe(IdType::Uuid) + ->and(SchemaShape::fromConfig(settingsConfig(['ids' => ['type' => 'ULID']]), 'UUID')->ids)->toBe(IdType::Ulid) + ->and(SchemaShape::fromConfig(settingsConfig(), 'nonsense')->ids)->toBe(IdType::Bigint); +}); + +it('round-trips through the schema file format', function (): void { + $shape = SchemaShape::fromConfig(settingsConfig([ + 'identity' => ['mode' => 'slug_per_row'], + 'translations' => ['mode' => 'json'], + 'categories' => ['soft_deletes' => true], + 'definitions' => ['table' => true], + 'tables' => ['prefix' => 'app_'], + 'stores' => [ + 'settings' => ['soft_deletes' => true, 'owners' => ['team']], + 'users' => ['layers' => ['database'], 'owners' => ['user'], 'mode' => 'dedicated', 'owner' => ['table' => 'members', 'key' => 'uuid', 'type' => 'uuid']], + ], + ])); + + expect(SchemaShape::fromArray($shape->toArray())->toArray())->toBe($shape->toArray()) + ->and($shape->store(new StoreName('users'))->fallback?->value)->toBe('settings') + ->and($shape->store(new StoreName('users'))->ownerKey)->toBe('uuid') + ->and($shape->differencesFrom($shape))->toBe([]); +}); + +it('lists every difference between two shapes, one line each', function (): void { + $before = SchemaShape::fromConfig(settingsConfig()); + $after = SchemaShape::fromConfig(settingsConfig(['identity' => ['mode' => 'uid_only'], 'stores' => ['settings' => ['soft_deletes' => true]]])); + + expect($after->differencesFrom($before))->toBe([ + 'switches.identity: slug_uid → uid_only', + 'stores.settings.soft_deletes: false → true', + ]); +}); + +it('keeps an existing store entry when the same store is added again', function (): void { + $shape = SchemaShape::fromConfig(settingsConfig()); + $other = new StoreSchema(new StoreName('settings'), softDeletes: true); + + expect($shape->withStore($other)->store(new StoreName('settings'))->softDeletes)->toBeFalse() + ->and($shape->withStore(new StoreSchema(new StoreName('extra')))->hasStore(new StoreName('extra')))->toBeTrue(); +}); + +it('names the config path of every invalid switch', function (array $extra, string $message): void { + expect(fn (): SchemaShape => SchemaShape::fromConfig(settingsConfig($extra)))->toThrow(InvalidConfiguration::class, $message); +})->with([ + 'identity' => [['identity' => ['mode' => 'nope']], 'identity.mode'], + 'owner key' => [['ids' => ['owner_key' => 'int']], 'ids.owner_key'], + 'id type not text' => [['ids' => ['type' => 5]], 'ids.type'], + 'translations' => [['translations' => ['mode' => 'po']], 'translations.mode'], + 'categories' => [['categories' => ['soft_deletes' => 'yes']], 'categories.soft_deletes'], + 'definitions table' => [['definitions' => ['table' => 'yes']], 'definitions.table'], + 'soft deletes' => [['stores' => ['settings' => ['soft_deletes' => 1]]], 'soft_deletes'], + 'table' => [['stores' => ['settings' => ['table' => 5]]], '.table'], + 'bad store name' => [['stores' => ['Bad Name' => ['layers' => ['database']]]], 'stores.Bad Name'], + 'section' => [['identity' => 'slug_uid'], 'laranail.settings.identity'], + 'dedicated chain' => [['stores' => [ + 'a' => ['layers' => ['database'], 'owners' => ['x'], 'mode' => 'dedicated', 'owner' => ['table' => 'xs'], 'fallback' => 'b'], + 'b' => ['layers' => ['database'], 'owners' => ['y'], 'mode' => 'dedicated', 'owner' => ['table' => 'ys']], + ]], 'is dedicated too'], + 'bad fallback name' => [['stores' => ['a' => ['layers' => ['database'], 'owners' => ['x'], 'mode' => 'dedicated', 'owner' => ['table' => 'xs'], 'fallback' => 'Bad Name']]], '.fallback'], + 'owner key column' => [['stores' => ['a' => ['layers' => ['database'], 'owners' => ['x'], 'mode' => 'dedicated', 'owner' => ['table' => 'xs', 'key' => 'Bad Key']]]], 'owner.key'], +]); + +it('refuses a dedicated store schema built without an owner', function (): void { + expect(fn (): StoreSchema => new StoreSchema(new StoreName('a'), StoreMode::Dedicated))->toThrow(InvalidConfiguration::class, 'dedicated store needs') + ->and(fn (): StoreSchema => new StoreSchema(new StoreName('a'), ownerTable: 'Bad Table'))->toThrow(InvalidConfiguration::class, 'owner.table'); +}); + +it('parses id types loosely and knows which identity columns each mode has', function (): void { + expect(IdType::parse(' BIGINT '))->toBe(IdType::Bigint) + ->and(IdType::parse('serial'))->toBeNull() + ->and(IdentityMode::UidOnly->hasSlug())->toBeFalse() + ->and(IdentityMode::SlugPerRow->hasUid())->toBeFalse() + ->and(IdentityMode::SlugUid->hasSlug() && IdentityMode::SlugUid->hasUid())->toBeTrue(); +});