From 61b3b8b31af0193ea2ae7d06573b0ba2dd590cbf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Franco?= Date: Sun, 22 Nov 2026 15:19:26 +0100 Subject: [PATCH 1/3] feat(concurrency): row versions on the bucket forms (REQ-RUNTIME-003 rule 4) The Storage page and the Move page new-bucket form were last-write-wins. storage_kit_profile gets an additive row_version column (never written by the ORM). Each form carries the version read from the database in a hidden rowVersion field; the save advances it with one atomic compare-and-set inside its existing write unit. A stale page writes nothing and answers a domain 409 (X-Error-Code: STORAGE_KIT_STALE_EDIT) with a translated message in the 7 locales. StorageMove::saveTarget() takes an optional expected version and advances it unchecked without one. Tests: two-connection races and a real MySQL/MariaDB deadlock inside the flush (audit ZH-M1: 409 CONFLICT_001, nesting level 0, next save works). --- src/Concurrency/RowVersion.php | 58 +++++ src/Concurrency/StaleEditException.php | 34 +++ src/Controller/StorageMoveController.php | 37 +++- src/Controller/StorageSettingsController.php | 53 ++++- src/Entity/StorageProfile.php | 17 ++ src/Form/StorageProfileType.php | 29 +++ .../translations/NowoStorageKitBundle.de.yaml | 2 + .../translations/NowoStorageKitBundle.en.yaml | 2 + .../translations/NowoStorageKitBundle.es.yaml | 2 + .../translations/NowoStorageKitBundle.fr.yaml | 2 + .../translations/NowoStorageKitBundle.it.yaml | 2 + .../translations/NowoStorageKitBundle.nl.yaml | 2 + .../translations/NowoStorageKitBundle.pt.yaml | 2 + src/Sync/StorageMove.php | 29 ++- .../Concurrency/ConcurrencyRaceTest.php | 12 +- .../Concurrency/RowVersionRaceTest.php | 203 ++++++++++++++++++ .../Integration/Functional/StaleEditTest.php | 192 +++++++++++++++++ tests/Support/deadlock-peer.php | 49 +++++ tests/Unit/Concurrency/RowVersionTest.php | 60 ++++++ 19 files changed, 768 insertions(+), 19 deletions(-) create mode 100644 src/Concurrency/RowVersion.php create mode 100644 src/Concurrency/StaleEditException.php create mode 100644 tests/Integration/Concurrency/RowVersionRaceTest.php create mode 100644 tests/Integration/Functional/StaleEditTest.php create mode 100644 tests/Support/deadlock-peer.php create mode 100644 tests/Unit/Concurrency/RowVersionTest.php diff --git a/src/Concurrency/RowVersion.php b/src/Concurrency/RowVersion.php new file mode 100644 index 0000000..41dce45 --- /dev/null +++ b/src/Concurrency/RowVersion.php @@ -0,0 +1,58 @@ +fetchOne(sprintf('SELECT row_version FROM %s WHERE id = ?', $table), [$id]); + + return is_numeric($version) ? (int) $version : self::MISSING; + } + + /** + * Advances the row `$id` by one version. With `$expected`, only while the row still has that version (the page's + * token); null advances it unchecked (a write with no page behind it), so pages opened before are refused as stale. + * + * @return bool whether the row was advanced (false: changed since the page was built, or gone) + */ + public static function advance(Connection $connection, string $table, int $id, ?int $expected): bool + { + $sql = sprintf('UPDATE %s SET row_version = row_version + 1 WHERE id = ?', $table); + $params = [$id]; + if ($expected !== null) { + $sql .= ' AND row_version = ?'; + $params[] = $expected; + } + + return (int) $connection->executeStatement($sql, $params) === 1; + } +} diff --git a/src/Concurrency/StaleEditException.php b/src/Concurrency/StaleEditException.php new file mode 100644 index 0000000..98c9328 --- /dev/null +++ b/src/Concurrency/StaleEditException.php @@ -0,0 +1,34 @@ +move->sync($active, $target); $running = $sync instanceof StorageSync && $sync->isOpen(); $form = $this->form($target, $scope, $running); + $stale = false; $form->handleRequest($request); if (!$running && $form->isSubmitted() && $form->isValid()) { /** @var array{provider: string|null, endpoint: string|null, public_endpoint: string|null, region: string|null, bucket: string|null, prefix: string|null, access_key: string|null, secret: string|null, path_style: bool|null} $data */ @@ -156,15 +158,23 @@ private function page(Request $request, ?string $scope): Response if ($data['secret'] !== null && $data['secret'] !== '') { $fields[] = 'secret'; } - $saved = $this->move->saveTarget($target, $this->guard->user(), $fields, $configure); - $this->addFlash($saved ? 'success' : 'error', $this->trans($saved ? 'move.flash.saved' : 'move.flash.unavailable')); - - return $this->redirectToRoute(...self::route($scope)); + try { + // 2.1 (REQ-RUNTIME-003 rule 4): a saved target is written only with the row version of this page. + $saved = $this->move->saveTarget($target, $this->guard->user(), $fields, $configure, $target->getId() === null ? null : StorageProfileType::submittedRowVersion($form)); + $this->addFlash($saved ? 'success' : 'error', $this->trans($saved ? 'move.flash.saved' : 'move.flash.unavailable')); + + return $this->redirectToRoute(...self::route($scope)); + } catch (StaleEditException) { + // Someone saved this target after the page was opened: nothing was written, the form is shown again. + $stale = true; + $this->addFlash('error', $this->trans('move.flash.stale')); + } + } else { + // Root errors are not part of the scaffold's child loop: attach it to the first missing field. + $missing = $submitted->getBucket() === '' ? 'bucket' : ($submitted->getAccessKey() === '' ? 'access_key' : 'secret'); + // @igor-ignore - Request-scoped form built in this action. + $form->get($missing)->addError(new FormError($this->trans('profile.error.incomplete'))); } - // Root errors are not part of the scaffold's child loop: attach it to the first missing field. - $missing = $submitted->getBucket() === '' ? 'bucket' : ($submitted->getAccessKey() === '' ? 'access_key' : 'secret'); - // @igor-ignore - Request-scoped form built in this action. - $form->get($missing)->addError(new FormError($this->trans('profile.error.incomplete'))); } [$settingsRoute, $settingsParams] = StorageSettingsController::route($scope); $usage = $active instanceof StorageProfile && $active->getId() !== null ? $this->files->usageOf($active) : ['files' => 0, 'bytes' => 0]; @@ -181,7 +191,14 @@ private function page(Request $request, ?string $scope): Response 'sync' => $sync, 'running' => $running, 'scope' => $scope, - ], new Response(status: $form->isSubmitted() ? Response::HTTP_UNPROCESSABLE_ENTITY : Response::HTTP_OK)); + ], new Response(status: match (true) { + $stale => Response::HTTP_CONFLICT, + $form->isSubmitted() => Response::HTTP_UNPROCESSABLE_ENTITY, + default => Response::HTTP_OK, + })); + if ($stale) { + $response->headers->set('X-Error-Code', StaleEditException::ERROR_CODE); + } $response->setPrivate(); $response->headers->addCacheControlDirective('no-store'); @@ -328,6 +345,8 @@ private function form(StorageProfile $target, ?string $scope, bool $running): Fo 'has_secret' => $target->hasSecret(), 'restricted' => $this->resolver->isRestricted($scope), 'with_enabled' => false, + // 2.1: the version of a saved target, read from the database (none for a target not saved yet). + 'row_version' => $this->move->rowVersion($target), ]); } diff --git a/src/Controller/StorageSettingsController.php b/src/Controller/StorageSettingsController.php index fb5b720..fe64a97 100644 --- a/src/Controller/StorageSettingsController.php +++ b/src/Controller/StorageSettingsController.php @@ -7,6 +7,8 @@ use Nowo\FormKitBundle\Form\CsrfOnlyFormFactory; use Nowo\StorageKitBundle\Audit\AuditRecorder; use Nowo\StorageKitBundle\Audit\StorageAuditEvent; +use Nowo\StorageKitBundle\Concurrency\RowVersion; +use Nowo\StorageKitBundle\Concurrency\StaleEditException; use Nowo\StorageKitBundle\Doctrine\StorageEntityManager; use Nowo\StorageKitBundle\Entity\StorageProfile; use Nowo\StorageKitBundle\Form\StorageProfileType; @@ -149,14 +151,22 @@ private function edit(Request $request, ?string $scope): Response }; $profile = $managed !== null ? $this->resolver->activeOf(null) : $this->profiles->activeOf($scope); $profile ??= new StorageProfile($scope); - $form = $managed !== null ? null : $this->form($profile, $scope); + $form = $managed !== null ? null : $this->form($profile, $scope); + $stale = false; if ($form instanceof FormInterface) { $form->handleRequest($request); if ($form->isSubmitted() && $form->isValid()) { - $saved = $this->save($form, $profile, $scope); - $this->addFlash($saved ? 'success' : 'error', $this->trans($saved ? 'settings.flash.saved' : 'settings.flash.changed')); - - return $this->redirectToRoute(...self::route($scope)); + try { + $saved = $this->save($form, $profile, $scope); + $this->addFlash($saved ? 'success' : 'error', $this->trans($saved ? 'settings.flash.saved' : 'settings.flash.changed')); + + return $this->redirectToRoute(...self::route($scope)); + } catch (StaleEditException) { + // 2.1 (REQ-RUNTIME-003 rule 4): someone saved this bucket after the page was opened. Nothing was + // written (the profile is only changed after the version check); the form is shown again. + $stale = true; + $this->addFlash('error', $this->trans('settings.flash.stale')); + } } } $usage = $profile->getId() === null ? ['files' => 0, 'bytes' => 0] : $this->files->usageOf($profile); @@ -182,7 +192,14 @@ private function edit(Request $request, ?string $scope): Response 'scope' => $scope, 'managed' => $managed, 'env_managed' => $managed === self::MANAGED_CONFIG, - ], new Response(status: $form?->isSubmitted() === true ? Response::HTTP_UNPROCESSABLE_ENTITY : Response::HTTP_OK)); + ], new Response(status: match (true) { + $stale => Response::HTTP_CONFLICT, + $form?->isSubmitted() === true => Response::HTTP_UNPROCESSABLE_ENTITY, + default => Response::HTTP_OK, + })); + if ($stale) { + $response->headers->set('X-Error-Code', StaleEditException::ERROR_CODE); + } return $this->noStore($response); } @@ -193,17 +210,27 @@ private function edit(Request $request, ?string $scope): Response * not edited. False (nothing written) when the owner changed since the page was read; the audit event is recorded * after the commit. * + * 2.1 (rule 4): an existing bucket is saved only while it still has the row version of the page (one atomic + * compare-and-set inside the unit, which also holds the row lock until the commit). + * * @param FormInterface $form + * + * @throws StaleEditException when the bucket was saved by someone else since the page was opened (nothing written) */ private function save(FormInterface $form, StorageProfile $profile, ?string $scope): bool { + $expected = StorageProfileType::submittedRowVersion($form); /** @var array{provider: string|null, enabled: bool|null, endpoint: string|null, public_endpoint: string|null, region: string|null, bucket: string|null, prefix: string|null, access_key: string|null, secret: string|null, path_style: bool|null} $data */ $data = $form->getData(); // @igor-ignore - The closure runs synchronously inside the unit of work; it is not stored on the service. - $changed = $this->entityManager->transactional(function () use ($data, $profile, $scope): ?array { + $changed = $this->entityManager->transactional(function () use ($data, $profile, $scope, $expected): ?array { if (!$this->profiles->isCurrent($profile, $scope, StorageProfile::STATE_ACTIVE)) { return null; } + $id = $profile->getId(); + if ($id !== null && !RowVersion::advance($this->entityManager->connection(), $this->entityManager->table(StorageProfile::class), $id, $expected)) { + throw new StaleEditException($id, $expected); + } $before = $this->snapshot($profile); $profile->configure( (string) $data['provider'], @@ -300,9 +327,21 @@ private function form(StorageProfile $profile, ?string $scope): FormInterface 'csrf_token_id' => self::formTokenId($scope), 'has_secret' => $profile->hasSecret(), 'restricted' => $this->resolver->isRestricted($scope), + // 2.1: the version of the stored bucket, read from the database (none for a bucket not saved yet). + 'row_version' => $this->rowVersion($this->entityManager, $profile), ]); } + /** + * 2.1: the current row version of a saved bucket, read from the database; null for a bucket not saved yet. + */ + private function rowVersion(StorageEntityManager $entityManager, StorageProfile $profile): ?int + { + $id = $profile->getId(); + + return $id === null ? null : RowVersion::read($entityManager->connection(), $entityManager->table(StorageProfile::class), $id); + } + private function scopeOrNotFound(string $scope): string { if (!$this->resolver->scopesEnabled() || !$this->guard->isScopeGranted($scope)) { diff --git a/src/Entity/StorageProfile.php b/src/Entity/StorageProfile.php index 566e729..d97fbc3 100644 --- a/src/Entity/StorageProfile.php +++ b/src/Entity/StorageProfile.php @@ -8,6 +8,7 @@ use Doctrine\ORM\Mapping as ORM; use InvalidArgumentException; use Nowo\DoctrineEncryptBundle\Configuration\Encrypted; +use Nowo\StorageKitBundle\Concurrency\RowVersion; use Nowo\StorageKitBundle\Scope\ScopeResolverInterface; use Nowo\StorageKitBundle\Scope\StorageScope; use Nowo\StorageKitBundle\Storage\S3Settings; @@ -117,6 +118,14 @@ class StorageProfile #[ORM\Column(name: 'updated_at')] private DateTimeImmutable $updatedAt; + /** + * 2.1 (REQ-RUNTIME-003 rule 4): the row version of the bucket form, advanced by one atomic SQL statement for every + * save of the connection fields ({@see RowVersion}). Never written by the ORM (not insertable, not updatable), so a + * flush can never move it backwards; the value here is the one loaded and may lag behind the database. + */ + #[ORM\Column(name: 'row_version', insertable: false, updatable: false, options: ['default' => 1])] + private int $rowVersion = 1; + /** * @param string|null $scope owner scope key (null = the instance) * @param string $state {@see self::STATE_ACTIVE} / {@see self::STATE_TARGET} @@ -479,4 +488,12 @@ public function getUpdatedAt(): DateTimeImmutable { return $this->updatedAt; } + + /** + * 2.1: the row version as loaded (the bucket form reads the current one from the database, {@see RowVersion::read()}). + */ + public function getRowVersion(): int + { + return $this->rowVersion; + } } diff --git a/src/Form/StorageProfileType.php b/src/Form/StorageProfileType.php index a644ae8..25e72f7 100644 --- a/src/Form/StorageProfileType.php +++ b/src/Form/StorageProfileType.php @@ -6,6 +6,7 @@ use Nowo\FormKitBundle\Attribute\FormKitConfig; use Nowo\FormKitBundle\Form\FormOptionsTrait; +use Nowo\StorageKitBundle\Concurrency\RowVersion; use Nowo\StorageKitBundle\NowoStorageKitBundle; use Nowo\StorageKitBundle\Security\EndpointGuard; use Nowo\StorageKitBundle\Storage\S3Settings; @@ -15,6 +16,7 @@ use Symfony\Component\Form\Extension\Core\Type\CheckboxType; use Symfony\Component\Form\Extension\Core\Type\ChoiceType; use Symfony\Component\Form\Extension\Core\Type\FileType; +use Symfony\Component\Form\Extension\Core\Type\HiddenType; use Symfony\Component\Form\Extension\Core\Type\PasswordType; use Symfony\Component\Form\Extension\Core\Type\TextType; use Symfony\Component\Form\FormBuilderInterface; @@ -28,7 +30,11 @@ use Symfony\Component\Validator\Context\ExecutionContextInterface; use function assert; +use function ctype_digit; use function is_array; +use function is_int; +use function is_string; +use function strlen; use function trim; /** @@ -53,6 +59,9 @@ final class StorageProfileType extends AbstractType { use FormOptionsTrait; + /** 2.1: name of the hidden row-version field (option `row_version`; rendered with the other hidden fields). */ + public const ROW_VERSION = 'rowVersion'; + /** * The SSRF guard checks the server-side endpoint of restricted profiles. */ @@ -170,6 +179,11 @@ public function buildForm(FormBuilderInterface $builder, array $options): void 'disabled' => $readOnly, 'row_attr' => $endpointOnly, ]); + if (is_int($options['row_version'])) { + // 2.1 (REQ-RUNTIME-003 rule 4): the row version the page was built from, unmapped; the save refuses the + // form when the bucket was saved by someone else since (RowVersion, StaleEditException). + $builder->add(self::ROW_VERSION, HiddenType::class, ['mapped' => false, 'required' => false, 'label' => false, 'data' => (string) $options['row_version']]); + } // The submitted provider decides which fields count (InstanceSettings 1.3 rules): the endpoint fields hidden // for Amazon S3 get their current values back, so they are neither validated nor changed. $builder->addEventListener(FormEvents::PRE_SUBMIT, static function (FormEvent $event): void { @@ -205,11 +219,13 @@ public function configureOptions(OptionsResolver $resolver): void 'has_secret' => false, 'restricted' => true, 'with_enabled' => true, + 'row_version' => null, ]); $resolver->setAllowedTypes('read_only', 'bool'); $resolver->setAllowedTypes('has_secret', 'bool'); $resolver->setAllowedTypes('restricted', 'bool'); $resolver->setAllowedTypes('with_enabled', 'bool'); + $resolver->setAllowedTypes('row_version', ['null', 'int']); } /** @@ -223,4 +239,17 @@ public function getBlockPrefix(): string /* * A non-empty value must (`$match`) or must not match `$regex`; the message is a bundle-domain key. */ + + /** + * 2.1: the row version a submitted form carries, or {@see RowVersion::MISSING} when the field is absent or not a + * whole number (never equal to a stored version, so such a save is refused as stale). + * + * @param FormInterface $form + */ + public static function submittedRowVersion(FormInterface $form): int + { + $token = $form->has(self::ROW_VERSION) ? $form->get(self::ROW_VERSION)->getData() : null; + + return is_string($token) && $token !== '' && strlen($token) <= 18 && ctype_digit($token) ? (int) $token : RowVersion::MISSING; + } } diff --git a/src/Resources/translations/NowoStorageKitBundle.de.yaml b/src/Resources/translations/NowoStorageKitBundle.de.yaml index d9ae74d..036f4ad 100644 --- a/src/Resources/translations/NowoStorageKitBundle.de.yaml +++ b/src/Resources/translations/NowoStorageKitBundle.de.yaml @@ -15,6 +15,7 @@ settings: flash: saved: 'Die Speichereinstellungen wurden gespeichert.' changed: 'Jemand anderes hat diesen Bucket inzwischen geändert. Prüfen Sie ihn und speichern Sie erneut.' + stale: 'Jemand anderes hat diesen Bucket gespeichert, nachdem Sie die Seite geöffnet haben. Ihre Änderungen wurden nicht gespeichert: Laden Sie die Seite neu und übernehmen Sie sie erneut.' section: config: 'Konfiguration' field: @@ -152,6 +153,7 @@ move: objects: '%copied% kopiert, %skipped% bereits vorhanden' flash: saved: 'Der neue Bucket wurde gespeichert. Testen Sie ihn und starten Sie dann das Kopieren.' + stale: 'Jemand anderes hat den neuen Bucket gespeichert, nachdem Sie die Seite geöffnet haben. Ihre Änderungen wurden nicht gespeichert: Laden Sie die Seite neu und übernehmen Sie sie erneut.' unavailable: 'Diese Aktion ist gerade nicht verfügbar.' started: 'Das Kopieren läuft im Hintergrund.' started_cli: 'Das Kopieren steht in der Warteschlange. Führen Sie aus: bin/console nowo:storage-kit:sync %from% %to%' diff --git a/src/Resources/translations/NowoStorageKitBundle.en.yaml b/src/Resources/translations/NowoStorageKitBundle.en.yaml index 75bf7ee..866d33e 100644 --- a/src/Resources/translations/NowoStorageKitBundle.en.yaml +++ b/src/Resources/translations/NowoStorageKitBundle.en.yaml @@ -15,6 +15,7 @@ settings: flash: saved: 'The storage settings were saved.' changed: 'Someone else changed this bucket meanwhile. Review it and save again.' + stale: 'Someone else saved this bucket after you opened the page. Your changes were not saved: reload the page and apply them again.' section: config: 'Configuration' field: @@ -152,6 +153,7 @@ move: objects: '%copied% copied, %skipped% already there' flash: saved: 'The new bucket was saved. Test it, then start copying.' + stale: 'Someone else saved the new bucket after you opened the page. Your changes were not saved: reload the page and apply them again.' unavailable: 'This action is not available now.' started: 'Copying started in the background.' started_cli: 'Copying is queued. Run: bin/console nowo:storage-kit:sync %from% %to%' diff --git a/src/Resources/translations/NowoStorageKitBundle.es.yaml b/src/Resources/translations/NowoStorageKitBundle.es.yaml index d61aeb2..a84b4ac 100644 --- a/src/Resources/translations/NowoStorageKitBundle.es.yaml +++ b/src/Resources/translations/NowoStorageKitBundle.es.yaml @@ -15,6 +15,7 @@ settings: flash: saved: 'Se ha guardado la configuración del almacenamiento.' changed: 'Otra persona ha cambiado este bucket mientras tanto. Revísalo y vuelve a guardar.' + stale: 'Otra persona ha guardado este bucket después de que abrieras la página. Tus cambios no se han guardado: recarga la página y vuelve a aplicarlos.' section: config: 'Configuración' field: @@ -152,6 +153,7 @@ move: objects: '%copied% copiados, %skipped% ya existían' flash: saved: 'Se ha guardado el bucket nuevo. Pruébalo y empieza a copiar.' + stale: 'Otra persona ha guardado el nuevo bucket después de que abrieras la página. Tus cambios no se han guardado: recarga la página y vuelve a aplicarlos.' unavailable: 'Esta acción no está disponible ahora.' started: 'La copia ha empezado en segundo plano.' started_cli: 'La copia está en cola. Ejecuta: bin/console nowo:storage-kit:sync %from% %to%' diff --git a/src/Resources/translations/NowoStorageKitBundle.fr.yaml b/src/Resources/translations/NowoStorageKitBundle.fr.yaml index d7b507e..3eb6af8 100644 --- a/src/Resources/translations/NowoStorageKitBundle.fr.yaml +++ b/src/Resources/translations/NowoStorageKitBundle.fr.yaml @@ -15,6 +15,7 @@ settings: flash: saved: 'Les paramètres de stockage ont été enregistrés.' changed: 'Quelqu’un d’autre a modifié ce bucket entre-temps. Vérifiez-le et enregistrez à nouveau.' + stale: 'Quelqu’un d’autre a enregistré ce bucket après l’ouverture de la page. Vos modifications n’ont pas été enregistrées : rechargez la page et appliquez-les à nouveau.' section: config: 'Configuration' field: @@ -152,6 +153,7 @@ move: objects: '%copied% copiés, %skipped% déjà présents' flash: saved: 'Le nouveau bucket a été enregistré. Testez-le, puis lancez la copie.' + stale: 'Quelqu’un d’autre a enregistré le nouveau bucket après l’ouverture de la page. Vos modifications n’ont pas été enregistrées : rechargez la page et appliquez-les à nouveau.' unavailable: 'Cette action n''est pas disponible pour le moment.' started: 'La copie a commencé en arrière-plan.' started_cli: 'La copie est en file d''attente. Lancez : bin/console nowo:storage-kit:sync %from% %to%' diff --git a/src/Resources/translations/NowoStorageKitBundle.it.yaml b/src/Resources/translations/NowoStorageKitBundle.it.yaml index 721e4b0..16bdd2b 100644 --- a/src/Resources/translations/NowoStorageKitBundle.it.yaml +++ b/src/Resources/translations/NowoStorageKitBundle.it.yaml @@ -15,6 +15,7 @@ settings: flash: saved: 'Le impostazioni di archiviazione sono state salvate.' changed: 'Qualcun altro ha modificato questo bucket nel frattempo. Controllalo e salva di nuovo.' + stale: 'Qualcun altro ha salvato questo bucket dopo che hai aperto la pagina. Le tue modifiche non sono state salvate: ricarica la pagina e applicale di nuovo.' section: config: 'Configurazione' field: @@ -152,6 +153,7 @@ move: objects: '%copied% copiati, %skipped% già presenti' flash: saved: 'Il nuovo bucket è stato salvato. Provalo e poi avvia la copia.' + stale: 'Qualcun altro ha salvato il nuovo bucket dopo che hai aperto la pagina. Le tue modifiche non sono state salvate: ricarica la pagina e applicale di nuovo.' unavailable: 'Questa azione non è disponibile ora.' started: 'La copia è stata avviata in background.' started_cli: 'La copia è in coda. Esegui: bin/console nowo:storage-kit:sync %from% %to%' diff --git a/src/Resources/translations/NowoStorageKitBundle.nl.yaml b/src/Resources/translations/NowoStorageKitBundle.nl.yaml index a99a687..b454da2 100644 --- a/src/Resources/translations/NowoStorageKitBundle.nl.yaml +++ b/src/Resources/translations/NowoStorageKitBundle.nl.yaml @@ -15,6 +15,7 @@ settings: flash: saved: 'De opslaginstellingen zijn opgeslagen.' changed: 'Iemand anders heeft deze bucket intussen gewijzigd. Controleer hem en sla opnieuw op.' + stale: 'Iemand anders heeft deze bucket opgeslagen nadat je de pagina opende. Je wijzigingen zijn niet opgeslagen: laad de pagina opnieuw en breng ze opnieuw aan.' section: config: 'Configuratie' field: @@ -152,6 +153,7 @@ move: objects: '%copied% gekopieerd, %skipped% al aanwezig' flash: saved: 'De nieuwe bucket is opgeslagen. Test hem en start dan het kopiëren.' + stale: 'Iemand anders heeft de nieuwe bucket opgeslagen nadat je de pagina opende. Je wijzigingen zijn niet opgeslagen: laad de pagina opnieuw en breng ze opnieuw aan.' unavailable: 'Deze actie is nu niet beschikbaar.' started: 'Het kopiëren is op de achtergrond gestart.' started_cli: 'Het kopiëren staat in de wachtrij. Voer uit: bin/console nowo:storage-kit:sync %from% %to%' diff --git a/src/Resources/translations/NowoStorageKitBundle.pt.yaml b/src/Resources/translations/NowoStorageKitBundle.pt.yaml index 38794fd..035184a 100644 --- a/src/Resources/translations/NowoStorageKitBundle.pt.yaml +++ b/src/Resources/translations/NowoStorageKitBundle.pt.yaml @@ -15,6 +15,7 @@ settings: flash: saved: 'As definições de armazenamento foram guardadas.' changed: 'Outra pessoa alterou este bucket entretanto. Reveja-o e guarde novamente.' + stale: 'Outra pessoa guardou este bucket depois de abrir a página. As suas alterações não foram guardadas: recarregue a página e aplique-as novamente.' section: config: 'Configuração' field: @@ -152,6 +153,7 @@ move: objects: '%copied% copiados, %skipped% já existentes' flash: saved: 'O bucket novo foi guardado. Teste-o e comece a copiar.' + stale: 'Outra pessoa guardou o novo bucket depois de abrir a página. As suas alterações não foram guardadas: recarregue a página e aplique-as novamente.' unavailable: 'Esta ação não está disponível agora.' started: 'A cópia começou em segundo plano.' started_cli: 'A cópia está em fila. Execute: bin/console nowo:storage-kit:sync %from% %to%' diff --git a/src/Sync/StorageMove.php b/src/Sync/StorageMove.php index 92b3f1b..a04dcee 100644 --- a/src/Sync/StorageMove.php +++ b/src/Sync/StorageMove.php @@ -8,6 +8,8 @@ use Nowo\InstanceSettingsBundle\Exception\InvalidSettingValueException; use Nowo\StorageKitBundle\Audit\AuditRecorder; use Nowo\StorageKitBundle\Audit\StorageAuditEvent; +use Nowo\StorageKitBundle\Concurrency\RowVersion; +use Nowo\StorageKitBundle\Concurrency\StaleEditException; use Nowo\StorageKitBundle\Doctrine\StorageEntityManager; use Nowo\StorageKitBundle\Entity\StorageProfile; use Nowo\StorageKitBundle\Entity\StorageSync; @@ -101,11 +103,19 @@ public function sync(?StorageProfile $active, ?StorageProfile $target): ?Storage * boundary dropped the private manager), that connection is applied to the bundle's instance inside the unit; 2.0.0 * saved the stored row unchanged and still reported it as saved. * + * 2.1 (REQ-RUNTIME-003 rule 4): a saved target is written only while it still has `$expectedVersion` (the row + * version of the Move page, {@see self::rowVersion()}), with one atomic compare-and-set inside the unit. Null + * (your own code, no page behind it) saves without the check but still advances the version, so a page opened + * before is refused instead of overwriting your save. + * * @param list $fields names of the changed fields * @param (callable(StorageProfile): void)|null $configure applies the submitted fields (null: the connection set * on `$target` is saved as it is) + * @param int|null $expectedVersion the row version of the edited page, or null for an unchecked save + * + * @throws StaleEditException when `$expectedVersion` is no longer the target's version (nothing written) */ - public function saveTarget(StorageProfile $target, ?object $actor, array $fields, ?callable $configure = null): bool + public function saveTarget(StorageProfile $target, ?object $actor, array $fields, ?callable $configure = null, ?int $expectedVersion = null): bool { // 2.0 (lesson W1-2): a saved target loaded through the application's manager is loaded again by the bundle's. $given = $target; @@ -115,10 +125,14 @@ public function saveTarget(StorageProfile $target, ?object $actor, array $fields } $scope = $target->getScope(); // @igor-ignore - The closure runs synchronously inside the unit of work; it is not stored on the service. - $saved = $this->entityManager->transactional(function () use ($target, $scope, $configure): bool { + $saved = $this->entityManager->transactional(function () use ($target, $scope, $configure, $expectedVersion): bool { if (!$this->profiles->isCurrent($target, $scope, StorageProfile::STATE_TARGET)) { return false; } + $id = $target->getId(); + if ($id !== null && !RowVersion::advance($this->entityManager->connection(), $this->entityManager->table(StorageProfile::class), $id, $expectedVersion)) { + throw new StaleEditException($id, $expectedVersion); + } if ($configure !== null) { $configure($target); } @@ -134,6 +148,17 @@ public function saveTarget(StorageProfile $target, ?object $actor, array $fields return $saved; } + /** + * 2.1: the current row version of a saved bucket, read from the database (the token of its form); null for a bucket + * not saved yet. + */ + public function rowVersion(StorageProfile $profile): ?int + { + $id = $profile->getId(); + + return $id === null ? null : RowVersion::read($this->entityManager->connection(), $this->entityManager->table(StorageProfile::class), $id); + } + /** * 2.0.1 (YH-1): applies the connection set on `$given` (provider, enabled, endpoints, region, bucket, prefix, * access key, path style and, when it differs, the secret) to the bundle's own instance of the same row. diff --git a/tests/Integration/Concurrency/ConcurrencyRaceTest.php b/tests/Integration/Concurrency/ConcurrencyRaceTest.php index 58a80d9..ac02960 100644 --- a/tests/Integration/Concurrency/ConcurrencyRaceTest.php +++ b/tests/Integration/Concurrency/ConcurrencyRaceTest.php @@ -6,6 +6,7 @@ use Doctrine\DBAL\Connection; use Doctrine\DBAL\Platforms\PostgreSQLPlatform; +use Nowo\StorageKitBundle\Concurrency\StaleEditException; use Nowo\StorageKitBundle\Concurrency\StorageConflicts; use Nowo\StorageKitBundle\Controller\FileUploadController; use Nowo\StorageKitBundle\Doctrine\StorageEntityManager; @@ -119,7 +120,16 @@ public function testTwoFirstSavesOfABucketWaitForEachOther(): void }, StorageProfileRepository::ownerLock('acme')); $this->assertUsable($this->b); - // B's retry edits A's bucket: still one active bucket for the owner. + // B's retry of the same page would overwrite A's bucket, which that page never showed: stale since 2.1. + $client->submit($form); + self::assertSame(409, $client->getResponse()->getStatusCode()); + self::assertSame(StaleEditException::ERROR_CODE, $client->getResponse()->headers->get('X-Error-Code')); + self::assertSame(0, $this->rows("SELECT COUNT(*) FROM storage_kit_profile WHERE bucket = 'from-b'")); + + // Reloaded, B edits A's bucket: still one active bucket for the owner. + $form = $client->request('GET', '/storage/scopes/acme')->selectButton('Save')->form()->disableValidation(); + $form['storage_profile[bucket]'] = 'from-b'; + $form['storage_profile[secret]'] = 'test-secret-not-real'; $client->submit($form); self::assertStringContainsString('The storage settings were saved.', $this->follow($client)); self::assertSame(1, $this->rows("SELECT COUNT(*) FROM storage_kit_profile WHERE scope = 'acme' AND state = 'active'")); diff --git a/tests/Integration/Concurrency/RowVersionRaceTest.php b/tests/Integration/Concurrency/RowVersionRaceTest.php new file mode 100644 index 0000000..c9ecfa4 --- /dev/null +++ b/tests/Integration/Concurrency/RowVersionRaceTest.php @@ -0,0 +1,203 @@ + ['owner_lock_timeout' => 1]]; + $hooks = static function (ContainerConfigurator $container): void { + $services = $container->services(); + $services->set(StatementHooks::class)->public(); + $services->set(StatementHook::class)->args([service(StatementHooks::class)])->tag('doctrine.middleware'); + }; + $this->a = $this->bootKernel($config, extra: $hooks); + $this->b = $this->bootKernel($config, extra: $hooks, schema: false); + foreach ([$this->a, $this->b] as $kernel) { + $connection = $this->connection($kernel); + $connection->executeStatement($connection->getDatabasePlatform() instanceof PostgreSQLPlatform ? "SET lock_timeout = '1s'" : 'SET SESSION innodb_lock_wait_timeout = 1'); + } + } + + private function connection(StorageKitTestKernel $kernel): Connection + { + return $this->service($kernel, StorageEntityManager::class)->connection(); + } + + private function version(StorageProfile $profile): int + { + return RowVersion::read($this->connection($this->a), 'storage_kit_profile', (int) $profile->getId()); + } + + private function bucket(StorageProfile $profile): string + { + return (string) $this->connection($this->a)->fetchOne('SELECT bucket FROM storage_kit_profile WHERE id = ?', [$profile->getId()]); + } + + private function form(KernelBrowser $client, string $bucket): Form + { + $form = $client->request('GET', '/storage/scopes/acme')->selectButton('Save')->form()->disableValidation(); + $form['storage_profile[bucket]'] = $bucket; + // Each test kernel has its own encryption key: the stored secret is typed again so the bucket stays complete. + $form['storage_profile[secret]'] = 'test-secret-not-real'; + + return $form; + } + + private function assertUsable(StorageKitTestKernel $kernel): void + { + $connection = $this->connection($kernel); + self::assertSame(0, $connection->getTransactionNestingLevel()); + self::assertSame(1, (int) $connection->fetchOne('SELECT 1')); + } + + public function testTwoEditorsWithTheSameVersionOneWinsTheOtherIsStale(): void + { + $profile = $this->profile($this->a, 'acme'); + $clientA = $this->client($this->a, 'scopeadmin'); + $clientB = $this->client($this->b, 'scopeadmin'); + $formA = $this->form($clientA, 'from-a'); + $formB = $this->form($clientB, 'from-b'); + + // A's save commits first on its own connection. + $clientA->submit($formA); + self::assertSame(302, $clientA->getResponse()->getStatusCode()); + + // B's page (same version) is stale: nothing written over A's save. + $clientB->submit($formB); + self::assertSame(409, $clientB->getResponse()->getStatusCode()); + self::assertSame(StaleEditException::ERROR_CODE, $clientB->getResponse()->headers->get('X-Error-Code')); + self::assertFalse($clientB->getResponse()->headers->has('X-Conflict-Code')); + self::assertSame('from-a', $this->bucket($profile)); + self::assertSame(2, $this->version($profile)); + $this->assertUsable($this->a); + $this->assertUsable($this->b); + } + + public function testASaveWaitingForAnOpenSaveIsStaleOnceTheOtherCommits(): void + { + $profile = $this->profile($this->a, 'acme'); + $clientB = $this->client($this->b, 'scopeadmin'); + $formB = $this->form($clientB, 'from-b'); + + // A has claimed the row (same version as B's page) and not committed yet: B's save waits for the row lock and + // answers the retry-safe lock conflict, writing nothing. + $a = $this->connection($this->a); + $a->beginTransaction(); + self::assertTrue(RowVersion::advance($a, 'storage_kit_profile', (int) $profile->getId(), 1)); + $a->executeStatement("UPDATE storage_kit_profile SET bucket = 'from-a' WHERE id = ?", [$profile->getId()]); + $clientB->submit($formB); + self::assertSame(409, $clientB->getResponse()->getStatusCode()); + self::assertSame('CONFLICT_001', $clientB->getResponse()->headers->get('X-Conflict-Code')); + $this->assertUsable($this->b); + $a->commit(); + + // B's retry of the same page is now stale (A's save won): never a lost update. + $clientB->submit($formB); + self::assertSame(409, $clientB->getResponse()->getStatusCode()); + self::assertSame(StaleEditException::ERROR_CODE, $clientB->getResponse()->headers->get('X-Error-Code')); + self::assertSame('from-a', $this->bucket($profile)); + self::assertSame(2, $this->version($profile)); + $this->assertUsable($this->b); + } + + /** + * ZH-M1: a real deadlock inside the save's flush on MySQL / MariaDB rolls the whole server transaction back, so the + * ORM's savepoint is gone and its rollback fails (1305). 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. + */ + public function testARealDeadlockInTheFlushAnswers409AndLeavesTheConnectionUsable(): void + { + $connection = $this->connection($this->b); + if (!$connection->getDatabasePlatform() instanceof AbstractMySQLPlatform) { + self::markTestSkipped('MySQL / MariaDB only: PostgreSQL rolls back to a savepoint of an aborted transaction.'); + } + $connection->executeStatement('SET SESSION innodb_lock_wait_timeout = 10'); + $profile = $this->profile($this->a, 'acme'); + $held = $this->profile($this->a, 'other', 'held'); + $extra = []; + for ($i = 0; $i < 10; ++$i) { + $extra[] = (int) $this->profile($this->a, 'other', 'extra', StorageProfile::STATE_RETIRED)->getId(); + } + $client = $this->client($this->b, 'scopeadmin'); + $form = $this->form($client, 'mine'); + + $peer = new Process([PHP_BINARY, dirname(__DIR__, 2) . '/Support/deadlock-peer.php', StorageKitTestKernel::databaseUrl(), (string) $profile->getId(), (string) $held->getId(), implode(',', $extra)]); + $peer->setTimeout(60); + $peer->start(); + $peer->waitUntil(static fn (string $type, string $output): bool => str_contains($output, 'ready')); + + // B's save holds the profile row (version claim) and, in the flush, waits for the row the peer holds; the peer + // then asks for the profile row: a deadlock, and B (fewer changed rows) is the victim. + $hooks = $this->service($this->b, StatementHooks::class); + $hooks->hook = static function (string $sql) use ($hooks, $connection, $held): void { + // The flush's UPDATE of the profile (not the version claim before it). + if (str_starts_with($sql, 'UPDATE storage_kit_profile SET') && !str_contains($sql, 'row_version')) { + $hooks->hook = null; + $connection->fetchOne('SELECT id FROM storage_kit_profile WHERE id = ? FOR UPDATE', [$held->getId()]); + } + }; + $client->submit($form); + $peer->wait(); + $peerResult = trim(str_replace('ready', '', $peer->getOutput())); + + $response = $client->getResponse(); + self::assertSame(409, $response->getStatusCode(), $peerResult); + self::assertSame('CONFLICT_001', $response->headers->get('X-Conflict-Code')); + self::assertSame('done ok', $peerResult, 'the peer was not the deadlock victim'); + self::assertSame(0, $connection->getTransactionNestingLevel()); + self::assertSame('files', $this->bucket($profile)); + self::assertSame(1, $this->version($profile)); + + // Nothing was written, so the same page saves on the same (repaired) connection. + $client->submit($form); + self::assertSame(302, $client->getResponse()->getStatusCode(), (string) $client->getResponse()->getContent()); + self::assertSame('mine', $this->bucket($profile)); + self::assertSame(2, $this->version($profile)); + $this->assertUsable($this->b); + } +} diff --git a/tests/Integration/Functional/StaleEditTest.php b/tests/Integration/Functional/StaleEditTest.php new file mode 100644 index 0000000..4f5a171 --- /dev/null +++ b/tests/Integration/Functional/StaleEditTest.php @@ -0,0 +1,192 @@ +service($kernel, StorageEntityManager::class); + } + + private function version(StorageKitTestKernel $kernel, StorageProfile $profile): int + { + return RowVersion::read($this->storage($kernel)->connection(), $this->storage($kernel)->table(StorageProfile::class), (int) $profile->getId()); + } + + private function bucket(StorageKitTestKernel $kernel, StorageProfile $profile): string + { + return (string) $this->storage($kernel)->connection()->fetchOne('SELECT bucket FROM storage_kit_profile WHERE id = ?', [$profile->getId()]); + } + + private function settingsForm(KernelBrowser $client, string $bucket): Form + { + $form = $client->request('GET', '/storage/scopes/acme')->selectButton('Save')->form()->disableValidation(); + $form['storage_profile[bucket]'] = $bucket; + + return $form; + } + + private function moveForm(KernelBrowser $client, string $bucket): Form + { + return $client->request('GET', '/admin/storage/move')->selectButton('Save the new bucket')->form([ + 'storage_target[endpoint]' => 'http://minio:9000', + 'storage_target[region]' => 'us-east-1', + 'storage_target[bucket]' => $bucket, + 'storage_target[prefix]' => '', + 'storage_target[access_key]' => 'test-key', + 'storage_target[secret]' => 'test-secret-not-real', + ]); + } + + private function assertStale(KernelBrowser $client, string $message): void + { + $response = $client->getResponse(); + self::assertSame(409, $response->getStatusCode()); + self::assertSame(StaleEditException::ERROR_CODE, $response->headers->get('X-Error-Code')); + self::assertFalse($response->headers->has('X-Conflict-Code'), 'a stale page is a domain answer, not a lock conflict'); + self::assertFalse($response->headers->has('Retry-After')); + self::assertStringContainsString($message, (string) $response->getContent()); + } + + public function testTheStoragePageCarriesTheVersionAndRefusesAStalePage(): void + { + $kernel = $this->bootKernel(); + $profile = $this->profile($kernel, 'acme'); + $mine = $this->client($kernel, 'scopeadmin'); + $theirs = $this->client($kernel, 'scopeadmin'); + + // Both admins open the page at version 1. + $mineForm = $this->settingsForm($mine, 'mine'); + $theirsForm = $this->settingsForm($theirs, 'theirs'); + self::assertSame('1', $mineForm->getValues()['storage_profile[rowVersion]'] ?? null); + + // The other admin saves first: the version advances by one. + $theirs->submit($theirsForm); + self::assertSame(302, $theirs->getResponse()->getStatusCode()); + self::assertSame(2, $this->version($kernel, $profile)); + + // This page is stale: nothing is written, the form is shown again with the message. + $mine->submit($mineForm); + $this->assertStale($mine, 'Someone else saved this bucket after you opened the page.'); + self::assertSame('theirs', $this->bucket($kernel, $profile)); + self::assertSame(2, $this->version($kernel, $profile)); + self::assertCount(1, $mine->getCrawler()->filter('input[name="storage_profile[bucket]"]')); + + // Reloaded, the page saves. + $mine->submit($this->settingsForm($mine, 'mine')); + self::assertSame(302, $mine->getResponse()->getStatusCode()); + self::assertSame('mine', $this->bucket($kernel, $profile)); + self::assertSame(3, $this->version($kernel, $profile)); + self::assertCount(2, array_filter($this->audit($kernel)->actions(), static fn (string $action): bool => $action === StorageAuditEvent::PROFILE_SAVED)); + } + + public function testAMissingOrForgedVersionIsStale(): void + { + $kernel = $this->bootKernel(); + $profile = $this->profile($kernel, 'acme'); + $client = $this->client($kernel, 'scopeadmin'); + + foreach (['', 'abc', '-1', '1e3', '99999999999999999999', null] as $token) { + $form = $this->settingsForm($client, 'forged'); + $values = $form->getPhpValues(); + if ($token === null) { + unset($values['storage_profile']['rowVersion']); + } else { + $values['storage_profile']['rowVersion'] = $token; + } + $client->request('POST', '/storage/scopes/acme', $values); + $this->assertStale($client, 'Someone else saved this bucket after you opened the page.'); + } + self::assertSame('files', $this->bucket($kernel, $profile)); + self::assertSame(1, $this->version($kernel, $profile)); + } + + public function testAFirstSaveHasNoVersionAndABucketCreatedMeanwhileMakesThePageStale(): void + { + $kernel = $this->bootKernel(); + $client = $this->client($kernel, 'scopeadmin'); + $form = $this->settingsForm($client, 'mine'); + self::assertFalse($form->has('storage_profile[rowVersion]')); + + // Another admin saved the scope's first bucket meanwhile: this page never saw it. + $theirs = $this->profile($kernel, 'acme', 'theirs'); + $client->submit($form); + $this->assertStale($client, 'Someone else saved this bucket after you opened the page.'); + self::assertSame('theirs', $this->bucket($kernel, $theirs)); + } + + public function testTheMovePageRefusesAStaleTarget(): void + { + $kernel = $this->bootKernel(); + $this->profile($kernel); + $target = $this->profile($kernel, null, 'target-files', StorageProfile::STATE_TARGET); + $mine = $this->client($kernel); + $theirs = $this->client($kernel); + + $mineForm = $this->moveForm($mine, 'mine'); + self::assertSame('1', $mineForm->getValues()['storage_target[rowVersion]'] ?? null); + $theirs->submit($this->moveForm($theirs, 'theirs')); + self::assertSame(302, $theirs->getResponse()->getStatusCode()); + + $mine->submit($mineForm); + $this->assertStale($mine, 'Someone else saved the new bucket after you opened the page.'); + self::assertSame('theirs', $this->bucket($kernel, $target)); + self::assertSame(2, $this->version($kernel, $target)); + + $mine->submit($this->moveForm($mine, 'mine')); + self::assertSame(302, $mine->getResponse()->getStatusCode()); + self::assertSame('mine', $this->bucket($kernel, $target)); + } + + public function testASaveOfYourCodeAdvancesTheVersionUnchecked(): void + { + $kernel = $this->bootKernel(); + $this->profile($kernel); + $target = $this->profile($kernel, null, 'target-files', StorageProfile::STATE_TARGET); + $client = $this->client($kernel); + $form = $this->moveForm($client, 'mine'); + + // Your code saves the target without a version: pages opened before are stale. + $move = $this->service($kernel, StorageMove::class); + self::assertTrue($move->saveTarget($target, null, ['bucket'], static function (StorageProfile $profile): void { + $profile->configure($profile->getProvider(), false, $profile->getEndpoint(), null, $profile->getRegion(), 'from-code', '', $profile->getAccessKey(), null, true); + })); + self::assertSame(2, $move->rowVersion($target)); + $client->submit($form); + $this->assertStale($client, 'Someone else saved the new bucket after you opened the page.'); + self::assertSame('from-code', $this->bucket($kernel, $target)); + + // A wrong version from your code throws and writes nothing. + try { + $move->saveTarget($target, null, ['bucket'], null, 1); + self::fail('A stale version was saved.'); + } catch (StaleEditException $e) { + self::assertSame((int) $target->getId(), $e->id); + self::assertSame(1, $e->expected); + } + self::assertSame(2, $move->rowVersion($target)); + self::assertNull($move->rowVersion(new StorageProfile())); + } +} diff --git a/tests/Support/deadlock-peer.php b/tests/Support/deadlock-peer.php new file mode 100644 index 0000000..2e9d493 --- /dev/null +++ b/tests/Support/deadlock-peer.php @@ -0,0 +1,49 @@ +". + */ + +$url = (string) ($argv[1] ?? ''); +$wanted = (int) ($argv[2] ?? 0); +$held = (int) ($argv[3] ?? 0); +$extra = array_map('intval', array_filter(explode(',', (string) ($argv[4] ?? '')))); +$parts = parse_url($url); +if (!is_array($parts) || !isset($parts['host'], $parts['path'])) { + throw new InvalidArgumentException('usage: deadlock-peer.php '); +} + +$pdo = new PDO( + sprintf('mysql:host=%s;port=%d;dbname=%s;charset=utf8mb4', $parts['host'], $parts['port'] ?? 3306, ltrim($parts['path'], '/')), + isset($parts['user']) ? urldecode($parts['user']) : null, + isset($parts['pass']) ? urldecode($parts['pass']) : null, + [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION], +); +$pdo->exec('SET SESSION innodb_lock_wait_timeout = 10'); +$pdo->beginTransaction(); +foreach ([$held, ...$extra] as $id) { + $pdo->prepare("UPDATE storage_kit_profile SET prefix = CONCAT('peer-', id) WHERE id = ?")->execute([$id]); +} +fwrite(\STDOUT, "ready\n"); +fflush(\STDOUT); + +// Waits on the server (not in PHP) while the test's save takes its row and starts waiting for the held one. +$pdo->exec('DO SLEEP(1.5)'); +$result = 'ok'; +try { + $pdo->prepare("UPDATE storage_kit_profile SET prefix = 'peer' WHERE id = ?")->execute([$wanted]); +} catch (PDOException $e) { + $result = (string) $e->getCode(); +} +if ($pdo->inTransaction()) { + $pdo->rollBack(); +} +fwrite(\STDOUT, 'done ' . $result . "\n"); diff --git a/tests/Unit/Concurrency/RowVersionTest.php b/tests/Unit/Concurrency/RowVersionTest.php new file mode 100644 index 0000000..32e4f5f --- /dev/null +++ b/tests/Unit/Concurrency/RowVersionTest.php @@ -0,0 +1,60 @@ + 'pdo_sqlite', 'memory' => true]); + $connection->executeStatement('CREATE TABLE profiles (id INTEGER PRIMARY KEY, row_version INTEGER NOT NULL DEFAULT 1)'); + $connection->executeStatement('INSERT INTO profiles (id) VALUES (7)'); + + return $connection; + } + + public function testAdvanceComparesAndSets(): void + { + $connection = $this->connection(); + self::assertSame(1, RowVersion::read($connection, 'profiles', 7)); + + self::assertFalse(RowVersion::advance($connection, 'profiles', 7, 2), 'a newer version than stored'); + self::assertFalse(RowVersion::advance($connection, 'profiles', 7, RowVersion::MISSING)); + self::assertTrue(RowVersion::advance($connection, 'profiles', 7, 1)); + self::assertFalse(RowVersion::advance($connection, 'profiles', 7, 1), 'the same page twice'); + self::assertSame(2, RowVersion::read($connection, 'profiles', 7)); + + // Unchecked (no page behind the write): advanced all the same. + self::assertTrue(RowVersion::advance($connection, 'profiles', 7, null)); + self::assertSame(3, RowVersion::read($connection, 'profiles', 7)); + } + + public function testAMissingRow(): void + { + $connection = $this->connection(); + self::assertSame(RowVersion::MISSING, RowVersion::read($connection, 'profiles', 8)); + self::assertFalse(RowVersion::advance($connection, 'profiles', 8, 1)); + self::assertFalse(RowVersion::advance($connection, 'profiles', 8, null)); + } + + public function testTheStaleAnswerAndANewProfile(): void + { + $stale = new StaleEditException(7, 3); + self::assertSame(7, $stale->id); + self::assertSame(3, $stale->expected); + self::assertStringNotContainsString('7', $stale->getMessage(), 'no identifier in the message'); + self::assertSame(1, (new StorageProfile())->getRowVersion()); + } +} From 3a4e934f0fbbc76b642effde9cc708f2d2a297cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Franco?= Date: Sun, 22 Nov 2026 15:19:26 +0100 Subject: [PATCH 2/3] docs(concurrency): row versions in CONCURRENCY, UPGRADING, CHANGELOG and Spec Kit --- docs/CHANGELOG.md | 79 ++++++++++++++++++---------- docs/CONCURRENCY.md | 20 +++++-- docs/UPGRADING.md | 25 +++++++++ specs/001-baseline/code-inventory.md | 18 ++++--- specs/001-baseline/spec.md | 5 ++ 5 files changed, 107 insertions(+), 40 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 36d797d..e1cb44b 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -6,71 +6,94 @@ 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 version it was built from in a hidden `rowVersion` + field (read from the database, not the identity map); the save advances it with one atomic compare-and-set inside + its existing write unit (`Concurrency\RowVersion`). 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 a `row_version` option (default null: no field) and `StorageProfile::getRowVersion()`. + +### 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. diff --git a/docs/CONCURRENCY.md b/docs/CONCURRENCY.md index d168bf5..25e7bbe 100644 --- a/docs/CONCURRENCY.md +++ b/docs/CONCURRENCY.md @@ -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 | @@ -53,6 +53,12 @@ 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 version is read from the database for each page (never from the identity map) and is never written by + the ORM (`insertable: false, updatable: false`), so it cannot go backwards. - 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. @@ -112,14 +118,20 @@ 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. - `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, diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md index ad1af5b..01a35b3 100644 --- a/docs/UPGRADING.md +++ b/docs/UPGRADING.md @@ -54,6 +54,31 @@ 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). + ## To 2.0.1 From **2.0.0**: diff --git a/specs/001-baseline/code-inventory.md b/specs/001-baseline/code-inventory.md index 53ff634..a23d65b 100644 --- a/specs/001-baseline/code-inventory.md +++ b/specs/001-baseline/code-inventory.md @@ -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 @@ -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 @@ -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 | @@ -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 | @@ -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 | @@ -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 | @@ -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) | diff --git a/specs/001-baseline/spec.md b/specs/001-baseline/spec.md index dff55fd..d9d15dc 100644 --- a/specs/001-baseline/spec.md +++ b/specs/001-baseline/spec.md @@ -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 version they were built from (hidden `rowVersion`, read from the + database); 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 From d34f8db293149722d70b98f135cbd8f55e052201 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Franco?= Date: Sun, 22 Nov 2026 19:14:09 +0100 Subject: [PATCH 3/3] fix(concurrency): tie the bucket form's row version to its row (audit ZK-M1) The hidden rowVersion field now carries :, and submittedRowVersion($form, $profile) returns MISSING when the token names another row, so a page opened before its bucket was replaced (target discarded and saved again, or a Move switch) can never overwrite the new row at an equal version. The version comes from the same load as the values (ZK-L1). Docs say host ORM writes do not advance it (ZK-I3). --- docs/CHANGELOG.md | 13 +++- docs/CONCURRENCY.md | 15 +++- docs/UPGRADING.md | 6 +- specs/001-baseline/spec.md | 4 +- src/Controller/StorageMoveController.php | 8 +- src/Controller/StorageSettingsController.php | 18 ++--- src/Form/StorageProfileType.php | 36 ++++++--- .../Integration/Functional/StaleEditTest.php | 73 ++++++++++++++++++- 8 files changed, 133 insertions(+), 40 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index e1cb44b..c8655dc 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -79,15 +79,20 @@ All notable changes to this project are documented here. The format follows - **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 version it was built from in a hidden `rowVersion` - field (read from the database, not the identity map); the save advances it with one atomic compare-and-set inside - its existing write unit (`Concurrency\RowVersion`). A page that is no longer current writes nothing and answers 409 + [UPGRADING](UPGRADING.md#unreleased)). Each form carries the row and the version it was built from in a hidden + `rowVersion` field (`:`, 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 a `row_version` option (default null: no field) and `StorageProfile::getRowVersion()`. + `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 diff --git a/docs/CONCURRENCY.md b/docs/CONCURRENCY.md index 25e7bbe..2332b1e 100644 --- a/docs/CONCURRENCY.md +++ b/docs/CONCURRENCY.md @@ -57,8 +57,14 @@ A lock conflict, deadlock, lock wait timeout or serialization failure (MySQL / M 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 version is read from the database for each page (never from the identity map) and is never written by - the ORM (`insertable: false, updatable: false`), so it cannot go backwards. + stale. The hidden field carries `:`, 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. @@ -125,7 +131,10 @@ read the code must list `X-Conflict-Code` in `Access-Control-Expose-Headers` (th 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. + 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. diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md index 01a35b3..c5044da 100644 --- a/docs/UPGRADING.md +++ b/docs/UPGRADING.md @@ -77,7 +77,11 @@ What changes for you: 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). + 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 `:`** (`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 diff --git a/specs/001-baseline/spec.md b/specs/001-baseline/spec.md index d9d15dc..e19ace2 100644 --- a/specs/001-baseline/spec.md +++ b/specs/001-baseline/spec.md @@ -237,8 +237,8 @@ becomes the settings-backed active profile; existing files keep downloading. 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 version they were built from (hidden `rowVersion`, read from the - database); the save advances it with one atomic compare-and-set inside its unit, and a page that is no longer + Storage and Move bucket forms carry the row and the version they were built from (hidden `rowVersion` = + `:`, 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. diff --git a/src/Controller/StorageMoveController.php b/src/Controller/StorageMoveController.php index bb44b3c..154d070 100644 --- a/src/Controller/StorageMoveController.php +++ b/src/Controller/StorageMoveController.php @@ -160,7 +160,7 @@ private function page(Request $request, ?string $scope): Response } try { // 2.1 (REQ-RUNTIME-003 rule 4): a saved target is written only with the row version of this page. - $saved = $this->move->saveTarget($target, $this->guard->user(), $fields, $configure, $target->getId() === null ? null : StorageProfileType::submittedRowVersion($form)); + $saved = $this->move->saveTarget($target, $this->guard->user(), $fields, $configure, $target->getId() === null ? null : StorageProfileType::submittedRowVersion($form, $target)); $this->addFlash($saved ? 'success' : 'error', $this->trans($saved ? 'move.flash.saved' : 'move.flash.unavailable')); return $this->redirectToRoute(...self::route($scope)); @@ -345,8 +345,10 @@ private function form(StorageProfile $target, ?string $scope, bool $running): Fo 'has_secret' => $target->hasSecret(), 'restricted' => $this->resolver->isRestricted($scope), 'with_enabled' => false, - // 2.1: the version of a saved target, read from the database (none for a target not saved yet). - 'row_version' => $this->move->rowVersion($target), + // 2.1: the row and its version, from the same load as the values (audit ZK-L1; none for a target not saved + // yet). + 'row_id' => $target->getId(), + 'row_version' => $target->getId() === null ? null : $target->getRowVersion(), ]); } diff --git a/src/Controller/StorageSettingsController.php b/src/Controller/StorageSettingsController.php index fe64a97..fd0d1af 100644 --- a/src/Controller/StorageSettingsController.php +++ b/src/Controller/StorageSettingsController.php @@ -219,7 +219,7 @@ private function edit(Request $request, ?string $scope): Response */ private function save(FormInterface $form, StorageProfile $profile, ?string $scope): bool { - $expected = StorageProfileType::submittedRowVersion($form); + $expected = StorageProfileType::submittedRowVersion($form, $profile); /** @var array{provider: string|null, enabled: bool|null, endpoint: string|null, public_endpoint: string|null, region: string|null, bucket: string|null, prefix: string|null, access_key: string|null, secret: string|null, path_style: bool|null} $data */ $data = $form->getData(); // @igor-ignore - The closure runs synchronously inside the unit of work; it is not stored on the service. @@ -327,21 +327,13 @@ private function form(StorageProfile $profile, ?string $scope): FormInterface 'csrf_token_id' => self::formTokenId($scope), 'has_secret' => $profile->hasSecret(), 'restricted' => $this->resolver->isRestricted($scope), - // 2.1: the version of the stored bucket, read from the database (none for a bucket not saved yet). - 'row_version' => $this->rowVersion($this->entityManager, $profile), + // 2.1: the row and its version, from the same load as the values (audit ZK-L1; none for a bucket not saved + // yet). The bundle's private manager is fresh for each request. + 'row_id' => $profile->getId(), + 'row_version' => $profile->getId() === null ? null : $profile->getRowVersion(), ]); } - /** - * 2.1: the current row version of a saved bucket, read from the database; null for a bucket not saved yet. - */ - private function rowVersion(StorageEntityManager $entityManager, StorageProfile $profile): ?int - { - $id = $profile->getId(); - - return $id === null ? null : RowVersion::read($entityManager->connection(), $entityManager->table(StorageProfile::class), $id); - } - private function scopeOrNotFound(string $scope): string { if (!$this->resolver->scopesEnabled() || !$this->guard->isScopeGranted($scope)) { diff --git a/src/Form/StorageProfileType.php b/src/Form/StorageProfileType.php index 25e72f7..e1061e1 100644 --- a/src/Form/StorageProfileType.php +++ b/src/Form/StorageProfileType.php @@ -7,6 +7,7 @@ use Nowo\FormKitBundle\Attribute\FormKitConfig; use Nowo\FormKitBundle\Form\FormOptionsTrait; use Nowo\StorageKitBundle\Concurrency\RowVersion; +use Nowo\StorageKitBundle\Entity\StorageProfile; use Nowo\StorageKitBundle\NowoStorageKitBundle; use Nowo\StorageKitBundle\Security\EndpointGuard; use Nowo\StorageKitBundle\Storage\S3Settings; @@ -30,11 +31,10 @@ use Symfony\Component\Validator\Context\ExecutionContextInterface; use function assert; -use function ctype_digit; use function is_array; use function is_int; use function is_string; -use function strlen; +use function preg_match; use function trim; /** @@ -59,9 +59,15 @@ final class StorageProfileType extends AbstractType { use FormOptionsTrait; - /** 2.1: name of the hidden row-version field (option `row_version`; rendered with the other hidden fields). */ + /** + * 2.1: name of the hidden row-version field (options `row_id` + `row_version`; rendered with the other hidden + * fields). Its value is `:`, so a page can only ever save the row it was built from. + */ public const ROW_VERSION = 'rowVersion'; + /** 2.1 (audit ZK-M1): the token `:`, each a positive whole number of at most 18 digits. */ + private const TOKEN_PATTERN = '/^([1-9][0-9]{0,17}):([1-9][0-9]{0,17})$/'; + /** * The SSRF guard checks the server-side endpoint of restricted profiles. */ @@ -179,10 +185,11 @@ public function buildForm(FormBuilderInterface $builder, array $options): void 'disabled' => $readOnly, 'row_attr' => $endpointOnly, ]); - if (is_int($options['row_version'])) { - // 2.1 (REQ-RUNTIME-003 rule 4): the row version the page was built from, unmapped; the save refuses the - // form when the bucket was saved by someone else since (RowVersion, StaleEditException). - $builder->add(self::ROW_VERSION, HiddenType::class, ['mapped' => false, 'required' => false, 'label' => false, 'data' => (string) $options['row_version']]); + if (is_int($options['row_id']) && is_int($options['row_version'])) { + // 2.1 (REQ-RUNTIME-003 rule 4): the row and the version the page was built from, unmapped; the save refuses + // the form when it is another row (a bucket replaced meanwhile, audit ZK-M1) or when the bucket was saved + // by someone else since (RowVersion, StaleEditException). + $builder->add(self::ROW_VERSION, HiddenType::class, ['mapped' => false, 'required' => false, 'label' => false, 'data' => $options['row_id'] . ':' . $options['row_version']]); } // The submitted provider decides which fields count (InstanceSettings 1.3 rules): the endpoint fields hidden // for Amazon S3 get their current values back, so they are neither validated nor changed. @@ -220,12 +227,14 @@ public function configureOptions(OptionsResolver $resolver): void 'restricted' => true, 'with_enabled' => true, 'row_version' => null, + 'row_id' => null, ]); $resolver->setAllowedTypes('read_only', 'bool'); $resolver->setAllowedTypes('has_secret', 'bool'); $resolver->setAllowedTypes('restricted', 'bool'); $resolver->setAllowedTypes('with_enabled', 'bool'); $resolver->setAllowedTypes('row_version', ['null', 'int']); + $resolver->setAllowedTypes('row_id', ['null', 'int']); } /** @@ -241,15 +250,20 @@ public function getBlockPrefix(): string */ /** - * 2.1: the row version a submitted form carries, or {@see RowVersion::MISSING} when the field is absent or not a - * whole number (never equal to a stored version, so such a save is refused as stale). + * 2.1: the row version a submitted form carries for `$profile`, or {@see RowVersion::MISSING} when the field is + * absent or malformed, or when the token was issued for another row (audit ZK-M1: a bucket replaced since the page + * was opened, whose version may be equal). MISSING never equals a stored version, so such a save is refused as stale. * * @param FormInterface $form + * @param StorageProfile $profile the row the save is about to write */ - public static function submittedRowVersion(FormInterface $form): int + public static function submittedRowVersion(FormInterface $form, StorageProfile $profile): int { $token = $form->has(self::ROW_VERSION) ? $form->get(self::ROW_VERSION)->getData() : null; + if (!is_string($token) || preg_match(self::TOKEN_PATTERN, $token, $match) !== 1) { + return RowVersion::MISSING; + } - return is_string($token) && $token !== '' && strlen($token) <= 18 && ctype_digit($token) ? (int) $token : RowVersion::MISSING; + return (int) $match[1] === $profile->getId() ? (int) $match[2] : RowVersion::MISSING; } } diff --git a/tests/Integration/Functional/StaleEditTest.php b/tests/Integration/Functional/StaleEditTest.php index 4f5a171..5bac80d 100644 --- a/tests/Integration/Functional/StaleEditTest.php +++ b/tests/Integration/Functional/StaleEditTest.php @@ -80,7 +80,7 @@ public function testTheStoragePageCarriesTheVersionAndRefusesAStalePage(): void // Both admins open the page at version 1. $mineForm = $this->settingsForm($mine, 'mine'); $theirsForm = $this->settingsForm($theirs, 'theirs'); - self::assertSame('1', $mineForm->getValues()['storage_profile[rowVersion]'] ?? null); + self::assertSame($profile->getId() . ':1', $mineForm->getValues()['storage_profile[rowVersion]'] ?? null); // The other admin saves first: the version advances by one. $theirs->submit($theirsForm); @@ -108,7 +108,8 @@ public function testAMissingOrForgedVersionIsStale(): void $profile = $this->profile($kernel, 'acme'); $client = $this->client($kernel, 'scopeadmin'); - foreach (['', 'abc', '-1', '1e3', '99999999999999999999', null] as $token) { + $id = (string) $profile->getId(); + foreach (['', 'abc', '-1', '1e3', '1', $id, $id . ':', ':1', $id . ':0', $id . ':01', $id . ':1:1', '0' . $id . ':1', $id . ':99999999999999999999', null] as $token) { $form = $this->settingsForm($client, 'forged'); $values = $form->getPhpValues(); if ($token === null) { @@ -146,7 +147,7 @@ public function testTheMovePageRefusesAStaleTarget(): void $theirs = $this->client($kernel); $mineForm = $this->moveForm($mine, 'mine'); - self::assertSame('1', $mineForm->getValues()['storage_target[rowVersion]'] ?? null); + self::assertSame($target->getId() . ':1', $mineForm->getValues()['storage_target[rowVersion]'] ?? null); $theirs->submit($this->moveForm($theirs, 'theirs')); self::assertSame(302, $theirs->getResponse()->getStatusCode()); @@ -160,6 +161,72 @@ public function testTheMovePageRefusesAStaleTarget(): void self::assertSame('mine', $this->bucket($kernel, $target)); } + /** + * Audit ZK-M1 (a): a Move page opened on target T1; another admin discards T1 and saves a new target T2, which + * starts at the same version (1). The old page names T1, so its save is stale and T2 is unchanged. + */ + public function testAMovePageOfADiscardedTargetIsStaleForTheNewTarget(): void + { + $kernel = $this->bootKernel(); + $this->profile($kernel); + $first = $this->profile($kernel, null, 'first-target', StorageProfile::STATE_TARGET); + $mine = $this->client($kernel); + $form = $this->moveForm($mine, 'mine'); + + $move = $this->service($kernel, StorageMove::class); + self::assertTrue($move->discard($first, null)); + $second = $this->profile($kernel, null, 'theirs', StorageProfile::STATE_TARGET); + self::assertSame(1, $this->version($kernel, $second), 'the same version as the page'); + + $mine->submit($form); + $this->assertStale($mine, 'Someone else saved the new bucket after you opened the page.'); + self::assertSame('theirs', $this->bucket($kernel, $second)); + self::assertSame(1, $this->version($kernel, $second)); + } + + /** + * Audit ZK-M1 (b): a Storage page opened on the active bucket P; a switch makes another row active, at the same + * version. The old page names P, so its save is stale and the new active bucket is unchanged. + */ + public function testAStoragePageOfTheBucketBeforeASwitchIsStaleForTheNewActiveBucket(): void + { + $kernel = $this->bootKernel(); + $before = $this->profile($kernel, 'acme', 'before'); + $mine = $this->client($kernel, 'scopeadmin'); + $form = $this->settingsForm($mine, 'mine'); + + // The switch: the former bucket retires and another row becomes the active one (version 1, like the page). + $this->storage($kernel)->connection()->executeStatement('UPDATE storage_kit_profile SET state = ? WHERE id = ?', [StorageProfile::STATE_RETIRED, $before->getId()]); + $after = $this->profile($kernel, 'acme', 'after'); + self::assertSame($this->version($kernel, $before), $this->version($kernel, $after), 'equal versions'); + + $mine->submit($form); + $this->assertStale($mine, 'Someone else saved this bucket after you opened the page.'); + self::assertSame('after', $this->bucket($kernel, $after)); + self::assertSame('before', $this->bucket($kernel, $before)); + self::assertSame(1, $this->version($kernel, $after)); + } + + /** + * Audit ZK-M1 (c): a token that names another row (with that row's current version) is stale. + */ + public function testATokenOfAnotherRowIsStale(): void + { + $kernel = $this->bootKernel(); + $profile = $this->profile($kernel, 'acme'); + $other = $this->profile($kernel, 'other', 'other-files'); + $client = $this->client($kernel, 'scopeadmin'); + + $values = $this->settingsForm($client, 'forged')->getPhpValues(); + $values['storage_profile']['rowVersion'] = $other->getId() . ':' . $this->version($kernel, $other); + $client->request('POST', '/storage/scopes/acme', $values); + + $this->assertStale($client, 'Someone else saved this bucket after you opened the page.'); + self::assertSame('files', $this->bucket($kernel, $profile)); + self::assertSame(1, $this->version($kernel, $profile)); + self::assertSame('other-files', $this->bucket($kernel, $other)); + } + public function testASaveOfYourCodeAdvancesTheVersionUnchecked(): void { $kernel = $this->bootKernel();