Separate provisioning from backfilling

Author: stevebauman

README.md

@@ -145,7 +145,7 @@ First, create a stable alias for the index in a migration:
 Index::putAlias('posts', 'posts_search');
 ```
 
-Start a deployment with the latest mapping and settings:
+Provision a candidate with the latest mapping and settings:
 
 ```php
 use DirectoryTree\OpenSearchAdapter\Indices\Mapping;
@@ -154,7 +154,7 @@ use DirectoryTree\OpenSearchMigrations\Deployer;
 
 $deployer = app(Deployer::class);
 
-$deployment = $deployer->start(
+$deployment = $deployer->provision(
     name: 'posts',
     alias: 'posts_search',
     configure: function (Mapping $mapping, Settings $settings) {
@@ -164,15 +164,18 @@ $deployment = $deployer->start(
 );
 ```
 
-The returned deployment exposes the physical candidate index for backfilling:
+The returned deployment exposes the physical candidate index for inspection while writes continue targeting only the active alias:
 
 ```php
 $deployment->candidateIndex;
+$deployment->writeIndexes(); // ['posts_search']
 ```
 
-While backfilling, send live writes and deletions to every deployment write index:
+Once the candidate has been inspected, begin backfilling before importing historical documents. This enables concurrent writes and deletions to the candidate:
 
 ```php
+$deployment = $deployer->beginBackfill('posts');
+
 $deployment->writeIndexes();
 ```
 

src/Deployer.php

@@ -25,9 +25,9 @@ public function __construct(
     ) {}
 
     /**
-     * Create a candidate index and begin a deployment.
+     * Provision a candidate index without enabling concurrent writes.
      */
-    public function start(
+    public function provision(
         string $name,
         string $alias,
         ?callable $configure = null,
@@ -48,7 +48,7 @@ public function start(
         $this->indexes->create($candidate, $configure);
 
         return $this->deployments->save(
-            Deployment::backfilling(
+            Deployment::provisioned(
                 name: $name,
                 alias: $prefixedAlias,
                 activeIndex: $activeIndex,
@@ -58,15 +58,31 @@ public function start(
         );
     }
 
+    /**
+     * Begin backfilling a provisioned candidate index.
+     */
+    public function beginBackfill(string $name): Deployment
+    {
+        $deployment = $this->deployments->findOrFail($name);
+
+        if ($deployment->status !== DeploymentStatus::Provisioned || ! $deployment->candidateIndex) {
+            throw new DeploymentException('The candidate index must be provisioned before backfilling.');
+        }
+
+        return $this->deployments->save(
+            $deployment->beginBackfill()
+        );
+    }
+
     /**
      * Mark a candidate index as ready for cutover.
      */
     public function markReady(string $name): Deployment
     {
         $deployment = $this->deployments->findOrFail($name);
 
-        if (! $deployment->candidateIndex) {
-            throw new DeploymentException('The deployment does not have a candidate index to mark as ready.');
+        if ($deployment->status !== DeploymentStatus::Backfilling || ! $deployment->candidateIndex) {
+            throw new DeploymentException('The candidate index must be backfilling before it can be marked as ready.');
         }
 
         return $this->deployments->save(

src/Deployments/Deployment.php

@@ -9,9 +9,9 @@
 class Deployment
 {
     /**
-     * Create a deployment that is ready to be backfilled.
+     * Create a deployment with a provisioned candidate index.
      */
-    public static function backfilling(
+    public static function provisioned(
         string $name,
         string $alias,
         string $activeIndex,
@@ -27,7 +27,7 @@ public static function backfilling(
             activeIndex: $activeIndex,
             candidateIndex: $candidateIndex,
             previousIndex: null,
-            status: DeploymentStatus::Backfilling,
+            status: DeploymentStatus::Provisioned,
             readyAt: null,
             cutoverAt: null,
             createdAt: $now,
@@ -72,6 +72,21 @@ protected function __construct(
         public CarbonImmutable $updatedAt,
     ) {}
 
+    /**
+     * Begin backfilling the candidate index.
+     */
+    public function beginBackfill(): static
+    {
+        return $this->transition(
+            activeIndex: $this->activeIndex,
+            candidateIndex: $this->candidateIndex,
+            previousIndex: $this->previousIndex,
+            status: DeploymentStatus::Backfilling,
+            readyAt: $this->readyAt,
+            cutoverAt: $this->cutoverAt,
+        );
+    }
+
     /**
      * Mark the candidate index as ready for cutover.
      */
@@ -184,9 +199,14 @@ public function retirePrevious(): static
      */
     public function writeIndexes(): array
     {
+        $candidate = in_array($this->status, [
+            DeploymentStatus::Backfilling,
+            DeploymentStatus::Ready,
+        ], true) ? $this->candidateIndex : null;
+
         return array_values(array_unique(array_filter([
             $this->alias,
-            $this->candidateIndex,
+            $candidate,
             $this->previousIndex,
         ])));
     }

src/Deployments/DeploymentStatus.php

@@ -6,5 +6,6 @@ enum DeploymentStatus: string
 {
     case Active = 'active';
     case Backfilling = 'backfilling';
+    case Provisioned = 'provisioned';
     case Ready = 'ready';
 }

tests/Integration/Console/FreshCommandTest.php

@@ -18,7 +18,7 @@
     $index = Mockery::mock(IndexManagerInterface::class);
     $deployments = app(DeploymentRepository::class);
     $deployments->prepare();
-    $deployments->save(Deployment::backfilling(
+    $deployments->save(Deployment::provisioned(
         name: 'posts',
         alias: 'posts_search',
         activeIndex: 'posts_blue',

tests/Integration/Console/RefreshCommandTest.php

@@ -29,7 +29,7 @@
 it('refuses to refresh while managed deployments exist', function (): void {
     $deployments = app(DeploymentRepository::class);
     $deployments->prepare();
-    $deployments->save(Deployment::backfilling(
+    $deployments->save(Deployment::provisioned(
         name: 'posts',
         alias: 'posts_search',
         activeIndex: 'posts_blue',

tests/Integration/Console/ResetCommandTest.php

@@ -28,7 +28,7 @@
 it('refuses to reset while managed deployments exist', function (): void {
     $deployments = app(DeploymentRepository::class);
     $deployments->prepare();
-    $deployments->save(Deployment::backfilling(
+    $deployments->save(Deployment::provisioned(
         name: 'posts',
         alias: 'posts_search',
         activeIndex: 'posts_blue',

tests/Integration/Deployments/DeployerTest.php

@@ -19,7 +19,7 @@
 
 uses(RefreshDatabase::class);
 
-it('creates a versioned candidate and records deployment state', function (): void {
+it('provisions a versioned candidate before enabling concurrent writes', function (): void {
     Date::setTestNow('2026-07-12 12:34:56.789');
     config()->set('opensearch-migrations.index_name_prefix', 'test_');
     config()->set('opensearch-migrations.alias_name_prefix', 'test_');
@@ -43,7 +43,7 @@
 
     $manager = new Deployer($repository, $indexes, $adapterIndexes, $openSearch);
 
-    $deployment = $manager->start('posts', 'posts_search', function (Mapping $mapping, Settings $settings): void {
+    $deployment = $manager->provision('posts', 'posts_search', function (Mapping $mapping, Settings $settings): void {
         $mapping->text('title');
         $settings->index(['number_of_replicas' => 0]);
     });
@@ -58,13 +58,22 @@
         ->and($deployment->alias)->toBe('test_posts_search')
         ->and($deployment->activeIndex)->toBe('test_posts_blue')
         ->and($deployment->candidateIndex)->toBe('test_posts_v20260712123456789')
-        ->and($deployment->status)->toBe(DeploymentStatus::Backfilling);
+        ->and($deployment->status)->toBe(DeploymentStatus::Provisioned)
+        ->and($deployment->writeIndexes())->toBe(['test_posts_search']);
+
+    $deployment = $manager->beginBackfill('posts');
+
+    expect($deployment->status)->toBe(DeploymentStatus::Backfilling)
+        ->and($deployment->writeIndexes())->toBe([
+            'test_posts_search',
+            'test_posts_v20260712123456789',
+        ]);
 });
 
 it('marks a candidate ready and cuts over its alias atomically', function (): void {
     $repository = app(DeploymentRepository::class);
     $repository->prepare();
-    $repository->save(Deployment::backfilling(
+    $repository->save(Deployment::provisioned(
         name: 'posts',
         alias: 'posts_search',
         activeIndex: 'posts_blue',
@@ -98,6 +107,7 @@
 
     $manager = new Deployer($repository, $indexes, $adapterIndexes, $openSearch);
 
+    expect($manager->beginBackfill('posts')->status)->toBe(DeploymentStatus::Backfilling);
     expect($manager->markReady('posts')->status)->toBe(DeploymentStatus::Ready);
 
     $deployment = $manager->cutover('posts');
@@ -108,16 +118,37 @@
         ->and($deployment->status)->toBe(DeploymentStatus::Active);
 });
 
+it('does not mark a provisioned candidate ready before backfilling begins', function (): void {
+    $repository = app(DeploymentRepository::class);
+    $repository->prepare();
+    $repository->save(Deployment::provisioned(
+        name: 'posts',
+        alias: 'posts_search',
+        activeIndex: 'posts_blue',
+        candidateIndex: 'posts_green',
+        now: Date::now(),
+    ));
+
+    $adapterIndexes = new FakeIndexManager;
+    $indexes = new IndexManagerAdapter($adapterIndexes);
+    $openSearch = mock(OpenSearchManager::class);
+
+    $deployer = new Deployer($repository, $indexes, $adapterIndexes, $openSearch);
+
+    expect(fn () => $deployer->markReady('posts'))
+        ->toThrow(DeploymentException::class, 'The candidate index must be backfilling before it can be marked as ready.');
+});
+
 it('finishes a cutover when the alias was already moved', function (): void {
     $repository = app(DeploymentRepository::class);
     $repository->prepare();
-    $repository->save(Deployment::backfilling(
+    $repository->save(Deployment::provisioned(
         name: 'posts',
         alias: 'posts_search',
         activeIndex: 'posts_blue',
         candidateIndex: 'posts_green',
         now: Date::now(),
-    )->markReady(Date::now())->stageCutover());
+    )->beginBackfill()->markReady(Date::now())->stageCutover());
 
     $adapterIndexes = new FakeIndexManager;
     $indexes = new IndexManagerAdapter($adapterIndexes);
@@ -144,13 +175,13 @@
 it('rolls a deployment back atomically', function (): void {
     $repository = app(DeploymentRepository::class);
     $repository->prepare();
-    $repository->save(Deployment::backfilling(
+    $repository->save(Deployment::provisioned(
         name: 'posts',
         alias: 'posts_search',
         activeIndex: 'posts_blue',
         candidateIndex: 'posts_green',
         now: Date::now(),
-    )->markReady(Date::now())->stageCutover()->completeCutover(Date::now()));
+    )->beginBackfill()->markReady(Date::now())->stageCutover()->completeCutover(Date::now()));
 
     $adapterIndexes = new FakeIndexManager;
     $indexes = new IndexManagerAdapter($adapterIndexes);
@@ -177,7 +208,7 @@
 it('cancels and deletes a candidate index', function (): void {
     $repository = app(DeploymentRepository::class);
     $repository->prepare();
-    $repository->save(Deployment::backfilling(
+    $repository->save(Deployment::provisioned(
         name: 'posts',
         alias: 'posts_search',
         activeIndex: 'posts_blue',
@@ -211,13 +242,13 @@
 it('retires the previous physical index', function (): void {
     $repository = app(DeploymentRepository::class);
     $repository->prepare();
-    $repository->save(Deployment::backfilling(
+    $repository->save(Deployment::provisioned(
         name: 'posts',
         alias: 'posts_search',
         activeIndex: 'posts_blue',
         candidateIndex: 'posts_green',
         now: Date::now(),
-    )->markReady(Date::now())->stageCutover()->completeCutover(Date::now()));
+    )->beginBackfill()->markReady(Date::now())->stageCutover()->completeCutover(Date::now()));
 
     $adapterIndexes = new FakeIndexManager;
     $indexes = new IndexManagerAdapter($adapterIndexes);
@@ -234,13 +265,13 @@
 it('restores deployment state when retirement fails', function (): void {
     $repository = app(DeploymentRepository::class);
     $repository->prepare();
-    $repository->save(Deployment::backfilling(
+    $repository->save(Deployment::provisioned(
         name: 'posts',
         alias: 'posts_search',
         activeIndex: 'posts_blue',
         candidateIndex: 'posts_green',
         now: Date::now(),
-    )->markReady(Date::now())->stageCutover()->completeCutover(Date::now()));
+    )->beginBackfill()->markReady(Date::now())->stageCutover()->completeCutover(Date::now()));
 
     $adapterIndexes = mock(AdapterIndexManagerInterface::class);
     $adapterIndexes->shouldReceive('delete')->once()->andThrow(new DeploymentException('Delete failed.'));

tests/Integration/Repositories/DeploymentRepositoryTest.php

@@ -38,7 +38,7 @@
     $repository = app(DeploymentRepository::class);
     $repository->prepare();
 
-    $deployment = $repository->save(Deployment::backfilling(
+    $deployment = $repository->save(Deployment::provisioned(
         name: 'posts',
         alias: 'posts_search',
         activeIndex: 'posts_blue',
@@ -51,7 +51,7 @@
         ->and($deployment->activeIndex)->toBe('posts_blue')
         ->and($deployment->candidateIndex)->toBe('posts_green')
         ->and($deployment->previousIndex)->toBeNull()
-        ->and($deployment->status)->toBe(DeploymentStatus::Backfilling)
+        ->and($deployment->status)->toBe(DeploymentStatus::Provisioned)
         ->and($deployment->createdAt->toDateTimeString())->toBe('2026-07-12 12:00:00');
 });
 
@@ -61,7 +61,7 @@
     $repository = app(DeploymentRepository::class);
     $repository->prepare();
 
-    $repository->save(Deployment::backfilling(
+    $repository->save(Deployment::provisioned(
         name: 'posts',
         alias: 'posts_search',
         activeIndex: 'posts_blue',
@@ -72,7 +72,7 @@
     Date::setTestNow('2026-07-12 13:00:00');
 
     $deployment = $repository->save(
-        $repository->findOrFail('posts')->markReady(Date::now())
+        $repository->findOrFail('posts')->beginBackfill()->markReady(Date::now())
     );
 
     expect($deployment->status)->toBe(DeploymentStatus::Ready)
@@ -100,7 +100,7 @@
 
     expect($repository->exists())->toBeFalse();
 
-    $repository->save(Deployment::backfilling(
+    $repository->save(Deployment::provisioned(
         name: 'posts',
         alias: 'posts_search',
         activeIndex: 'posts_blue',