[CLI] Avoid breaks during Playground boot when --xdebug enabled (#2835)

## Motivation for the change, related issues

Today, Playground enables Xdebug during boot which may be surprising to
users. If the debugger breaks at the first line, the user will be
debugging the Playground boot process. Let's skip this by default and
consider adding a command line flag to enable boot-time Xdebug breaks.

## Implementation details

A big change in this PR is that the first Playground worker is now only
used during boot. We discard it after that boot and setup process
completes. Some positive consequences of this change are:

- Reflects the truth that the Playground worker has special
configuration and responsibilities as part of the boot process.
- Allows us to be clear that all post-boot workers are based on the same
configuration and truth. There is no remaining special boot-time worker
that might behave differently from the others.
- Allows us to control whether the boot-and-setup worker has Xdebug
enabled separately from the regular workers.

## Testing Instructions (or ideally a Blueprint)

Before checking out this branch:
- Create a local directory at the top level of your Playground working
dir that can be mounted as `/wordpress`
- Run `npx nx unbuilt-asyncify playground-cli -- server --mount-dir
<local-dir> /wordpress` so Playground will download and install
WordPress in your local directory.
- Open the local directory as a project root in Visual Studio Code,
select the debug pane, and create a launch.json file containing the
following configuration:
  ```
  {
      "name": "PR test for WP Playground CLI - Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
          "/": "${workspaceFolder}/.playground-xdebug-root",
          "/wordpress": "${workspaceFolder}/"
      },
      "stopOnEntry": true,
  }
  ```
- Start the "PR test for WP Playground CLI - Listen for Xdebug" debug
target within vscode
- `cd` into the local WP dir and run the following command and confirm
that vscode hit a breakpoint before the "WordPress is running on
http://127.0.0.1:9400" message is printed:
`node --experimental-strip-types --experimental-transform-types
--disable-warning=ExperimentalWarning --import
../packages/meta/src/node-es-module-loader/register.mts
../packages/playground/cli/src/cli.ts server --auto-mount=.
--verbosity=debug --skip-wordpress-setup --xdebug
--experimental-unsafe-ide-integration --php=8.3
--experimental-multi-worker=4`

After checking out this branch:
- Open the previously created local WP dir as the workspace root within
vscode
- Run the "PR test for WP Playground CLI - Listen for Xdebug" debug
target
- `cd` into the local WP dir, re-run the above node command, and confirm
that no breakpoint was hit during the boot process.

---------

Co-authored-by: Adam Zieliński <adam@adamziel.com>

Author: brandonpayton

packages/playground/cli/src/blueprints-v1/blueprints-v1-handler.ts

@@ -1,6 +1,5 @@
 import { logger } from '@php-wasm/logger';
 import { EmscriptenDownloadMonitor, ProgressTracker } from '@php-wasm/progress';
-import type { SupportedPHPVersion } from '@php-wasm/universal';
 import { consumeAPI } from '@php-wasm/universal';
 import type { BlueprintV1Declaration } from '@wp-playground/blueprints';
 import {
@@ -34,7 +33,6 @@ import {
  * implemented in TypeScript and orchestrated by this class.
  */
 export class BlueprintsV1Handler {
-	private phpVersion: SupportedPHPVersion | undefined;
 	private lastProgressMessage = '';
 
 	private siteUrl: string;
@@ -57,7 +55,7 @@ export class BlueprintsV1Handler {
 		return 'v1';
 	}
 
-	async bootPrimaryWorker(
+	async bootAndSetUpInitialPlayground(
 		phpPort: NodeMessagePort,
 		fileLockManagerPort: NodeMessagePort,
 		nativeInternalDirPath: string
@@ -135,7 +133,7 @@ export class BlueprintsV1Handler {
 			this.getEffectiveBlueprint()
 		);
 		await playground.useFileLockManager(fileLockManagerPort);
-		await playground.bootAsPrimaryWorker({
+		await playground.bootAndSetUpInitialWorker({
 			phpVersion: runtimeConfiguration.phpVersion,
 			wpVersion: runtimeConfiguration.wpVersion,
 			siteUrl: this.siteUrl,
@@ -149,7 +147,11 @@ export class BlueprintsV1Handler {
 			followSymlinks,
 			trace,
 			internalCookieStore: this.args.internalCookieStore,
-			withXdebug: !!this.args.xdebug,
+			// We do not enable Xdebug by default for the initial worker
+			// because we do not imagine users expect to hit breakpoints
+			// until Playground has fully booted.
+			// TODO: Consider supporting Xdebug for the initial worker via a dedicated flag.
+			withXdebug: false,
 			nativeInternalDirPath,
 		});
 
@@ -169,7 +171,7 @@ export class BlueprintsV1Handler {
 		return playground;
 	}
 
-	async bootSecondaryWorker({
+	async bootPlayground({
 		worker,
 		fileLockManagerPort,
 		firstProcessId,
@@ -180,14 +182,17 @@ export class BlueprintsV1Handler {
 		firstProcessId: number;
 		nativeInternalDirPath: string;
 	}) {
-		const additionalPlayground = consumeAPI<PlaygroundCliBlueprintV1Worker>(
+		const playground = consumeAPI<PlaygroundCliBlueprintV1Worker>(
 			worker.phpPort
 		);
 
-		await additionalPlayground.isConnected();
-		await additionalPlayground.useFileLockManager(fileLockManagerPort);
-		await additionalPlayground.bootAsSecondaryWorker({
-			phpVersion: this.phpVersion!,
+		await playground.isConnected();
+		const runtimeConfiguration = await resolveRuntimeConfiguration(
+			this.getEffectiveBlueprint()
+		);
+		await playground.useFileLockManager(fileLockManagerPort);
+		await playground.bootWorker({
+			phpVersion: runtimeConfiguration.phpVersion,
 			siteUrl: this.siteUrl,
 			mountsBeforeWpInstall: this.args['mount-before-install'] || [],
 			mountsAfterWpInstall: this.args['mount'] || [],
@@ -201,8 +206,8 @@ export class BlueprintsV1Handler {
 			withXdebug: !!this.args.xdebug,
 			nativeInternalDirPath,
 		});
-		await additionalPlayground.isReady();
-		return additionalPlayground;
+		await playground.isReady();
+		return playground;
 	}
 
 	async compileInputBlueprint(additionalBlueprintSteps: any[]) {

packages/playground/cli/src/blueprints-v1/worker-thread-v1.ts

@@ -56,14 +56,15 @@ export type PrimaryWorkerBootOptions = WorkerBootOptions & {
 
 interface WorkerBootRequestHandlerOptions {
 	siteUrl: string;
-	allow?: string;
+	followSymlinks: boolean;
 	phpVersion: SupportedPHPVersion;
 	firstProcessId: number;
 	processIdSpaceLength: number;
 	trace: boolean;
 	nativeInternalDirPath: string;
 	mountsBeforeWpInstall: Array<Mount>;
 	mountsAfterWpInstall: Array<Mount>;
+	withXdebug?: boolean;
 }
 
 /**
@@ -123,7 +124,7 @@ export class PlaygroundCliBlueprintV1Worker extends PHPWorker {
 		}
 	}
 
-	async bootAsPrimaryWorker({
+	async bootAndSetUpInitialWorker({
 		siteUrl,
 		mountsBeforeWpInstall,
 		mountsAfterWpInstall,
@@ -229,20 +230,21 @@ export class PlaygroundCliBlueprintV1Worker extends PHPWorker {
 		}
 	}
 
-	async bootAsSecondaryWorker(args: WorkerBootOptions) {
+	async bootWorker(args: WorkerBootOptions) {
 		await this.bootRequestHandler(args);
 	}
 
 	async bootRequestHandler({
 		siteUrl,
-		allow,
+		followSymlinks,
 		phpVersion,
 		firstProcessId,
 		processIdSpaceLength,
 		trace,
 		nativeInternalDirPath,
 		mountsBeforeWpInstall,
 		mountsAfterWpInstall,
+		withXdebug,
 	}: WorkerBootRequestHandlerOptions) {
 		if (this.booted) {
 			throw new Error('Playground already booted');
@@ -275,7 +277,8 @@ export class PlaygroundCliBlueprintV1Worker extends PHPWorker {
 							},
 							phpWasmInitOptions: { nativeInternalDirPath },
 						},
-						followSymlinks: allow?.includes('follow-symlinks'),
+						followSymlinks,
+						withXdebug,
 					});
 				},
 				onPHPInstanceCreated: async (php) => {

packages/playground/cli/src/blueprints-v2/blueprints-v2-handler.ts

@@ -38,7 +38,7 @@ export class BlueprintsV2Handler {
 		return 'v2';
 	}
 
-	async bootPrimaryWorker(
+	async bootAndSetUpInitialPlayground(
 		phpPort: NodeMessagePort,
 		fileLockManagerPort: NodeMessagePort,
 		nativeInternalDirPath: string
@@ -56,19 +56,20 @@ export class BlueprintsV2Handler {
 			processIdSpaceLength: this.processIdSpaceLength,
 			trace: this.args.debug || false,
 			blueprint: this.args.blueprint!,
-			withXdebug: !!this.args.xdebug,
-			xdebug:
-				typeof this.args.xdebug === 'object'
-					? this.args.xdebug
-					: undefined,
+			// We do not enable Xdebug by default for the initial worker
+			// because we do not imagine users expect to hit breakpoints
+			// until Playground has fully booted.
+			// TODO: Consider supporting Xdebug for the initial worker via a dedicated flag.
+			withXdebug: false,
+			xdebug: undefined,
 			nativeInternalDirPath,
 		};
 
-		await playground.bootAsPrimaryWorker(workerBootArgs);
+		await playground.bootAndSetUpInitialWorker(workerBootArgs);
 		return playground;
 	}
 
-	async bootSecondaryWorker({
+	async bootPlayground({
 		worker,
 		fileLockManagerPort,
 		firstProcessId,
@@ -86,7 +87,7 @@ export class BlueprintsV2Handler {
 
 		const workerBootArgs: SecondaryWorkerBootArgs = {
 			...this.args,
-			phpVersion: this.phpVersion!,
+			phpVersion: this.phpVersion,
 			siteUrl: this.siteUrl,
 			firstProcessId,
 			processIdSpaceLength: this.processIdSpaceLength,
@@ -97,7 +98,7 @@ export class BlueprintsV2Handler {
 			mountsAfterWpInstall: this.args.mount || [],
 		};
 
-		await playground.bootAsSecondaryWorker(workerBootArgs);
+		await playground.bootWorker(workerBootArgs);
 
 		return playground;
 	}

packages/playground/cli/src/blueprints-v2/worker-thread-v2.ts

@@ -204,7 +204,7 @@ export class PlaygroundCliBlueprintV2Worker extends PHPWorker {
 		}
 	}
 
-	async bootAsPrimaryWorker(args: PrimaryWorkerBootArgs) {
+	async bootAndSetUpInitialWorker(args: PrimaryWorkerBootArgs) {
 		const constants = {
 			WP_DEBUG: true,
 			WP_DEBUG_LOG: true,
@@ -252,7 +252,7 @@ export class PlaygroundCliBlueprintV2Worker extends PHPWorker {
 		await this.runBlueprintV2(args);
 	}
 
-	async bootAsSecondaryWorker(args: SecondaryWorkerBootArgs) {
+	async bootWorker(args: SecondaryWorkerBootArgs) {
 		await this.bootRequestHandler({
 			...args,
 			onPHPInstanceCreated: async (php: PHP) => {

packages/playground/cli/src/load-balancer.ts

@@ -33,6 +33,20 @@ export class LoadBalancer {
 			activeRequests: new Set(),
 		});
 	}
+	async removeWorker(worker: RemoteAPI<PlaygroundCliWorker>) {
+		const workerIndex = this.workerLoads.findIndex(
+			(workerLoad) => workerLoad.worker === worker
+		);
+		if (workerIndex === -1) {
+			return;
+		}
+
+		const [removedWorker] = this.workerLoads.splice(workerIndex, 1);
+
+		// A worker can only be considered fully removed once all
+		// its active requests have settled.
+		await Promise.allSettled(removedWorker.activeRequests);
+	}
 
 	async handleRequest(request: PHPRequest) {
 		let smallestWorkerLoad = this.workerLoads[0];