[PHP] Inline rotatePHPRuntime() into the PHP class (#2559)

## Motivation for the change, related issues

Moves the `rotatePHPRuntime()` logic inside the PHP class and properly
await them to prevent async rotation failures:

```
{
  type: 'request.error',
  error: Error: PHP.run() failed with exit code 255.
      at runExecutionFunction.then.dispatchEvent.type (/Users/cloudnik/www/Automattic/core/plugins/wordpress-playground/packages/php-wasm/universal/src/lib/php.ts:1052:14),
  source: 'php-wasm'
}
Trace: hotSwapPHPRuntime called on a disposed PHP instance
    at PHP.hotSwapPHPRuntime (/Users/cloudnik/www/Automattic/core/plugins/wordpress-playground/packages/php-wasm/universal/src/lib/php.ts:1272:13)
    at rotateRuntime (/Users/cloudnik/www/Automattic/core/plugins/wordpress-playground/packages/php-wasm/universal/src/lib/rotate-php-runtime.ts:45:14)
    at async rotateRuntimeForPhpWasmError (/Users/cloudnik/www/Automattic/core/plugins/wordpress-playground/packages/php-wasm/universal/src/lib/rotate-php-runtime.ts:64:4)
```

## Implementation

The `rotatePHPRuntime()` function kills the "worn out" PHP Emscripten
runtimes and replaces them with new ones. php-fpm does the same thing.
Rotating the runtime happens in response to a few events emitted by the
PHP class. However, rotation is an async operation and event listeners
are expected to be synchronous. As a result, a PHP instance may get
killed and the rotate handler will attempt to rotate it asynchronously,
causing errors such as the one cited above.

This PR inlines that logic in the PHP class via a new
`php.enableRuntimeRotation()` method. The PHP instance now keeps track
if the rotation condition internally and optionally rotates the runtime
before every `php.run()`, `php.runStream()`, and `php.cli()` call. This
approach also has other benefits:

* Ability to call `php.cli()` and `php.run()` multiple times without
trashing the instance – the rotation is handled internally.
* It creates a way to get rid of the `primary` and `secondary` PHP
instance concept in the PHPProcessManager class. We no longer need to
worry about accidentally trashing the primary instance by calling
`.cli()` on it.
* The rotation is now lazy, not eager, and only happens on the next PHP
code execution.

### Potential follow-up work

* Expose a static `PHP.create( runtimeFactory )` method to simplify the
instance constructions. Right now you need to do `const php = new PHP(
runtimeId ); PHP.enableRuntimeRotation( runtimeFactory );`.

## Testing Instructions (or ideally a Blueprint)

CI

---------

Co-authored-by: Brandon Payton <[email protected]>

Author: adamziel

packages/php-wasm/fs-journal/src/lib/fs-journal.ts

@@ -178,11 +178,11 @@ export function journalFSEvents(
 		php[__private__dont__use].journal.unbind();
 		delete php[__private__dont__use].journal;
 	}
-	php.addEventListener('runtime.beforedestroy', unbindFromOldRuntime);
+	php.addEventListener('runtime.beforeExit', unbindFromOldRuntime);
 
 	return function unbind() {
 		php.removeEventListener('runtime.initialized', bindToCurrentRuntime);
-		php.removeEventListener('runtime.beforedestroy', unbindFromOldRuntime);
+		php.removeEventListener('runtime.beforeExit', unbindFromOldRuntime);
 		return php[__private__dont__use].journal.unbind();
 	};
 }

packages/php-wasm/node/src/test/php.spec.ts

@@ -2868,6 +2868,22 @@ phpLoaderOptions.forEach((options) => {
 					'/internal/shared/bin/php'
 				);
 			});
+
+			it('should support multiple calls to php.cli() and php.runStream() when runtime rotation is enabled', async () => {
+				php.enableRuntimeRotation({
+					maxRequests: 1,
+					recreateRuntime: () =>
+						loadNodeRuntime(phpVersion as any, options),
+				});
+				const response = await php.cli(['php', '-r', 'echo "Hello";']);
+				expect(await response.stdoutText).toBe('Hello');
+				const response2 = await php.runStream({
+					code: `<?php echo "Hello";`,
+				});
+				expect(await response2.stdoutText).toBe('Hello');
+				const response3 = await php.cli(['php', '-r', 'echo "Hello";']);
+				expect(await response3.stdoutText).toBe('Hello');
+			});
 		});
 
 		describe('Response parsing', { skip: options.withXdebug }, () => {

packages/php-wasm/node/src/test/rotate-php-runtime.spec.ts

@@ -5,22 +5,20 @@ import {
 	LatestSupportedPHPVersion,
 	PHP,
 	__private__dont__use,
-	rotatePHPRuntime,
 } from '@php-wasm/universal';
 import { loadNodeRuntime } from '../lib';
 import { createNodeFsMountHandler } from '../lib/node-fs-mount';
 
 const recreateRuntime = async (version: any = LatestSupportedPHPVersion) =>
 	await loadNodeRuntime(version);
 
-describe('rotatePHPRuntime()', () => {
+describe('php.enableRuntimeRotation()', () => {
 	it('Preserves the /internal directory through PHP runtime recreation', async () => {
 		// Rotate the PHP runtime
 		const recreateRuntimeSpy = vitest.fn(recreateRuntime);
 
 		const php = new PHP(await recreateRuntime());
-		rotatePHPRuntime({
-			php,
+		php.enableRuntimeRotation({
 			cwd: '/test-root',
 			recreateRuntime: recreateRuntimeSpy,
 			maxRequests: 10,
@@ -55,8 +53,7 @@ describe('rotatePHPRuntime()', () => {
 		const recreateRuntimeSpy = vitest.fn(recreateRuntime);
 
 		const php = new PHP(await recreateRuntime());
-		rotatePHPRuntime({
-			php,
+		php.enableRuntimeRotation({
 			cwd: '/test-root',
 			recreateRuntime: recreateRuntimeSpy,
 			maxRequests: 10,
@@ -89,8 +86,7 @@ describe('rotatePHPRuntime()', () => {
 		const recreateRuntimeSpy = vitest.fn(recreateRuntime);
 
 		const php = new PHP(await recreateRuntime());
-		rotatePHPRuntime({
-			php,
+		php.enableRuntimeRotation({
 			cwd: '/wordpress',
 			recreateRuntime: recreateRuntimeSpy,
 			maxRequests: 10,
@@ -192,8 +188,7 @@ describe('rotatePHPRuntime()', () => {
 		const recreateRuntimeSpy = vitest.fn(recreateRuntime);
 		// Rotate the PHP runtime
 		const php = new PHP(await recreateRuntime());
-		rotatePHPRuntime({
-			php,
+		php.enableRuntimeRotation({
 			cwd: '/test-root',
 			recreateRuntime: recreateRuntimeSpy,
 			maxRequests: 1000,
@@ -222,62 +217,39 @@ describe('rotatePHPRuntime()', () => {
 	it('Should recreate the PHP runtime after maxRequests', async () => {
 		const recreateRuntimeSpy = vitest.fn(recreateRuntime);
 		const php = new PHP(await recreateRuntimeSpy());
-		rotatePHPRuntime({
-			php,
+		php.enableRuntimeRotation({
 			cwd: '/test-root',
 			recreateRuntime: recreateRuntimeSpy,
 			maxRequests: 1,
 		});
 		// Rotate the PHP runtime
 		await php.run({ code: `` });
-		expect(recreateRuntimeSpy).toHaveBeenCalledTimes(2);
-	}, 30_000);
-
-	it('Should not rotate after the cleanup handler is called, even if max requests is reached', async () => {
-		const recreateRuntimeSpy = vitest.fn(recreateRuntime);
-		const php = new PHP(await recreateRuntimeSpy());
-		const cleanup = rotatePHPRuntime({
-			php,
-			cwd: '/test-root',
-			recreateRuntime: recreateRuntimeSpy,
-			maxRequests: 1,
-		});
-		// Rotate the PHP runtime
 		await php.run({ code: `` });
 		expect(recreateRuntimeSpy).toHaveBeenCalledTimes(2);
-
-		cleanup();
-
-		// No further rotation should happen
-		await php.run({ code: `` });
-		await php.run({ code: `` });
-
-		expect(recreateRuntimeSpy).toHaveBeenCalledTimes(2);
 	}, 30_000);
 
 	it('Should recreate the PHP runtime after a PHP runtime crash', async () => {
 		const recreateRuntimeSpy = vitest.fn(recreateRuntime);
 		const php = new PHP(await recreateRuntimeSpy());
-		rotatePHPRuntime({
-			php,
+		php.enableRuntimeRotation({
 			cwd: '/test-root',
 			recreateRuntime: recreateRuntimeSpy,
 			maxRequests: 1234,
 		});
 		// Cause a PHP runtime rotation due to error
-		await php.dispatchEvent({
+		php.dispatchEvent({
 			type: 'request.error',
 			error: new Error('mock error'),
 			source: 'php-wasm',
 		});
+		await php.run({ code: `` });
 		expect(recreateRuntimeSpy).toHaveBeenCalledTimes(2);
 	}, 30_000);
 
 	it('Should not recreate the PHP runtime after a PHP fatal', async () => {
 		const recreateRuntimeSpy = vitest.fn(recreateRuntime);
 		const php = new PHP(await recreateRuntimeSpy());
-		rotatePHPRuntime({
-			php,
+		php.enableRuntimeRotation({
 			cwd: '/test-root',
 			recreateRuntime: recreateRuntimeSpy,
 			maxRequests: 1234,
@@ -296,31 +268,6 @@ describe('rotatePHPRuntime()', () => {
 		expect(recreateRuntimeSpy).toHaveBeenCalledTimes(1);
 	}, 30_000);
 
-	it('Should not rotate after the cleanup handler is called, even if there is a PHP runtime error', async () => {
-		const recreateRuntimeSpy = vitest.fn(recreateRuntime);
-		const php = new PHP(await recreateRuntimeSpy());
-		const cleanup = rotatePHPRuntime({
-			php,
-			cwd: '/test-root',
-			recreateRuntime: recreateRuntimeSpy,
-			maxRequests: 1,
-		});
-		// Rotate the PHP runtime
-		await php.run({ code: `` });
-		expect(recreateRuntimeSpy).toHaveBeenCalledTimes(2);
-
-		cleanup();
-
-		// No further rotation should happen
-		php.dispatchEvent({
-			type: 'request.error',
-			error: new Error('mock error'),
-			source: 'php-wasm',
-		});
-
-		expect(recreateRuntimeSpy).toHaveBeenCalledTimes(2);
-	}, 30_000);
-
 	it('Should hotswap the PHP runtime from 8.2 to 8.3', async () => {
 		let nbCalls = 0;
 		const recreateRuntimeSpy = vitest.fn(() => {
@@ -331,8 +278,7 @@ describe('rotatePHPRuntime()', () => {
 			return recreateRuntime('8.3');
 		});
 		const php = new PHP(await recreateRuntimeSpy());
-		rotatePHPRuntime({
-			php,
+		php.enableRuntimeRotation({
 			cwd: '/test-root',
 			recreateRuntime: recreateRuntimeSpy,
 			maxRequests: 1,
@@ -353,8 +299,7 @@ describe('rotatePHPRuntime()', () => {
 
 	it('Should preserve the custom SAPI name', async () => {
 		const php = new PHP(await recreateRuntime());
-		rotatePHPRuntime({
-			php,
+		php.enableRuntimeRotation({
 			cwd: '/test-root',
 			recreateRuntime,
 			maxRequests: 1,
@@ -371,8 +316,7 @@ describe('rotatePHPRuntime()', () => {
 
 	it('Should preserve the MEMFS files', async () => {
 		const php = new PHP(await recreateRuntime());
-		rotatePHPRuntime({
-			php,
+		php.enableRuntimeRotation({
 			cwd: '/test-root',
 			recreateRuntime,
 			maxRequests: 1,
@@ -395,15 +339,15 @@ describe('rotatePHPRuntime()', () => {
 
 	it('Should not overwrite the NODEFS files', async () => {
 		const php = new PHP(await recreateRuntime());
-		rotatePHPRuntime({
-			php,
+		php.enableRuntimeRotation({
 			cwd: '/test-root',
 			recreateRuntime,
 			maxRequests: 1,
 		});
 
 		// Rotate the PHP runtime
-		await php.run({ code: `` });
+		const result = await php.run({ code: `` });
+		await result.text;
 
 		php.mkdir('/test-root');
 		php.writeFile('/test-root/index.php', 'test');
@@ -415,7 +359,10 @@ describe('rotatePHPRuntime()', () => {
 		date.setFullYear(date.getFullYear() - 1);
 		fs.utimesSync(tempFile, date, date);
 		try {
-			php.mount('/test-root/nodefs', createNodeFsMountHandler(tempDir));
+			await php.mount(
+				'/test-root/nodefs',
+				createNodeFsMountHandler(tempDir)
+			);
 
 			// Rotate the PHP runtime
 			await php.run({ code: `` });
@@ -429,6 +376,7 @@ describe('rotatePHPRuntime()', () => {
 		} finally {
 			fs.rmSync(tempFile);
 			fs.rmdirSync(tempDir);
+			php.exit();
 		}
 	}, 30_000);
 });