SP1: Boot WebSocket worker on :8097 with shared SyncPlayManager

config/server.php

@@ -64,4 +64,16 @@
         // default and keeps the segment count (and per-request overhead) sane.
         'segment_seconds' => 6,
     ],
+
+    // WebSocket server settings for SyncPlay realtime communication.
+    // The WS worker runs as count=1 (one authoritative SyncPlayManager for all
+    // connections) on a dedicated port separate from the HTTP workers.
+    'websocket' => [
+        'host' => '0.0.0.0',
+        'port' => 8097,
+        // Interval for cleaning up stale connections (seconds).
+        'stale_connection_timeout' => 300,
+        // Interval for cleaning up stale SyncPlay groups (seconds).
+        'stale_group_timeout' => 3600,
+    ],
 ];

src/Server/WebSocket/WebSocketServer.php

@@ -8,6 +8,7 @@
 use Workerman\Connection\TcpConnection;
 use Phlix\Common\Logger\LoggerFactory;
 use Phlix\Common\Logger\LogChannels;
+use Phlix\Session\SyncPlay\SyncPlayManager;
 
 /**
  * WebSocket server implementation for real-time communication.
@@ -33,13 +34,17 @@ class WebSocketServer
     /** @var ConnectionPool Manages active WebSocket connections */
     private ConnectionPool $connections;
 
+    /** @var SyncPlayManager|null SyncPlay manager for group state */
+    private ?SyncPlayManager $syncPlayManager = null;
+
     /** @var array<string, mixed> Server configuration */
     private array $config;
 
     /**
      * Creates a new WebSocket server instance.
      *
      * @param array<string, mixed> $config Server configuration with 'host' and 'port' keys
+     * @param MessageHandler|null $handler Optional message handler (for SP1 singletons)
      *
      * @example
      * ```php
@@ -50,11 +55,11 @@ class WebSocketServer
      * $server->run();
      * ```
      */
-    public function __construct(array $config)
+    public function __construct(array $config, ?MessageHandler $handler = null)
     {
         $this->config = $config;
         $this->connections = ConnectionPool::getInstance();
-        $this->handler = new MessageHandler($this->connections);
+        $this->handler = $handler ?? new MessageHandler($this->connections);
 
         $host = $config['host'] ?? '0.0.0.0';
         $port = $config['port'] ?? 8097;
@@ -86,11 +91,31 @@ public function onStart(): void
             'port' => is_numeric($port) ? (int)$port : 8097,
         ]);
 
+        $staleConnectionTimeoutRaw = $this->config['stale_connection_timeout'] ?? 300;
+        $staleConnectionTimeout = is_numeric($staleConnectionTimeoutRaw) ? (int) $staleConnectionTimeoutRaw : 300;
+
+        $staleGroupTimeoutRaw = $this->config['stale_group_timeout'] ?? 3600;
+        $staleGroupTimeout = is_numeric($staleGroupTimeoutRaw) ? (int) $staleGroupTimeoutRaw : 3600;
+
         // Start cleanup timer for stale connections (every 60 seconds)
         if (function_exists('Workerman\Timer')) {
-            \Workerman\Timer::add(60, function (): void {
-                $this->connections->cleanupStaleConnections(300);
+            \Workerman\Timer::add(60, function () use ($staleConnectionTimeout): void {
+                $this->connections->cleanupStaleConnections($staleConnectionTimeout);
             });
+
+            // Start cleanup timer for stale SyncPlay groups (every 5 minutes)
+            $syncPlayManager = $this->syncPlayManager;
+            if ($syncPlayManager !== null) {
+                \Workerman\Timer::add(300, function () use ($syncPlayManager, $staleGroupTimeout): void {
+                    $removed = $syncPlayManager->cleanupStaleGroups($staleGroupTimeout);
+                    if ($removed > 0) {
+                        $logger = LoggerFactory::get(LogChannels::WEBSOCKET);
+                        $logger->info('Cleaned up stale SyncPlay groups', [
+                            'removed' => $removed,
+                        ]);
+                    }
+                });
+            }
         }
     }
 
@@ -218,6 +243,20 @@ public function getHandler(): MessageHandler
         return $this->handler;
     }
 
+    /**
+     * Sets the SyncPlay manager for group state management.
+     *
+     * This must be called before onStart() to enable the stale groups
+     * cleanup timer.
+     *
+     * @param \Phlix\Session\SyncPlay\SyncPlayManager $manager The SyncPlay manager
+     * @return void
+     */
+    public function setSyncPlayManager(\Phlix\Session\SyncPlay\SyncPlayManager $manager): void
+    {
+        $this->syncPlayManager = $manager;
+    }
+
     /**
      * Starts the WebSocket server.
      *

start.php

@@ -168,6 +168,71 @@
 //    REST + SSR surface.
 // -----------------------------------------------------------------------------
 
+// -----------------------------------------------------------------------------
+// 4a. WebSocket worker for SyncPlay realtime communication (SP1).
+//
+// SyncPlay requires exactly ONE authoritative SyncPlayManager shared across all
+// WS connections, so this worker runs as count=1 on port 8097 (separate from the
+// HTTP workers on 8096). The manager is constructed once in onWorkerStart and
+// its state persists for the lifetime of this worker process.
+//
+// Architecture:
+//   - WebSocketServer accepts an injected MessageHandler so the same handler
+//     instance is used for both SyncPlay message routing and general WS events.
+//   - SyncPlayManager::initialize() registers the per-type callbacks that route
+//     incoming SyncPlay messages to the appropriate handler methods.
+//   - ConnectionPool and MessageHandler are singletons shared within this worker.
+// -----------------------------------------------------------------------------
+
+try {
+    $wsWorker = new Worker('websocket://0.0.0.0:8097');
+    $wsWorker->count = 1;
+    $wsWorker->name = 'phlix-server-ws';
+    $wsWorker->onWorkerStart = static function (Worker $w) use ($config, $applyCuratedCoroutineHooks): void {
+        $applyCuratedCoroutineHooks();
+
+        // Build the container inside the fork so each worker owns its own state.
+        $container = ContainerFactory::create($config);
+
+        // Create the shared MessageHandler and ConnectionPool singletons.
+        $connections = \Phlix\Server\WebSocket\ConnectionPool::getInstance();
+        $messageHandler = new \Phlix\Server\WebSocket\MessageHandler($connections);
+
+        // Construct ONE authoritative SyncPlayManager and initialize it with the
+        // message handler so SyncPlay message types are routed to their handlers.
+        /** @var \Phlix\Common\Logger\StructuredLogger $logger */
+        $logger = $container->get('logger.websocket');
+        $syncPlayManager = new \Phlix\Session\SyncPlay\SyncPlayManager($logger);
+        $syncPlayManager->initialize($messageHandler);
+
+        // Build and configure the WebSocket server with the shared manager.
+        $wsConfigRaw = $config['websocket'] ?? null;
+        $wsConfig = is_array($wsConfigRaw) ? $wsConfigRaw : [];
+        $wsConfig['host'] = $wsConfig['host'] ?? '0.0.0.0';
+        $wsConfig['port'] = $wsConfig['port'] ?? 8097;
+        $wsConfig['stale_connection_timeout'] = $wsConfig['stale_connection_timeout'] ?? 300;
+        $wsConfig['stale_group_timeout'] = $wsConfig['stale_group_timeout'] ?? 3600;
+
+        /** @var array<string, mixed> $wsConfig */
+        $wsServer = new \Phlix\Server\WebSocket\WebSocketServer($wsConfig, $messageHandler);
+        $wsServer->setSyncPlayManager($syncPlayManager);
+
+        // Trigger onStart to log the startup message and arm cleanup timers.
+        // The actual Workerman worker callbacks (onConnect, onMessage, onClose)
+        // are already bound in the WebSocketServer constructor.
+        $wsServer->onStart();
+
+        /** @var \Phlix\Common\Logger\StructuredLogger $wsLogger */
+        $wsLogger = $container->get('logger.websocket');
+        $wsLogger->info('SyncPlay manager initialized', [
+            'message' => 'One SyncPlayManager instance handles all WS connections',
+        ]);
+    };
+} catch (\Throwable $e) {
+    // The WS worker is best-effort; never block the HTTP server.
+    trigger_error('Failed to set up WebSocket worker: ' . $e->getMessage(), E_USER_WARNING);
+}
+
 // -----------------------------------------------------------------------------
 // 4b. Managed worker processes (1.1b).
 //