fix(editor): keep working when the realtime channel never delivers

Author: dnlblasco

app/Http/Controllers/Api/SessionValidationController.php

@@ -50,6 +50,10 @@ public function __invoke(Request $request, string $sessionId, EditorSessionManag
             );
         }
 
+        // A session that needed no confirmation has no window yet; the first
+        // one to arrive takes it.
+        $sessions->adoptWindow($session, $verificationId);
+
         if (! $session->matchesConfirmedVerification($verificationId)) {
             return $this->refuse(
                 $sessionId,

app/Models/Server.php

@@ -32,6 +32,11 @@ class Server extends Model implements Authenticatable
         'token_hash',
     ];
 
+    /** Until a plugin reports a live channel, its requests are queued. */
+    protected $attributes = [
+        'uses_polling' => true,
+    ];
+
     /**
      * A server is considered reachable while it has sent a heartbeat inside this window.
      */

app/Services/EditorSessionManager.php

@@ -86,6 +86,33 @@ public function confirm(string $verificationId, string $confirmedBy): ?EditorSes
         });
     }
 
+    /**
+     * Adopts a window as the confirmed one when no confirmation was required.
+     *
+     * Such a session is created already confirmed but with no window attached,
+     * so without this the first window to validate is turned away as if another
+     * had got there first.
+     */
+    public function adoptWindow(EditorSession $session, string $verificationId): bool
+    {
+        if ($session->require_confirmation || $session->confirmed_verification_id !== null) {
+            return false;
+        }
+
+        return DB::transaction(function () use ($session, $verificationId): bool {
+            $locked = EditorSession::whereKey($session->getKey())->lockForUpdate()->first();
+
+            if ($locked === null || $locked->confirmed_verification_id !== null || $locked->require_confirmation) {
+                return false;
+            }
+
+            $locked->update(['confirmed_verification_id' => $verificationId]);
+            $session->setAttribute('confirmed_verification_id', $verificationId);
+
+            return true;
+        });
+    }
+
     /**
      * Claims the session for the first browser window that validates it.
      */

database/factories/ServerFactory.php

@@ -32,6 +32,12 @@ public function definition(): array
         ];
     }
 
+    /** A server whose plugin holds a live channel, so requests are broadcast. */
+    public function onChannel(): static
+    {
+        return $this->state(['uses_polling' => false]);
+    }
+
     public function offline(): static
     {
         return $this->state(['last_seen_at' => now()->subHour()]);

database/migrations/2026_08_31_103324_default_servers_to_polling.php

@@ -0,0 +1,30 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * A server is assumed to be collecting requests over HTTP until it proves
+     * it holds a live channel. A queued request can always be picked up later,
+     * while one broadcast to an empty channel is simply lost.
+     */
+    public function up(): void
+    {
+        Schema::table('servers', function (Blueprint $table) {
+            $table->boolean('uses_polling')->default(true)->change();
+        });
+
+        DB::table('servers')->update(['uses_polling' => true]);
+    }
+
+    public function down(): void
+    {
+        Schema::table('servers', function (Blueprint $table) {
+            $table->boolean('uses_polling')->default(false)->change();
+        });
+    }
+};

tests/Feature/Http/Controllers/Api/MenuControllerTest.php

@@ -5,6 +5,7 @@
 use App\Events\MenuChanged;
 use App\Events\RpcRequested;
 use App\Models\EditorSession;
+use App\Models\Server;
 use App\Services\RpcBridge;
 use Illuminate\Foundation\Testing\RefreshDatabase;
 use Illuminate\Support\Facades\Event;
@@ -93,7 +94,9 @@ public function test_returns_422_for_an_unknown_platform(): void
 
     private function editorSession(): EditorSession
     {
-        return EditorSession::factory()->create(['confirmed' => true, 'consumed' => true, 'active' => false]);
+        return EditorSession::factory()
+            ->for(Server::factory()->onChannel())
+            ->create(['confirmed' => true, 'consumed' => true, 'active' => false]);
     }
 
     /**

tests/Feature/Http/Controllers/Api/SessionValidationControllerTest.php

@@ -37,6 +37,33 @@ public function test_signs_the_window_in_so_it_can_reach_the_menu_endpoints(): v
         $this->assertAuthenticatedAs($session, 'editor');
     }
 
+    public function test_opens_a_session_that_needed_no_confirmation(): void
+    {
+        // The plugin marks these confirmed on creation but attaches no window.
+        $session = EditorSession::factory()->create(['require_confirmation' => false, 'confirmed' => true]);
+        $verificationId = (string) Str::uuid();
+        $session->verifications()->create(['verification_id' => $verificationId]);
+
+        $this->getJson($this->url($session->session_id, $verificationId))
+            ->assertOk()
+            ->assertJson(['valid' => true, 'message' => 'Session validated']);
+    }
+
+    public function test_refuses_a_second_window_on_a_session_that_needed_no_confirmation(): void
+    {
+        $session = EditorSession::factory()->create(['require_confirmation' => false, 'confirmed' => true]);
+        $first = (string) Str::uuid();
+        $second = (string) Str::uuid();
+        $session->verifications()->create(['verification_id' => $first]);
+        $session->verifications()->create(['verification_id' => $second]);
+
+        $this->getJson($this->url($session->session_id, $first))->assertJson(['valid' => true]);
+
+        $this->getJson($this->url($session->session_id, $second))
+            ->assertOk()
+            ->assertJson(['valid' => false, 'message' => 'Session already validated from another window']);
+    }
+
     public function test_reserves_the_session_so_a_second_window_is_refused(): void
     {
         $verificationId = (string) Str::uuid();

tests/Feature/Services/RpcBridgeTest.php

@@ -18,7 +18,7 @@ class RpcBridgeTest extends TestCase
     public function test_returns_the_payload_the_plugin_posts_back(): void
     {
         $bridge = app(RpcBridge::class);
-        $server = Server::factory()->create();
+        $server = Server::factory()->onChannel()->create();
 
         // The plugin answers on a separate request; a listener stands in for it.
         Event::listen(RpcRequested::class, fn (RpcRequested $event) => $bridge->resolve($event->requestId, [
@@ -36,7 +36,7 @@ public function test_returns_the_payload_the_plugin_posts_back(): void
     public function test_broadcasts_the_request_on_the_private_channel_of_the_server(): void
     {
         $bridge = app(RpcBridge::class);
-        $server = Server::factory()->create();
+        $server = Server::factory()->onChannel()->create();
         $captured = null;
 
         Event::listen(RpcRequested::class, function (RpcRequested $event) use ($bridge, &$captured): void {