playground-worker-endpoint.ts

import type { FilesystemOperation } from '@php-wasm/fs-journal';
import { journalFSEvents, replayFSJournal } from '@php-wasm/fs-journal';
import type { EmscriptenDownloadMonitor } from '@php-wasm/progress';
import { setURLScope } from '@php-wasm/scopes';
import { joinPaths, sendmailSpawnHandler } from '@php-wasm/util';
import type {
	DirectoryHandleMount,
	PHPWebExtension,
	SyncProgressCallback,
	TCPOverFetchOptions,
} from '@php-wasm/web';
import type { MountDevice } from '@wp-playground/storage';
import {
	createDirectoryHandleMountHandler,
	loadWebRuntime,
} from '@php-wasm/web';
import { createMemoizedFetch } from '@wp-playground/common';
import { directoryHandleFromMountDevice } from '@wp-playground/storage';
import {
	LatestMinifiedWordPressVersion,
	MinifiedWordPressVersions,
} from '@wp-playground/wordpress-builds';
import { wordPressSiteUrl } from './config';
import {
	backfillStaticFilesRemovedFromMinifiedBuild,
	hasCachedStaticFilesRemovedFromMinifiedBuild,
} from './worker-utils';
/* @ts-ignore */
import transportFetch from './playground-mu-plugin/playground-includes/wp_http_fetch.php?raw';
/* @ts-ignore */
import transportDummy from './playground-mu-plugin/playground-includes/wp_http_dummy.php?raw';
import { logger } from '@php-wasm/logger';
import type {
	AllPHPVersion,
	PathAlias,
	PHP,
	PHPRequestHandler,
} from '@php-wasm/universal';
import {
	isLegacyPHPVersion,
	MountStillActiveError,
	PHPResponse,
	PHPWorker,
	isPathToSharedFS,
	proxyFileSystem,
	sandboxedSpawnHandlerFactory,
} from '@php-wasm/universal';
import { certificateToPEM, generateCertificate } from '@php-wasm/web';
import type { BlueprintDeclaration } from '@wp-playground/blueprints';
import type { WordPressInstallMode } from '@wp-playground/wordpress';
import {
	bootRequestHandler,
	getFileNotFoundActionForWordPress,
	getLoadedWordPressVersion,
} from '@wp-playground/wordpress';
import { wpVersionToStaticAssetsDirectory } from '@wp-playground/wordpress-builds';
import { networkingDisabledFunctions } from './disabled-functions';
/* @ts-ignore */
import playgroundWebMuPlugin from './playground-mu-plugin/0-playground.php?raw';
/* @ts-ignore */
import playgroundWebMuPluginPhp52 from './playground-mu-plugin/0-playground-php52.php?raw';
import { WordPressFetchNetworkTransport } from './wordpress-fetch-network-transport';

let activeRequestHandler: PHPRequestHandler | undefined;
const WITH_ADMIN_TRANSITIONS_PARAM = 'with-admin-transitions';

export interface MountDescriptor {
	mountpoint: string;
	device: MountDevice;
	initialSyncDirection: 'opfs-to-memfs' | 'memfs-to-opfs';
	/** Origin-wide Web Lock that guards journal writes against direct readers. */
	durabilityLockName?: string;
}

export type WorkerBootOptions = {
	wpVersion?: string;
	/** A caller-provided WordPress archive used instead of downloading one. */
	wordPressZip?: File;
	sqliteDriverVersion?: string;
	phpVersion?: AllPHPVersion;
	sapiName?: string;
	scope: string;
	extensions?: PHPWebExtension[];
	withNetworking: boolean;
	mounts?: Array<MountDescriptor>;
	/** @deprecated Use `wordpressInstallMode` instead. */
	shouldInstallWordPress?: boolean;
	corsProxyUrl?: string;
	/** Blueprint v2 declaration used for worker-side execution or preflight checks. */
	blueprint?: BlueprintDeclaration;
	/**
	 * How to handle WordPress installation.
	 * Defaults to `download-and-install`.
	 */
	wordpressInstallMode?: WordPressInstallMode;
	/**
	 * Path aliases that map URL prefixes to filesystem paths outside
	 * the document root. Similar to Nginx's `alias` directive.
	 */
	pathAliases?: PathAlias[];
};

/** @inheritDoc PHPClient */
export abstract class PlaygroundWorkerEndpoint extends PHPWorker {
	booted = false;

	/**
	 * A string representing the scope of the Playground instance.
	 */
	scope: string | undefined;

	/**
	 * A string representing the requested version of WordPress.
	 */
	requestedWordPressVersion: string | undefined;

	/**
	 * A string representing the version of WordPress that was loaded.
	 */
	loadedWordPressVersion: string | undefined;

	unmounts: Record<string, () => any> = createNullPrototypeRecord();
	private opfsMounts: Record<string, DirectoryHandleMount> =
		createNullPrototypeRecord();

	private networkTransport: WordPressFetchNetworkTransport | undefined;
	private requestHandler: PHPRequestHandler | undefined;

	protected downloadMonitor: EmscriptenDownloadMonitor;
	protected memoizedFetch: ReturnType<typeof createMemoizedFetch>;

	constructor(monitor: EmscriptenDownloadMonitor) {
		super(undefined, monitor);

		this.downloadMonitor = monitor;
		const monitoredFetch = (input: RequestInfo | URL, init?: RequestInit) =>
			this.downloadMonitor.monitorFetch(fetch(input, init));
		this.memoizedFetch = createMemoizedFetch(monitoredFetch);
	}

	protected computeSiteUrl(scope: string) {
		return setURLScope(wordPressSiteUrl, scope).toString();
	}

	// NOTE: Version-specific boot methods are implemented in the concrete worker entrypoints

	protected async createRequestHandler({
		siteUrl,
		sapiName,
		corsProxyUrl,
		knownRemoteAssetPaths,
		extensions,
		withNetworking,
		phpVersion,
		pathAliases,
	}: {
		siteUrl: string;
		sapiName: string;
		corsProxyUrl?: string;
		knownRemoteAssetPaths: Set<string>;
		extensions?: PHPWebExtension[];
		withNetworking: boolean;
		phpVersion: AllPHPVersion;
		pathAliases?: PathAlias[];
	}) {
		const phpIniEntries: Record<string, string> = {
			'openssl.cafile': '/internal/shared/ca-bundle.crt',
			'curl.cainfo': '/internal/shared/ca-bundle.crt',
		};

		let tcpOverFetch: TCPOverFetchOptions | undefined = undefined;
		let caBundleContent = '';
		if (withNetworking) {
			// @TODO: Is it fine this is only set in this code branch? That
			//        makes sense and all, but the previous worker always created the transport.
			this.networkTransport = new WordPressFetchNetworkTransport({
				corsProxyUrl,
			});
			const CAroot = await generateCertificate({
				subject: {
					commonName: 'WordPressPlaygroundCA',
					organizationName: 'WordPressPlaygroundCA',
					countryName: 'US',
				},
				basicConstraints: {
					ca: true,
				},
			});
			caBundleContent = certificateToPEM(CAroot.certificate);
			tcpOverFetch = {
				CAroot,
				corsProxyUrl,
			};
		} else {
			phpIniEntries['allow_url_fopen'] = '0';
			phpIniEntries['disable_functions'] = (
				phpIniEntries['disable_functions'] ?? ''
			)
				.split(',')
				.concat(networkingDisabledFunctions)
				.filter((n) => n)
				.join(',');
		}

		const parsedSiteUrl = new URL(siteUrl);
		const isLegacyPhp = isLegacyPHPVersion(phpVersion);
		const requestHandler = await bootRequestHandler({
			siteUrl,
			phpVersion,
			createPhpRuntime: async () => {
				let wasmUrl = '';
				return await loadWebRuntime(phpVersion, {
					extensions,
					tcpOverFetch,
					onPhpLoaderModuleLoaded: (phpLoaderModule) => {
						wasmUrl = phpLoaderModule.dependencyFilename;
						this.downloadMonitor.expectAssets({
							[wasmUrl]: phpLoaderModule.dependenciesTotalSize,
						});
					},
					emscriptenOptions: {
						instantiateWasm: async (
							imports: any,
							receiveInstance: any
						) => {
							const response = await this.memoizedFetch(wasmUrl, {
								credentials: 'same-origin',
							});
							const wasm = await WebAssembly.instantiateStreaming(
								response as Response,
								imports
							);
							receiveInstance(wasm.instance, wasm.module);
							return {} as any;
						},
					},
				});
			},
			onPHPInstanceCreated: async (php: PHP, { isPrimary }) => {
				/**
				 * The remote runtime has no mail server. Capture sendmail stdin as an
				 * event through a null transport; consumers must relay the message if
				 * they want it delivered.
				 */
				php.setCommandSpawnHandler(
					'sendmail',
					sendmailSpawnHandler(php)
				);

				if (!isPrimary) {
					/**
					 * Secondary PHP instances write through the primary PHP's filesystem.
					 * Their request-end event stays on the secondary instance, so trigger
					 * every active mount journal here after those proxied writes finish.
					 */
					php.addEventListener('request.end', () => {
						for (const [mountpoint, mount] of Object.entries(
							this.opfsMounts
						)) {
							void mount.flush().catch((error) => {
								logger.error(
									`OPFS flush failed after a pooled PHP request at "${mountpoint}"`,
									error
								);
							});
						}
					});
					const pathsToShareBetweenPhpInstances = [
						'/tmp',
						requestHandler.documentRoot,
						'/internal/shared',
						'/internal/symlinks',
						// Runtime-installed tools are shared state. Share their filesystem
						// boundary instead of mounting individual tool directories.
						'/tools',
					];
					const pathsToProxy = pathsToShareBetweenPhpInstances.filter(
						(path) => !isPathToSharedFS(php, path)
					);

					// TODO: Document that this shift is a breaking change.
					// Proxy the filesystem for all secondary PHP instances to
					// the primary one.
					// proxyFileSystem auto-detects legacy PHP from the
					// replica's runtime and skips the PROXYFS mmap patch
					// there, so this call is the same for every PHP
					// version.
					await proxyFileSystem(
						await requestHandler.getPrimaryPhp(),
						php,
						pathsToProxy
					);
				}
				if (withNetworking) {
					await this.networkTransport!.setupMessageHandler(php);
				}
			},
			spawnHandler: sandboxedSpawnHandlerFactory,
			sapiName,
			phpIniEntries,
			pathAliases,
			createFiles: {
				'/internal/shared/ca-bundle.crt': caBundleContent,
				'/internal/shared/mu-plugins': {
					...viewTransitionsWorkaroundMuPlugin(),
					// Legacy PHP can't parse closures at all (even with an
					// early return), so use a minimal compatible stub instead.
					'1-playground-web.php': isLegacyPhp
						? playgroundWebMuPluginPhp52
						: playgroundWebMuPlugin,
					'playground-includes': {
						'wp_http_dummy.php': transportDummy,
						'wp_http_fetch.php': transportFetch,
					},
				},
			},
			getFileNotFoundAction(relativeUri: string) {
				/**
				 * Known remote asset paths are stored as site-relative paths. We
				 * need to remove the site root path prefix (e.g. scope:my-site) from
				 * the request URL's pathname.
				 */
				const siteRelativePath =
					parsedSiteUrl.pathname.length > 0 &&
					relativeUri.startsWith(parsedSiteUrl.pathname)
						? relativeUri.substring(parsedSiteUrl.pathname.length)
						: relativeUri;
				if (!knownRemoteAssetPaths.has(siteRelativePath)) {
					return getFileNotFoundActionForWordPress(siteRelativePath);
				}
				// This path is listed as a remote asset. Mark it as a static file
				// so the service worker knows it can issue a real fetch() to the server.
				return {
					type: 'response',
					response: new PHPResponse(
						404,
						{
							'x-backfill-from': ['remote-host'],
							// Include x-file-type header so remote asset
							// retrieval continues to work for clients
							// running a prior service worker version.
							'x-file-type': ['static'],
						},
						new TextEncoder().encode('404 File not found')
					),
				};
			},
		});

		const primaryPhp = await requestHandler.getPrimaryPhp();
		primaryPhp.requestHandler ??= requestHandler;
		await this.setPrimaryPHP(primaryPhp);
		this.__internal_setRequestHandler(requestHandler);
		this.requestHandler = requestHandler;
		activeRequestHandler = requestHandler;
		return requestHandler;
	}

	protected async finalizeAfterBoot(
		requestHandler: any,
		withNetworking: boolean,
		knownRemoteAssetPaths: Set<string>
	) {
		const primaryPhp = await requestHandler.getPrimaryPhp();
		primaryPhp.requestHandler ??= requestHandler;
		this.requestHandler = requestHandler;
		activeRequestHandler = requestHandler;

		if (withNetworking) {
			/**
			 * Only setup the network transport after WordPress have been installed. Otherwise,
			 * the installer may send a network request to /wp-cron.php, which will fail because
			 * the entire setup around network, SQLite, etc. is not complete yet.
			 */
			await this.networkTransport!.setEnabled(primaryPhp, true);
		}

		// NOTE: We need to derive the loaded WP version or we might assume WP loaded
		// from browser storage is the default version when it is actually something else.
		// Assuming an incorrect WP version would break remote asset retrieval for minified
		// WP builds – we would download the wrong assets pack.
		this.loadedWordPressVersion =
			await getLoadedWordPressVersion(requestHandler);
		if (this.requestedWordPressVersion !== this.loadedWordPressVersion) {
			logger.warn(
				`Loaded WordPress version (${this.loadedWordPressVersion}) differs ` +
					`from requested version (${this.requestedWordPressVersion}).`
			);
		}

		const wpStaticAssetsDir = wpVersionToStaticAssetsDirectory(
			this.loadedWordPressVersion
		);
		const remoteAssetListPath = joinPaths(
			requestHandler.documentRoot,
			'wordpress-remote-asset-paths'
		);
		if (
			wpStaticAssetsDir !== undefined &&
			!primaryPhp.fileExists(remoteAssetListPath)
		) {
			const listUrl = new URL(
				joinPaths(wpStaticAssetsDir, 'wordpress-remote-asset-paths'),
				wordPressSiteUrl
			);
			try {
				const remoteAssetPaths = await fetch(listUrl).then((res) =>
					res.text()
				);
				primaryPhp.writeFile(remoteAssetListPath, remoteAssetPaths);
			} catch {
				logger.warn(
					`Failed to fetch remote asset paths from ${listUrl}`
				);
			}
		}

		if (primaryPhp.isFile(remoteAssetListPath)) {
			const remoteAssetPaths = primaryPhp
				.readFileAsText(remoteAssetListPath)
				.split('\n');
			remoteAssetPaths.forEach((wpRelativePath: string) =>
				knownRemoteAssetPaths.add(joinPaths('/', wpRelativePath))
			);
		}

		this.__internal_setRequestHandler(requestHandler);
	}

	protected override getRequestHandler(required?: true): PHPRequestHandler;
	protected override getRequestHandler(
		required: false
	): PHPRequestHandler | undefined;
	protected override getRequestHandler(required = true) {
		const requestHandler =
			super.getRequestHandler(false) ??
			this.requestHandler ??
			activeRequestHandler;
		if (requestHandler || !required) {
			return requestHandler;
		}
		throw new Error(
			'Playground worker is not connected to a request handler.'
		);
	}

	// NOTE: Version-specific boot methods are implemented in the concrete worker entrypoints

	/**
	 * @returns WordPress module details, including the static assets directory and default theme.
	 */
	async getWordPressModuleDetails() {
		return {
			majorVersion:
				this.loadedWordPressVersion || this.requestedWordPressVersion,
			staticAssetsDirectory: this.loadedWordPressVersion
				? wpVersionToStaticAssetsDirectory(this.loadedWordPressVersion)
				: undefined,
		};
	}

	async getMinifiedWordPressVersions() {
		return {
			all: MinifiedWordPressVersions,
			latest: LatestMinifiedWordPressVersion,
		};
	}

	async hasOpfsMount(mountpoint: string) {
		return hasOwnProperty(this.opfsMounts, mountpoint);
	}

	async mountOpfs(
		options: MountDescriptor,
		onProgress?: SyncProgressCallback
	) {
		const php = this.__internal_getPHP()!;
		await this.mountOpfsIntoPhp(php, options, onProgress);
	}

	async flushOpfs(mountpoint: string) {
		const opfsMount = this.opfsMounts[mountpoint];
		if (opfsMount === undefined) {
			throw new Error(`No OPFS mount found at "${mountpoint}".`);
		}
		await opfsMount.flush();
	}

	/**
	 * Flushes and detaches an OPFS mount.
	 *
	 * On success, clears its tracking. If the final flush fails, keeps the mount
	 * registered for retry and rejects with the original persistence error.
	 * Other unmount failures clear tracking because the mount did not guarantee
	 * that it remained live.
	 */
	async unmountOpfs(mountpoint: string) {
		const unmount = this.unmounts[mountpoint];
		if (
			this.opfsMounts[mountpoint] === undefined ||
			unmount === undefined
		) {
			throw new Error(`No OPFS mount found at "${mountpoint}".`);
		}
		let mountIsStillActive = false;
		try {
			await unmount();
		} catch (error) {
			if (error instanceof MountStillActiveError) {
				// PHP retained its callback and journal. Keep endpoint tracking
				// aligned, but do not expose this internal lifecycle signal.
				mountIsStillActive = true;
				throw error.cause;
			}
			throw error;
		} finally {
			if (!mountIsStillActive) {
				delete this.unmounts[mountpoint];
				delete this.opfsMounts[mountpoint];
			}
		}
	}

	async backfillStaticFilesRemovedFromMinifiedBuild() {
		await backfillStaticFilesRemovedFromMinifiedBuild(
			this.__internal_getPHP()!
		);
	}

	async hasCachedStaticFilesRemovedFromMinifiedBuild() {
		return await hasCachedStaticFilesRemovedFromMinifiedBuild(
			this.__internal_getPHP()!
		);
	}

	// eslint-disable-next-line @typescript-eslint/no-unused-vars
	abstract boot(_: any): Promise<void>;

	/**
	 * Pre-fetch the slow initial burst of wp_update_* requests to greatly
	 * improve the first wp-admin load time.
	 */
	async prefetchUpdateChecks() {
		const primaryPhp = this.__internal_getPHP()!;
		await this.networkTransport!.prefetchUpdateChecks(primaryPhp);
	}

	// These methods are only here for the time traveling Playground demo.
	// Let's consider removing them in the future.

	async journalFSEvents(
		root: string,
		callback: (op: FilesystemOperation) => void
	) {
		return journalFSEvents(this.__internal_getPHP()!, root, callback);
	}

	async replayFSJournal(events: FilesystemOperation[]) {
		return replayFSJournal(this.__internal_getPHP()!, events);
	}

	protected async mountOpfsIntoPhp(
		php: PHP,
		options: MountDescriptor,
		onProgress?: SyncProgressCallback
	) {
		if (
			hasOwnProperty(this.opfsMounts, options.mountpoint) ||
			hasOwnProperty(this.unmounts, options.mountpoint)
		) {
			throw new Error(
				`OPFS mount already exists at "${options.mountpoint}".`
			);
		}
		const handle = await directoryHandleFromMountDevice(options.device);
		let opfsMount: DirectoryHandleMount | undefined;
		const unmount = await php.mount(
			options.mountpoint,
			createDirectoryHandleMountHandler(handle, {
				initialSync: {
					onProgress,
					direction: options.initialSyncDirection,
				},
				durabilityLockName: options.durabilityLockName,
				onMount(mount) {
					opfsMount = mount;
				},
			})
		);
		if (opfsMount === undefined) {
			try {
				await unmount();
			} catch (error) {
				logger.error(error);
			}
			throw new Error(
				`Could not create an OPFS mount at "${options.mountpoint}".`
			);
		}
		this.unmounts[options.mountpoint] = unmount;
		this.opfsMounts[options.mountpoint] = opfsMount;
	}
}

/**
 * Disable view transitions in Google Chrome until
 * https://issues.chromium.org/issues/530704642 is resolved.
 *
 * @see https://github.com/WordPress/wordpress-playground/issues/3845.
 */
function viewTransitionsWorkaroundMuPlugin(): Record<string, string> {
	const userEnforcedTransitions = new URL(
		globalThis.location.href
	).searchParams.has(WITH_ADMIN_TRANSITIONS_PARAM);
	const navigatorObject = globalThis.navigator;
	const brands = navigatorObject
		? (
				navigatorObject as Navigator & {
					userAgentData?: { brands?: Array<{ brand: string }> };
				}
			).userAgentData?.brands
		: undefined;
	// Naive but sufficient browser detection for the crash workaround.
	const isChromiumBasedBrowser = brands
		? brands.some(({ brand }) =>
				[
					'Chromium',
					'Google Chrome',
					'Microsoft Edge',
					'Opera',
				].includes(brand)
			)
		: /\b(?:Chrome|Chromium|Edg|OPR)\//.test(
				navigatorObject?.userAgent || ''
			);

	if (userEnforcedTransitions || !isChromiumBasedBrowser) {
		return {};
	}

	return {
		'0-playground-chrome-view-transitions-workaround.php': `<?php
/**
 * Disable view transitions in Google Chrome until
 * https://issues.chromium.org/issues/530704642 is resolved.
 *
 * @see https://github.com/WordPress/wordpress-playground/issues/3845.
 */
function playground_remove_admin_view_transitions_for_chrome_crash() {
	remove_action( 'admin_print_styles', 'playground_enable_view_transitions', 0 );
}
add_action( 'admin_print_styles', 'playground_remove_admin_view_transitions_for_chrome_crash', -1 );

function playground_dequeue_admin_view_transitions_for_chrome_crash() {
	if ( ! function_exists( 'wp_dequeue_style' ) || ! function_exists( 'wp_deregister_style' ) ) {
		return;
	}

	wp_dequeue_style( 'wp-view-transitions-admin' );
	wp_deregister_style( 'wp-view-transitions-admin' );
}
add_action( 'admin_enqueue_scripts', 'playground_dequeue_admin_view_transitions_for_chrome_crash', PHP_INT_MAX );
`,
	};
}

function createNullPrototypeRecord<T>() {
	return Object.create(null) as Record<string, T>;
}

function hasOwnProperty(object: object, property: PropertyKey) {
	return Object.prototype.hasOwnProperty.call(object, property);
}