Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 56 additions & 28 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,71 +6,99 @@ All notable changes to this project are documented here. The format follows
## Table of contents

- [[Unreleased]](#unreleased)
- [[2.0.1] - 2026-11-22](#201---2026-11-22)
- [Added](#added)
- [Changed](#changed)
- [Fixed](#fixed)
- [[2.0.1] - 2026-11-22](#201---2026-11-22)
- [Fixed](#fixed-1)
- [[2.0.0] - 2026-11-21](#200---2026-11-21)
- [Removed](#removed)
- [Changed](#changed)
- [Changed](#changed-1)
- [Security](#security)
- [[1.8.1] - 2026-11-20](#181---2026-11-20)
- [Fixed](#fixed-1)
- [Fixed](#fixed-2)
- [[1.8.0] - 2026-11-20](#180---2026-11-20)
- [Added](#added)
- [Added](#added-1)
- [Deprecated](#deprecated)
- [Changed](#changed-1)
- [Changed](#changed-2)
- [[1.7.1] - 2026-11-19](#171---2026-11-19)
- [Fixed](#fixed-2)
- [[1.7.0] - 2026-11-19](#170---2026-11-19)
- [Added](#added-1)
- [Fixed](#fixed-3)
- [Changed](#changed-2)
- [[1.6.1] - 2026-11-15](#161---2026-11-15)
- [[1.7.0] - 2026-11-19](#170---2026-11-19)
- [Added](#added-2)
- [Fixed](#fixed-4)
- [Changed](#changed-3)
- [[1.6.1] - 2026-11-15](#161---2026-11-15)
- [Fixed](#fixed-5)
- [Tests](#tests)
- [[1.6.0] - 2026-11-15](#160---2026-11-15)
- [Added](#added-2)
- [Changed](#changed-3)
- [Added](#added-3)
- [Changed](#changed-4)
- [Tests](#tests-1)
- [[1.5.3] - 2026-11-13](#153---2026-11-13)
- [Security](#security-1)
- [Added](#added-3)
- [Changed](#changed-4)
- [Added](#added-4)
- [Changed](#changed-5)
- [Tests](#tests-2)
- [[1.5.2] - 2026-11-13](#152---2026-11-13)
- [Security](#security-2)
- [Fixed](#fixed-5)
- [Fixed](#fixed-6)
- [Tests](#tests-3)
- [[1.5.1] - 2026-11-12](#151---2026-11-12)
- [Fixed](#fixed-6)
- [Fixed](#fixed-7)
- [Tests](#tests-4)
- [[1.5.0] - 2026-11-12](#150---2026-11-12)
- [Added](#added-4)
- [Changed](#changed-5)
- [Added](#added-5)
- [Changed](#changed-6)
- [Deprecated](#deprecated-1)
- [[1.4.0] - 2026-11-11](#140---2026-11-11)
- [Added](#added-5)
- [Added](#added-6)
- [Security](#security-3)
- [Fixed](#fixed-7)
- [Changed](#changed-6)
- [[1.3.0] - 2026-11-11](#130---2026-11-11)
- [Fixed](#fixed-8)
- [Added](#added-6)
- [Changed](#changed-7)
- [[1.3.0] - 2026-11-11](#130---2026-11-11)
- [Fixed](#fixed-9)
- [Added](#added-7)
- [Changed](#changed-8)
- [Deprecated](#deprecated-2)
- [[1.2.0] - 2026-11-10](#120---2026-11-10)
- [Security](#security-4)
- [Added](#added-7)
- [Changed](#changed-8)
- [[1.1.0] - 2026-11-03](#110---2026-11-03)
- [Added](#added-8)
- [Changed](#changed-9)
- [Fixed](#fixed-9)
- [[1.0.0] - 2026-11-03](#100---2026-11-03)
- [[1.1.0] - 2026-11-03](#110---2026-11-03)
- [Added](#added-9)
- [Changed](#changed-10)
- [Fixed](#fixed-10)
- [[1.0.0] - 2026-11-03](#100---2026-11-03)
- [Added](#added-10)
- [Security](#security-5)

## [Unreleased]

### Added

- **Row versions on the bucket forms (REQ-RUNTIME-003 rule 4, lost update).** The Storage page and the Move page's
new-bucket form were last-write-wins: two admins editing the same bucket both saved, and the second save silently
replaced the first. `storage_kit_profile` gets an additive `row_version INT NOT NULL DEFAULT 1` column (migration in
[UPGRADING](UPGRADING.md#unreleased)). Each form carries the row and the version it was built from in a hidden
`rowVersion` field (`<row id>:<row version>`, from the same load as the values); the save advances the version with
one atomic compare-and-set inside its existing write unit (`Concurrency\RowVersion`). A page of another bucket is
stale too: a page opened before its bucket was replaced (a target discarded and saved again, or a Move switch) never
saves the new row, even at an equal version. A page that is no longer current writes nothing and answers 409
with the form, a translated message (7 locales) and `X-Error-Code: STORAGE_KIT_STALE_EDIT` (a domain answer: no
`X-Conflict-Code`, no `Retry-After`). Lock conflicts keep `CONFLICT_001` / `CONFLICT_002`.
- `StorageMove::saveTarget()` takes an optional fifth argument `?int $expectedVersion` (throws
`Concurrency\StaleEditException` when it no longer matches); without it the version is advanced unchecked, so a
Move page opened before your save is refused. `StorageMove::rowVersion()` reads the current version.
`StorageProfileType` takes the `row_id` and `row_version` options (default null: no field),
`StorageProfileType::submittedRowVersion($form, $profile)` returns the version only for the token of `$profile`'s
row, and `StorageProfile::getRowVersion()`. Direct ORM writes of your own to a `StorageProfile` do not advance the
version; save through `StorageMove::saveTarget()` for that.

### Changed

- A first save of a bucket whose page did not show it (another admin created the owner's bucket meanwhile) now answers
the stale 409 instead of overwriting that bucket.

### Fixed

- No translation changed. A new strict `TranslationCatalogueTest` fails on a non-en locale missing a key, on a non-en value identical to English (any length, placeholders included; values without letters are skipped) unless allow-listed per locale (brands, units, protocols, loanwords, true cognates), on a non-es value identical to the Spanish one (longer than 12 characters, different from English) unless allow-listed as genuinely shared, and on stale entries in either allow-list.
Expand Down
29 changes: 25 additions & 4 deletions docs/CONCURRENCY.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ MySQL / MariaDB `GET_LOCK()`, PostgreSQL `pg_advisory_xact_lock()` (both wait at

| Path | Transaction | Control (rule 4) | Conflict answer |
| --- | --- | --- | --- |
| Storage page: save the bucket (`StorageSettingsController`) | Unit | Owner lock; the owner's active profile is read again inside the unit (a first save racing another, or a profile switched away meanwhile, writes nothing and shows "Someone else changed this bucket meanwhile") | 409 page (HttpException) |
| Storage page: save the bucket (`StorageSettingsController`) | Unit | Owner lock; the owner's active profile is read again inside the unit (a first save racing another, or a profile switched away meanwhile, writes nothing and shows "Someone else changed this bucket meanwhile"); 2.1: row version of the page, compare-and-set inside the unit (`UPDATE … SET row_version = row_version + 1 WHERE id = ? AND row_version = ?`, which also holds the row lock until the commit), so a page opened before another save writes nothing | Lock conflict: 409 page (HttpException). Stale page: 409 form, `X-Error-Code: STORAGE_KIT_STALE_EDIT` |
| Storage / Move page: *Test connection* (`ProfileTester`) | One DBAL `UPDATE` of the test fields (no flush) | Last test wins (a probe result, not user data) | 409 page |
| Move page: save the new bucket (`StorageMove::saveTarget`) | Unit | Owner lock; the owner's target read again inside the unit (at most one target) | 409 page |
| Move page: save the new bucket (`StorageMove::saveTarget`) | Unit | Owner lock; the owner's target read again inside the unit (at most one target); 2.1: row version of the page, compare-and-set inside the unit (your code without a version: advanced unchecked, so a page opened before is stale) | Lock conflict: 409 page. Stale page: 409 form, `X-Error-Code: STORAGE_KIT_STALE_EDIT`; your code: `StaleEditException` |
| Move page: start / resume copying (`StorageMove::start`) | Unit; the Messenger message is dispatched after the commit | Owner lock; both profiles and the pair's sync read again inside the unit (never two open syncs, never dispatched twice) | 409 page |
| Move page: stop copying (`StorageMove::cancel`) | One guarded `UPDATE` | Compare-and-set on `status` (only from queued / running: a runner that completed or failed meanwhile is not overwritten) | 409 page |
| Move page: switch (`StorageMove::switch`) | Unit (the `storage` Instance Settings write, the file re-pointing `UPDATE` and both profiles) | Owner lock; the sync, the files uploaded since it and both profiles read again inside the unit | 409 page |
Expand Down Expand Up @@ -53,6 +53,18 @@ A lock conflict, deadlock, lock wait timeout or serialization failure (MySQL / M
| `CONFLICT_002` | Part of the request was committed (transaction-doctrine's request commit mark, or the bundle's own mark on its connection since 1.7.1; a Messenger handler that already completed; a lost savepoint): read again, do not repeat | 409 (or 503) | `X-Conflict-Code: CONFLICT_002`, no `Retry-After` |

- The Storage and Move pages become an `HttpException` with that status and those headers, rendered by your error page.
- **A stale bucket form is not a lock conflict** (2.1, rule 4): someone saved the bucket after the page was opened.
Nothing is written, repeating the request can never succeed, so it is a domain answer: 409, the form rendered again
with "Someone else saved this bucket after you opened the page…", `X-Error-Code: STORAGE_KIT_STALE_EDIT`, no
`X-Conflict-Code` and no `Retry-After`. The admin reloads the page. A missing or malformed `rowVersion` counts as
stale. The hidden field carries `<row id>:<row version>`, so **a page of another bucket is stale** too: a page opened
before its bucket was replaced (a target discarded and saved again, or a Move switch that made another row active)
never saves the new row, even when the versions are equal. The version comes from the same load as the values
(the bundle's manager is fresh for each request) and is never written by the ORM (`insertable: false,
updatable: false`), so it cannot go backwards.
- **What advances the version:** the Storage page's save, `StorageMove::saveTarget()` (with or without an expected
version). Direct ORM writes of your own to a `StorageProfile` do **not** advance it: a page opened before such a
write can still overwrite it. Save through `StorageMove::saveTarget()` (null version) to make open pages stale.
- The upload endpoint keeps its JSON error shape and adds the code: `{"error": "conflict", "message": "…", "code": "CONFLICT_001"}`.
- The download endpoint answers `text/plain`.
- Not conflicts, never mapped: unique (and other constraint) violations and lost connections. They stay real errors.
Expand Down Expand Up @@ -112,14 +124,23 @@ read the code must list `X-Conflict-Code` in `Access-Control-Expose-Headers` (th
your transaction keeping your write and your `SET LOCAL lock_timeout`.
- `tests/Integration/Functional/ConcurrentWritesTest.php`: the same re-checks on one connection (SQLite and the three
databases) with a statement hook as the other writer, plus a deadlock on the settings page and on the upload insert.
- `tests/Integration/Concurrency/RowVersionRaceTest.php` (2.1): two editors with the same version on two
connections (one wins, the other gets the stale 409, the stored row is the winner's); a save waiting on the row lock
of an open save answers `CONFLICT_001`, then its retry is stale; and (MySQL / MariaDB, audit ZH-M1) a real deadlock
inside the save's flush, against a second process: the deadlock destroys the ORM's savepoint, the runner repairs
the nesting level, the page answers 409 `CONFLICT_001` (never a 500), the connection is back at level 0 and the
next save works.
- `tests/Integration/Functional/StaleEditTest.php` (2.1, SQLite and the database jobs): stale, missing and forged
versions on the Storage and Move pages, a first save, a bucket created meanwhile, an unchecked save from your code,
and the pages of a replaced bucket (audit ZK-M1): a Move page of a discarded target saved after a new target, a
Storage page saved after a switch at an equal version, and a token that names another row; each answers 409 with
the new row unchanged.
- `tests/Unit/Concurrency`, `tests/Unit/EventListener/StorageKitConflictListenerTest.php`,
`tests/Unit/Doctrine/OwnerLockTest.php`: the mapping (001 / 002, unique violations and lost connections excluded) and
the lock per platform.

## Residual risks

- **Stale form, last writer wins.** Two admins editing the same existing bucket both save; the second save overwrites
the first (both are audited with the changed field names). The owner lock prevents duplicates, not this.
- **Owner lock inside your transaction.** If you call a Move / Storage write inside a transaction you opened, the
MySQL / MariaDB lock is released when the bundle's unit ends, before your commit (`GET_LOCK()` is session-scoped).
The Storage / Move writes are the bundle's own pages, which open no transaction around them. The first-use rows,
Expand Down
29 changes: 29 additions & 0 deletions docs/UPGRADING.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,35 @@ The breaking changes 1.x announced (REQ-BC-001), applied in 2.0 ([To 2.0.0](#to-

## Unreleased

From **2.0.1**: `composer update nowo-tech/storage-kit-bundle`, then add the new column **in the same deploy as the
code** (the pages read and write `row_version`; without the column the Storage and Move pages fail).

`storage_kit_profile` gets `row_version` (REQ-RUNTIME-003 rule 4: the bucket forms refuse a page that is no longer
current instead of overwriting another admin's save). `php bin/console doctrine:migrations:diff` (or
`doctrine:schema:update --dump-sql`) produces it; the SQL is the same on MySQL 8.4, MariaDB 11.4 and PostgreSQL 16,
an instant, additive change (existing rows start at version 1):

```sql
ALTER TABLE storage_kit_profile ADD row_version INT DEFAULT 1 NOT NULL;
```

With `doctrine.table_prefix`, use your prefixed table name.

What changes for you:

- **Admins:** a save from a page opened before someone else saved the same bucket shows "Someone else saved this
bucket after you opened the page…" and writes nothing (409, `X-Error-Code: STORAGE_KIT_STALE_EDIT`). They reload
the page and apply their change again.
- **Custom templates** (`web_ui.templates.settings` / `move`) that list the form fields one by one must also render
the hidden `rowVersion` field (`form_rest()` does); without it every save of an existing bucket is refused as stale.
- **Your code** calling `StorageMove::saveTarget()` is unchanged: without the new fifth argument the save is not
checked, but it advances the version, so a Move page opened before is refused. Pass the version the user saw to
get the check (`StaleEditException` when it no longer matches). Direct ORM writes of your own to a
`StorageProfile` do not advance the version.
- **The hidden token is `<row id>:<row version>`** (`StorageProfileType` options `row_id` + `row_version`), so a page
built for another bucket row (one replaced since) is refused. Code of yours reading the submitted token uses
`StorageProfileType::submittedRowVersion($form, $profile)`.

## To 2.0.1

From **2.0.0**:
Expand Down
18 changes: 10 additions & 8 deletions specs/001-baseline/code-inventory.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Code inventory — 001-baseline

**Last audited**: 2026-11-22 (v2.0.1)
**Last audited**: 2026-11-22 (v2.0.1 + Unreleased 2.1 row versions)
**Scope**: every production file under `src/` (`find src -type f | wc -l`). Tests, demo and generated caches are out of scope.

## Bundle / DI
Expand All @@ -26,6 +26,8 @@
| `src/EventListener/StorageKitConflictListener.php` | Bundle / DI | FR-RUN-002 |
| `src/Doctrine/OwnerLock.php` | Bundle / DI | FR-RUN-002 |
| `src/DependencyInjection/Compiler/StoragePrivateEntityManagerPass.php` | Bundle / DI | FR-DI-011 |
| `src/Concurrency/RowVersion.php` | Bundle / DI | FR-RUN-003 |
| `src/Concurrency/StaleEditException.php` | Bundle / DI | FR-RUN-003 |

## Storage

Expand Down Expand Up @@ -55,7 +57,7 @@

| Source path | Spec section | Requirement IDs |
| --- | --- | --- |
| `src/Entity/StorageProfile.php` | Profiles | FR-PROF-001 |
| `src/Entity/StorageProfile.php` | Profiles | FR-PROF-001, FR-RUN-003 |
| `src/Profile/StorageProfiles.php` | Profiles | FR-PROF-002 |
| `src/Profile/ConfigProfiles.php` | Profiles | FR-PROF-003 |
| `src/Repository/StorageProfileRepository.php` | Profiles | FR-PROF-004 |
Expand Down Expand Up @@ -132,7 +134,7 @@

| Source path | Spec section | Requirement IDs |
| --- | --- | --- |
| `src/Sync/StorageMove.php` | Moves | FR-MOVE-001 |
| `src/Sync/StorageMove.php` | Moves | FR-MOVE-001, FR-RUN-003 |
| `src/Sync/StorageSyncer.php` | Moves | FR-MOVE-002 |
| `src/Sync/SyncFailure.php` | Moves | FR-MOVE-002 |
| `src/Entity/StorageSync.php` | Moves | FR-MOVE-003 |
Expand Down Expand Up @@ -172,9 +174,9 @@

| Source path | Spec section | Requirement IDs |
| --- | --- | --- |
| `src/Controller/StorageSettingsController.php` | Admin UI and access | FR-UI-001 |
| `src/Controller/StorageMoveController.php` | Admin UI and access | FR-UI-002 |
| `src/Form/StorageProfileType.php` | Admin UI and access | FR-UI-003, FR-UI-007 |
| `src/Controller/StorageSettingsController.php` | Admin UI and access | FR-UI-001, FR-RUN-003 |
| `src/Controller/StorageMoveController.php` | Admin UI and access | FR-UI-002, FR-RUN-003 |
| `src/Form/StorageProfileType.php` | Admin UI and access | FR-UI-003, FR-UI-007, FR-RUN-003 |
| `src/Form/AwsAccessKeyCsv.php` | Admin UI and access | FR-UI-007 |
| `src/Form/AwsAccessKeyCsvException.php` | Admin UI and access | FR-UI-007 |
| `src/Form/AwsCsvImport.php` | Admin UI and access | FR-UI-007 |
Expand Down Expand Up @@ -222,7 +224,7 @@ These 6 `src/` files were added by releases after the last review. Each row maps

| Category | Files |
| --- | --- |
| Bundle / DI | 19 |
| Bundle / DI | 21 |
| Storage | 12 |
| SSRF | 2 |
| Profiles | 5 |
Expand All @@ -237,4 +239,4 @@ These 6 `src/` files were added by releases after the last review. Each row maps
| Admin UI and access | 20 |
| Translations | 7 |
| Removal port and default remover | 3 |
| **Total production sources** | **138 / 138** (`find src -type f \| wc -l` = 138) |
| **Total production sources** | **140 / 140** (`find src -type f \| wc -l` = 140) |
5 changes: 5 additions & 0 deletions specs/001-baseline/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -236,6 +236,11 @@ becomes the settings-backed active profile; existing files keep downloading.
/ `exclusively()` / `updateIf()` (1.7, REQ-RUNTIME-003): one unit per Storage / Move write under an owner lock with
the owner read again inside it, compare-and-set sync status changes, and the bundle routes' conflict answer (409 or
503, `X-Conflict-Code` `CONFLICT_001` with `Retry-After` / `CONFLICT_002` without); see `docs/CONCURRENCY.md`.
- **FR-RUN-003** — `RowVersion`, `StaleEditException`, `StorageProfile::$rowVersion` (2.1, REQ-RUNTIME-003 rule 4): the
Storage and Move bucket forms carry the row and the version they were built from (hidden `rowVersion` =
`<row id>:<row version>`, from the same load as the values; a token of another row is stale, audit ZK-M1); the save advances it with one atomic compare-and-set inside its unit, and a page that is no longer
current writes nothing and answers 409 `X-Error-Code: STORAGE_KIT_STALE_EDIT` (a domain answer, no
`X-Conflict-Code`); `StorageMove::saveTarget()` without a version advances it unchecked.

### Personal data and audit

Expand Down
Loading
Loading