diff --git a/.gitignore b/.gitignore index 407dcac..0a8b38b 100644 --- a/.gitignore +++ b/.gitignore @@ -5,5 +5,5 @@ composer.lock .phpunit.cache .php-cs-fixer.cache .DS_Store -# Design, ledger and audit files never enter the repository (design §8). +# Local design, ledger and audit notes stay out of the repository. /.claude/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 127b3f3..d07fc95 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Automatic promotion. A store set to `promote: auto` (or every store, with + `LARANAIL_SETTINGS_PROMOTE=auto`) copies its runtime file into its database layer once, the + first time the connection answers and its table exists: straight after `migrate`, or after the + first request or queued job that finds the database ready, once the response is sent. It runs as + the system under the promotion lock, skips keys that already have a row, and archives the file. + A failure is logged and retried on the next run, and reads keep coming from the file until then. + `manual`, the default, keeps today's behaviour. The runtime configuration's + `promote($store, $mode)` sets it per request, and `Settings::promoteWhenReady()` promotes now + when it can and otherwise sets the store to `auto` for the rest of the request, job or command. + `doctor` warns about an `auto` store whose file is still there while its database is ready. +- Selective promotion. `promote` also takes a long form, `['mode' => 'auto', 'include' => + ['settings', 'owners'], 'owners' => ['user', 'team']]`: `settings` are the application-wide + values, `owners` the per-owner values, optionally limited to some morph aliases (`['*']`, the + default, is everything; the runtime file holds setting values only, so these are the only + kinds). The archive keeps the whole original file, and the values left out are written back to + the runtime file in one rename, so they keep answering reads from there. `laranail::settings.promote` + takes `--only=settings,owners` and `--owner=user,team`, `promoteWhenReady()` and the runtime + configuration's `promote()` take a `PromotionSelection`, and `PromotionReport` lists what was + `kept`. +- Fluent promotion setters: `Settings::store('settings')->promotion()->auto()->only('owners') + ->forOwners('user')` (also `manual()`, `everything()`, `forAllOwners()`), for the current + request or job. Each option is resolved in one place, highest first: the fluent setters, the + runtime configuration, persisted configuration, then the configuration file. Automatic promotion, + `promoteWhenReady()`, `doctor` and the command's defaults all read that result, and `SettingsFake` + supports the chain. +- `laranail::settings.show` reads a cached answer's row past the cache and prints its `Stored` + version and whether the `Cache` is stale. +- `doctor` warns when a dedicated store's `owner_id` column does not have the type of the owner + table's key (`: owner key`). + - `laranail::settings.show {key} [--store=] [--owner=] [--locale=] [--reveal]`: prints how one setting resolves (value, layer, scope, type, version, locked, encrypted and sensitive flags, and the latest audit entry), through the same `ExplainSetting` action as `explain()`. Sensitive and @@ -209,6 +239,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- REST listings read `http.page_size` (default 50, clamped to 1 to 200) for a request without + `?limit=`; the key was documented as reserved and every listing used 50. +- Sanctum token abilities are vendor-scoped: `laranail-settings:` and + `laranail-settings:*`, in place of `settings:` and `settings:*`. Issue tokens with the + new names; a token holding only the old names is refused. +- Problem `type` URIs point at sections of the exceptions reference, + `https://opensource.simtabi.com/documentation/laranail/settings/tools/exceptions#` + (`#http-status` for every `http-` type), instead of `…/settings/problems/`, + which had no page. Each type has an anchor there, and a test holds the two together. +- `composer test-coverage` reports coverage without a fixed `--min` floor; coverage ratchets + instead (see CONTRIBUTING). +- With the REST API on, an `authorization.driver` that cannot be built fails closed (every actor + denied, API requests answer `401 actor-required`, one warning logged) instead of raising + `InvalidConfiguration` on every call. Without the API it still raises. - The table shape is fixed, with `tenancy.mode` as the one switch: every table is keyed by a ULID, each values row has a unique `uid` (the history's `setting_ref`) and no `slug`, `settable_id` is `string(36)`, and titles, labels and descriptions are JSON maps of locale to text. The migration diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cda4f15..16b6ce5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,7 @@ Contributions are welcome via pull requests. | Command | What it checks | |---|---| | `composer test` | the Pest suite (Arch, Unit, Feature) | -| `composer test-coverage` | the suite with line coverage, failing below 90 % | +| `composer test-coverage` | the suite with a line coverage report. There is no fixed floor: coverage ratchets, so a pull request may not lower the total it reports, and a number set before it was measured would only be a guess CI enforces | | `composer mutate` | Pest mutation testing of the whole package, failing below a 70 % score (slow; CI runs it weekly, not on pull requests). For your change only: `vendor/bin/pest --mutate --path=src/Changed.php,src/Other.php --exclude-group=mutation-excluded --min=70` | | `composer lint` | Pint (shared laranail config), PHPStan at level max, Rector dry run; never changes files | | `composer composer-audit` | known-vulnerable dependencies | diff --git a/README.md b/README.md index 2fe47ea..b063b63 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,12 @@ `laranail/settings` is not published to Packagist, so there is no registry-version badge to show: see [Install](#install). -> Key-value settings for any Laravel owner (the application, a user, a tenant, a product), stored in layered stores that work before the database exists. +> Key-value settings for any Laravel owner (the application, a user, a tenant, a product), stored in layered stores that work even before the database exists, and after it does. Requires PHP 8.4.1+ or 8.5 and Laravel 13. Works on MySQL, PostgreSQL and SQLite; SQL Server is not supported in 0.x. -> **Pre-release.** The engine, caching, history, approvals, import and export, the opt-in REST API -> and typed settings classes are built; the 0.1 release is being prepared. See -> [Getting started](docs/getting-started.md). +> **Pre-1.0.** 0.1.0 is the first tagged release. Before 1.0 a minor release may change the API; +> [Upgrading](docs/upgrading.md) and the [CHANGELOG](CHANGELOG.md) say what changed. ## Install @@ -28,9 +27,10 @@ composer require laranail/settings ### Getting started Publish the config and the package's one migration (it creates `settings_categories`, a values -table per database store, `settings_audit`, `settings_history` and `settings_change_requests`), migrate, and optionally seed the default -categories: the default store reads the database first, then its runtime file, then shipped -defaults from `settings/defaults.php` when that file exists. +table per database store, `settings_audit`, `settings_history`, `settings_change_requests`, +`settings_definitions` and `settings_stores`), migrate, and optionally seed the default categories. +The default store reads the database first, then its runtime file, then shipped defaults from +`settings/defaults.php` when that file exists. ```bash php artisan laranail::settings.install @@ -74,7 +74,9 @@ $mail->fromAddress = 'ops@acme.test'; $mail->save(); ``` -The JSON REST API is off until `http.enabled` is true; see [REST API](docs/tools/rest-api.md). +The JSON REST API is off until `http.enabled` is true; the [REST API quick start](docs/recipes/rest-api-quick-start.md) +gets a first request through. When something does not resolve as expected, run +`php artisan laranail::settings.doctor` and see [Troubleshooting](docs/troubleshooting.md). [Getting started](docs/getting-started.md) walks through stores, owners and definitions; the [Documentation](#documentation) index lists every page. @@ -89,6 +91,8 @@ The hosted docs live at abilities a ceiling on what the token may do.", "stancl/tenancy": "Detected automatically (tenancy.discriminator = auto): settings, categories, audit rows and in-memory reads are kept per tenant.", "spatie/laravel-multitenancy": "Detected automatically (tenancy.discriminator = auto), like stancl/tenancy." @@ -77,7 +77,7 @@ "scripts": { "setup": "@composer install", "test": "vendor/bin/pest --colors=always", - "test-coverage": "@test --coverage --min=90", + "test-coverage": "@test --coverage", "test-dirty": "@test --dirty --compact", "mutate": "vendor/bin/pest --mutate --everything --exclude-group=mutation-excluded --min=70", "bench": [ diff --git a/config/settings.php b/config/settings.php index 71eef98..092d943 100644 --- a/config/settings.php +++ b/config/settings.php @@ -35,6 +35,8 @@ | locked setting. | approvals: key globs (`mail.*`) whose writes become change requests. | bootstrap: skip the database layer while the application installs. + | promote: `manual` (run laranail::settings.promote) or `auto` (copy + | the runtime file into the database once it is ready). | table: the values table name (default: the store name). | mode: `polymorphic` or `dedicated` (one owner alias, with a | foreign key to `owner.table`; read when migrating). @@ -56,6 +58,7 @@ 'locks' => ['overridable' => false], 'approvals' => ['keys' => []], 'bootstrap' => false, + 'promote' => 'manual', 'mode' => 'polymorphic', 'soft_deletes' => false, ], @@ -68,6 +71,12 @@ */ 'bootstrap' => env('LARANAIL_SETTINGS_BOOTSTRAP', false), + /* + | Overrides every store's `promote` when set: `manual` or `auto`. Null + | leaves each store's own setting. + */ + 'promote' => env('LARANAIL_SETTINGS_PROMOTE'), + /* | Table names. `prefix` is prepended to every table, including each store's | values table. @@ -415,7 +424,7 @@ | routes: switch route groups off. | idempotency: how long (`ttl`) and where (`cache`) responses to writes | sent with an Idempotency-Key header are kept. - | page_size: items per page in listings. + | page_size: items per page in listings without `?limit=` (1 to 200). | | An optional `owners` key maps owner aliases a URL may name to model | classes; unset, the morph map is used. diff --git a/docs/architecture.md b/docs/architecture.md index f0515dd..114ccd0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,11 +1,13 @@ # Architecture -How `laranail/settings` is shaped, and why. +How `laranail/settings` is shaped, and why: key-value settings for any Laravel owner (the +application, a user, a tenant, a product), stored in layered stores that work even before the +database exists, and after it does. ## The model - **Stores.** Settings live in named stores. The default store is `settings`; an application adds - more (`user_settings`, `product_settings`) through configuration and a generated migration. + more (`user_settings`, `product_settings`) through configuration; a store added after install gets its own migration from `make-store`. - **Layers.** A store reads through ordered layers, each backed by a driver: the database, a runtime JSON file, a shipped PHP file, config. Before the application is installed, a store that opts in can serve from its files; once installed, an unreachable database is an error, never @@ -34,16 +36,14 @@ are read and written by the database driver on the query builder, because that p every request. An action never touches a connection or the schema builder itself. A change and its audit entry always go through `Support\AuditedTransaction`, so every write, category change and promotion commits and audits the same way. Only entry points depend on actions. Architecture tests hold each rule, -and each exemption (the guards the actions run through, the action bundles, `QueryAudit`'s three -result shapes) carries its reason and fails when it is no longer needed. +and each exemption (the guards the actions run through, `QueryAudit`'s three result shapes) carries its reason and fails when it is no longer needed. -## Why a Services namespace? +## Why a `Services` namespace? The layering above names a service as a stateful collaborator that owns I/O or a body of rules, -but until 0.1 the services sat beside whatever they served: `Database\AuditRepository` next to the -schema value objects, `Stores\SettingWriter` next to `Store` and `Layer`, `Support\ValuePipeline` -among the stateless helpers it is not one of. Reading a directory did not say which kind of class -it held. Every service now lives under `Services\` (`Database`, `Stores`, `Resolution`, `Access`, +but before 0.1 the services sat beside whatever they served: `SettingWriter` next to `Store` and +`Layer`, `ValuePipeline` among the stateless helpers it is not one of. Reading a directory did not +say which kind of class it held. Every service now lives under `Services\` (`Database`, `Stores`, `Resolution`, `Access`, `Configuration`, `Definitions`, `Tenancy`, `Casting`, `Values`, `Drivers`, `Cache`), and the classes left in their old directories are value objects, contract implementations and entry points. @@ -51,7 +51,7 @@ entry points. Two architecture tests keep it so: nothing under `Services\` implements a plug-in contract (a driver, sink, authorizer, caster, verifier, resolver or discriminator stays beside its kind, where a reader looking for "the drivers" finds them), and no class named `*Repository` or `*Registry` -lives anywhere else. The 19 classes that moved there in 0.1 kept no old name: the package had never +lives anywhere else. The classes that moved there before 0.1 kept no old name: the package had never been tagged, so the aliases were removed before the first release, and a third test asserts the old names no longer resolve. @@ -144,8 +144,7 @@ Every write is one `final` action (`Actions\SetSetting`, …) that authorizes, w Every application gets the same tables: ULID keys, a `uid` per values row, a string owner key (`settable_id`, 36 characters, which fits integer, UUID and ULID model keys alike), and titles, labels and descriptions as JSON maps of locale to text. Each of those used to be a migration-time -switch, recorded in a schema file the runtime read back, and the suite ran a pairwise matrix of -every combination. Most of the combinations served no application, and every one of them was a +switch, recorded in a file the runtime read back, and the suite tested the combinations. Most of the combinations served no application, and every one of them was a branch in the migration, the driver, the models and the doctor. A fixed shape is the shape `spatie/laravel-permission` ships: one migration that reads as what it @@ -174,7 +173,7 @@ it needs neither tenancy package: a `TenantDiscriminator` says who the current t adapters for stancl/tenancy and spatie/laravel-multitenancy picked by `class_exists`. A tenant column (one database) and a database per tenant are both common, so both are modes, and the default is none. In column mode the filter sits where every query is built (the database driver, -the categories repository, the audit sink and queries), so no call path can forget it, and the +the models' tenant scope, the audit sink and queries), so no call path can forget it, and the tenant leads the unique keys so two tenants can hold the same key. Definitions describe settings rather than hold values, so they stay shared. Memoised reads are keyed by tenant in every mode, because a job that loops over tenants is the easiest way to leak one tenant's settings into @@ -221,7 +220,7 @@ mode, so the empty answers before installation are never cached. A bag holds every row of its scope, not only the autoload rows, because a cached bag is treated as complete: a partial bag would turn a non-autoload value into a miss. It is stored as plain arrays, never objects, so the cache never unserializes a package class (applications may restrict -`cache.serializable_classes`), and an entry written by another release, or a corrupted one, reads +Laravel's `cache.serializable_classes`), and an entry written by another release, or a corrupted one, reads as a miss, never as an empty scope. Measured with `composer bench` (phpbench 1.7, PHP 8.5.7, SQLite file database, 200 revolutions x @@ -302,6 +301,13 @@ can still change a shipped default. The runtime file is archived afterwards, so nothing. Its lock is only as wide as the cache store, so a multi-server install needs a shared cache. +Automatic promotion (`promote: auto`) is the same action, run as the system after migrations, +after each request (from a terminating callback, so no response waits on it) and after each +queued job. Its checks are ordered by cost: the configuration first, so an application with no +`auto` store resolves nothing; then one file existence check, so a promoted store costs no query; +then the schema readiness db-tools caches. It never throws into the request: a failure is logged, +the file keeps answering reads, and the next run retries. + ## Why install checks for foreign tables A bare `settings` table plausibly belongs to the application. Installing over it would fail half diff --git a/docs/configuration.md b/docs/configuration.md index aeacd2f..aed1397 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -4,6 +4,8 @@ Every key in `config/laranail/settings.php`, read at `config('laranail.settings. ## Keys +### Stores + | Key | Default | Purpose | |---|---|---| | `default` | `settings` (`LARANAIL_SETTINGS_STORE`) | the store used when a call names neither a store nor an owner | @@ -15,30 +17,64 @@ Every key in `config/laranail/settings.php`, read at `config('laranail.settings. | `stores..table` | the store name | the store's values table, after `tables.prefix` | | `stores..bootstrap` | `false` | skip the database layer while, and only while, there is evidence of an install in progress | | `bootstrap` | `false` (`LARANAIL_SETTINGS_BOOTSTRAP`) | evidence of an install in progress; set it for the install window only | -| `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 definitions table | +| `stores..promote` | `manual` | `manual`: copy the runtime file into the database with `laranail::settings.promote`; `auto`: copy it once, the first time the database connection answers and the store's table exists. A string is shorthand for `['mode' => …]` with every value included | +| `stores..promote.mode` | `manual` | `manual` or `auto`, as above | +| `stores..promote.include` | `['*']` | what automatic promotion copies: `settings` (application-wide values), `owners` (per-owner values), or `*` for both. The runtime file holds setting values only, so these are the only kinds | +| `stores..promote.owners` | `null` | owner values only for these morph aliases (`['user', 'team']`); `null` for every owner | +| `promote` | `null` (`LARANAIL_SETTINGS_PROMOTE`) | `manual` or `auto` for every store, overriding each store's `promote`; `null` leaves each store's own | | `stores..mode` | `polymorphic` | `dedicated`: one owner alias, an `owner_id` foreign key to `owner.table`, owner rows only (read when migrating) | | `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 | -| `writes.retry_on_conflict` | `true` | retry a plain `set()` once after a concurrent change | +| `stores..approvals.keys` | `[]` | key globs (`billing.*`) whose writes become change requests | + +### Tables and tenancy + +| Key | Default | Purpose | +|---|---|---| +| `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 definitions table | | `readiness.flush_on` | the stancl and spatie tenancy events | events after which schema readiness is re-checked | | `tenancy.mode` | `none` (`LARANAIL_SETTINGS_TENANCY`) | `column` adds a `tenant` column to the values, categories, audit, history and change requests tables; `database` relies on a database per tenant (read when migrating, and on every query) | | `tenancy.discriminator` | `auto` | who the current tenant is: `auto` (stancl/tenancy, then spatie/laravel-multitenancy, when installed), `null`, `stancl`, `spatie`, or a class implementing `TenantDiscriminator` | -| `seed.enabled` | `true` (`LARANAIL_SETTINGS_SEED`) | whether `db:seed` creates the default categories | -| `seed.stores` | `[]` | the stores to seed; empty means the default store | -| `seed.categories` | general, appearance, localisation, mail, notifications, security | `slug => title` or `slug => [title, description, icon, parent, sort_order, translations]` | +| `tables.history` | `settings_history` | the history table's name (after `tables.prefix`) | +| `tables.change_requests` | `settings_change_requests` | the change requests table (after `tables.prefix`), one per connection | +| `tables.stores` | `settings_stores` | the persisted configuration table, on the default store's connection | + +### Layers and definitions + +| Key | Default | Purpose | +|---|---|---| | `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` | options only | `key => attributes`; see [Definitions](tools/definitions.md). `table`, `sources` and `allowed_rules` are options, not keys | +| `definitions` | options only | `key => attributes`; see [Definitions](tools/definitions.md). `sources` and `allowed_rules` are options, not keys | | `definitions.sources` | `code`, `config` | where definitions come from; add `database` to read rows edited at runtime (one query per store per request) | | `definitions.allowed_rules` | common rule names | the rules a definitions-table row may use | + +### Writes, cache and seeding + +| Key | Default | Purpose | +|---|---|---| +| `writes.retry_on_conflict` | `true` | retry a plain `set()` once after a concurrent change | +| `seed.enabled` | `true` (`LARANAIL_SETTINGS_SEED`) | whether `db:seed` creates the default categories | +| `seed.stores` | `[]` | the stores to seed; empty means the default store | +| `seed.categories` | general, appearance, localisation, mail, notifications, security | `slug => title` or `slug => [title, description, icon, parent, sort_order, translations]` | +| `cache.enabled` | `true` (`LARANAIL_SETTINGS_CACHE`) | cache each database layer's per-scope bags | +| `cache.store` | `null` (`LARANAIL_SETTINGS_CACHE_STORE`) | a store from `config/cache.php`; null is the default store; share it between servers | +| `cache.prefix` | `laranail-settings` | the start of every cache key | +| `cache.ttl` | `3600` | seconds a cached bag is fresh (at least 1) | +| `cache.stale` | `300` | seconds after `ttl` a stale bag is still answered while it is refreshed (`Cache::flexible()`); `0` for none | + +### Access + +| Key | Default | Purpose | +|---|---|---| | `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 | @@ -48,21 +84,33 @@ Every key in `config/laranail/settings.php`, read at `config('laranail.settings. | `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 | + +### Audit, logging and history + +| Key | Default | Purpose | +|---|---|---| | `audit.sinks` | `['auto']` | `auto` (`database` for a store with an active database layer, else `log`), `database`, `log`, `null` or classes; every sink gets every entry | | `audit.keep_days` | `365` | how long `prune-audit` keeps audit rows | | `logging.channel` | `null` | the application's default channel, a channel name, or `false` for off | | `logging.level` | `info` (`LARANAIL_SETTINGS_LOG_LEVEL`) | the lowest level written | -| `cache.enabled` | `true` (`LARANAIL_SETTINGS_CACHE`) | cache each database layer's per-scope bags | -| `cache.store` | `null` (`LARANAIL_SETTINGS_CACHE_STORE`) | a store from `config/cache.php`; null is the default store; share it between servers | -| `cache.prefix` | `laranail-settings` | the start of every cache key | -| `cache.ttl` | `3600` | seconds a cached bag is fresh (at least 1) | -| `cache.stale` | `300` | seconds after `ttl` a stale bag is still answered while it is refreshed (`Cache::flexible()`); `0` for none | -| `tables.history` | `settings_history` | the history table's name (after `tables.prefix`) | | `history.keep_days` | `365` | how long `prune-history` keeps history entries; null for no age limit | | `history.keep_versions` | `null` | how many versions of each setting `prune-history` keeps; null for all | -| `stores..approvals.keys` | `[]` | key globs (`billing.*`) whose writes become change requests | -| `tables.change_requests` | `settings_change_requests` | the change requests table (after `tables.prefix`), one per connection | -| `tables.stores` | `settings_stores` | the persisted configuration table, on the default store's connection | + +### Events and alerts + +| Key | Default | Purpose | +|---|---|---| +| `listeners.alerts` | `true` | register the alert listener (alerts still need `alerts.enabled`) | +| `listeners.log` | `false` | write every settings event to the logging channel | +| `alerts.enabled` | `false` (`LARANAIL_SETTINGS_ALERTS`) | send alerts | +| `alerts.cache` | `null` | the cache store holding the alert throttle; null for the default | +| `alerts.throttle` | `300` | seconds a rule stays quiet about one key after alerting; `0` for never | +| `alerts.rules` | `[]` | which events alert whom; see [Alerts](tools/alerts.md) | + +### Approvals, persisted configuration, importers and typed classes + +| Key | Default | Purpose | +|---|---|---| | `approvals.min_approvals` | `1` | approvals that apply a change | | `approvals.allow_self` | `false` | let the requester approve their own request | | `approvals.expire_after` | `7` | days before an open request expires; null for never | @@ -71,6 +119,11 @@ Every key in `config/laranail/settings.php`, read at `config('laranail.settings. | `configuration.sources` | `['config', 'database', 'runtime']` | merge order of the file, persisted entries and runtime changes; later wins | | `importers` | `spatie`, `toolkit`, `akaunting` | importers `import --from=` can use, name => class | | `typed.classes` | `[]` | typed settings classes whose properties are registered as definitions | + +### REST API + +| Key | Default | Purpose | +|---|---|---| | `http.enabled` | `false` (`LARANAIL_SETTINGS_HTTP`) | register the REST API's routes | | `http.prefix` | `api/settings` (`LARANAIL_SETTINGS_HTTP_PREFIX`) | the routes' prefix; they live under `/v1`, and an empty prefix mounts them at `/v1`. Change it when the application already has routes under `/api/settings`: Laravel keeps the last route registered for a method and URI and says nothing | | `http.middleware` | `null` | the routes' middleware; null is `['api', 'auth:sanctum']` with Sanctum, else `['api', 'auth']` | @@ -78,13 +131,7 @@ Every key in `config/laranail/settings.php`, read at `config('laranail.settings. | `http.routes.` | `true` | switch a group off: `stores`, `definitions`, `settings`, `history`, `audit`, `approvals`, `categories`, `configuration`, `transfer` | | `http.idempotency.cache` / `http.idempotency.ttl` | `null` / `86400` | where and how long a write's response is kept for an `Idempotency-Key` | | `http.owners` | unset | owner alias => model class for URLs; unset uses the morph map | -| `http.page_size` | `50` | the default page size of lists | -| `listeners.alerts` | `true` | register the alert listener (alerts still need `alerts.enabled`) | -| `listeners.log` | `false` | write every settings event to the logging channel | -| `alerts.enabled` | `false` (`LARANAIL_SETTINGS_ALERTS`) | send alerts | -| `alerts.cache` | `null` | the cache store holding the alert throttle; null for the default | -| `alerts.throttle` | `300` | seconds a rule stays quiet about one key after alerting; `0` for never | -| `alerts.rules` | `[]` | which events alert whom; see [Alerts](tools/alerts.md) | +| `http.page_size` | `50` | items per page in every REST listing without `?limit=`; clamped to 1 to 200 | 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`. diff --git a/docs/getting-started.md b/docs/getting-started.md index e7c805f..72f027e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -2,6 +2,11 @@ Read and write settings, give them owners, and describe them with definitions. +`laranail/settings` keeps key-value settings for any Laravel owner (the application, a user, a +tenant, a product), stored in layered stores that work even before the database exists, and after +it does. This page +takes a fresh application from install to its first owner and definition. + ## Install and migrate ```bash @@ -65,14 +70,37 @@ app(DefinitionRegistry::class)->define('limits.seats') Definitions add types, defaults, validation, encryption, locks and inheritance. See [Definitions](tools/definitions.md). -## What comes next +## Act on a user's behalf + +A call without an actor is trusted application code, audited as `system`. Name the actor when a +person is behind the change, and the call is authorized against the `laranail-settings.` +gates and audited with the reason: + +```php +Settings::as($request->user())->because('INC-123')->set('mail.from.address', 'ap@acme.test'); +``` + +Define the gates first (`Gate::define('laranail-settings.update', …)`): an ability nobody defined is +denied. See [Act as a user](recipes/acting-as-a-user.md) and [Access control](tools/access-control.md). + +## Check it + +```bash +php artisan laranail::settings.doctor # tables, columns, encryption and stored data +php artisan laranail::settings.show site.name # where one value comes from +``` + +When something does not resolve as expected, [Troubleshooting](troubleshooting.md) lists the common +errors and what to run. + +## Where to go next -| Phase | Adds | -|---|---| -| Dedicated stores | an `owner_id` foreign key that deletes an owner's settings with it; soft deletes | -| Performance | caching with stale-while-revalidate | -| Governance | history and rollback, approvals, export and import, the full `doctor` | -| Typed classes | strongly typed settings classes over the same engine | +- [Typed settings](tools/typed-settings.md) for a class over a group of keys. +- [REST API](tools/rest-api.md), off by default, for an admin UI or a mobile client; the + [REST quick start](recipes/rest-api-quick-start.md) gets a first request through. +- [Caching](tools/caching.md), [History](tools/history.md) and [Approvals](tools/approvals.md) for + production use. +- [Tenancy](tools/tenancy.md) before the first migration of a multi-tenant application. --- diff --git a/docs/installation.md b/docs/installation.md index 8a5d7dd..7d2db3e 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -61,13 +61,7 @@ name it. It creates the `seed.categories` set (general, appearance, localisation notifications, security) as system categories and changes nothing when run again. See [Seed the default categories](recipes/seeding-default-categories.md). -## Upgrading from the four migration stubs - -Before the single migration, install published four migrations (`create_settings_categories_table`, -`create_settings_table`, `create_settings_audit_table`, `create_settings_definitions_table`). -They stay in your `database/migrations` and keep working; do not publish the new one next to -them, or the tables would be created twice. Store migrations written by an older `make-store` -keep working too. +## When install refuses Install refuses to publish anything when a table of the same name already exists and is not this package's (a `settings` table of your own, say). Rename the package's tables with @@ -87,6 +81,20 @@ and shipped PHP defaults, as before: To start on files and move to the database later, see [Moving from files to the database](recipes/moving-from-files-to-the-database.md). +## From an installer + +An installer that writes settings before the database exists can let the package move them once +it does. Put the store in bootstrap mode, then ask for the promotion at the start of the install: + +```php +Settings::store('settings')->asSystem('installer')->promoteWhenReady(); +``` + +The values the installer writes go to the runtime file. When its `migrate` call finishes, the +store is promoted in the same process. To keep doing this after the install, on every server, set +`'promote' => 'auto'` on the store or `LARANAIL_SETTINGS_PROMOTE=auto`; `promote.include` and +`promote.owners` limit what is moved (see [Configuration](configuration.md)). + ## The REST API The JSON API is off until `http.enabled` is true; nothing is routed before that. It uses the diff --git a/docs/recipes/calling-the-rest-api-with-sanctum.md b/docs/recipes/calling-the-rest-api-with-sanctum.md index 739d134..d1cd0d2 100644 --- a/docs/recipes/calling-the-rest-api-with-sanctum.md +++ b/docs/recipes/calling-the-rest-api-with-sanctum.md @@ -24,10 +24,10 @@ Gate::define('laranail-settings.update', fn (User $user) => $user->is_admin); ## Issue a token ```php -$token = $user->createToken('deploy-bot', ['settings:view', 'settings:update'])->plainTextToken; +$token = $user->createToken('deploy-bot', ['laranail-settings:view', 'laranail-settings:update'])->plainTextToken; ``` -A token's `settings:` abilities are a ceiling on top of the gates: the token above can never `forget`, `rollback` or `approve`, even for an admin. `settings:*` lifts the ceiling. +A token's `laranail-settings:` abilities are a ceiling on top of the gates: the token above can never `forget`, `rollback` or `approve`, even for an admin. `laranail-settings:*` lifts the ceiling. ## Call it diff --git a/docs/recipes/consuming-from-an-spa-or-mobile-app.md b/docs/recipes/consuming-from-an-spa-or-mobile-app.md index c98d15c..ea6aa5d 100644 --- a/docs/recipes/consuming-from-an-spa-or-mobile-app.md +++ b/docs/recipes/consuming-from-an-spa-or-mobile-app.md @@ -15,7 +15,7 @@ The SPA calls `/sanctum/csrf-cookie` once, logs in, then sends `credentials: 'in ## A mobile app: a token with a ceiling ```php -$token = $user->createToken('ios', ['settings:view', 'settings:update'])->plainTextToken; +$token = $user->createToken('ios', ['laranail-settings:view', 'laranail-settings:update'])->plainTextToken; ``` ```http diff --git a/docs/recipes/migrating-from-spatie-laravel-settings.md b/docs/recipes/migrating-from-spatie-laravel-settings.md index 3b75bef..5e94319 100644 --- a/docs/recipes/migrating-from-spatie-laravel-settings.md +++ b/docs/recipes/migrating-from-spatie-laravel-settings.md @@ -42,7 +42,7 @@ final class GeneralSettings extends TypedSettings Properties map to snake-cased keys by default (`siteName` is `general.site_name`), so `#[Key]` is only needed where the names differ. Replace `GeneralSettings::class` injections with the new class (resolved from the container, it loads itself) and `$settings->save()` keeps working. -spatie's settings migrations become [settings migrations](../tools/typed-settings.md#settings-migrations-g-17). When nothing reads spatie's table any more, drop it. +spatie's settings migrations become [settings migrations](../tools/typed-settings.md#settings-migrations). When nothing reads spatie's table any more, drop it. --- diff --git a/docs/recipes/moving-from-files-to-the-database.md b/docs/recipes/moving-from-files-to-the-database.md index 6dbbf87..345aa7b 100644 --- a/docs/recipes/moving-from-files-to-the-database.md +++ b/docs/recipes/moving-from-files-to-the-database.md @@ -37,7 +37,83 @@ database restored from an older backup: php artisan laranail::settings.promote --from=laranail/settings/settings.promoted-20261109_101500_000000.json ``` -Then remove `LARANAIL_SETTINGS_BOOTSTRAP`. From then on an unreachable database raises +## Promoting automatically + +Set the store to promote on its own, and it copies the runtime file into the database once, the +first time the database connection answers and the store's table exists: + +```php +'stores' => [ + 'settings' => ['layers' => ['database', 'runtime', 'shipped'], 'bootstrap' => true, 'promote' => 'auto'], +], +``` + +`LARANAIL_SETTINGS_PROMOTE=auto` does the same for every store. + +## Configure promotion + +Every promotion option can be set in the configuration file, in code, or both: + +```php +// config/laranail/settings.php +'stores' => [ + 'settings' => [ + 'promote' => [ + 'mode' => 'auto', // manual | auto + 'include' => ['owners'], // settings, owners, or ['*'] (the default) + 'owners' => ['user'], // null (the default) for every owner + ], + ], +], +``` + +```php +// in code, for the current request or job +Settings::store('settings')->promotion() + ->auto() // ->manual() + ->only('owners') // ->everything() + ->forOwners('user'); // ->forAllOwners() +``` + +**Precedence, highest first: the fluent setters, then the runtime configuration +(`configuration()->addStore()`), then persisted configuration, then the configuration file** +(the last three in `configuration.sources` order, which is that order by default). +`LARANAIL_SETTINGS_PROMOTE` overrides every store's configured `mode`; only the fluent setters +beat it. Each option is resolved on its own, so `->only('owners')` changes what is copied and +leaves the mode to configuration. The string `'promote' => 'auto'` is shorthand for everything. +Automatic promotion, `promoteWhenReady()`, the command's defaults and `doctor` all read the same +resolved options. + +The runtime file holds setting values only: `settings` are the application-wide values and +`owners` the per-owner ones. Categories and definitions never go to the file, so they cannot be +promoted from it, and naming them is an error. + +The archive keeps the whole original file. What the selection leaves out is written back to the +runtime file in one rename, so it keeps answering reads from there, and it is never promoted on +its own. The command takes the same choice: `--only=settings,owners` and `--owner=user,team`. The promotion runs straight after +`php artisan migrate`, and otherwise after the first request or queued job that finds the database +ready, once the response has been sent. Until then each request costs one file check; once the +file is archived there is nothing left to check against the database. While a selective +promotion leaves values in the file, each request also reads the file to see that none of them is +selected, and still runs no query. It runs as the system, takes +the same lock as the command (a held lock means another process is already promoting), skips keys +that already have a database row, and is audited and logged like a manual promotion. When it +fails, the failure is logged as a warning, the file keeps answering reads, and the next request +tries again. + +An installer that cannot know whether the database is ready yet can ask for the same thing in +code: + +```php +Settings::store('settings')->asSystem('installer')->promoteWhenReady(); +``` + +It promotes at once when it can, and otherwise sets the store to `auto` for the rest of the +request, job or command. + +## Leaving bootstrap mode + +Once the values are in the database, remove `LARANAIL_SETTINGS_BOOTSTRAP`. From then on an unreachable database raises `DriverUnavailable`; it never falls back to the file. --- diff --git a/docs/recipes/rest-api-quick-start.md b/docs/recipes/rest-api-quick-start.md new file mode 100644 index 0000000..9e3f1b8 --- /dev/null +++ b/docs/recipes/rest-api-quick-start.md @@ -0,0 +1,51 @@ +# REST API quick start + +Turn the API on, authenticate, and make a first read and write. + +## Enable it + +```dotenv +LARANAIL_SETTINGS_HTTP=true +``` + +The routes live under `/api/settings/v1` and use `['api', 'auth:sanctum']` when Sanctum is +installed, else `['api', 'auth']`. Change the prefix with `LARANAIL_SETTINGS_HTTP_PREFIX` if the +application already has routes under `/api/settings`. + +## Authenticate and allow + +The API runs as the authenticated user, never as trusted code, so define the gates that user needs: + +```php +// app/Providers/AppServiceProvider.php, in boot() +Gate::define('laranail-settings.view', fn (User $user) => true); +Gate::define('laranail-settings.update', fn (User $user) => $user->is_admin); +``` + +For a token, install Sanctum and issue one: + +```php +$token = $user->createToken('admin-ui', ['laranail-settings:view', 'laranail-settings:update'])->plainTextToken; +``` + +## First request + +```bash +curl -s https://app.example/api/settings/v1/stores \ + -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' + +curl -si -X PUT https://app.example/api/settings/v1/stores/settings/settings/site.name \ + -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \ + -d '{"value": "Acme", "reason": "first run"}' +``` + +The write answers `200` with the setting and an `ETag` header; send it back as `If-Match` on the +next write so a concurrent change answers `412` instead of being overwritten. Errors are RFC 9457 +problem details. + +Next: [Call the REST API with Sanctum](calling-the-rest-api-with-sanctum.md) for token abilities and +idempotency, and the [REST API reference](../tools/rest-api-reference.md) for every route. + +--- + +[← Docs index](../../README.md#documentation) diff --git a/docs/release.md b/docs/release.md index a86079c..6027a72 100644 --- a/docs/release.md +++ b/docs/release.md @@ -6,7 +6,7 @@ How `laranail/settings` is versioned and released. Semantic versioning. Every release is a new, increasing tag (`v0.1.0`, `v0.1.1`, …). A published tag is never moved, deleted or reused: the next fix gets the next number. Breaking changes before -1.0 bump the minor version and carry an `UPGRADING` note. +1.0 bump the minor version and are listed in [Upgrading](upgrading.md). ## Cutting a release diff --git a/docs/tools/access-control.md b/docs/tools/access-control.md index 131918f..aabd060 100644 --- a/docs/tools/access-control.md +++ b/docs/tools/access-control.md @@ -1,6 +1,6 @@ # Access control -Actors, the 17 abilities, the authorizers that decide them, guarded locks, sensitive reads and step-up verification. +Actors, the 18 abilities, the authorizers that decide them, guarded locks, sensitive reads and step-up verification. ## When access is checked @@ -79,9 +79,16 @@ An ability nobody defined abstains, and `authorization.undefined` decides it: `d An authorizer returns a `Decision`: `allow()`, `deny($reason)`, `requiresVerification()`, `requiresApproval()` or `abstain()`. A denial raises `AccessDenied`, which carries the ability, store and key and never a value. +When `authorization.driver` names something that cannot be built, every call raises +`InvalidConfiguration` naming the path. With the REST API on, the package fails closed instead, +so the API is never left open by a typo: it uses a guard that denies every actor and resolves +none, logs one warning per request saying why, and keeps trusted code (calls without an actor) +working. API requests then answer `401 actor-required`; actors calling the PHP API get +`AccessDenied`. + ## Tokens are a ceiling -A token-bearing actor must also hold the ability in its token: `settings:`, `settings:*` or `*`. The token never grants anything on its own; the authorizer must allow too. +A token-bearing actor must also hold the ability in its token: `laranail-settings:`, `laranail-settings:*` or `*`. The token never grants anything on its own; the authorizer must allow too. ## Guarded locks @@ -117,7 +124,7 @@ An unverified actor gets `VerificationRequired`. Send the user through Laravel's ## Approvals -A definition can say `requiresApproval()`. Four-eyes approval needs the database layer, which arrives in a later release, so until then every write to such a setting raises `ApprovalUnavailable`, with or without an actor. An actor not allowed to write at all gets `AccessDenied` first. +A definition can say `requiresApproval()`, and a store can name key globs in `approvals.keys`. A write to such a setting opens a change request instead of writing; see [Approvals](approvals.md). A store without an active database layer cannot hold change requests, so there the write raises `ApprovalUnavailable`, as it does when an authorizer answers that the ability needs approval. An actor not allowed to write at all gets `AccessDenied` first. --- diff --git a/docs/tools/caching.md b/docs/tools/caching.md index 22f924d..c0782fc 100644 --- a/docs/tools/caching.md +++ b/docs/tools/caching.md @@ -20,6 +20,7 @@ A read through the cascade (owner, parents, global) costs, per distinct store in | cold (bags not cached) | one, covering every scope the read needs from that store | two (tokens, then bags) and one write | | warm (bags cached) | none | two | | again in the same request | none | none (bags and tokens are held in memory for the request) | +| `cache.enabled` off | one per read | none | ## Keys diff --git a/docs/tools/commands.md b/docs/tools/commands.md index c169009..75b99ac 100644 --- a/docs/tools/commands.md +++ b/docs/tools/commands.md @@ -8,7 +8,7 @@ Nineteen Artisan commands, all named `laranail::settings.`. |---|---| | `laranail::settings.install` | publishes the config and the package's one migration, 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 (a copy of the package migration pinned to that store) 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.promote [store] [--force] [--from=] [--only=] [--owner=]` | copies values written before install from the runtime file into the database; `--only=settings,owners` and `--owner=user,team` copy only some (default: the store's resolved `promote` options), and the rest stay in the file | | `laranail::settings.doctor [--json] [--fix]` | checks readiness, missing columns and rows the database cannot guard; `--fix` syncs definitions first | | `laranail::settings.show {key} [--store=] [--owner=] [--locale=] [--reveal]` | prints how one setting resolves: value, layer, scope, type, version, flags and the latest audit entry | | `laranail::settings.sync-definitions` | copies code and config definitions into the definitions table as system rows | @@ -49,13 +49,17 @@ exists); it prints the layer to add. It refuses a store that already has a migra ## `doctor` -For every store with a database layer: +For every store with a database layer (a store without one is reported as skipped): | Check | Fails when | |---|---| | readiness | the connection does not answer or the table is missing (a warning in bootstrap mode) | +| promotion | warns when a store set to `promote: auto` still has values it selects in its runtime file although its database is ready | +| owner key | for a dedicated store, warns when `owner_id` does not have the type of the owner table's key | | schema | a column the package uses is missing from the values, categories, audit, history or change requests table (and, on the default store's connection, the definitions and stores tables) | | scopes | a scope names a class instead of a morph alias (fails) or an alias the store does not list (warns) | +| encryption | an encrypted value cannot be decrypted with the current or previous keys (put the old key in `APP_PREVIOUS_KEYS`, then run `reencrypt`) | +| change requests | warns when open change requests are past their expiry (schedule `prune-changes`) | | categories | a row points at a category of another store | | category keys | warns when a value's key does not start with its category's slug | @@ -85,6 +89,8 @@ php artisan laranail::settings.show theme --owner=user:42 --locale=fr | From scope | global | | Type | string | | Version | 3 | +| Stored | version 3 | +| Cache | current | | Locked | no | | Encrypted | no | | Sensitive | no | @@ -100,6 +106,10 @@ definition, or show `-`. `Last audit` is the newest entry for that key and scope audit trail is not stored in the database. The command runs as the system actor, through the same `Actions\Reads\ExplainSetting` action as `explain()` and the REST API. +When the answer came through the settings cache, `Stored` is the version of the row read past the +cache, and `Cache` says `stale: run laranail::settings.clear-cache` when the two differ (a row +edited by hand, say). + ## `prune-orphans` Lists, per store and alias, the owner scopes whose model no longer exists (soft-deleted models diff --git a/docs/tools/exceptions.md b/docs/tools/exceptions.md index 544e943..ea1e715 100644 --- a/docs/tools/exceptions.md +++ b/docs/tools/exceptions.md @@ -32,7 +32,7 @@ Messages name the store, key, scope and ability involved, never a value, so they | `AccessDenied` | `SettingsException` | an actor may not perform the ability on the subject; carries the ability, store and key | `403 access-denied` | | `ActorRequired` | `SettingsException` | a call has no actor while `authorization.require_actor` is on, or `asCurrentActor()` finds nobody | `401 actor-required` | | `VerificationRequired` | `SettingsException` | the actor is allowed but must verify again (step-up), for an ability in `verification.abilities` or a definition that `requiresVerification()` | `428 verification-required` | -| `ApprovalUnavailable` | `SettingsException` | a write needs approval but the store cannot hold change requests (no active database layer, or no change requests table) | `409 approval-unavailable` | +| `ApprovalUnavailable` | `SettingsException` | a write needs approval but the store cannot hold change requests (no active database layer), or an authorizer answered that the ability needs approval | `409 approval-unavailable` | | `ChangeRequestClosed` | `SettingsException` | a change request was already applied, rejected, cancelled, stale or expired | `409 change-request-closed` | | `UnknownChangeRequest` | `SettingsException` | no change request with this id exists in the store (for the current tenant) | `404 unknown-change-request` | | `ConcurrentModification` | `SettingsException` | another writer changed the row between read and update (the version check failed), or `If-Match` did not match; re-read and retry | `412 precondition-failed` | @@ -61,7 +61,130 @@ Messages name the store, key, scope and ability involved, never a value, so they `LogicException` (PHP's own) is thrown for a programming error rather than a runtime condition: `flush()` without `for($owner)`. -Each exception names its HTTP status and problem type itself (`STATUS` and `TYPE` constants), and `Http\Support\Problems` renders them; anything without its own is a `500 settings-error`; [REST API reference](rest-api-reference.md#problem-types) lists every problem type. +Each exception names its HTTP status and problem type itself (`STATUS` and `TYPE` constants), and `Http\Support\Problems` renders them; anything without its own is a `500 settings-error`; [Problem types](#problem-types) below lists every problem type. + +## Problem types + +Each REST error is a problem document whose `type` is this page's URL with the problem type as +its fragment, for example +`https://opensource.simtabi.com/documentation/laranail/settings/tools/exceptions#locked`. Every +`http-` type points at [`http-status`](#http-status). + +### `access-denied` + +Status 403. Raised by `AccessDenied`. + +### `actor-required` + +Status 401. Raised by `ActorRequired`. + +### `unauthenticated` + +Status 401. Raised by the host's authentication middleware. + +### `verification-required` + +Status 428. Raised by `VerificationRequired`: verify (confirm the password) and retry. + +### `unknown-store` + +Status 404. Raised by `UnknownStore`. + +### `unknown-setting` + +Status 404. Raised by `UnknownSetting` (a strict store's undefined key). + +### `unknown-owner` + +Status 404. Raised by `UnknownOwner` (an alias or record the owner resolver cannot find). + +### `unknown-category` + +Status 404. Raised by `UnknownCategory`. + +### `unknown-change-request` + +Status 404. Raised by `UnknownChangeRequest`. + +### `invalid-value` + +Status 422. Raised by `InvalidSettingValue`. + +### `invalid-identifier` + +Status 422. Raised by `InvalidIdentifier`, `InvalidKey` (a key, store, locale, alias or filter). + +### `invalid-import` + +Status 422. Raised by `InvalidImport`. + +### `invalid-definition` + +Status 422. Raised by `InvalidDefinition`. + +### `invalid-configuration` + +Status 422. Raised by `InvalidConfiguration`. + +### `type-mismatch` + +Status 422. Raised by `TypeMismatch`. + +### `category-cycle` + +Status 422. Raised by `CategoryCycle`. + +### `category-store-mismatch` + +Status 422. Raised by `CategoryStoreMismatch`. + +### `validation` + +Status 422. Raised by request validation; the body adds `errors`. + +### `locked` + +Status 423. Raised by `LockedSetting`. + +### `precondition-failed` + +Status 412. Raised by `ConcurrentModification` (`If-Match` did not match). + +### `approval-unavailable` + +Status 409. Raised by `ApprovalUnavailable`. + +### `change-request-closed` + +Status 409. Raised by `ChangeRequestClosed`. + +### `owner-not-allowed` + +Status 409. Raised by `OwnerNotAllowed`. + +### `store-not-writable` + +Status 409. Raised by `StoreNotWritable`. + +### `history-unavailable` + +Status 409. Raised by `HistoryUnavailable`. + +### `too-many-requests` + +Status 429. Raised by the rate limit. + +### `unavailable` + +Status 503. Raised by `DriverUnavailable`. + +### `http-` + +Status that status. Raised by any other HTTP exception (`http-404` for an unknown route). + +### `settings-error` + +Status 500. Raised by any other package exception (its message is not exposed). --- diff --git a/docs/tools/rest-api-reference.md b/docs/tools/rest-api-reference.md index 9f3a14b..5aeadfd 100644 --- a/docs/tools/rest-api-reference.md +++ b/docs/tools/rest-api-reference.md @@ -9,7 +9,7 @@ Paths are under `/{http.prefix}/v1`, by default `/api/settings/v1`; set `http.pr | Topic | Rule | |---|---| | Authentication | the host's `http.middleware` authenticates; the actor resolver turns the request into an actor on the `rest` channel. No actor: `401`. The API never runs as trusted code. | -| Abilities | each route names the ability its action checks. A Sanctum token's `settings:` abilities are a ceiling on top. | +| Abilities | each route names the ability its action checks. A Sanctum token's `laranail-settings:` abilities are a ceiling on top. | | Owners | a settings route has a global form (`/stores/{store}/settings/…`) and an owner form (`/stores/{store}/owners/{alias}/{id}/settings/…`). `{alias}` is a morph alias from `http.owners` or the morph map, never a class name. | | Locales | `?locale=fr` on settings routes; the write routes also take it. | | Bodies | JSON. Every write may send `"reason"` (recorded in the audit trail and history). | @@ -313,10 +313,10 @@ Answers `200` with the `ImportReport` (`applied`, `created`, `updated`, `unchang ## Problem types -Every error is a problem document whose `type` is `https://opensource.simtabi.com/documentation/laranail/settings/problems/`: +Every error is a problem document whose `type` is `https://opensource.simtabi.com/documentation/laranail/settings/tools/exceptions#`, a section of the [exceptions reference](exceptions.md#problem-types) (`http-` types point at `#http-status`): ```json -{"type": "https://opensource.simtabi.com/documentation/laranail/settings/problems/locked", "title": "Locked", "status": 423, +{"type": "https://opensource.simtabi.com/documentation/laranail/settings/tools/exceptions#locked", "title": "Locked", "status": 423, "detail": "Setting [billing.currency] in store [settings] is locked for scope [global].", "instance": "/api/settings/v1/stores/settings/settings/billing.currency"} ``` diff --git a/docs/tools/rest-api.md b/docs/tools/rest-api.md index 45853ba..856d4ec 100644 --- a/docs/tools/rest-api.md +++ b/docs/tools/rest-api.md @@ -15,7 +15,7 @@ A JSON API over every capability of the PHP API, in this package and off by defa ], ``` -No route is registered until `enabled` is true. The routes are declared in `routes/api.php`, and each controller method takes the action it runs as a parameter, so under Octane no request's actor, tenant or stores reach the next one. Routes are named `laranail-settings.api.` (the owner form of a settings route adds `owners.`), run through `http.middleware` and the `laranail-settings` rate limiter, and every write runs through the idempotency middleware. The host's middleware authenticates; the configured actor resolver turns the request into an [actor](access-control.md) on the `rest` channel, so with the `sanctum` resolver a token's `settings:` abilities are a ceiling on what it may do. A request nobody is authenticated for is refused (`401`); the API never runs as trusted code. +No route is registered until `enabled` is true. The routes are declared in `routes/api.php`, and each controller method takes the action it runs as a parameter, so under Octane no request's actor, tenant or stores reach the next one. Routes are named `laranail-settings.api.` (the owner form of a settings route adds `owners.`), run through `http.middleware` and the `laranail-settings` rate limiter, and every write runs through the idempotency middleware. The host's middleware authenticates; the configured actor resolver turns the request into an [actor](access-control.md) on the `rest` channel, so with the `sanctum` resolver a token's `laranail-settings:` abilities are a ceiling on what it may do. A request nobody is authenticated for is refused (`401`); the API never runs as trusted code. ## Endpoints @@ -76,7 +76,7 @@ Idempotency-Key: 6c0d1e8e-… RFC 9457 problem details, `application/problem+json`: ```json -{"type": "https://opensource.simtabi.com/documentation/laranail/settings/problems/locked", "title": "Locked", "status": 423, +{"type": "https://opensource.simtabi.com/documentation/laranail/settings/tools/exceptions#locked", "title": "Locked", "status": 423, "detail": "Setting [theme] in store [settings] is locked for scope [user:1].", "instance": "/api/settings/v1/…"} ``` diff --git a/docs/tools/runtime-configuration.md b/docs/tools/runtime-configuration.md index 7521fbc..1151137 100644 --- a/docs/tools/runtime-configuration.md +++ b/docs/tools/runtime-configuration.md @@ -20,6 +20,7 @@ | `auditTo(AuditSink ...)` | add audit sinks next to the configured ones | | `logTo(LoggerInterface\|false)` | send the operational log elsewhere, or nowhere | | `requireActor()` / `allowActorless()` | override `authorization.require_actor` | +| `promote($store, 'manual'\|'auto', ?PromotionSelection $only)` | how a store promotes its runtime file, and optionally what it copies; wins over `stores..promote` and the global `promote` | Each change returns the configuration, so calls chain, and each is logged and audited as `configure`. diff --git a/docs/tools/settings-api.md b/docs/tools/settings-api.md index c27a657..2227726 100644 --- a/docs/tools/settings-api.md +++ b/docs/tools/settings-api.md @@ -38,7 +38,7 @@ $settings->store('user_settings')->for($user)->locale('fr')->as($admin)->because | Cache and loading | [`preload()`](#preload), [`warmCache()`](#warmcache), [`clearCache()`](#clearcache) | | History | [`history()`](#history), [`historyDiff()`](#historydiff), [`rollback()`](#rollback) | | Approvals | [`propose()`](#propose), [`approvals()`](#approvals) | -| Store administration | [`categories()`](#categories), [`promote()`](#promote), [`audit()`](#audit), [`export()`](#export), [`import()`, `previewImport()`](#import-and-previewimport), [`compare()`](#compare), [`persistedConfiguration()`](#persistedconfiguration) | +| Store administration | [`categories()`](#categories), [`promote()`](#promote), [`promoteWhenReady()`](#promotewhenready), [`promotion()`](#promotion), [`audit()`](#audit), [`export()`](#export), [`import()`, `previewImport()`](#import-and-previewimport), [`compare()`](#compare), [`persistedConfiguration()`](#persistedconfiguration) | | Context | [`actor()`](#actor), [`configuration()`](#configuration), [`withConfiguration()`](#withconfiguration) | Abilities are named in the [access control](access-control.md) reference. A handle **without** an actor is trusted code: it is not authorized, and it is audited as `system` (unless `authorization.require_actor` is on, when it throws `ActorRequired`). A handle **with** an actor is authorized for every operation, reads included, and every refusal fires `AccessWasDenied`. @@ -440,6 +440,37 @@ $report->promoted; // keys copied into the database Copies the values written to the runtime file before the database existed into the database layer; shipped defaults are never copied. Idempotent. Needs `promote`. Throws `PromotionLocked`, `StoreNotWritable`, `AccessDenied`. Fires `StorePromoting` and `StorePromoted`. See [Move from files to the database](../recipes/moving-from-files-to-the-database.md). +### `promoteWhenReady()` + +```php +public function promoteWhenReady(?PromotionSelection $only = null): ?PromotionReport + +$report = $settings->store('settings')->asSystem('installer')->promoteWhenReady(); +``` + +Promotes now when the store's database connection answers and its table exists, and returns the +report. Otherwise it returns `null` and sets the store to promote automatically for the rest of +the request, job or command, so the promotion runs after the migrations finish or when the request +ends. Returns `null` too when another process holds the promotion lock. `$only` picks what is +copied, as `promote.include` and `promote.owners` do: `new PromotionSelection(settings: true, +owners: false)` copies the application-wide values and leaves owner values in the file; null uses +the store's configuration. Needs `promote`. Throws +`StoreNotWritable` when the store has no database layer, and `AccessDenied`. + +### `promotion()` + +```php +public function promotion(): PromotionSettings + +Settings::store('settings')->promotion()->auto()->only('owners')->forOwners('user', 'team'); +``` + +Fluent setters for the store's promotion, for the current request or job: `auto()`, `manual()`, +`only('settings', 'owners')`, `everything()`, `forOwners('user', ...)` and `forAllOwners()`. Each +returns the builder and wins over the same option in configuration; an option it does not set keeps +coming from configuration. `only()` throws `InvalidConfiguration` for a kind the runtime file cannot +hold. See [Configure promotion](../recipes/moving-from-files-to-the-database.md#configure-promotion). + ### `audit()` ```php diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..c069db6 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,40 @@ +# Troubleshooting + +The errors people meet most often, what each means, and the command that shows the cause. + +## Two commands to run first + +```bash +php artisan laranail::settings.doctor # tables, columns, encryption and stored data +php artisan laranail::settings.show mail.from_address # where one value comes from, and the last change +``` + +`doctor` exits non-zero on a failure, so it can also gate a deploy. `show` prints the value, the +layer and scope that answered, the version, the flags and the latest audit entry, then the +resolution steps. From PHP, `Settings::explain('mail.from_address')` returns the same steps. + +## Errors + +| You see | Cause | Fix | +|---|---|---| +| a store set to `promote: auto` still reads from its runtime file | promotion runs only once the connection answers and the table exists, after migrations, a request or a queued job; a failed attempt is logged as a warning and retried on the next one | run `doctor` (`promotion`), read the log entry (`could not promote store`), fix the cause, or run `laranail::settings.promote` | +| `DriverUnavailable`: the database layer is unavailable (unreachable, or table missing) | the migration has not run, or the connection is down; the package never falls back to defaults silently | `php artisan migrate`, then `doctor` (`readiness`). While installing, see [bootstrap mode](recipes/moving-from-files-to-the-database.md) | +| `InvalidConfiguration` naming a path such as `laranail.settings.stores.settings.layers` | that config entry has the wrong shape or names something unknown | fix the entry the message names; [Configuration](configuration.md) lists every key | +| `AccessDenied` for a call made with `as($user)` | the `laranail-settings.` gate is not defined, or it said no; an undefined ability is denied | define the gate, or call without an actor for trusted code; see [Access control](tools/access-control.md) | +| `VerificationRequired` (REST `428`) | the ability is in `verification.abilities`, or the definition `requiresVerification()` | send the user through `password.confirm`, or use the `actor` verifier with a fresh `verifiedAt` | +| `LockedSetting` (REST `423`) | the setting is locked for that scope, or its definition's precedence forbids store writes | `unlock()` it, or write as an actor allowed `override_lock` when the store's `locks.overridable` is on | +| a write returns but the value does not change | the setting needs approval, so the write opened a change request | see [Approvals](tools/approvals.md); `ApprovalUnavailable` means the store has no active database layer to hold one | +| `OwnerNotAllowed` | no store lists the owner's morph alias in `stores..owners`, or a dedicated store was asked for a global value | add the alias to the store, or write global values to its fallback store | +| `InvalidIdentifier` for a model owner | the model has no morph alias, so its alias would be a class name | register one: `Relation::enforceMorphMap(['user' => User::class])` | +| `UnknownSetting` | the store is `strict` and the key has no definition | define the key, or turn `strict` off for that store | +| `ConcurrentModification` (REST `412`) | another writer changed the setting after you read it | read it again and retry; a plain `set()` already retries once | +| `UndecryptableValue` after rotating `APP_KEY` | encrypted values were written with the old key | put the old key in `APP_PREVIOUS_KEYS`, run `laranail::settings.reencrypt`, then `doctor` (`encryption`) | +| a value edited in the database by hand does not show | the cached bag still holds the old rows | `php artisan laranail::settings.clear-cache`; see [Warm the cache after a deploy](recipes/warming-the-cache.md) | +| every REST route answers `404` | `http.enabled` is off, a route group is switched off, or another route already owns the path | set `LARANAIL_SETTINGS_HTTP=true`; move the API with `http.prefix`; see [REST API](tools/rest-api.md) | +| REST `401` | no user is authenticated on the request; the API never runs as trusted code | send a session cookie or a bearer token the configured middleware accepts | + +Every exception and its REST answer is listed in [Exceptions](tools/exceptions.md). + +--- + +[← Docs index](../README.md#documentation) diff --git a/docs/upgrading.md b/docs/upgrading.md new file mode 100644 index 0000000..a90ac36 --- /dev/null +++ b/docs/upgrading.md @@ -0,0 +1,43 @@ +# Upgrading + +What changes between releases, and where to read about it. + +## Where changes are recorded + +Every release's changes are in [`CHANGELOG.md`](../CHANGELOG.md), newest first, in the Keep a +Changelog sections `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed` and `Security`. Before 1.0 a +minor release (`0.1` to `0.2`) may break the API; the section of that release says what breaks and +what to do, and this page lists the steps. + +## From a pre-release checkout to 0.1.0 + +0.1.0 is the first tagged release. A checkout taken before it may carry config keys, classes and +commands that were removed before the tag. The `Removed` entries in the CHANGELOG name each one and +its replacement. + +A checkout from before the single migration published four migrations +(`create_settings_categories_table`, `create_settings_table`, `create_settings_audit_table`, +`create_settings_definitions_table`). They stay in your `database/migrations` and keep working; do +not publish the new one next to them, or the tables would be created twice. Store migrations +written by an older `make-store` keep working too. + +1. Compare your `config/laranail/settings.php` with the package's `config/settings.php`, and drop + any key that [Configuration](configuration.md) does not list. +2. Re-run `php artisan laranail::settings.doctor`. It checks that every column the package uses + exists. + +## After any upgrade + +```bash +composer update laranail/settings +php artisan migrate +php artisan laranail::settings.doctor +php artisan laranail::settings.clear-cache +``` + +`laranail/*` packages resolve from their GitHub repositories, so run `composer clear-cache` first if +a new tag does not seem to arrive. + +--- + +[← Docs index](../README.md#documentation) diff --git a/phpstan.neon b/phpstan.neon index 365a237..a3a7614 100644 --- a/phpstan.neon +++ b/phpstan.neon @@ -2,7 +2,7 @@ includes: - vendor/larastan/larastan/extension.neon parameters: - # Strictest level, no baseline (design §8). An ignore needs a comment saying why. + # Strictest level, no baseline. An ignore needs a comment saying why. level: max # src only, as across the family: Larastan reads a package's own config/ file as if it sat # outside the application's config directory and flags its env() calls, which is wrong. diff --git a/src/Actions/DiagnoseSettings.php b/src/Actions/DiagnoseSettings.php index 09b611a..b7b90cd 100644 --- a/src/Actions/DiagnoseSettings.php +++ b/src/Actions/DiagnoseSettings.php @@ -7,6 +7,7 @@ use Carbon\CarbonImmutable; use Simtabi\Laranail\Settings\Data\Scope; use Simtabi\Laranail\Settings\Stores\Store; +use Simtabi\Laranail\Settings\Drivers\JsonDriver; use Simtabi\Laranail\Settings\Diagnostics\Finding; use Simtabi\Laranail\Settings\Models\ModelContext; use Simtabi\Laranail\Settings\Drivers\DatabaseDriver; @@ -23,7 +24,8 @@ /** * The findings of `laranail::settings.doctor`. Read-only. * - * Per store with a database layer: readiness, missing columns, scopes that name a class or an + * Per store with a database layer: readiness, a runtime file a store set to promote + * automatically has not promoted, missing columns, scopes that name a class or an * alias the store does not list, category links to another store, keys outside their category, * encrypted values no key can read, and overdue change requests. Then: every code or config * definition whose key sits outside its category, and persisted configuration entries skipped as @@ -76,7 +78,17 @@ public function handle(): array } $findings[] = new Finding("{$name}: readiness", 'The database layer answers and its table exists', DoctorResult::pass(sprintf('Table [%s] on [%s] is ready.', $database->tableFor($store->name), $database->connectionName()))); + + if ($store->autoPromote) { + $findings[] = $this->autoPromotion($store); + } + $findings[] = $this->columns($store, $database); + + if ($store->isDedicated()) { + $findings[] = $this->ownerKeyType($store, $database); + } + $findings[] = $this->scopes($store, $database); $findings[] = $this->categories($store, $database); $findings[] = $this->categoryKeys($store, $database); @@ -106,6 +118,33 @@ private function databaseOf(Store $store): ?DatabaseDriver return null; } + /** A store set to promote automatically has no runtime file left once its database is ready. */ + private function autoPromotion(Store $store): Finding + { + $file = $store->runtimeFile(); + + $waiting = $file instanceof JsonDriver && $file->hasFile($store->name) && array_any($file->all($store->name), $store->promotion->includes(...)); + + return new Finding("{$store->name}: promotion", 'A store set to promote automatically has promoted its runtime file', $waiting + ? DoctorResult::warn('The runtime file has not been promoted although the database is ready; check the log for a failed promotion, or run laranail::settings.promote.') + : DoctorResult::pass('No runtime file is waiting to be promoted.')); + } + + /** A dedicated store's `owner_id` column has the type of the owner table's key. */ + private function ownerKeyType(Store $store, DatabaseDriver $database): Finding + { + $inspector = new SchemaInspector($database); + $ownerId = $inspector->idType($database->tableFor($store->name), 'owner_id'); + $ownerKey = $store->ownerTable === null ? null : $inspector->idType($store->ownerTable, $store->ownerKey); + $label = 'owner_id has the type of the owner table\'s key'; + + return match (true) { + $ownerId === null || $ownerKey === null => new Finding("{$store->name}: owner key", $label, DoctorResult::skip('The owner table or its key column could not be read.')), + $ownerId === $ownerKey => new Finding("{$store->name}: owner key", $label, DoctorResult::pass(sprintf('owner_id and %s.%s are both %s.', $store->ownerTable, $store->ownerKey, $ownerId))), + default => new Finding("{$store->name}: owner key", $label, DoctorResult::warn(sprintf('owner_id is %s but %s.%s is %s; set stores.%s.owner.type to match and migrate again.', $ownerId, $store->ownerTable, $store->ownerKey, $ownerKey, $store->name))), + }; + } + /** Every column the package uses exists on the store's tables. */ private function columns(Store $store, DatabaseDriver $database): Finding { diff --git a/src/Actions/PromoteReadyStores.php b/src/Actions/PromoteReadyStores.php new file mode 100644 index 0000000..bedee47 --- /dev/null +++ b/src/Actions/PromoteReadyStores.php @@ -0,0 +1,78 @@ +stores->all(); + } catch (Throwable $exception) { + $this->failed(null, $actor, $exception); + + return; + } + + foreach ($stores as $store) { + if (! $store->autoPromote) { + continue; + } + + try { + $report = ($this->promote)()->handle($store, $actor); + } catch (Throwable $exception) { + $this->failed($store->name->value, $actor, $exception); + + continue; + } + + if ($report !== null) { + $this->logger->info(sprintf('laranail/settings promoted store [%s] automatically.', $report->store), LogContext::of( + store: $report->store, + actor: $actor, + extra: ['promoted' => count($report->promoted), 'skipped' => count($report->skipped), 'archive' => $report->archive], + )); + } + } + } + + private function failed(?string $store, Actor $actor, Throwable $exception): void + { + try { + $this->logger->warning(sprintf('laranail/settings could not promote store [%s] automatically; it will try again.', $store ?? '*'), LogContext::of( + store: $store, + actor: $actor, + extra: ['exception' => $exception::class, 'message' => $exception->getMessage()], + )); + } catch (Throwable) { + // A broken log channel must not reach the request either. + } + } +} diff --git a/src/Actions/PromoteStore.php b/src/Actions/PromoteStore.php index 6d51c78..63550f6 100644 --- a/src/Actions/PromoteStore.php +++ b/src/Actions/PromoteStore.php @@ -54,7 +54,7 @@ public function handle(Store $store, PromotionRequest $request = new PromotionRe $this->access->authorize($actor, Ability::Promote, $subject); $database = $store->requireDatabase(' to promote into.'); - $runtime = $this->runtime($store); + $runtime = $store->runtimeFile(); if (! $runtime instanceof JsonDriver) { return new PromotionReport($store->name->value); @@ -76,7 +76,10 @@ public function handle(Store $store, PromotionRequest $request = new PromotionRe private function promote(Store $store, PromotionRequest $request, ?Actor $actor, Subject $subject, DatabaseDriver $database, JsonDriver $runtime): PromotionReport { - $records = $request->from === null ? $runtime->all($store->name) : $runtime->recordsIn($request->from); + $all = $request->from === null ? $runtime->all($store->name) : $runtime->recordsIn($request->from); + $only = $request->only ?? $store->promotion; + $records = array_values(array_filter($all, $only->includes(...))); + $kept = array_values(array_filter($all, static fn (Record $record): bool => ! $only->includes($record))); $this->events->dispatch(new StorePromoting($store->name->value)); @@ -96,11 +99,18 @@ private function promote(Store $store, PromotionRequest $request, ?Actor $actor, // The rows bypassed the cache, so reset the store's bags. $store->forgetCachedStore(); - $archive = $request->from === null ? $runtime->archive($store->name, CarbonImmutable::now()) : null; + // The archive keeps the whole original. What the selection left out stays in the runtime + // file, rewritten in one rename so reads never find it missing; a file whose every + // record was left out is not touched. + $archive = match (true) { + $request->from !== null, $records === [] && $kept !== [] => null, + $kept === [] => $runtime->archive($store->name, CarbonImmutable::now()), + default => $runtime->archiveKeeping($store->name, CarbonImmutable::now(), $kept), + }; $this->events->dispatch(new StorePromoted($store->name->value, count($promoted), count($skipped), $archive)); - return new PromotionReport($store->name->value, $promoted, $skipped, $archive); + return new PromotionReport($store->name->value, $promoted, $skipped, $archive, array_map(static fn (Record $record): string => $record->identity(), $kept)); } /** @@ -151,16 +161,4 @@ private function copy(Store $store, PromotionRequest $request, DatabaseDriver $d return [$promoted, $skipped]; } - - /** The first writable JSON layer. */ - private function runtime(Store $store): ?JsonDriver - { - foreach ($store->layers as $layer) { - if ($layer->driver instanceof JsonDriver && $layer->driver->isWritable()) { - return $layer->driver; - } - } - - return null; - } } diff --git a/src/Actions/PromoteWhenReady.php b/src/Actions/PromoteWhenReady.php new file mode 100644 index 0000000..297699a --- /dev/null +++ b/src/Actions/PromoteWhenReady.php @@ -0,0 +1,55 @@ +promotion; + + if (! $this->holdsSelected($store, $only) || $store->database()?->isReady($store->name) !== true) { + return null; + } + + try { + return $this->promote->handle($store, new PromotionRequest(only: $only), $actor); + } catch (PromotionLocked) { + return null; + } + } + + /** Whether the store has a database layer and its runtime file still holds a selected value. */ + private function holdsSelected(Store $store, PromotionSelection $only): bool + { + $file = $store->runtimeFile(); + + if (! $file instanceof JsonDriver || ! $store->hasDatabaseLayer() || ! $file->hasFile($store->name)) { + return false; + } + + return $only->isEverything() || array_any($file->all($store->name), $only->includes(...)); + } +} diff --git a/src/Authentication/SanctumActorResolver.php b/src/Authentication/SanctumActorResolver.php index 4aa04ce..a570833 100644 --- a/src/Authentication/SanctumActorResolver.php +++ b/src/Authentication/SanctumActorResolver.php @@ -15,7 +15,7 @@ /** * Resolves through Sanctum and copies the token's abilities onto the actor. A token's - * `settings:` limits what the authorizer may allow; it never grants anything itself. + * `laranail-settings:` limits what the authorizer may allow; it never grants anything itself. * A first-party session has no token and is not limited. Requires laravel/sanctum. */ final readonly class SanctumActorResolver implements ActorResolver diff --git a/src/Configuration/PersistedConfigurationEditor.php b/src/Configuration/PersistedConfigurationEditor.php index c909753..3097019 100644 --- a/src/Configuration/PersistedConfigurationEditor.php +++ b/src/Configuration/PersistedConfigurationEditor.php @@ -67,11 +67,13 @@ public function saveLayer(string $name, array $config): void $this->save->handle(new ConfigurationEntry(ConfigurationEntry::LAYER, $name, $config), $this->actor); } + /** Remove a persisted store entry; false when there was none. */ public function deleteStore(string $name): bool { return $this->delete->handle(new ConfigurationEntry(ConfigurationEntry::STORE, $name), $this->actor); } + /** Remove a persisted layer entry; false when there was none. */ public function deleteLayer(string $name): bool { return $this->delete->handle(new ConfigurationEntry(ConfigurationEntry::LAYER, $name), $this->actor); diff --git a/src/Configuration/PromotionSettings.php b/src/Configuration/PromotionSettings.php new file mode 100644 index 0000000..5e187fb --- /dev/null +++ b/src/Configuration/PromotionSettings.php @@ -0,0 +1,72 @@ +promotion()->auto()->only('settings')->forOwners('user'); + * + * It writes to the request's runtime configuration, so nothing outlives the request. + */ +final readonly class PromotionSettings +{ + public function __construct( + private RuntimeConfiguration $runtime, + private string $store, + ) {} + + /** Promote the runtime file once the database is ready. */ + public function auto(): self + { + return $this->set(['mode' => 'auto']); + } + + /** Promote only when asked: `promote()` or the command. */ + public function manual(): self + { + return $this->set(['mode' => 'manual']); + } + + /** + * Copy only these kinds: `settings` (application-wide values) and `owners` (per-owner values). + * + * @throws InvalidConfiguration for a kind the runtime file cannot hold + */ + public function only(string ...$kinds): self + { + return $this->set(['include' => array_values($kinds)]); + } + + /** Copy every value. */ + public function everything(): self + { + return $this->set(['include' => ['*'], 'owners' => null]); + } + + /** Copy owner values only for these morph aliases. */ + public function forOwners(string ...$aliases): self + { + return $this->set(['owners' => array_values($aliases)]); + } + + /** Copy owner values for every owner alias. */ + public function forAllOwners(): self + { + return $this->set(['owners' => null]); + } + + /** @param array{mode?: string, include?: list, owners?: list|null} $options */ + private function set(array $options): self + { + $this->runtime->setPromotion($this->store, $options); + + return $this; + } +} diff --git a/src/Console/DoctorCommand.php b/src/Console/DoctorCommand.php index b549038..a92d253 100644 --- a/src/Console/DoctorCommand.php +++ b/src/Console/DoctorCommand.php @@ -13,7 +13,7 @@ use Simtabi\Laranail\Console\Tools\Commands\Concerns\SupportsNamespacedNames; /** - * Check each database store's readiness, schema drift and the rows the database cannot guard. + * Check each database store's readiness, missing columns and the rows the database cannot guard. * Exits non-zero on a failure; `--fix` refreshes the definitions table's system rows first. */ final class DoctorCommand extends Command @@ -24,7 +24,7 @@ final class DoctorCommand extends Command {--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'; + protected $description = 'Check the settings stores: readiness, missing columns and data the database cannot guard'; public function handle(DiagnoseSettings $diagnose, SyncDefinitions $sync): int { diff --git a/src/Console/PromoteCommand.php b/src/Console/PromoteCommand.php index fea3fdb..cc0d751 100644 --- a/src/Console/PromoteCommand.php +++ b/src/Console/PromoteCommand.php @@ -7,6 +7,7 @@ use Simtabi\Laranail\Settings\Contracts\Settings; use Simtabi\Laranail\Console\Tools\Commands\Command; use Simtabi\Laranail\Settings\Data\PromotionRequest; +use Simtabi\Laranail\Settings\Data\PromotionSelection; use Simtabi\Laranail\Settings\Exceptions\SettingsException; use Simtabi\Laranail\Console\Tools\Commands\Concerns\SupportsNamespacedNames; @@ -22,7 +23,9 @@ final class PromoteCommand extends Command protected $signature = 'laranail::settings.promote {store? : The store to promote (default: the default store)} {--force : Overwrite keys that already have a database row} - {--from= : Replay an archived runtime file (a path on the runtime disk)}'; + {--from= : Replay an archived runtime file (a path on the runtime disk)} + {--only= : Promote only these kinds, comma-separated: settings (global values), owners (per-owner values); default: the store promote.include} + {--owner= : Promote owner values only for these owner aliases, comma-separated; default: the store promote.owners}'; protected $description = 'Promote values written before install from the runtime file into the database'; @@ -36,6 +39,7 @@ public function handle(Settings $settings): int $report = $handle->asSystem('laranail::settings.promote')->promote(new PromotionRequest( force: $this->option('force') === true, from: is_string($from) && $from !== '' ? $from : null, + only: $this->selection(), )); } catch (SettingsException $exception) { $this->error($exception->getMessage()); @@ -53,10 +57,31 @@ public function handle(Settings $settings): int )); } + if ($report->kept !== []) { + $this->line(sprintf('%d value(s) not selected stay in the runtime file.', count($report->kept))); + } + if ($report->archive !== null) { $this->line(__('laranail/settings::settings.console.promote_archived', ['archive' => $report->archive])); } return self::SUCCESS; } + + /** `--only` and `--owner`; null without either, for the store's configured selection. */ + private function selection(): ?PromotionSelection + { + $only = $this->list('only'); + $owners = $this->list('owner'); + + return $only === null && $owners === null ? null : PromotionSelection::from($only ?? ['*'], $owners, 'laranail::settings.promote'); + } + + /** @return list|null a comma-separated option as a list; null when it is not given */ + private function list(string $option): ?array + { + $value = $this->option($option); + + return is_string($value) && $value !== '' ? array_values(array_filter(array_map(trim(...), explode(',', $value)), static fn (string $item): bool => $item !== '')) : null; + } } diff --git a/src/Console/ShowCommand.php b/src/Console/ShowCommand.php index 0ec6d08..36e53f0 100644 --- a/src/Console/ShowCommand.php +++ b/src/Console/ShowCommand.php @@ -18,6 +18,7 @@ use Simtabi\Laranail\Settings\Contracts\Settings; use Simtabi\Laranail\Settings\Data\SettingAddress; use Simtabi\Laranail\Console\Tools\Commands\Command; +use Simtabi\Laranail\Settings\Drivers\CachingDriver; use Simtabi\Laranail\Settings\Resolution\Explanation; use Simtabi\Laranail\Settings\Actions\Reads\ExplainSetting; use Simtabi\Laranail\Settings\Exceptions\InvalidIdentifier; @@ -28,6 +29,7 @@ /** * Show how one setting resolves: value, layer, type, version, flags and the latest audit entry. + * For a cached answer it also reads the stored row past the cache and flags a stale cache. * Sensitive values print as `[protected]` unless `--reveal` is given. */ final class ShowCommand extends Command @@ -53,6 +55,7 @@ public function handle(Settings $settings, ExplainSetting $explain, SettingTarge $audit = $this->latestAudit($settings, $address, $actor); $explanation = $explain->handle($address, $actor); $record = $this->record($store, $explanation, $address); + $stored = $this->stored($store, $explanation, $address); } catch (SettingsException $exception) { $this->error($exception->getMessage()); @@ -72,6 +75,7 @@ public function handle(Settings $settings, ExplainSetting $explain, SettingTarge ['From scope', $lookup->scope()->value ?? '-'], ['Type', $record->type ?? $definition->type ?? '-'], ['Version', $record instanceof Record ? (string) $record->version : '-'], + ...$this->cacheRows($record, $stored), ['Locked', $this->flag($record instanceof Record ? $record->locked : $definition?->locked)], ['Encrypted', $this->flag($record instanceof Record ? $record->encrypted : $definition?->encrypted)], ['Sensitive', $this->flag($definition?->isSensitive())], @@ -131,6 +135,39 @@ private function record(Store $store, Explanation $explanation, SettingAddress $ return null; } + /** + * The stored row behind a cached answer, read past the cache; false when the answer did not + * come through the cache. + */ + private function stored(Store $store, Explanation $explanation, SettingAddress $address): Record|false|null + { + $scope = $explanation->lookup->scope(); + + foreach ($store->layers as $layer) { + if ($scope instanceof Scope && $layer->name === $explanation->lookup->layer() && $layer->driver instanceof CachingDriver) { + return $layer->driver->uncached()->load($store->name, [$scope])->find($scope, new Key($address->key), new Locale($address->locale)); + } + } + + return false; + } + + /** @return list the stored version beside the cached one, and whether the cache is stale */ + private function cacheRows(?Record $cached, Record|false|null $stored): array + { + if ($stored === false) { + return []; + } + + $version = static fn (?Record $record): string => $record instanceof Record ? (string) $record->version : '-'; + $stale = $version($cached) !== $version($stored); + + return [ + ['Stored', 'version ' . $version($stored)], + ['Cache', $stale ? 'stale: run laranail::settings.clear-cache' : 'current'], + ]; + } + private function value(Explanation $explanation, bool $sensitive): string { $lookup = $explanation->lookup; diff --git a/src/Contracts/Settings.php b/src/Contracts/Settings.php index 51dd7bc..2ff1b5d 100644 --- a/src/Contracts/Settings.php +++ b/src/Contracts/Settings.php @@ -20,6 +20,7 @@ use Simtabi\Laranail\Settings\Data\PromotionRequest; use Simtabi\Laranail\Settings\Exceptions\InvalidKey; use Simtabi\Laranail\Settings\Resolution\Explanation; +use Simtabi\Laranail\Settings\Data\PromotionSelection; use Simtabi\Laranail\Settings\Data\Transfer\StoreDiff; use Simtabi\Laranail\Settings\Exceptions\AccessDenied; use Simtabi\Laranail\Settings\Exceptions\TypeMismatch; @@ -35,6 +36,7 @@ use Simtabi\Laranail\Settings\Exceptions\HistoryUnavailable; use Simtabi\Laranail\Settings\Exceptions\ApprovalUnavailable; use Simtabi\Laranail\Settings\Exceptions\InvalidSettingValue; +use Simtabi\Laranail\Settings\Configuration\PromotionSettings; use Simtabi\Laranail\Settings\Exceptions\VerificationRequired; use Simtabi\Laranail\Settings\Configuration\PersistedConfigurationEditor; use Simtabi\Laranail\Settings\Services\Configuration\RuntimeConfiguration; @@ -247,6 +249,25 @@ public function categories(): CategoryManager; */ public function promote(?PromotionRequest $request = null): PromotionReport; + /** + * Promote now if the store's database is ready, and otherwise set the store to promote + * automatically for the rest of this request, job or command, once it is. Returns the report, + * or null when the promotion is deferred (or another process holds the promotion lock). + * `$only` picks the values to copy, as `promote.include` and `promote.owners` do; null uses the + * store's configuration. + * + * @throws AccessDenied + * @throws StoreNotWritable when the store has no database layer at all + */ + public function promoteWhenReady(?PromotionSelection $only = null): ?PromotionReport; + + /** + * Fluent setters for this handle's store's promotion, for the current request or job: + * `auto()`, `manual()`, `only(...)`, `everything()`, `forOwners(...)`, `forAllOwners()`. Each + * wins over the same option in configuration. + */ + public function promotion(): PromotionSettings; + /** * Query the audit trail. Needs `view_audit`. Entries never hold values. */ diff --git a/src/Data/Actor.php b/src/Data/Actor.php index cb6405a..55d69cc 100644 --- a/src/Data/Actor.php +++ b/src/Data/Actor.php @@ -111,7 +111,7 @@ public function tokenAllows(Ability $ability): bool return true; } - return array_intersect(['*', 'settings:*', $ability->tokenAbility()], $this->abilities) !== []; + return array_intersect(['*', 'laranail-settings:*', $ability->tokenAbility()], $this->abilities) !== []; } public function withReason(string $reason): self diff --git a/src/Data/PromotionReport.php b/src/Data/PromotionReport.php index 929fd6f..7b5b526 100644 --- a/src/Data/PromotionReport.php +++ b/src/Data/PromotionReport.php @@ -4,21 +4,26 @@ namespace Simtabi\Laranail\Settings\Data; -/** What a promotion did per identity: promoted, or skipped as `exists` or `undefined`. */ +/** + * What a promotion did per identity: promoted, or skipped as `exists` or `undefined`. `kept` lists + * the values a selective promotion left in the runtime file. + */ final readonly class PromotionReport { /** * @param list $promoted * @param array $skipped identity => reason + * @param list $kept */ public function __construct( public string $store, public array $promoted = [], public array $skipped = [], public ?string $archive = null, + public array $kept = [], ) {} - /** @return array{store: string, promoted: list, skipped: array, archive: ?string} */ + /** @return array{store: string, promoted: list, skipped: array, archive: ?string, kept: list} */ public function toArray(): array { return [ @@ -26,6 +31,7 @@ public function toArray(): array 'promoted' => $this->promoted, 'skipped' => $this->skipped, 'archive' => $this->archive, + 'kept' => $this->kept, ]; } } diff --git a/src/Data/PromotionRequest.php b/src/Data/PromotionRequest.php index 05f881b..8a6dc05 100644 --- a/src/Data/PromotionRequest.php +++ b/src/Data/PromotionRequest.php @@ -6,12 +6,17 @@ use Simtabi\Laranail\Settings\Exceptions\InvalidIdentifier; -/** Promotion options: `force` overwrites existing rows; `from` replays an archived runtime file. */ +/** + * Promotion options: `force` overwrites existing rows; `from` replays an archived runtime file; + * `only` picks which values are copied (the rest stay in the runtime file); null uses the store's + * resolved `promote` options. + */ final readonly class PromotionRequest { public function __construct( public bool $force = false, public ?string $from = null, + public ?PromotionSelection $only = null, ) { if ($from !== null && ($from === '' || str_contains($from, '..'))) { throw new InvalidIdentifier(sprintf('Invalid archive path [%s].', $from)); diff --git a/src/Data/PromotionSelection.php b/src/Data/PromotionSelection.php new file mode 100644 index 0000000..4409c18 --- /dev/null +++ b/src/Data/PromotionSelection.php @@ -0,0 +1,85 @@ +|null $ownerAliases owner values only for these aliases; null for every alias */ + public function __construct( + public bool $settings = true, + public bool $owners = true, + public ?array $ownerAliases = null, + ) {} + + /** + * Build a selection from configuration or console options. + * + * @param mixed $include `['*']`, or a list of `settings` and `owners` + * @param mixed $owners null, or a list of owner aliases + * + * @throws InvalidConfiguration naming `$path` + */ + public static function from(mixed $include, mixed $owners, string $path): self + { + $kinds = is_array($include) ? array_values(array_filter($include, is_string(...))) : null; + + if ($kinds === null || $kinds === [] || count($kinds) !== count($include)) { + throw new InvalidConfiguration($path . '.include: a list of settings and owners, or [*].'); + } + + $unknown = array_diff($kinds, ['*', ...self::KINDS]); + + if ($unknown !== []) { + throw new InvalidConfiguration(sprintf('%s.include: [%s] cannot be promoted; the runtime file holds setting values only (settings, owners).', $path, implode(', ', $unknown))); + } + + $aliases = is_array($owners) ? array_values(array_filter($owners, is_string(...))) : null; + + if ($owners !== null && ($aliases === null || $aliases === [] || count($aliases) !== count($owners))) { + throw new InvalidConfiguration($path . '.owners: a list of owner aliases, or null for every owner.'); + } + + $all = in_array('*', $kinds, true); + + return new self($all || in_array('settings', $kinds, true), $all || in_array('owners', $kinds, true), $aliases); + } + + /** @return array{include: list, owners: list|null} the selection as `promote` options */ + public function toOptions(): array + { + $include = $this->settings && $this->owners ? ['*'] : array_keys(array_filter(['settings' => $this->settings, 'owners' => $this->owners])); + + return ['include' => $include, 'owners' => $this->ownerAliases]; + } + + /** Whether a runtime-file record is promoted by this selection. */ + public function includes(Record $record): bool + { + $owner = $record->scope->owner(); + + if (! $owner instanceof OwnerRef) { + return $this->settings; + } + + return $this->owners && ($this->ownerAliases === null || in_array($owner->alias, $this->ownerAliases, true)); + } + + /** Whether every record of the file is promoted. */ + public function isEverything(): bool + { + return $this->settings && $this->owners && $this->ownerAliases === null; + } +} diff --git a/src/Data/Transfer/ExportedSetting.php b/src/Data/Transfer/ExportedSetting.php index 3c5a781..e282544 100644 --- a/src/Data/Transfer/ExportedSetting.php +++ b/src/Data/Transfer/ExportedSetting.php @@ -34,7 +34,7 @@ public function __construct( public static function fromArray(array $data, int|string $index): self { try { - $scope = Scope::fromString(is_string($data['scope'] ?? null) ? $data['scope'] : '') ?? throw new InvalidImport('bad scope'); + $scope = Scope::fromString(is_string($data['scope'] ?? null) ? $data['scope'] : '') ?? throw new InvalidImport(sprintf('scope [%s] is neither global nor alias:id.', is_scalar($data['scope'] ?? null) ? (string) $data['scope'] : get_debug_type($data['scope'] ?? null))); return new self( $scope, diff --git a/src/Definitions/DefinitionBuilder.php b/src/Definitions/DefinitionBuilder.php index d8555b1..b685ac8 100644 --- a/src/Definitions/DefinitionBuilder.php +++ b/src/Definitions/DefinitionBuilder.php @@ -153,7 +153,7 @@ public function requiresVerification(): self return $this; } - /** Writes need a second person's approval; without a change requests table they raise ApprovalUnavailable. */ + /** Writes become change requests; a store without an active database layer raises ApprovalUnavailable. */ public function requiresApproval(): self { $this->requiresApproval = true; diff --git a/src/Drivers/CachingDriver.php b/src/Drivers/CachingDriver.php index f5749f6..ad86ec2 100644 --- a/src/Drivers/CachingDriver.php +++ b/src/Drivers/CachingDriver.php @@ -27,7 +27,7 @@ public function __construct( private SettingsCache $cache, ) {} - /** The uncached database layer. */ + /** The layer this cache wraps, for a caller that must read or check it without the cache. */ public function uncached(): DatabaseBacked { return $this->inner; diff --git a/src/Drivers/JsonDriver.php b/src/Drivers/JsonDriver.php index 5a397e4..374d347 100644 --- a/src/Drivers/JsonDriver.php +++ b/src/Drivers/JsonDriver.php @@ -62,6 +62,16 @@ public function isWritable(): bool return $this->writable; } + /** Whether the store's file exists: one existence check (an `is_file()` on a local disk). */ + public function hasFile(StoreName $store): bool + { + try { + return $this->disk->exists($this->path($store)); + } catch (Throwable $exception) { + throw new DriverFailure(sprintf('Settings file [%s] could not be read.', $this->path($store)), $exception->getCode(), previous: $exception); + } + } + /** * Every record in the store's file. * @@ -92,11 +102,43 @@ public function recordsIn(string $path): array return $exists ? array_values($this->readPath($path)) : throw new DriverFailure(sprintf('Settings file [%s] does not exist.', $path)); } + /** + * Copy the store's file aside, then replace it with only these records in one atomic rename: + * what a selective promotion leaves in the file. Returns the archive's path. + * + * @param list $kept + */ + public function archiveKeeping(StoreName $store, CarbonImmutable $at, array $kept): string + { + $path = $this->path($store); + $archive = $this->archivePath($store, $at); + + try { + if (! $this->disk->copy($path, $archive)) { + throw new DriverFailure(sprintf('Settings file [%s] could not be archived.', $path)); + } + } catch (DriverFailure $exception) { + throw $exception; + } catch (Throwable $exception) { + throw new DriverFailure(sprintf('Settings file [%s] could not be archived.', $path), $exception->getCode(), previous: $exception); + } + + $records = []; + + foreach ($kept as $record) { + $records[$record->identity()] = $record; + } + + $this->write($store, $records); + + return $archive; + } + /** Move the store's file aside after promotion and return the archive's path, if any. */ public function archive(StoreName $store, CarbonImmutable $at): ?string { $path = $this->path($store); - $archive = preg_replace('/\.json$/', '', $path) . '.promoted-' . $at->format('Ymd_His_u') . '.json'; + $archive = $this->archivePath($store, $at); try { if (! $this->disk->exists($path)) { @@ -178,6 +220,11 @@ private function write(StoreName $store, array $records): void } } + private function archivePath(StoreName $store, CarbonImmutable $at): string + { + return preg_replace('/\.json$/', '', $this->path($store)) . '.promoted-' . $at->format('Ymd_His_u') . '.json'; + } + private function path(StoreName $store): string { return str_replace('{store}', $store->value, $this->pathTemplate); diff --git a/src/Enums/Ability.php b/src/Enums/Ability.php index 8559088..8206551 100644 --- a/src/Enums/Ability.php +++ b/src/Enums/Ability.php @@ -10,7 +10,7 @@ /** * Everything an actor can be authorized to do: the gate `laranail-settings.`, and for a - * token-bearing actor the token ability `settings:`. + * token-bearing actor the token ability `laranail-settings:`. */ enum Ability: string implements Enumerator { @@ -79,7 +79,7 @@ public function gateName(): string /** The token ability a token-bearing actor must hold for this ability. */ public function tokenAbility(): string { - return 'settings:' . $this->value; + return 'laranail-settings:' . $this->value; } /** Whether the ability only reads, so step-up verification never applies to it. */ diff --git a/src/Facades/Settings.php b/src/Facades/Settings.php index beb07dd..e8ac7bb 100644 --- a/src/Facades/Settings.php +++ b/src/Facades/Settings.php @@ -33,6 +33,7 @@ use Simtabi\Laranail\Settings\Data\PromotionRequest; use Simtabi\Laranail\Settings\Resolution\Explanation; use Simtabi\Laranail\Settings\Audit\InMemoryAuditSink; +use Simtabi\Laranail\Settings\Data\PromotionSelection; use Simtabi\Laranail\Settings\Data\Transfer\StoreDiff; use Simtabi\Laranail\Settings\Categories\CategoryManager; use Simtabi\Laranail\Settings\Data\Transfer\ImportReport; @@ -44,6 +45,7 @@ use Simtabi\Laranail\Settings\Services\Stores\StoreRegistry; use Simtabi\Laranail\Settings\Services\Values\ValuePipeline; use Simtabi\Laranail\Settings\Actions\Approvals\ProposeChange; +use Simtabi\Laranail\Settings\Configuration\PromotionSettings; use Simtabi\Laranail\Settings\Contracts\Settings as SettingsContract; use Simtabi\Laranail\Settings\Configuration\PersistedConfigurationEditor; use Simtabi\Laranail\Settings\Services\Configuration\RuntimeConfiguration; @@ -78,6 +80,8 @@ * @method static void preload(iterable $owners) * @method static CategoryManager categories() * @method static PromotionReport promote(?PromotionRequest $request = null) + * @method static PromotionReport|null promoteWhenReady(?PromotionSelection $only = null) + * @method static PromotionSettings promotion() * @method static AuditQuery audit() * @method static bool missing(string $key) * @method static array many(array $keys) diff --git a/src/Http/Requests/PageRequest.php b/src/Http/Requests/PageRequest.php index 5320019..cb40466 100644 --- a/src/Http/Requests/PageRequest.php +++ b/src/Http/Requests/PageRequest.php @@ -4,6 +4,7 @@ namespace Simtabi\Laranail\Settings\Http\Requests; +use Illuminate\Contracts\Config\Repository; use Illuminate\Foundation\Http\FormRequest; use Simtabi\Laranail\Settings\Data\Http\PageInput; use Simtabi\Laranail\Settings\Data\Http\AddressInput; @@ -14,6 +15,9 @@ final class PageRequest extends FormRequest { use ReadsAddress; + /** The largest page a listing serves, and the bound `http.page_size` is clamped to. */ + public const int MAX_LIMIT = 200; + private const array FILTERS = ['store', 'key', 'scope', 'status', 'action', 'outcome', 'locale', 'since', 'until']; public function authorize(): bool @@ -25,15 +29,17 @@ public function authorize(): bool public function rules(): array { return [ - 'limit' => ['nullable', 'integer', 'min:1', 'max:200'], + 'limit' => ['nullable', 'integer', 'min:1', 'max:' . self::MAX_LIMIT], 'cursor' => ['nullable', 'string', 'max:255'], 'since' => ['nullable', 'date'], 'until' => ['nullable', 'date'], ] + array_fill_keys(array_diff(self::FILTERS, ['since', 'until']), ['nullable', 'string', 'max:191']); } - public function toData(int $defaultLimit = 50): PageInput + /** @param ?int $defaultLimit the page size without `?limit=`; null reads `http.page_size` */ + public function toData(?int $defaultLimit = null): PageInput { + $defaultLimit ??= $this->configuredPageSize(); $limit = $this->query('limit'); $cursor = $this->query('cursor'); $filters = []; @@ -53,4 +59,12 @@ public function addressData(): AddressInput { return $this->address(); } + + /** `http.page_size`, clamped to 1 to MAX_LIMIT (50 when unset). */ + private function configuredPageSize(): int + { + $size = $this->container->make(Repository::class)->get('laranail.settings.http.page_size', 50); + + return max(1, min(self::MAX_LIMIT, is_numeric($size) ? (int) $size : 50)); + } } diff --git a/src/Http/Support/Problems.php b/src/Http/Support/Problems.php index 5f228d0..fdc13c0 100644 --- a/src/Http/Support/Problems.php +++ b/src/Http/Support/Problems.php @@ -20,7 +20,8 @@ */ final readonly class Problems { - public const string TYPE_BASE = 'https://opensource.simtabi.com/documentation/laranail/settings/problems/'; + /** Problem types are sections of the exceptions reference: this URL plus the type as its fragment. */ + public const string TYPE_BASE = 'https://opensource.simtabi.com/documentation/laranail/settings/tools/exceptions#'; private const string LINES = 'laranail/settings::settings.'; @@ -28,6 +29,12 @@ public function __construct( private Translator $translator, ) {} + /** The documented URI of a problem type; every `http-` type shares the `http-status` section. */ + public static function typeUri(string $type): string + { + return self::TYPE_BASE . (preg_match('/^http-\d{3}$/', $type) === 1 ? 'http-status' : $type); + } + /** The problem response for an exception raised by an API route, or null to leave it alone. */ public function render(Throwable $exception, Request $request): ?JsonResponse { @@ -53,7 +60,7 @@ public function make(int $status, string $type, string $detail, ?Request $reques $title = $this->translator->get(self::LINES . 'problems.titles.' . $type); return new JsonResponse([ - 'type' => self::TYPE_BASE . $type, + 'type' => self::typeUri($type), 'title' => is_string($title) && $title !== self::LINES . 'problems.titles.' . $type ? $title : ucfirst(str_replace('-', ' ', $type)), 'status' => $status, 'detail' => $detail, diff --git a/src/Providers/SettingsServiceProvider.php b/src/Providers/SettingsServiceProvider.php index 0424f1a..7897b31 100644 --- a/src/Providers/SettingsServiceProvider.php +++ b/src/Providers/SettingsServiceProvider.php @@ -14,6 +14,7 @@ use Illuminate\Filesystem\Filesystem; use Illuminate\Support\Facades\Route; use Illuminate\Cache\RateLimiting\Limit; +use Illuminate\Queue\Events\JobProcessed; use Simtabi\Laranail\Settings\Data\Actor; use Illuminate\Contracts\Auth\Access\Gate; use Illuminate\Queue\Events\JobProcessing; @@ -21,6 +22,7 @@ use Illuminate\Contracts\Events\Dispatcher; use Simtabi\Laranail\Package\Tools\Package; use Simtabi\Laranail\Settings\Enums\Ability; +use Simtabi\Laranail\Settings\Enums\Channel; use Simtabi\Laranail\Settings\Support\Clock; use Simtabi\Laranail\Settings\Data\AlertRule; use Simtabi\Laranail\Settings\Data\StoreName; @@ -69,6 +71,7 @@ use Simtabi\Laranail\Settings\Contracts\ActorResolver; use Simtabi\Laranail\Settings\Services\Access\Auditor; use Simtabi\Laranail\Settings\Typed\SettingsMigration; +use Simtabi\Laranail\Settings\Actions\PromoteWhenReady; use Simtabi\Laranail\Settings\Console\MakeStoreCommand; use Simtabi\Laranail\Settings\Console\ReencryptCommand; use Simtabi\Laranail\Settings\Console\WarmCacheCommand; @@ -78,6 +81,7 @@ use Simtabi\Laranail\Settings\Console\PruneAuditCommand; use Simtabi\Laranail\Settings\Logging\OperationalLogger; use Simtabi\Laranail\Settings\Verification\NullVerifier; +use Simtabi\Laranail\Settings\Actions\PromoteReadyStores; use Simtabi\Laranail\Settings\Listeners\LogSettingsEvent; use Simtabi\Laranail\Settings\Console\PruneChangesCommand; use Simtabi\Laranail\Settings\Console\PruneHistoryCommand; @@ -202,6 +206,7 @@ public function packageBooted(): void $config = $this->app->make(Repository::class); $this->bootReadinessFlush($config); + $this->bootAutoPromotion(); $this->bootTypedBindings($config); if (filter_var($config->get('laranail.settings.http.enabled', false), FILTER_VALIDATE_BOOL)) { @@ -349,6 +354,26 @@ private static function instance(Application $app, mixed $class, string $contrac return $instance instanceof $contract ? $instance : throw new InvalidConfiguration(sprintf('%s: [%s] did not build a %s.', $path, $class, $contract)); } + /** + * Whether any store could be set to `promote: auto`, read from configuration alone, so an + * application that never asks for it resolves nothing per request. + */ + private static function mayPromoteAutomatically(Application $app): bool + { + $config = $app->make(Repository::class); + $global = $config->get('laranail.settings.promote'); + $stores = $config->array('laranail.settings.stores', []); + + if ($app->resolved(RuntimeConfiguration::class)) { + $runtime = $app->make(RuntimeConfiguration::class); + $stores = [...$stores, ...$runtime->stores(), ...array_map(static fn (string $mode): array => ['promote' => $mode], $runtime->promotions())]; + } + + return $global === 'auto' + || filter_var($config->get('laranail.settings.configuration.persisted', false), FILTER_VALIDATE_BOOL) + || array_any($stores, static fn (mixed $store): bool => is_array($store) && in_array('auto', [$store['promote'] ?? null, is_array($store['promote'] ?? null) ? $store['promote']['mode'] ?? null : null], true)); + } + // Registration ------------------------------------------------------------------------- /** The current tenant, and the context the Eloquent models read it from. */ @@ -433,6 +458,13 @@ static function (string $change) use ($app): void { cache: self::cacheEnabled($app) ? $app->make(SettingsCache::class) : null, persisted: $app->make(PersistedConfiguration::class), sources: self::configurationSources($app->make(Repository::class)), + promote: $app->make(Repository::class)->get('laranail.settings.promote'), + )); + + $this->app->bind(PromoteReadyStores::class, static fn (Application $app): PromoteReadyStores => new PromoteReadyStores( + $app->make(StoreRegistry::class), + $app->make(OperationalLogger::class), + static fn (): PromoteWhenReady => $app->make(PromoteWhenReady::class), )); $this->app->bind(MakeStore::class, static fn (Application $app): MakeStore => new MakeStore( @@ -555,8 +587,22 @@ private function registerAccess(): void throw new InvalidConfiguration('laranail.settings.authorization.undefined: use [allow] or [deny].'); } + // With the REST API on, an authorizer that cannot be built fails closed rather than + // throwing on every request: every actor is denied, and the warning says why. + try { + $authorizer = $app->make(Authorizer::class); + } catch (Throwable $exception) { + if (! $exception instanceof InvalidConfiguration || ! filter_var($config->get('laranail.settings.http.enabled', false), FILTER_VALIDATE_BOOL)) { + throw $exception; + } + + $app->make(OperationalLogger::class)->warning('laranail/settings has no usable authorizer, so every actor is denied: ' . $exception->getMessage(), LogContext::of(extra: ['exception' => $exception::class])); + + return AccessGuard::closed(); + } + return new AccessGuard( - $app->make(Authorizer::class), + $authorizer, $app->make(Verifier::class), $app->make(ActorResolver::class), $app->make(Auditor::class), @@ -653,6 +699,33 @@ private function bootReadinessFlush(Repository $config): void } } + /** + * Promote stores set to `promote: auto` once their database is ready: after migrations (in + * the console, once readiness is flushed), and after each request and queued job, when no + * response waits on it. Octane terminates each request through the kernel, which runs the + * terminating callbacks too. Each run costs one file check per `auto` store until it promotes. + */ + private function bootAutoPromotion(): void + { + $app = $this->app; + $events = $app->make(Dispatcher::class); + + $run = static function (Channel $channel) use ($app): void { + try { + if (self::mayPromoteAutomatically($app)) { + $app->make(PromoteReadyStores::class)->handle($channel); + } + } catch (Throwable $exception) { + // Building the action failed (a configuration error): report it, never throw. + $app->make(ExceptionHandler::class)->report($exception); + } + }; + + $events->listen(MigrationsEnded::class, static fn () => $run(Channel::Console)); + $events->listen(JobProcessed::class, static fn () => $run(Channel::Queue)); + $app->terminating(static fn () => $run($app->runningInConsole() ? Channel::Console : Channel::Php)); + } + /** Each typed settings class in `typed.classes` resolves loaded, through the request's handle. */ private function bootTypedBindings(Repository $config): void { diff --git a/src/Services/Access/AccessGuard.php b/src/Services/Access/AccessGuard.php index a906aae..3be9c1b 100644 --- a/src/Services/Access/AccessGuard.php +++ b/src/Services/Access/AccessGuard.php @@ -51,7 +51,7 @@ public function __construct( private ?Dispatcher $events = null, ) {} - /** A guard that denies every actor and audits nowhere. */ + /** A guard that denies every actor and audits nowhere, for code that must refuse everything without configuration. */ public static function closed(): self { return new self( @@ -153,7 +153,7 @@ public function authorize(?Actor $actor, Ability $ability, Subject $subject): vo if ($decision->needsApproval()) { $this->refuse($actor, $ability, $subject, 'approval_unavailable', $decision->reason); - throw new ApprovalUnavailable(sprintf('[%s] on [%s] needs approval, which this release cannot hold.', $ability->value, $subject->store)); + throw new ApprovalUnavailable(sprintf('[%s] on [%s] needs approval; propose the change instead.', $ability->value, $subject->store)); } if ($this->needsVerification($decision, $ability, $subject) && ! $this->verifier()->isVerified($actor, $subject)) { diff --git a/src/Services/Configuration/RuntimeConfiguration.php b/src/Services/Configuration/RuntimeConfiguration.php index 86bdecd..9110faf 100644 --- a/src/Services/Configuration/RuntimeConfiguration.php +++ b/src/Services/Configuration/RuntimeConfiguration.php @@ -21,6 +21,7 @@ use Simtabi\Laranail\Settings\Contracts\AuditSink; use Simtabi\Laranail\Settings\Contracts\Authorizer; use Simtabi\Laranail\Settings\Contracts\ActorResolver; +use Simtabi\Laranail\Settings\Data\PromotionSelection; use Simtabi\Laranail\Settings\Verification\ClosureVerifier; use Simtabi\Laranail\Settings\Definitions\DefinitionBuilder; use Simtabi\Laranail\Settings\Services\Stores\StoreRegistry; @@ -63,6 +64,9 @@ final class RuntimeConfiguration private ?bool $requireActor = null; + /** @var array, owners?: list|null}> promotion options set this request, by store name */ + private array $promotions = []; + private int $generation = 0; /** @@ -206,6 +210,62 @@ public function allowActorless(): self return $this->changed('actorless calls allowed'); } + /** + * Set how a store promotes its runtime file for this request: `manual`, or `auto` to promote + * once its database is ready, optionally of only some values. Overrides the store's `promote` + * and the global override. + * + * @throws InvalidConfiguration for any other mode + */ + public function promote(string $store, string $mode, ?PromotionSelection $only = null): self + { + return $this->setPromotion($store, ['mode' => $mode, ...($only instanceof PromotionSelection ? $only->toOptions() : [])]); + } + + /** + * Override some of a store's promotion options for this request; what is not given keeps + * coming from the configuration. Validated before it is kept. + * + * @param array{mode?: string, include?: list, owners?: list|null} $options + * + * @throws InvalidConfiguration + */ + public function setPromotion(string $store, array $options): self + { + $merged = [...$this->promotions[$store] ?? [], ...$options]; + + if (isset($merged['mode']) && ! in_array($merged['mode'], ['manual', 'auto'], true)) { + throw new InvalidConfiguration(sprintf('Promotion of store [%s]: use [manual] or [auto], not [%s].', $store, $merged['mode'])); + } + + PromotionSelection::from($merged['include'] ?? ['*'], $merged['owners'] ?? null, sprintf('Promotion of store [%s]', $store)); + $this->promotions[$store] = $merged; + + return $this->changed(sprintf('store [%s] promotion set (%s)', $store, implode(', ', array_keys($options)))); + } + + /** @return array the promotion modes set this request, by store name */ + public function promotions(): array + { + return array_filter(array_map(static fn (array $options): ?string => $options['mode'] ?? null, $this->promotions), is_string(...)); + } + + /** + * The promotion options set for a store this request; each one not set comes from the configuration. + * + * @return array{mode?: string, include?: list, owners?: list|null} + */ + public function promotionOptions(string $store): array + { + return $this->promotions[$store] ?? []; + } + + /** The promotion mode set for a store this request, or null to use the configuration. */ + public function promotion(string $store): ?string + { + return $this->promotions[$store]['mode'] ?? null; + } + /** * Apply `$change`, run `$run`, then restore the previous configuration even when `$run` throws. * @@ -221,6 +281,7 @@ public function temporarily(callable $change, callable $run): mixed $snapshot = [ $this->stores, $this->layers, $this->drivers, clone $this->definitions, $this->authorizer, $this->verifier, $this->actorResolver, $this->auditSinks, $this->logger, $this->requireActor, + $this->promotions, ]; try { @@ -231,6 +292,7 @@ public function temporarily(callable $change, callable $run): mixed [ $this->stores, $this->layers, $this->drivers, $this->definitions, $this->authorizer, $this->verifier, $this->actorResolver, $this->auditSinks, $this->logger, $this->requireActor, + $this->promotions, ] = $snapshot; $this->changed('runtime configuration restored'); } diff --git a/src/Services/Database/SchemaInspector.php b/src/Services/Database/SchemaInspector.php index 21cd9c1..d33f6c4 100644 --- a/src/Services/Database/SchemaInspector.php +++ b/src/Services/Database/SchemaInspector.php @@ -43,8 +43,8 @@ public function columns(string $table): ?array } } - /** The database type of the table's `id` column, or null. */ - public function idType(string $table): ?string + /** The database type of a table's key column (`id` by default), or null when it cannot be read. */ + public function idType(string $table, string $column = 'id'): ?string { try { $columns = $this->database->connection()->getSchemaBuilder()->getColumns($table); @@ -52,9 +52,9 @@ public function idType(string $table): ?string return null; } - foreach ($columns as $column) { - if (($column['name'] ?? null) === 'id') { - return (string) ($column['type_name'] ?? '?'); + foreach ($columns as $candidate) { + if (($candidate['name'] ?? null) === $column) { + return (string) ($candidate['type_name'] ?? '?'); } } diff --git a/src/Services/Stores/StoreRegistry.php b/src/Services/Stores/StoreRegistry.php index 5db0eb8..e29dfc3 100644 --- a/src/Services/Stores/StoreRegistry.php +++ b/src/Services/Stores/StoreRegistry.php @@ -18,6 +18,7 @@ use Simtabi\Laranail\Settings\Database\SchemaNames; use Simtabi\Laranail\Settings\Drivers\CachingDriver; use Simtabi\Laranail\Settings\Drivers\DatabaseDriver; +use Simtabi\Laranail\Settings\Data\PromotionSelection; use Simtabi\Laranail\Settings\Exceptions\UnknownStore; use Simtabi\Laranail\Settings\Contracts\DatabaseBacked; use Simtabi\Laranail\Settings\Exceptions\OwnerNotAllowed; @@ -46,6 +47,7 @@ final class StoreRegistry * @param array $layerConfig `laranail.settings.layers` * @param ?Dispatcher $events receives {@see LayerSkipped} when bootstrap mode skips a layer * @param list $sources merge order of config, database and runtime entries; later wins + * @param mixed $promote `laranail.settings.promote`: overrides every store's `promote` when set */ public function __construct( private readonly DriverFactory $drivers, @@ -59,12 +61,13 @@ public function __construct( private readonly ?SettingsCache $cache = null, private readonly ?PersistedConfiguration $persisted = null, private readonly array $sources = ['config', 'database', 'runtime'], + private readonly mixed $promote = null, ) {} /** A copy whose every layer is replaced by one driver. */ public function withEveryLayer(Driver $driver): self { - return new self($this->drivers, $this->default, $this->storeConfig, $this->layerConfig, $driver, $this->runtime, $this->evidence, $this->events, $this->cache, $this->persisted, $this->sources); + return new self($this->drivers, $this->default, $this->storeConfig, $this->layerConfig, $driver, $this->runtime, $this->evidence, $this->events, $this->cache, $this->persisted, $this->sources, $this->promote); } /** @throws InvalidConfiguration for the first problem in any store or layer */ @@ -176,6 +179,7 @@ private function build(): array throw new InvalidConfiguration($path . '.soft_deletes: true or false.'); } + $promote = $this->promotion($storeName, $config['promote'] ?? 'manual', $path . '.promote'); $owner = $this->dedicatedOwner($config, $storeName, $path); $options = ['table' => $table, 'soft_deletes' => $softDeletes, 'owner' => $owner]; @@ -192,6 +196,10 @@ private function build(): array fallback: $owner === null ? null : new StoreName($owner['fallback']), approvalKeys: $this->approvalKeys($config['approvals'] ?? [], $path . '.approvals'), softDeletes: $softDeletes, + autoPromote: $this->autoPromote($promote['mode'], $promote['modePath']), + promotion: PromotionSelection::from($promote['include'], $promote['owners'], $promote['path']), + ownerTable: $owner['table'] ?? null, + ownerKey: $owner['key'] ?? 'id', ); } @@ -350,6 +358,47 @@ private function dedicatedOwner(array $config, StoreName $store, string $path): return ['alias' => $owners[array_key_first($owners)], 'table' => $owner['table'], 'key' => $key, 'type' => $type, 'fallback' => $fallback->value]; } + /** + * The one place a store's promotion options are resolved. Each option comes from the first + * of: the fluent setters and runtime configuration for this request, the global `promote` + * override (mode only), then the store's `promote` from persisted configuration or the file. + * The string shorthand (`'auto'`) means every value. + * + * @return array{mode: mixed, include: mixed, owners: mixed, path: string, modePath: string} + */ + private function promotion(StoreName $store, mixed $promote, string $path): array + { + if (is_array($promote)) { + $unknown = array_diff(array_keys($promote), ['mode', 'include', 'owners']); + + if ($unknown !== []) { + throw new InvalidConfiguration(sprintf('%s: unknown option [%s]; use mode, include and owners.', $path, implode(', ', $unknown))); + } + } + + $configured = is_array($promote) + ? ['mode' => $promote['mode'] ?? 'manual', 'include' => $promote['include'] ?? ['*'], 'owners' => $promote['owners'] ?? null] + : ['mode' => $promote, 'include' => ['*'], 'owners' => null]; + $modePath = is_array($promote) ? $path . '.mode' : $path; + + if ($this->promote !== null && $this->promote !== '') { + [$configured['mode'], $modePath] = [$this->promote, 'laranail.settings.promote']; + } + + $set = $this->runtime?->promotionOptions($store->value) ?? []; + + return [...$configured, ...$set, 'path' => $path, 'modePath' => $modePath]; + } + + private function autoPromote(mixed $mode, string $path): bool + { + return match ($mode) { + 'auto' => true, + 'manual' => false, + default => throw new InvalidConfiguration($path . ': use [manual] or [auto].'), + }; + } + private function locksOverridable(mixed $locks, string $path): bool { if (! is_array($locks)) { diff --git a/src/SettingsManager.php b/src/SettingsManager.php index be71184..787bfd6 100644 --- a/src/SettingsManager.php +++ b/src/SettingsManager.php @@ -48,9 +48,11 @@ use Simtabi\Laranail\Settings\Exceptions\InvalidKey; use Simtabi\Laranail\Settings\Resolution\Explanation; use Simtabi\Laranail\Settings\Actions\RollbackSetting; +use Simtabi\Laranail\Settings\Data\PromotionSelection; use Simtabi\Laranail\Settings\Data\Transfer\StoreDiff; use Simtabi\Laranail\Settings\Exceptions\AccessDenied; use Simtabi\Laranail\Settings\Exceptions\TypeMismatch; +use Simtabi\Laranail\Settings\Actions\PromoteWhenReady; use Simtabi\Laranail\Settings\Exceptions\ActorRequired; use Simtabi\Laranail\Settings\Exceptions\UnknownSetting; use Simtabi\Laranail\Settings\Actions\Transfer\DiffStore; @@ -59,6 +61,7 @@ use Simtabi\Laranail\Settings\Exceptions\OwnerNotAllowed; use Simtabi\Laranail\Settings\Data\Transfer\ExportRequest; use Simtabi\Laranail\Settings\Data\Transfer\ImportRequest; +use Simtabi\Laranail\Settings\Exceptions\StoreNotWritable; use Simtabi\Laranail\Settings\Services\Access\AccessGuard; use Simtabi\Laranail\Settings\Actions\Transfer\ExportStore; use Simtabi\Laranail\Settings\Actions\Transfer\ImportStore; @@ -68,6 +71,7 @@ use Simtabi\Laranail\Settings\Services\Resolution\ScopeKeys; use Simtabi\Laranail\Settings\Services\Stores\StoreRegistry; use Simtabi\Laranail\Settings\Actions\Approvals\ProposeChange; +use Simtabi\Laranail\Settings\Configuration\PromotionSettings; use Simtabi\Laranail\Settings\Services\Definitions\Definitions; use Simtabi\Laranail\Settings\Services\Definitions\DefinitionRegistry; use Simtabi\Laranail\Settings\Configuration\PersistedConfigurationEditor; @@ -119,6 +123,7 @@ public function __construct( private readonly CategoryManager $categories, private readonly Approvals $approvals, private readonly PersistedConfigurationEditor $configurationEditor, + private readonly PromoteWhenReady $promoteWhenReady, ) {} public function store(string $name): static @@ -427,6 +432,28 @@ public function promote(?PromotionRequest $request = null): PromotionReport return $this->promote->handle($this->targetStore(), $request ?? new PromotionRequest, $this->actingAs); } + public function promoteWhenReady(?PromotionSelection $only = null): ?PromotionReport + { + $store = $this->targetStore(); + + if (! $store->hasDatabaseLayer()) { + throw new StoreNotWritable(sprintf('Store [%s] has no database layer to promote into.', $store->name)); + } + + $report = $this->promoteWhenReady->handle($store, $this->actingAs, $only); + + if (! $report instanceof PromotionReport) { + $this->runtime->promote($store->name->value, 'auto', $only); + } + + return $report; + } + + public function promotion(): PromotionSettings + { + return new PromotionSettings($this->runtime, $this->targetStore()->name->value); + } + public function audit(): AuditQuery { $query = new AuditQuery($this->auditQuery, $this->actingAs); diff --git a/src/Stores/Store.php b/src/Stores/Store.php index e33b814..a668806 100644 --- a/src/Stores/Store.php +++ b/src/Stores/Store.php @@ -10,8 +10,10 @@ use Simtabi\Laranail\Settings\Data\RecordSet; use Simtabi\Laranail\Settings\Data\StoreName; use Simtabi\Laranail\Settings\Enums\StoreMode; +use Simtabi\Laranail\Settings\Drivers\JsonDriver; use Simtabi\Laranail\Settings\Drivers\CachingDriver; use Simtabi\Laranail\Settings\Drivers\DatabaseDriver; +use Simtabi\Laranail\Settings\Data\PromotionSelection; use Simtabi\Laranail\Settings\Contracts\DatabaseBacked; use Simtabi\Laranail\Settings\Exceptions\StoreNotWritable; use Simtabi\Laranail\Settings\Exceptions\ApprovalUnavailable; @@ -25,6 +27,9 @@ * @param list $layers * @param list $owners * @param list $approvalKeys key globs whose writes become change requests + * @param bool $autoPromote promote the runtime file once the database is ready (`promote: auto`) + * @param ?string $ownerTable a dedicated store's owner table (`owner.table`), keyed by `$ownerKey` + * @param PromotionSelection $promotion which runtime-file values automatic promotion copies (`promote.include`, `promote.owners`) */ public function __construct( public StoreName $name, @@ -39,6 +44,10 @@ public function __construct( public ?StoreName $fallback = null, public array $approvalKeys = [], public bool $softDeletes = false, + public bool $autoPromote = false, + public PromotionSelection $promotion = new PromotionSelection, + public ?string $ownerTable = null, + public string $ownerKey = 'id', ) {} /** Whether a write of this key becomes a change request. */ @@ -86,6 +95,18 @@ public function database(): ?DatabaseDriver return null; } + /** The first writable JSON layer: the runtime file that promotion copies from. */ + public function runtimeFile(): ?JsonDriver + { + foreach ($this->layers as $layer) { + if ($layer->driver instanceof JsonDriver && $layer->driver->isWritable()) { + return $layer->driver; + } + } + + return null; + } + /** * The first active database layer's driver. * diff --git a/src/Testing/SettingsFake.php b/src/Testing/SettingsFake.php index 5ec851d..7e74033 100644 --- a/src/Testing/SettingsFake.php +++ b/src/Testing/SettingsFake.php @@ -25,10 +25,12 @@ use Simtabi\Laranail\Settings\History\HistoryQuery; use Simtabi\Laranail\Settings\Data\PromotionRequest; use Simtabi\Laranail\Settings\Resolution\Explanation; +use Simtabi\Laranail\Settings\Data\PromotionSelection; use Simtabi\Laranail\Settings\Data\Transfer\StoreDiff; use Simtabi\Laranail\Settings\Categories\CategoryManager; use Simtabi\Laranail\Settings\Data\Transfer\ImportReport; use Simtabi\Laranail\Settings\Data\Transfer\ExportDocument; +use Simtabi\Laranail\Settings\Configuration\PromotionSettings; use Simtabi\Laranail\Settings\Configuration\PersistedConfigurationEditor; use Simtabi\Laranail\Settings\Services\Configuration\RuntimeConfiguration; @@ -243,6 +245,16 @@ public function promote(?PromotionRequest $request = null): PromotionReport return $this->inner->promote($request); } + public function promoteWhenReady(?PromotionSelection $only = null): ?PromotionReport + { + return $this->inner->promoteWhenReady($only); + } + + public function promotion(): PromotionSettings + { + return $this->inner->promotion(); + } + public function audit(): AuditQuery { return $this->inner->audit(); diff --git a/tests/Arch/LayeringTest.php b/tests/Arch/LayeringTest.php index f5886f5..47a3586 100644 --- a/tests/Arch/LayeringTest.php +++ b/tests/Arch/LayeringTest.php @@ -6,7 +6,7 @@ * The layering: entry points → actions → services → support. * * 1. An action exposes handle() and nothing else public. - * 2. Actions never touch the database connection or schema builder themselves; repositories + * 2. Actions never touch the database connection or schema builder themselves; models * and drivers do. * 3. Only entry points depend on actions. * 4. Support classes hold no mutable state. diff --git a/tests/Arch/NoLiteralCredentialsTest.php b/tests/Arch/NoLiteralCredentialsTest.php index 65144fe..25220b3 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 = 45; +const SETTINGS_TEST_FILE_FLOOR = 75; it('keeps literal credentials out of the tests', function (): void { $this->assertNoLiteralCredentialsIn([dirname(__DIR__)], minFiles: SETTINGS_TEST_FILE_FLOOR); diff --git a/tests/Arch/ServicesTest.php b/tests/Arch/ServicesTest.php index 1a50b18..0194d33 100644 --- a/tests/Arch/ServicesTest.php +++ b/tests/Arch/ServicesTest.php @@ -47,7 +47,7 @@ function servicesSources(): array $files = []; foreach (new RecursiveIteratorIterator(new RecursiveDirectoryIterator($root, FilesystemIterator::SKIP_DOTS)) as $file) { - if ($file instanceof SplFileInfo && $file->getExtension() === 'php' && $file->getFilename() !== 'deprecated-aliases.php') { + if ($file instanceof SplFileInfo && $file->getExtension() === 'php') { $files[substr($file->getPathname(), strlen($root))] = (string) file_get_contents($file->getPathname()); } } @@ -96,10 +96,8 @@ function servicesSources(): array it('leaves no old name for a moved class, and every new name loads', function (): void { $base = 'Simtabi\\Laranail\\Settings\\'; - $root = dirname(__DIR__, 2); expect(count(MOVED_SERVICES))->toBe(15) - ->and(is_file($root . '/src/deprecated-aliases.php'))->toBeFalse() ->and(array_keys(array_filter(MOVED_SERVICES, static fn (string $new, string $old): bool => class_exists($base . $old), ARRAY_FILTER_USE_BOTH)))->toBe([]) ->and(array_values(array_filter(MOVED_SERVICES, static fn (string $new): bool => ! class_exists($base . $new))))->toBe([]); }); diff --git a/tests/Feature/ActorTest.php b/tests/Feature/ActorTest.php index e9396c4..d5aef71 100644 --- a/tests/Feature/ActorTest.php +++ b/tests/Feature/ActorTest.php @@ -31,7 +31,7 @@ }); it('makes an actor with token abilities a token actor', function (): void { - expect(Actor::user(user(), abilities: ['settings:view'])->type)->toBe(ActorType::Token); + expect(Actor::user(user(), abilities: ['laranail-settings:view'])->type)->toBe(ActorType::Token); }); it('builds an explicit system actor carrying its reason', function (): void { @@ -47,7 +47,7 @@ $actor = Actor::user( user(7), Channel::Rest, - ['settings:view'], + ['laranail-settings:view'], new ActorContext('10.0.0.1', 'agent', 'req-1', 'INC-1'), now()->toImmutable()->startOfSecond(), ); @@ -61,7 +61,7 @@ ->and($copy->id)->toBe('7') ->and($copy->type)->toBe(ActorType::Token) ->and($copy->channel)->toBe(Channel::Rest) - ->and($copy->abilities)->toBe(['settings:view']) + ->and($copy->abilities)->toBe(['laranail-settings:view']) ->and($copy->verifiedAt?->equalTo($actor->verifiedAt))->toBeTrue() ->and($copy->context)->toEqual($actor->context); }); @@ -123,11 +123,11 @@ it('copies Sanctum token abilities into the actor, and leaves a token-less session unlimited', function (): void { $user = user(); - $user->tokenAbilities = ['settings:view', 42]; + $user->tokenAbilities = ['laranail-settings:view', 42]; Auth::guard()->setUser($user); $resolver = new SanctumActorResolver(app('auth'), ['web'], static fn (): null => null, stdClass::class); - expect($resolver->resolve()?->abilities)->toBe(['settings:view']) + expect($resolver->resolve()?->abilities)->toBe(['laranail-settings:view']) ->and($resolver->resolve()?->type)->toBe(ActorType::Token); $user->tokenAbilities = null; @@ -169,8 +169,8 @@ }); it('lets a token-bearing actor be checked against the token ceiling only for the asked ability', function (): void { - expect(Actor::user(user(), abilities: ['settings:update'])->tokenAllows(Ability::Update))->toBeTrue() - ->and(Actor::user(user(), abilities: ['settings:update'])->tokenAllows(Ability::View))->toBeFalse() + expect(Actor::user(user(), abilities: ['laranail-settings:update'])->tokenAllows(Ability::Update))->toBeTrue() + ->and(Actor::user(user(), abilities: ['laranail-settings:update'])->tokenAllows(Ability::View))->toBeFalse() ->and(Actor::user(user())->tokenAllows(Ability::View))->toBeTrue(); }); diff --git a/tests/Feature/AuthorizationTest.php b/tests/Feature/AuthorizationTest.php index e891886..fe3aca1 100644 --- a/tests/Feature/AuthorizationTest.php +++ b/tests/Feature/AuthorizationTest.php @@ -7,6 +7,7 @@ use Simtabi\Laranail\Settings\Data\Subject; use Simtabi\Laranail\Settings\Data\Decision; use Simtabi\Laranail\Settings\Enums\Ability; +use Simtabi\Laranail\Settings\Data\StoreName; use Simtabi\Laranail\Settings\Data\AuditEntry; use Simtabi\Laranail\Settings\Enums\ActorType; use Simtabi\Laranail\Settings\Enums\AuditAction; @@ -14,6 +15,7 @@ use Simtabi\Laranail\Settings\Exceptions\AccessDenied; use Simtabi\Laranail\Settings\Tests\Fixtures\TestUser; use Simtabi\Laranail\Settings\Exceptions\ActorRequired; +use Simtabi\Laranail\Settings\Services\Access\AccessGuard; use Simtabi\Laranail\Settings\Exceptions\ApprovalUnavailable; use Simtabi\Laranail\Settings\Exceptions\InvalidConfiguration; @@ -147,12 +149,12 @@ it('treats a token as an extra ceiling: the token must hold the ability as well as the gate', function (): void { allowGates(Ability::View, Ability::Update); - $limited = Actor::user(user(), abilities: ['settings:view']); - $wildcard = Actor::user(user(), abilities: ['settings:*']); + $limited = Actor::user(user(), abilities: ['laranail-settings:view']); + $wildcard = Actor::user(user(), abilities: ['laranail-settings:*']); $everything = Actor::user(user(), abilities: ['*']); expect(settings()->as($limited)->get('site.name'))->toBeNull() - ->and(fn () => settings()->as($limited)->set('site.name', 'x'))->toThrow(AccessDenied::class, 'the token lacks [settings:update]'); + ->and(fn () => settings()->as($limited)->set('site.name', 'x'))->toThrow(AccessDenied::class, 'the token lacks [laranail-settings:update]'); settings()->as($wildcard)->set('site.name', 'Acme'); settings()->as($everything)->set('site.name', 'Acme'); @@ -164,7 +166,7 @@ allowGates(Ability::View); Gate::define('laranail-settings.update', static fn (TestUser $user): bool => false); - expect(fn () => settings()->as(Actor::user(user(), abilities: ['settings:*']))->set('site.name', 'x'))->toThrow(AccessDenied::class); + expect(fn () => settings()->as(Actor::user(user(), abilities: ['laranail-settings:*']))->set('site.name', 'x'))->toThrow(AccessDenied::class); }); it('runs an explicit system actor as trusted code', function (): void { @@ -212,3 +214,13 @@ public function authorize(Actor $actor, Ability $ability, Subject $subject): Dec return $ability === Ability::View ? Decision::allow() : Decision::deny('view only'); } } + +it('closes a guard that denies every actor and lets only trusted code through', function (): void { + $guard = AccessGuard::closed(); + $subject = new Subject(new StoreName('settings')); + + expect(fn () => $guard->authorize(Actor::user(user()), Ability::View, $subject))->toThrow(AccessDenied::class); + + $guard->authorize(null, Ability::Update, $subject); + $guard->authorize(Actor::system('test'), Ability::Update, $subject); +}); diff --git a/tests/Feature/Database/AutoPromotionTest.php b/tests/Feature/Database/AutoPromotionTest.php new file mode 100644 index 0000000..e872aac --- /dev/null +++ b/tests/Feature/Database/AutoPromotionTest.php @@ -0,0 +1,490 @@ +put(RUNTIME_FILE, (string) json_encode(['records' => [ + ['scope' => 'global', 'key' => 'site.name', 'locale' => '', 'payload' => json_encode($name), 'version' => 1], + ]])); +} + +/** Set the default store's promotion mode, as an operator would in config. */ +function promoteMode(string $mode): void +{ + config()->set('laranail.settings.stores.settings.layers', ['database', 'runtime', 'shipped']); + config()->set('laranail.settings.stores.settings.promote', $mode); + app()->forgetScopedInstances(); +} + +/** A logger that keeps what it is given. */ +function promotionLogger(): AbstractLogger +{ + return new class extends AbstractLogger + { + /** @var list}> */ + public array $records = []; + + public function log($level, Stringable|string $message, array $context = []): void + { + $this->records[] = [(string) $level, (string) $message, $context]; + } + }; +} + +/** Count existence checks on the `local` disk. */ +function countingDisk(): object +{ + $root = Storage::disk('local')->path(''); + $adapter = new class($root) extends LocalFilesystemAdapter + { + public int $checks = 0; + + public function fileExists(string $location): bool + { + $this->checks++; + + return parent::fileExists($location); + } + }; + + Storage::set('local', new FilesystemAdapter(new Flysystem($adapter), $adapter, ['root' => $root])); + + return $adapter; +} + +it('waits for the database, then promotes exactly once, straight after the migrations', function (): void { + Event::fake([StorePromoted::class]); + writeRuntimeFile(); + promoteMode('auto'); + + app()->terminate(); + + expect(Storage::disk('local')->exists(RUNTIME_FILE))->toBeTrue(); + Event::assertNotDispatched(StorePromoted::class); + + // migrate fires MigrationsEnded, which promotes in the console once readiness is flushed. + useDatabase(['stores.settings.promote' => 'auto']); + + Event::assertDispatchedTimes(StorePromoted::class, 1); + expect(Storage::disk('local')->exists(RUNTIME_FILE))->toBeFalse() + ->and(DB::table('settings')->where('key', 'site.name')->value('value'))->toBe('"Acme"') + ->and(settings()->lookup('site.name')->layer())->toBe('database'); + + app()->terminate(); + + Event::assertDispatchedTimes(StorePromoted::class, 1); +}); + +it('promotes after the request ends and after a queued job, as the system', function (): void { + useDatabase(); + $audit = auditInMemory(); + writeRuntimeFile(); + settings()->configuration()->promote('settings', 'auto'); + + app()->terminate(); + + expect(Storage::disk('local')->exists(RUNTIME_FILE))->toBeFalse() + ->and(settings()->get('site.name'))->toBe('Acme'); + + $entry = array_values(array_filter($audit->entries(), static fn (AuditEntry $entry): bool => $entry->action === AuditAction::Promote))[0] ?? null; + expect($entry?->actorType)->toBe(ActorType::System) + ->and($entry?->reason)->toBe('laranail::settings.auto-promote') + // The test runs in the console; a web request records `php`. + ->and($entry?->channel)->toBe(Channel::Console); + + writeRuntimeFile('Later'); + DB::table('settings')->delete(); + event(new JobProcessed('sync', Mockery::mock(Job::class))); + + expect(Storage::disk('local')->exists(RUNTIME_FILE))->toBeFalse() + ->and(DB::table('settings')->value('value'))->toBe('"Later"'); + + $channels = array_map(static fn (AuditEntry $entry): Channel => $entry->channel, array_values(array_filter($audit->entries(), static fn (AuditEntry $entry): bool => $entry->action === AuditAction::Promote))); + expect($channels)->toBe([Channel::Console, Channel::Queue]); +}); + +it('skips quietly while another process holds the promotion lock', function (): void { + useDatabase(); + $logger = promotionLogger(); + writeRuntimeFile(); + promoteMode('auto'); + settings()->configuration()->logTo($logger); + + $lock = Cache::lock('laranail-settings:promote:settings', 60); + $lock->get(); + app()->terminate(); + + expect(Storage::disk('local')->exists(RUNTIME_FILE))->toBeTrue() + ->and(array_filter($logger->records, static fn (array $record): bool => $record[0] === 'warning'))->toBe([]); + + $lock->release(); + app()->terminate(); + + expect(Storage::disk('local')->exists(RUNTIME_FILE))->toBeFalse(); +}); + +it('logs a failure, keeps reading the file, and succeeds on a later run', function (): void { + useDatabase(); + $logger = promotionLogger(); + writeRuntimeFile(); + promoteMode('auto'); + settings()->configuration()->logTo($logger); + $disk = new ArrayObject(['full' => true]); + Event::listen(StorePromoting::class, static function () use ($disk): void { + if ($disk['full'] === true) { + throw new RuntimeException('disk full'); + } + }); + + app()->terminate(); + + $warnings = array_values(array_filter($logger->records, static fn (array $record): bool => $record[0] === 'warning')); + expect($warnings)->toHaveCount(1) + ->and($warnings[0][1])->toContain('could not promote store [settings]') + ->and(array_slice(array_keys($warnings[0][2]), 0, 5))->toBe(['store', 'key', 'scope', 'actor', 'channel']) + ->and($warnings[0][2]['store'])->toBe('settings') + ->and($warnings[0][2]['message'])->toBe('disk full') + ->and(Storage::disk('local')->exists(RUNTIME_FILE))->toBeTrue() + ->and(settings()->lookup('site.name')->layer())->toBe('runtime'); + + $disk['full'] = false; + app()->terminate(); + + expect(Storage::disk('local')->exists(RUNTIME_FILE))->toBeFalse() + ->and(settings()->lookup('site.name')->layer())->toBe('database'); +}); + +it('runs no query once promoted, or when there is no file, and checks the file once', function (): void { + useDatabase(); + writeRuntimeFile(); + promoteMode('auto'); + app()->terminate(); + expect(Storage::disk('local')->exists(RUNTIME_FILE))->toBeFalse(); + + $disk = countingDisk(); + app()->forgetScopedInstances(); + // A new request: nothing remembers that the database was ready. + app(SchemaReadinessInterface::class)->flush(); + DB::enableQueryLog(); + DB::flushQueryLog(); + + app()->terminate(); + + expect(DB::getQueryLog())->toBe([]) + ->and($disk->checks)->toBe(1); +}); + +it('never promotes on its own in manual mode, the default', function (): void { + useDatabase(); + writeRuntimeFile(); + DB::enableQueryLog(); + DB::flushQueryLog(); + + app()->terminate(); + + expect(Storage::disk('local')->exists(RUNTIME_FILE))->toBeTrue() + ->and(DB::getQueryLog())->toBe([]); + + // The global override turns every store to auto, and to manual again. + config()->set('laranail.settings.promote', 'manual'); + promoteMode('auto'); + app()->terminate(); + + expect(Storage::disk('local')->exists(RUNTIME_FILE))->toBeTrue(); + + config()->set('laranail.settings.promote', 'auto'); + promoteMode('manual'); + app()->terminate(); + + expect(Storage::disk('local')->exists(RUNTIME_FILE))->toBeFalse(); +}); + +it('rejects a promotion mode it does not know', function (): void { + promoteMode('sometimes'); + + expect(fn (): mixed => settings()->get('site.name'))->toThrow(InvalidConfiguration::class, 'laranail.settings.stores.settings.promote: use [manual] or [auto].') + ->and(fn (): mixed => settings()->configuration()->promote('settings', 'later'))->toThrow(InvalidConfiguration::class, 'use [manual] or [auto]'); + + config()->set('laranail.settings.stores.settings.promote', 'manual'); + config()->set('laranail.settings.promote', 'eventually'); + app()->forgetScopedInstances(); + + expect(fn (): mixed => settings()->get('site.name'))->toThrow(InvalidConfiguration::class, 'laranail.settings.promote: use [manual] or [auto].'); +}); + +it('promotes now from promoteWhenReady() when the database is ready', function (): void { + useDatabase(); + writeRuntimeFile(); + + $report = settings()->store('settings')->asSystem('installer')->promoteWhenReady(); + + expect($report)->toBeInstanceOf(PromotionReport::class) + ->and($report?->promoted)->toBe(['global|site.name|']) + ->and(Storage::disk('local')->exists(RUNTIME_FILE))->toBeFalse(); +}); + +it('defers promoteWhenReady() until the migrations when the database is not ready', function (): void { + // An installer: bootstrap mode, with the evidence of an install in progress. + config()->set('laranail.settings.stores.settings.bootstrap', true); + config()->set('laranail.settings.bootstrap', true); + writeRuntimeFile(); + promoteMode('manual'); + + expect(settings()->asSystem('installer')->promoteWhenReady())->toBeNull() + ->and(settings()->configuration()->promotion('settings'))->toBe('auto') + ->and(Storage::disk('local')->exists(RUNTIME_FILE))->toBeTrue(); + + // An installer migrating in the same process: the runtime switch is still in force. + Artisan::call('migrate', ['--path' => dirname(__DIR__, 3) . '/database/migrations', '--realpath' => true]); + + expect(Storage::disk('local')->exists(RUNTIME_FILE))->toBeFalse() + ->and(settings()->get('site.name'))->toBe('Acme'); + + config()->set('laranail.settings.stores.settings.layers', ['runtime']); + app()->forgetScopedInstances(); + + expect(fn (): mixed => settings()->promoteWhenReady())->toThrow(StoreNotWritable::class, 'no database layer'); +}); + +it('passes promoteWhenReady() through the fake', function (): void { + expect(fn (): mixed => Settings::fake()->promoteWhenReady())->toThrow(StoreNotWritable::class, 'no database layer'); +}); + +it('warns from doctor when an auto store still has its file while the database is ready', function (): void { + useDatabase(); + $this->artisan('laranail::settings.doctor')->doesntExpectOutputToContain('settings: promotion')->assertSuccessful(); + + writeRuntimeFile(); + config()->set('laranail.settings.stores.settings.promote', 'auto'); + app()->forgetScopedInstances(); + + $this->artisan('laranail::settings.doctor') + ->expectsOutputToContain('The runtime file has not been promoted although the database is ready') + ->assertSuccessful(); + + app()->terminate(); + app()->forgetScopedInstances(); + + $this->artisan('laranail::settings.doctor')->expectsOutputToContain('No runtime file is waiting to be promoted.')->assertSuccessful(); +}); + +it('logs a configuration it cannot build instead of throwing into the request', function (): void { + config()->set('laranail.settings.promote', 'auto'); + config()->set('laranail.settings.stores.settings.layers', ['missing']); + config()->set('laranail.settings.audit.sinks', ['null']); + app()->forgetScopedInstances(); + $logger = promotionLogger(); + settings()->configuration()->logTo($logger); + + app()->terminate(); + + $warnings = array_values(array_filter($logger->records, static fn (array $record): bool => $record[0] === 'warning')); + expect($warnings)->toHaveCount(1) + ->and($warnings[0][1])->toContain('could not promote store [*]') + ->and($warnings[0][2]['exception'])->toBe(InvalidConfiguration::class); +}); + +/** A runtime file with a global value and two owners' values. */ +function writeMixedRuntimeFile(): void +{ + Storage::disk('local')->put(RUNTIME_FILE, (string) json_encode(['records' => [ + ['scope' => 'global', 'key' => 'site.name', 'locale' => '', 'payload' => '"Acme"', 'version' => 1], + ['scope' => 'user:1', 'key' => 'ui.theme', 'locale' => '', 'payload' => '"dark"', 'version' => 1], + ['scope' => 'team:2', 'key' => 'ui.theme', 'locale' => '', 'payload' => '"light"', 'version' => 1], + ]])); +} + +/** @return list the scopes left in the runtime file */ +function runtimeScopes(): array +{ + $file = json_decode((string) Storage::disk('local')->get(RUNTIME_FILE), true); + + return array_column($file['records'], 'scope'); +} + +it('promotes only the kinds a store selects, and the rest keep answering from the file', function (array $promote, array $inDatabase, array $inFile): void { + useDatabase(['stores.settings.owners' => ['user', 'team'], 'stores.settings.promote' => ['mode' => 'auto', ...$promote]]); + writeMixedRuntimeFile(); + + app()->terminate(); + + expect(DB::table('settings')->orderBy('scope')->pluck('scope')->all())->toBe($inDatabase); + + if ($inFile === []) { + expect(Storage::disk('local')->exists(RUNTIME_FILE))->toBeFalse(); + } else { + expect(runtimeScopes())->toBe($inFile) + ->and(settings()->for(new OwnerRef('team', 2))->lookup('ui.theme')->layer())->toBe(in_array('team:2', $inFile, true) ? 'runtime' : 'database') + ->and(settings()->for(new OwnerRef('team', 2))->get('ui.theme'))->toBe('light'); + } + + // The archive keeps the whole original file. + $archive = collect(Storage::disk('local')->files('laranail/settings'))->first(static fn (string $path): bool => str_contains($path, '.promoted-')); + expect(count(json_decode((string) Storage::disk('local')->get((string) $archive), true)['records']))->toBe(3); + + // A remainder the selection leaves out is not promoted again, and costs no query. + DB::enableQueryLog(); + DB::flushQueryLog(); + app()->terminate(); + + expect(DB::getQueryLog())->toBe([]) + ->and(Storage::disk('local')->files('laranail/settings'))->toHaveCount($inFile === [] ? 1 : 2); +})->with([ + 'settings only' => [['include' => ['settings']], ['global'], ['user:1', 'team:2']], + 'owners only' => [['include' => ['owners']], ['team:2', 'user:1'], ['global']], + 'everything' => [['include' => ['*']], ['global', 'team:2', 'user:1'], []], + 'one owner alias' => [['include' => ['owners'], 'owners' => ['user']], ['user:1'], ['global', 'team:2']], +]); + +it('takes the string shorthand as everything, and refuses kinds the runtime file cannot hold', function (): void { + config()->set('laranail.settings.stores.settings.promote', 'auto'); + app()->forgetScopedInstances(); + + expect(app(StoreRegistry::class)->default()->promotion->isEverything())->toBeTrue(); + + config()->set('laranail.settings.stores.settings.promote', ['mode' => 'auto', 'include' => ['settings', 'categories']]); + app()->forgetScopedInstances(); + + expect(fn (): mixed => settings()->get('x'))->toThrow(InvalidConfiguration::class, 'laranail.settings.stores.settings.promote.include: [categories] cannot be promoted; the runtime file holds setting values only'); + + config()->set('laranail.settings.stores.settings.promote', ['mode' => 'auto', 'owners' => 'user']); + app()->forgetScopedInstances(); + + expect(fn (): mixed => settings()->get('x'))->toThrow(InvalidConfiguration::class, 'promote.owners: a list of owner aliases'); + + config()->set('laranail.settings.stores.settings.promote', ['mode' => 'auto', 'only' => ['settings']]); + app()->forgetScopedInstances(); + + expect(fn (): mixed => settings()->get('x'))->toThrow(InvalidConfiguration::class, 'unknown option [only]'); +}); + +it('selects from the command and from promoteWhenReady()', function (): void { + useDatabase(['stores.settings.owners' => ['user', 'team']]); + writeMixedRuntimeFile(); + + $this->artisan('laranail::settings.promote', ['--only' => 'owners', '--owner' => 'team']) + ->expectsOutputToContain('Store [settings]: 1 promoted, 0 skipped.') + ->expectsOutputToContain('2 value(s) not selected stay in the runtime file.') + ->assertSuccessful(); + + expect(runtimeScopes())->toBe(['global', 'user:1']); + + $this->artisan('laranail::settings.promote', ['--only' => 'categories'])->expectsOutputToContain('[categories] cannot be promoted')->assertFailed(); + + $report = settings()->asSystem('installer')->promoteWhenReady(new PromotionSelection(settings: true, owners: false)); + + expect($report?->promoted)->toBe(['global|site.name|']) + ->and($report?->kept)->toBe(['user:1|ui.theme|']) + ->and(runtimeScopes())->toBe(['user:1']); +}); + +it('decides "already has a row" from the stored rows, never from a stale cache', function (): void { + useDatabase(); + // The cache remembers an empty global scope... + expect(settings()->get('site.name'))->toBeNull(); + // ...and a row arrives behind its back. + DB::table('settings')->insert(['id' => (string) Str::ulid(), 'uid' => (string) Str::ulid(), 'scope' => 'global', 'key' => 'site.name', 'group' => 'site', 'locale' => '', 'value' => '"Stored"', 'version' => 1, 'created_at' => now(), 'updated_at' => now()]); + writeRuntimeFile('File'); + + $report = settings()->promote(); + + expect($report->skipped)->toBe(['global|site.name|' => 'exists']) + ->and(DB::table('settings')->value('value'))->toBe('"Stored"'); +}); + +it('lets fluent setters win over configuration, option by option', function (): void { + config()->set('laranail.settings.stores.settings.promote', ['mode' => 'manual', 'include' => ['settings'], 'owners' => ['team']]); + app()->forgetScopedInstances(); + $store = static fn () => app(StoreRegistry::class)->default(); + + // Unset fluent values fall through to configuration. + expect($store()->autoPromote)->toBeFalse() + ->and($store()->promotion->settings)->toBeTrue() + ->and($store()->promotion->owners)->toBeFalse(); + + $builder = settings()->store('settings')->promotion(); + + expect($builder->auto())->toBe($builder) + ->and($store()->autoPromote)->toBeTrue() + ->and($store()->promotion->owners)->toBeFalse() + ->and($builder->only('owners'))->toBe($builder) + ->and($store()->promotion->settings)->toBeFalse() + ->and($store()->promotion->ownerAliases)->toBe(['team']) + ->and($builder->forOwners('user', 'team')->forAllOwners())->toBe($builder) + ->and($store()->promotion->ownerAliases)->toBeNull() + ->and($builder->forOwners('user'))->toBe($builder) + ->and($store()->promotion->ownerAliases)->toBe(['user']) + ->and($builder->everything())->toBe($builder) + ->and($store()->promotion->isEverything())->toBeTrue() + ->and($builder->manual())->toBe($builder) + ->and($store()->autoPromote)->toBeFalse(); + + // The fluent mode beats the global override too. + config()->set('laranail.settings.promote', 'auto'); + app()->forgetInstance(StoreRegistry::class); + + expect($store()->autoPromote)->toBeFalse() + ->and(fn (): mixed => $builder->only('categories'))->toThrow(InvalidConfiguration::class, '[categories] cannot be promoted'); +}); + +it('keeps fluent promotion settings to the request that set them', function (): void { + settings()->store('settings')->promotion()->auto()->only('owners'); + + expect(app(StoreRegistry::class)->default()->autoPromote)->toBeTrue(); + + // What Octane does between requests. + app()->forgetScopedInstances(); + + expect(app(StoreRegistry::class)->default()->autoPromote)->toBeFalse() + ->and(app(StoreRegistry::class)->default()->promotion->isEverything())->toBeTrue(); +}); + +it('drives the fluent chain through the fake, and promoteWhenReady() uses the merged result', function (): void { + Settings::fake()->store('settings')->promotion()->auto()->only('settings'); + + expect(app(StoreRegistry::class)->default()->autoPromote)->toBeTrue() + ->and(app(StoreRegistry::class)->default()->promotion->owners)->toBeFalse(); + + useDatabase(['stores.settings.owners' => ['user', 'team']]); + writeMixedRuntimeFile(); + settings()->store('settings')->promotion()->only('owners')->forOwners('team'); + + $report = settings()->store('settings')->promoteWhenReady(); + + expect($report?->promoted)->toBe(['team:2|ui.theme|']) + ->and(runtimeScopes())->toBe(['global', 'user:1']); + + // The command's defaults read the same resolved options. + $this->artisan('laranail::settings.promote')->expectsOutputToContain('0 promoted')->assertSuccessful(); +}); diff --git a/tests/Feature/Database/DebuggingAidsTest.php b/tests/Feature/Database/DebuggingAidsTest.php index dca2aac..595a18a 100644 --- a/tests/Feature/Database/DebuggingAidsTest.php +++ b/tests/Feature/Database/DebuggingAidsTest.php @@ -50,6 +50,21 @@ public function log($level, string|Stringable $message, array $context = []): vo ->expectsOutputToContain('| Locked | no') ->expectsOutputToContain('| Encrypted | no') ->expectsOutputToContain('| Last audit | update allowed by system via php') + ->expectsOutputToContain('| Stored | version 2') + ->expectsOutputToContain('| Cache | current') + ->assertSuccessful(); +}); + +it('reads past the cache and flags a stale one', function (): void { + settings()->set('site.name', 'Acme'); + settings()->get('site.name'); + // A change the cache never saw, as a hand edit or another deploy's write would be. + DB::table('settings')->where('key', 'site.name')->update(['version' => 5]); + + $this->artisan('laranail::settings.show', ['key' => 'site.name']) + ->expectsOutputToContain('| Version | 1') + ->expectsOutputToContain('| Stored | version 5') + ->expectsOutputToContain('| Cache | stale: run laranail::settings.clear-cache') ->assertSuccessful(); }); diff --git a/tests/Feature/Database/DedicatedStoreTest.php b/tests/Feature/Database/DedicatedStoreTest.php index d92d183..69478e6 100644 --- a/tests/Feature/Database/DedicatedStoreTest.php +++ b/tests/Feature/Database/DedicatedStoreTest.php @@ -82,3 +82,22 @@ function useDedicatedStore(array $extra = []): void 'bad owner key type' => [['owners' => ['user'], 'owner' => ['table' => 'users', 'type' => 'serial']], '`type` one of'], 'unknown mode' => [['mode' => 'shared'], 'use [polymorphic] or [dedicated]'], ]); + +it('has doctor compare owner_id with the owner table key', function (): void { + useDedicatedStore(); + + $this->artisan('laranail::settings.doctor')->expectsOutputToContain('owner_id and users.id are both')->assertSuccessful(); +}); + +it('has doctor warn when owner_id does not match the owner table key', function (): void { + // MySQL and Postgres refuse the mismatched foreign key outright; SQLite builds it, so doctor must catch it. + if (DB::getDriverName() !== 'sqlite') { + $this->markTestSkipped('Only SQLite accepts a foreign key between different column types.'); + } + + useDatabase([ + 'stores.user_settings' => ['layers' => ['database'], 'owners' => ['user'], 'mode' => 'dedicated', 'owner' => ['table' => 'users', 'type' => 'bigint']], + ], stores: ['user_settings'], ownerTables: ['users' => 'uuid']); + + $this->artisan('laranail::settings.doctor')->expectsOutputToContain('set stores.user_settings.owner.type to match')->assertSuccessful(); +}); diff --git a/tests/Feature/Database/HandlesTest.php b/tests/Feature/Database/HandlesTest.php index 0f181fa..cdf4152 100644 --- a/tests/Feature/Database/HandlesTest.php +++ b/tests/Feature/Database/HandlesTest.php @@ -97,6 +97,7 @@ 'promoted' => ['global|a|'], 'skipped' => ['global|b|' => 'exists'], 'archive' => 'x.json', + 'kept' => [], ]); }); diff --git a/tests/Feature/Database/PersistedConfigurationTest.php b/tests/Feature/Database/PersistedConfigurationTest.php index cec7bd7..3f89d78 100644 --- a/tests/Feature/Database/PersistedConfigurationTest.php +++ b/tests/Feature/Database/PersistedConfigurationTest.php @@ -48,6 +48,8 @@ ->and(DB::table('settings_audit')->where('action', AuditAction::ManageStores->value)->count())->toBe(2) ->and($editor->deleteStore('extra'))->toBeTrue() ->and($editor->deleteStore('extra'))->toBeFalse() + ->and($editor->deleteLayer('scratch'))->toBeTrue() + ->and($editor->deleteLayer('scratch'))->toBeFalse() ->and(fn (): mixed => settings()->store('extra')->get('feature.on'))->toThrow(UnknownStore::class); }); diff --git a/tests/Feature/Database/RestApiTest.php b/tests/Feature/Database/RestApiTest.php index f334bda..7e420bc 100644 --- a/tests/Feature/Database/RestApiTest.php +++ b/tests/Feature/Database/RestApiTest.php @@ -12,11 +12,14 @@ use Simtabi\Laranail\Settings\Enums\Ability; use Simtabi\Laranail\Settings\Data\NewCategory; use Illuminate\Database\Eloquent\Relations\Relation; +use Simtabi\Laranail\Settings\Http\Support\Problems; +use Simtabi\Laranail\Settings\Exceptions\AccessDenied; use Simtabi\Laranail\Settings\Tests\Fixtures\TestUser; use Simtabi\Laranail\Settings\Tests\Support\ApiSchemas; use Simtabi\Laranail\Settings\Tests\Support\JsonSchema; use Simtabi\Laranail\Package\Tools\Testing\TestCredentials; use Simtabi\Laranail\Settings\Tests\Fixtures\SettingsOwner; +use Simtabi\Laranail\Settings\Exceptions\InvalidConfiguration; use Simtabi\Laranail\Settings\Services\Definitions\DefinitionRegistry; /* @@ -69,7 +72,7 @@ function api(string $method, string $uri, array $data = [], array $headers = []) api('PUT', 'stores/settings/settings/site.name', ['value' => 'Stale'], ['If-Match' => $etag]) ->assertStatus(412) ->assertHeader('Content-Type', 'application/problem+json') - ->assertJsonPath('type', 'https://opensource.simtabi.com/documentation/laranail/settings/problems/precondition-failed'); + ->assertJsonPath('type', 'https://opensource.simtabi.com/documentation/laranail/settings/tools/exceptions#precondition-failed'); expect(settings()->get('site.name'))->toBe('Acme Ltd') ->and(DB::table('settings_audit')->where('channel', 'rest')->where('action', 'update')->count())->toBe(2); @@ -155,6 +158,8 @@ function api(string $method, string $uri, array $data = [], array $headers = []) api('GET', 'stores')->assertOk()->assertJsonCount(2, 'data'); api('PUT', 'configuration/stores/broken', ['config' => ['layers' => ['missing']]])->assertUnprocessable(); api('DELETE', 'configuration/stores/extra')->assertNoContent(); + api('DELETE', 'configuration/layers/scratch')->assertNoContent(); + api('GET', 'configuration')->assertOk()->assertJsonCount(0, 'data'); api('PUT', 'stores/settings/definitions/site.theme', ['attributes' => ['type' => 'string', 'default' => 'light']])->assertOk()->assertJsonPath('data.default', 'light'); api('GET', 'stores/settings/definitions')->assertOk()->assertJsonPath('data.0.key', 'site.theme'); @@ -173,7 +178,7 @@ function api(string $method, string $uri, array $data = [], array $headers = []) api('POST', 'stores/settings/import', ['document' => $document])->assertOk()->assertJsonPath('data.applied', false); expect(settings()->get('site.name'))->toBe('Changed'); api('POST', 'stores/settings/import', ['document' => $document, 'apply' => true])->assertOk()->assertJsonPath('data.updated', ['global|site.name|']); - api('POST', 'stores/settings/import', ['document' => ['format' => 'other']])->assertUnprocessable()->assertJsonPath('type', 'https://opensource.simtabi.com/documentation/laranail/settings/problems/invalid-import'); + api('POST', 'stores/settings/import', ['document' => ['format' => 'other']])->assertUnprocessable()->assertJsonPath('type', 'https://opensource.simtabi.com/documentation/laranail/settings/tools/exceptions#invalid-import'); expect(settings()->get('site.name'))->toBe('Acme'); }); @@ -197,7 +202,7 @@ function api(string $method, string $uri, array $data = [], array $headers = []) expect(app(Router::class)->getRoutes()->getByName('laranail-settings.api.changes.index'))->toBeNull() ->and(app(Router::class)->getRoutes()->getByName('laranail-settings.api.settings.show'))->not->toBeNull(); - test()->json('GET', '/api/settings/v1/stores')->assertUnauthorized()->assertJsonPath('type', 'https://opensource.simtabi.com/documentation/laranail/settings/problems/actor-required'); + test()->json('GET', '/api/settings/v1/stores')->assertUnauthorized()->assertJsonPath('type', 'https://opensource.simtabi.com/documentation/laranail/settings/tools/exceptions#actor-required'); }); it('has a response shape for every registered route, and none for a route that is gone', function (): void { @@ -224,7 +229,7 @@ function api(string $method, string $uri, array $data = [], array $headers = []) settings()->for(new OwnerRef('team', 3))->set('theme', 'teal'); api('GET', 'stores/settings/owners/owner/5/settings/theme')->assertOk()->assertJsonPath('data.value', 'teal')->assertJsonPath('data.from', 'team:3'); - api('GET', 'stores/settings/owners/owner/6/settings/theme')->assertNotFound()->assertJsonPath('type', 'https://opensource.simtabi.com/documentation/laranail/settings/problems/unknown-owner'); + api('GET', 'stores/settings/owners/owner/6/settings/theme')->assertNotFound()->assertJsonPath('type', 'https://opensource.simtabi.com/documentation/laranail/settings/tools/exceptions#unknown-owner'); api('GET', 'stores/settings/owners/owner/bad%20id/settings/theme')->assertNotFound(); // Mapped only for URLs: addressed by alias and id, so no parents. @@ -233,3 +238,40 @@ function api(string $method, string $uri, array $data = [], array $headers = []) app()->forgetScopedInstances(); api('GET', 'stores/settings/owners/member/5/settings/theme')->assertOk()->assertJsonPath('data.found', false); }); + +it('pages listings by http.page_size, 50 by default and clamped to 1 to 200', function (): void { + foreach (range(1, 51) as $n) { + settings()->set(sprintf('page.key_%02d', $n), $n); + } + + api('GET', 'stores/settings/settings')->assertOk()->assertJsonCount(50, 'data')->assertJsonPath('meta.next_cursor', 'page.key_50'); + + config()->set('laranail.settings.http.page_size', 20); + api('GET', 'stores/settings/settings')->assertOk()->assertJsonCount(20, 'data'); + api('GET', 'stores/settings/settings?limit=3')->assertOk()->assertJsonCount(3, 'data'); + + config()->set('laranail.settings.http.page_size', 0); + api('GET', 'stores/settings/settings')->assertOk()->assertJsonCount(1, 'data'); + + config()->set('laranail.settings.http.page_size', 1000); + api('GET', 'stores/settings/settings')->assertOk()->assertJsonCount(51, 'data'); +}); + +it('fails closed, with one warning, when the API is on and no authorizer can be built', function (): void { + $log = sys_get_temp_dir() . '/laranail-settings-closed-' . bin2hex(random_bytes(4)) . '.log'; + config()->set('logging.channels.settings_closed', ['driver' => 'single', 'path' => $log]); + config()->set('laranail.settings.logging.channel', 'settings_closed'); + config()->set('laranail.settings.authorization.driver', 'Nope\\Authorizer'); + app()->forgetScopedInstances(); + + api('GET', 'stores')->assertUnauthorized()->assertJsonPath('type', Problems::typeUri('actor-required')); + expect(fn (): mixed => settings()->as(user())->get('site.name'))->toThrow(AccessDenied::class) + ->and(settings()->get('site.name'))->toBeNull() + ->and(substr_count((string) file_get_contents($log), 'has no usable authorizer'))->toBe(1); + + // Without the API, a broken authorizer still raises the configuration error. + config()->set('laranail.settings.http.enabled', false); + app()->forgetScopedInstances(); + + expect(fn (): mixed => settings()->as(user())->get('site.name'))->toThrow(InvalidConfiguration::class, 'laranail.settings.authorization.driver'); +}); diff --git a/tests/Feature/ReferenceDocsTest.php b/tests/Feature/ReferenceDocsTest.php index 3379f60..a9fb76b 100644 --- a/tests/Feature/ReferenceDocsTest.php +++ b/tests/Feature/ReferenceDocsTest.php @@ -6,6 +6,7 @@ use Illuminate\Support\Facades\Artisan; use Illuminate\Routing\Route as RoutingRoute; use Simtabi\Laranail\Settings\Contracts\Settings; +use Simtabi\Laranail\Settings\Http\Support\Problems; use Simtabi\Laranail\Settings\Facades\Settings as SettingsFacade; /* @@ -94,6 +95,22 @@ function documentedConfigKeys(array $config, string $prefix = ''): array } }); +it('points every problem type URI at an anchor on the exceptions page', function (): void { + $page = referencePage('tools/exceptions.md'); + // The exceptions' own types, and those Problems renders for framework exceptions. + $types = [...problemTypes(), 'validation', 'unauthenticated', 'too-many-requests', 'http-404', 'http-405']; + + expect(count($types))->toBeGreaterThanOrEqual(29); + + foreach ($types as $type) { + $uri = Problems::typeUri($type); + [$base, $anchor] = explode('#', $uri, 2); + + expect($base)->toBe('https://opensource.simtabi.com/documentation/laranail/settings/tools/exceptions') + ->and(str_contains($page, ''))->toBeTrue(sprintf('exceptions.md has no anchor for problem type %s (#%s)', $type, $anchor)); + } +}); + it('documents every event', function (): void { $events = classesIn('Events'); $page = referencePage('tools/events.md'); diff --git a/tests/Support/JsonSchema.php b/tests/Support/JsonSchema.php index 88a5909..785445c 100644 --- a/tests/Support/JsonSchema.php +++ b/tests/Support/JsonSchema.php @@ -8,14 +8,14 @@ use LogicException; /** - * The subset of JSON Schema (2020-12, as OpenAPI 3.1 uses it) the settings OpenAPI document - * uses: `type` (one or a list, `null` included), `enum`, `const`, `required`, `properties`, + * The subset of JSON Schema (2020-12) the REST API response schemas in `ApiSchemas` + * use: `type` (one or a list, `null` included), `enum`, `const`, `required`, `properties`, * `items`, `minimum`, `maximum` and `$ref` into `#/components/schemas`. Small on purpose, and in * the repository, so validating responses needs no dependency. Unknown keywords are ignored. */ final readonly class JsonSchema { - /** @param array $document the OpenAPI document */ + /** @param array $document the response schemas, keyed under `components.schemas` */ public function __construct(private array $document) {} /** diff --git a/tests/Unit/AccessValuesTest.php b/tests/Unit/AccessValuesTest.php index 8db2997..d6e8b83 100644 --- a/tests/Unit/AccessValuesTest.php +++ b/tests/Unit/AccessValuesTest.php @@ -31,7 +31,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::OverrideLock->tokenAbility())->toBe('laranail-settings:override_lock') ->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']); @@ -137,7 +137,7 @@ function subjectFor(string $key = 'site.name'): Subject it('keeps an actor\'s other fields when deriving copies', function (): void { $at = CarbonImmutable::parse('2026-11-09 12:00:00'); - $actor = Actor::user(new GenericUser(['id' => 5]), abilities: ['settings:view']) + $actor = Actor::user(new GenericUser(['id' => 5]), abilities: ['laranail-settings:view']) ->withVerifiedAt($at) ->withChannel(Channel::Console) ->withContext(new ActorContext('1.2.3.4')) @@ -147,6 +147,6 @@ function subjectFor(string $key = 'site.name'): Subject ->and($actor->channel->value)->toBe('console') ->and($actor->context->ip)->toBe('1.2.3.4') ->and($actor->context->reason)->toBe('why') - ->and($actor->abilities)->toBe(['settings:view']) + ->and($actor->abilities)->toBe(['laranail-settings:view']) ->and($actor->id)->toBe('5'); }); diff --git a/tests/Unit/DocsConformanceTest.php b/tests/Unit/DocsConformanceTest.php index 1e0f7f6..aa82c15 100644 --- a/tests/Unit/DocsConformanceTest.php +++ b/tests/Unit/DocsConformanceTest.php @@ -6,10 +6,10 @@ uses(AssertsDocsConformance::class); -// Floor = the 49 pages shipped today (5 guides, 26 reference, 18 recipes; counted 2026-11-10, after schema-switches.md was folded into database.md). Raise it as pages +// Floor = the 52 pages shipped today (7 guides, 26 reference, 19 recipes; counted 2026-11-11). 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), 49); + $this->assertDocsConformToStandard(dirname(__DIR__, 2), 52); expect(true)->toBeTrue(); });