Retry stale manual runtime refreshes

Author: fabpot

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## 0.17.0 (2026-08-28)
 
+- Retry manual runtime refreshes invalidated by concurrent file changes
 - Keep generic installation examples unchanged during releases
 - Integrate headless diagnostics with Symfony CLI project-aware PHP defaults
 - Find Twig function and filter usages from PHP declarations

src/Feature/Configuration/ProjectConfigurationValidationSnapshotLoader.php

@@ -2,7 +2,6 @@
 
 namespace Symfony\Lsp\Feature\Configuration;
 
-use Amp\CancelledException;
 use Symfony\Lsp\Project\Project;
 
 final class ProjectConfigurationValidationSnapshotLoader
@@ -21,7 +20,7 @@ public function load(Project $project, array $snapshot): void
     {
         $generation = $snapshot['configurationGeneration'] ?? 0;
         if (!\is_int($generation) || $generation !== $this->validations->generation($project)) {
-            throw new CancelledException();
+            throw new StaleConfigurationValidationSnapshotException();
         }
         $validation = $snapshot['configurationValidation'] ?? null;
         $projectMetadata = $snapshot['project'] ?? null;

src/Feature/Configuration/StaleConfigurationValidationSnapshotException.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Symfony\Lsp\Feature\Configuration;
+
+use Amp\CancelledException;
+
+final class StaleConfigurationValidationSnapshotException extends CancelledException
+{
+}

src/Index/IndexCommandHandler.php

@@ -3,6 +3,7 @@
 namespace Symfony\Lsp\Index;
 
 use Amp\Cancellation;
+use Symfony\Lsp\Feature\Configuration\StaleConfigurationValidationSnapshotException;
 use Symfony\Lsp\Project\Project;
 use Symfony\Lsp\Project\ProjectRegistry;
 use Symfony\Lsp\Project\TrustStatus;
@@ -50,15 +51,15 @@ public function execute(array $params, ?Cancellation $cancellation = null): ?arr
                 $cancellation?->throwIfRequested();
                 $this->configuration->setEnvironment($project, $environment);
                 if ($this->configuration->runtimeIndexing($project) && TrustStatus::Trusted === $this->workspaceTrust->status($project)) {
-                    $this->runtimeInitializer->initialize($project, new RuntimeRefreshPlan(RuntimeRefreshMode::Clear), $cancellation);
+                    $this->initializeRuntime($project, new RuntimeRefreshPlan(RuntimeRefreshMode::Clear), $cancellation);
                 }
             }
         } elseif (self::REFRESH_COMMAND === $command) {
             foreach ($projects as $project) {
                 $cancellation?->throwIfRequested();
                 $this->sourceScanner->refreshProject($project, $cancellation);
                 if ($this->configuration->runtimeIndexing($project) && TrustStatus::Trusted === $this->workspaceTrust->status($project)) {
-                    $this->runtimeInitializer->initialize($project, cancellation: $cancellation);
+                    $this->initializeRuntime($project, cancellation: $cancellation);
                 }
             }
         }
@@ -71,6 +72,22 @@ public function execute(array $params, ?Cancellation $cancellation = null): ?arr
         ], $projects);
     }
 
+    private function initializeRuntime(Project $project, ?RuntimeRefreshPlan $plan = null, ?Cancellation $cancellation = null): void
+    {
+        while (true) {
+            try {
+                $this->runtimeInitializer->initialize($project, $plan, $cancellation);
+
+                return;
+            } catch (StaleConfigurationValidationSnapshotException $error) {
+                $cancellation?->throwIfRequested();
+                if (!$this->projects->contains($project)) {
+                    throw $error;
+                }
+            }
+        }
+    }
+
     /** @param array<array-key, mixed> $params */
     private function environment(array $params): ?string
     {

tests/Feature/Configuration/ConfigurationValidationRegistryTest.php

@@ -2,12 +2,12 @@
 
 namespace Symfony\Lsp\Tests\Feature\Configuration;
 
-use Amp\CancelledException;
 use PHPUnit\Framework\TestCase;
 use Symfony\Lsp\Feature\Configuration\ConfigurationValidationException;
 use Symfony\Lsp\Feature\Configuration\ConfigurationValidationRegistry;
 use Symfony\Lsp\Feature\Configuration\ConfigurationValidationResult;
 use Symfony\Lsp\Feature\Configuration\ProjectConfigurationValidationSnapshotLoader;
+use Symfony\Lsp\Feature\Configuration\StaleConfigurationValidationSnapshotException;
 use Symfony\Lsp\Project\Project;
 
 final class ConfigurationValidationRegistryTest extends TestCase
@@ -69,7 +69,7 @@ public function testRejectsResultsFromAnOlderConfigurationGeneration(): void
                 'configurationValidation' => ['status' => 'valid'],
             ]);
             self::fail('The stale configuration validation was accepted.');
-        } catch (CancelledException) {
+        } catch (StaleConfigurationValidationSnapshotException) {
         }
 
         self::assertSame(ConfigurationValidationResult::PENDING, $registry->result($project)->state);

tests/Index/IndexCommandHandlerTest.php

@@ -6,6 +6,7 @@
 use Amp\Sync\LocalKeyedMutex;
 use PHPUnit\Framework\TestCase;
 use Symfony\Lsp\Document\DocumentStore;
+use Symfony\Lsp\Feature\Configuration\StaleConfigurationValidationSnapshotException;
 use Symfony\Lsp\Index\ApplicationSourceScanner;
 use Symfony\Lsp\Index\IndexCommandHandler;
 use Symfony\Lsp\Index\PhpRuntimeStructureHasher;
@@ -113,6 +114,50 @@ public function testManuallyRefreshesSourceAndTrustedRuntimeIndexes(): void
         ]);
         self::assertFalse($untrusted[0]['trusted'] ?? null);
     }
+
+    public function testRetriesManualRuntimeRefreshAfterAConfigurationChangeInvalidatesTheSnapshot(): void
+    {
+        $projects = new ProjectRegistry();
+        $projects->replace([$project = new Project(
+            $this->temporaryDirectory,
+            'file://'.$this->temporaryDirectory,
+            '^8.0',
+        )]);
+        $statuses = new ProjectIndexStatusRegistry();
+        $sourceScanner = new ApplicationSourceScanner(
+            $projects,
+            new DocumentStore(),
+            $statuses,
+            new NullProgressReporter(),
+            new InMemorySourceIndexStore(),
+            new SourceIndexPayloadCodec(),
+            new PhpRuntimeStructureHasher(),
+            new UriToPathConverter(),
+            new SourceFileEnumerator(new GitignoreMatcher(), new ProjectFileScopeRegistry()),
+            new LocalKeyedMutex(),
+            new ServerLogger(null, new SensitiveDataRedactor()),
+            [],
+        );
+        $runtime = new RecordingRuntimeInitializer(1);
+        $workspaceTrust = new WorkspaceTrust();
+        $workspaceTrust->set($project, TrustStatus::Trusted);
+        $handler = new IndexCommandHandler(
+            $projects,
+            $workspaceTrust,
+            $sourceScanner,
+            new StatusRuntimeInitializer($runtime, $statuses, $projects),
+            $statuses,
+            new RuntimeConfiguration(),
+        );
+
+        $result = $handler->execute([
+            'command' => IndexCommandHandler::REFRESH_COMMAND,
+            'arguments' => [$project->rootUri()],
+        ]);
+
+        self::assertSame([$this->temporaryDirectory, $this->temporaryDirectory], $runtime->projects);
+        self::assertSame('ready', $result[0]['runtime']['state'] ?? null);
+    }
 }
 
 final class RecordingRuntimeInitializer implements RuntimeInitializerInterface
@@ -123,9 +168,18 @@ final class RecordingRuntimeInitializer implements RuntimeInitializerInterface
     /** @var list<RuntimeRefreshPlan> */
     public array $plans = [];
 
+    public function __construct(private int $staleSnapshots = 0)
+    {
+    }
+
     public function initialize(Project $project, ?RuntimeRefreshPlan $plan = null, ?Cancellation $cancellation = null): void
     {
         $this->projects[] = $project->rootPath();
         $this->plans[] = $plan ?? new RuntimeRefreshPlan();
+        if (0 < $this->staleSnapshots) {
+            --$this->staleSnapshots;
+
+            throw new StaleConfigurationValidationSnapshotException();
+        }
     }
 }