@wp-playground/client 0.7.0 → 0.7.3

package/index.d.ts

@@ -183,6 +183,7 @@ export declare class PHPResponse implements PHPResponseData {
 	/** @inheritDoc */
 	readonly httpStatusCode: number;
 	constructor(httpStatusCode: number, headers: Record<string, string[]>, body: ArrayBuffer, errors?: string, exitCode?: number);
+	static forHttpCode(httpStatusCode: number, text?: string): PHPResponse;
 	static fromRawData(data: PHPResponseData): PHPResponse;
 	toRawData(): PHPResponseData;
 	/**
@@ -487,7 +488,13 @@ export type ChildProcess = EventEmitter & {
 	stderr: EventEmitter;
 };
 export type SpawnHandler = (command: string, args: string[]) => ChildProcess;
-export type IsomorphicRemotePHP = Remote<IsomorphicLocalPHP>;
+/**
+ * The omited methods must either be called synchronously before
+ * the PHP internal state is initialized, or with a complex argument
+ * that can't be serialized over a remote connection. Therefeore,
+ * they don't make sense in a remote PHP instance.
+ */
+export type IsomorphicRemotePHP = Remote<Omit<IsomorphicLocalPHP, "setSapiName" | "setPhpIniEntry" | "setPhpIniPath">>;
 export type UniversalPHP = IsomorphicLocalPHP | IsomorphicRemotePHP;
 export type HTTPMethod = "GET" | "POST" | "HEAD" | "OPTIONS" | "PATCH" | "PUT" | "DELETE";
 export type PHPRequestHeaders = Record<string, string>;
@@ -574,39 +581,60 @@ export interface ListFilesOptions {
 	 */
 	prependPath: boolean;
 }
-/**
- * Emscripten's filesystem-related Exception.
- *
- * @see https://emscripten.org/docs/api_reference/Filesystem-API.html
- * @see https://github.com/emscripten-core/emscripten/blob/main/system/lib/libc/musl/arch/emscripten/bits/errno.h
- * @see https://github.com/emscripten-core/emscripten/blob/38eedc630f17094b3202fd48ac0c2c585dbea31e/system/include/wasi/api.h#L336
- */
-export interface ErrnoError extends Error {
-	node?: any;
-	errno: number;
-	message: string;
+export type RuntimeType = "NODE" | "WEB" | "WORKER";
+export type PHPRuntimeId = number;
+export type PHPRuntime = any;
+export type PHPLoaderModule = {
+	dependencyFilename: string;
+	dependenciesTotalSize: number;
+	init: (jsRuntime: string, options: EmscriptenOptions) => PHPRuntime;
+};
+export type EmscriptenOptions = {
+	onAbort?: (message: string) => void;
+	/**
+	 * Set to true for debugging tricky WebAssembly errors.
+	 */
+	debug?: boolean;
+	ENV?: Record<string, string>;
+	locateFile?: (path: string) => string;
+	noInitialRun?: boolean;
+	print?: (message: string) => void;
+	printErr?: (message: string) => void;
+	quit?: (status: number, toThrow: any) => void;
+	onRuntimeInitialized?: () => void;
+	monitorRunDependencies?: (left: number) => void;
+	onMessage?: (listener: EmscriptenMessageListener) => void;
+	instantiateWasm?: (info: WebAssembly.Imports, receiveInstance: (instance: WebAssembly.Instance, module: WebAssembly.Module) => void) => void;
+} & Record<string, any>;
+export type EmscriptenMessageListener = (type: string, data: string) => void;
+export interface SemaphoreOptions {
+	/**
+	 * The maximum number of concurrent locks.
+	 */
+	concurrency: number;
+	/**
+	 * The maximum time to wait for a lock to become available.
+	 */
+	timeout?: number;
 }
-export declare const SupportedPHPVersions: readonly [
-	"8.3",
-	"8.2",
-	"8.1",
-	"8.0",
-	"7.4",
-	"7.3",
-	"7.2",
-	"7.1",
-	"7.0"
-];
-export declare const LatestSupportedPHPVersion: "8.3";
-export declare const SupportedPHPVersionsList: string[];
-export type SupportedPHPVersion = (typeof SupportedPHPVersions)[number];
-export type SupportedPHPExtension = "iconv" | "mbstring" | "xml-bundle" | "gd";
-export type SupportedPHPExtensionBundle = "kitchen-sink" | "light";
+declare class Semaphore {
+	private _running;
+	private concurrency;
+	private timeout?;
+	private queue;
+	constructor({ concurrency, timeout }: SemaphoreOptions);
+	get remaining(): number;
+	get running(): number;
+	acquire(): Promise<() => void>;
+	run<T>(fn: () => T | Promise<T>): Promise<T>;
+}
+export declare function phpVar(value: unknown): string;
+export declare function phpVars<T extends Record<string, unknown>>(vars: T): Record<keyof T, string>;
 export type RewriteRule = {
 	match: RegExp;
 	replacement: string;
 };
-export interface PHPRequestHandlerConfiguration {
+export interface BaseConfiguration {
 	/**
 	 * The directory in the PHP filesystem where the server will look
 	 * for the files to serve. Default: `/var/www`.
@@ -621,6 +649,30 @@ export interface PHPRequestHandlerConfiguration {
 	 */
 	rewriteRules?: RewriteRule[];
 }
+export type PHPRequestHandlerFactoryArgs<PHP extends BasePHP> = PHPFactoryOptions & {
+	requestHandler: PHPRequestHandler<PHP>;
+};
+export type PHPRequestHandlerConfiguration<PHP extends BasePHP> = BaseConfiguration & ({
+	/**
+	 * PHPProcessManager is required because the request handler needs
+	 * to make a decision for each request.
+	 *
+	 * Static assets are served using the primary PHP's filesystem, even
+	 * when serving 100 static files concurrently. No new PHP interpreter
+	 * is ever created as there's no need for it.
+	 *
+	 * Dynamic PHP requests, however, require grabbing an available PHP
+	 * interpreter, and that's where the PHPProcessManager comes in.
+	 */
+	processManager: PHPProcessManager<PHP>;
+} | {
+	phpFactory: (requestHandler: PHPRequestHandlerFactoryArgs<PHP>) => Promise<PHP>;
+	/**
+	 * The maximum number of PHP instances that can exist at
+	 * the same time.
+	 */
+	maxPhpInstances?: number;
+});
 /**
  * Handles HTTP requests using PHP runtime as a backend.
  *
@@ -675,18 +727,23 @@ export interface PHPRequestHandlerConfiguration {
  * // "Hi from PHP!"
  * ```
  */
-export declare class PHPRequestHandler {
+export declare class PHPRequestHandler<PHP extends BasePHP> {
 	#private;
 	rewriteRules: RewriteRule[];
+	processManager: PHPProcessManager<PHP>;
 	/**
-	 * The PHP instance
-	 */
-	php: BasePHP;
-	/**
+	 * The request handler needs to decide whether to serve a static asset or
+	 * run the PHP interpreter. For static assets it should just reuse the primary
+	 * PHP even if there's 50 concurrent requests to serve. However, for
+	 * dynamic PHP requests, it needs to grab an available interpreter.
+	 * Therefore, it cannot just accept PHP as an argument as serving requests
+	 * requires access to ProcessManager.
+	 *
 	 * @param  php    - The PHP instance.
 	 * @param  config - Request Handler configuration.
 	 */
-	constructor(php: BasePHP, config?: PHPRequestHandlerConfiguration);
+	constructor(config: PHPRequestHandlerConfiguration<PHP>);
+	getPrimaryPhp(): Promise<PHP>;
 	/**
 	 * Converts a path to an absolute URL based at the PHPRequestHandler
 	 * root.
@@ -703,7 +760,6 @@ export declare class PHPRequestHandler {
 	 * @returns The relative path.
 	 */
 	internalUrlToPath(internalUrl: string): string;
-	get isRequestRunning(): boolean;
 	/**
 	 * The absolute URL of this PHPRequestHandler instance.
 	 */
@@ -763,60 +819,11 @@ export declare class PHPRequestHandler {
 	 */
 	request(request: PHPRequest): Promise<PHPResponse>;
 }
-export type RuntimeType = "NODE" | "WEB" | "WORKER";
-export type PHPRuntimeId = number;
-export type PHPRuntime = any;
-export type PHPLoaderModule = {
-	dependencyFilename: string;
-	dependenciesTotalSize: number;
-	init: (jsRuntime: string, options: EmscriptenOptions) => PHPRuntime;
-};
-export type EmscriptenOptions = {
-	onAbort?: (message: string) => void;
-	/**
-	 * Set to true for debugging tricky WebAssembly errors.
-	 */
-	debug?: boolean;
-	ENV?: Record<string, string>;
-	locateFile?: (path: string) => string;
-	noInitialRun?: boolean;
-	print?: (message: string) => void;
-	printErr?: (message: string) => void;
-	quit?: (status: number, toThrow: any) => void;
-	onRuntimeInitialized?: () => void;
-	monitorRunDependencies?: (left: number) => void;
-	onMessage?: (listener: EmscriptenMessageListener) => void;
-	instantiateWasm?: (info: WebAssembly.Imports, receiveInstance: (instance: WebAssembly.Instance, module: WebAssembly.Module) => void) => void;
-} & Record<string, any>;
-export type EmscriptenMessageListener = (type: string, data: string) => void;
-export interface SemaphoreOptions {
-	/**
-	 * The maximum number of concurrent locks.
-	 */
-	concurrency: number;
-	/**
-	 * The maximum time to wait for a lock to become available.
-	 */
-	timeout?: number;
-}
-declare class Semaphore {
-	private _running;
-	private concurrency;
-	private timeout?;
-	private queue;
-	constructor({ concurrency, timeout }: SemaphoreOptions);
-	get remaining(): number;
-	get running(): number;
-	acquire(): Promise<() => void>;
-	run<T>(fn: () => T | Promise<T>): Promise<T>;
-}
-export declare function phpVar(value: unknown): string;
-export declare function phpVars<T extends Record<string, unknown>>(vars: T): Record<keyof T, string>;
 declare const __private__dont__use: unique symbol;
-declare abstract class BasePHP implements IsomorphicLocalPHP {
+declare abstract class BasePHP implements IsomorphicLocalPHP, Disposable {
 	#private;
 	protected [__private__dont__use]: any;
-	requestHandler?: PHPRequestHandler;
+	requestHandler?: PHPRequestHandler<any>;
 	/**
 	 * An exclusive lock that prevent multiple requests from running at
 	 * the same time.
@@ -827,9 +834,9 @@ declare abstract class BasePHP implements IsomorphicLocalPHP {
 	 *
 	 * @internal
 	 * @param  PHPRuntime - Optional. PHP Runtime ID as initialized by loadPHPRuntime.
-	 * @param  serverOptions - Optional. Options for the PHPRequestHandler. If undefined, no request handler will be initialized.
+	 * @param  requestHandlerOptions - Optional. Options for the PHPRequestHandler. If undefined, no request handler will be initialized.
 	 */
-	constructor(PHPRuntimeId?: PHPRuntimeId, serverOptions?: PHPRequestHandlerConfiguration);
+	constructor(PHPRuntimeId?: PHPRuntimeId);
 	addEventListener(eventType: PHPEvent["type"], listener: PHPEventListener): void;
 	removeEventListener(eventType: PHPEvent["type"], listener: PHPEventListener): void;
 	dispatchEvent<Event extends PHPEvent>(event: Event): void;
@@ -854,7 +861,10 @@ declare abstract class BasePHP implements IsomorphicLocalPHP {
 	setPhpIniEntry(key: string, value: string): void;
 	/** @inheritDoc */
 	chdir(path: string): void;
-	/** @inheritDoc */
+	/**
+	 * Do not use. Use new PHPRequestHandler() instead.
+	 * @deprecated
+	 */
 	request(request: PHPRequest): Promise<PHPResponse>;
 	/** @inheritDoc */
 	run(request: PHPRunOptions): Promise<PHPResponse>;
@@ -893,7 +903,114 @@ declare abstract class BasePHP implements IsomorphicLocalPHP {
 	 */
 	hotSwapPHPRuntime(runtime: number, cwd?: string): void;
 	exit(code?: number): void;
+	[Symbol.dispose](): void;
 }
+export type PHPFactoryOptions = {
+	isPrimary: boolean;
+};
+export type PHPFactory<PHP extends BasePHP> = (options: PHPFactoryOptions) => Promise<PHP>;
+export interface ProcessManagerOptions<PHP extends BasePHP> {
+	/**
+	 * The maximum number of PHP instances that can exist at
+	 * the same time.
+	 */
+	maxPhpInstances?: number;
+	/**
+	 * The number of milliseconds to wait for a PHP instance when
+	 * we have reached the maximum number of PHP instances and
+	 * cannot spawn a new one. If the timeout is reached, we assume
+	 * all the PHP instances are deadlocked and a throw MaxPhpInstancesError.
+	 *
+	 * Default: 5000
+	 */
+	timeout?: number;
+	/**
+	 * The primary PHP instance that's never killed. This instance
+	 * contains the reference filesystem used by all other PHP instances.
+	 */
+	primaryPhp?: PHP;
+	/**
+	 * A factory function used for spawning new PHP instances.
+	 */
+	phpFactory?: PHPFactory<PHP>;
+}
+export interface SpawnedPHP<PHP extends BasePHP> {
+	php: PHP;
+	reap: () => void;
+}
+declare class PHPProcessManager<PHP extends BasePHP> implements AsyncDisposable {
+	private primaryPhp?;
+	private primaryIdle;
+	private nextInstance;
+	/**
+	 * All spawned PHP instances, including the primary PHP instance.
+	 * Used for bookkeeping and reaping all instances on dispose.
+	 */
+	private allInstances;
+	private phpFactory?;
+	private maxPhpInstances;
+	private semaphore;
+	constructor(options?: ProcessManagerOptions<PHP>);
+	/**
+	 * Get the primary PHP instance.
+	 *
+	 * If the primary PHP instance is not set, it will be spawned
+	 * using the provided phpFactory.
+	 *
+	 * @throws {Error} when called twice before the first call is resolved.
+	 */
+	getPrimaryPhp(): Promise<PHP>;
+	/**
+	 * Get a PHP instance.
+	 *
+	 * It could be either the primary PHP instance, an idle disposable PHP instance,
+	 * or a newly spawned PHP instance – depending on the resource availability.
+	 *
+	 * @throws {MaxPhpInstancesError} when the maximum number of PHP instances is reached
+	 *                                and the waiting timeout is exceeded.
+	 */
+	acquirePHPInstance(): Promise<SpawnedPHP<PHP>>;
+	/**
+	 * Initiated spawning of a new PHP instance.
+	 * This function is synchronous on purpose – it needs to synchronously
+	 * add the spawn promise to the allInstances array without waiting
+	 * for PHP to spawn.
+	 */
+	private spawn;
+	/**
+	 * Actually acquires the lock and spawns a new PHP instance.
+	 */
+	private doSpawn;
+	[Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Emscripten's filesystem-related Exception.
+ *
+ * @see https://emscripten.org/docs/api_reference/Filesystem-API.html
+ * @see https://github.com/emscripten-core/emscripten/blob/main/system/lib/libc/musl/arch/emscripten/bits/errno.h
+ * @see https://github.com/emscripten-core/emscripten/blob/38eedc630f17094b3202fd48ac0c2c585dbea31e/system/include/wasi/api.h#L336
+ */
+export interface ErrnoError extends Error {
+	node?: any;
+	errno: number;
+	message: string;
+}
+export declare const SupportedPHPVersions: readonly [
+	"8.3",
+	"8.2",
+	"8.1",
+	"8.0",
+	"7.4",
+	"7.3",
+	"7.2",
+	"7.1",
+	"7.0"
+];
+export declare const LatestSupportedPHPVersion: "8.3";
+export declare const SupportedPHPVersionsList: string[];
+export type SupportedPHPVersion = (typeof SupportedPHPVersions)[number];
+export type SupportedPHPExtension = "iconv" | "mbstring" | "xml-bundle" | "gd";
+export type SupportedPHPExtensionBundle = "kitchen-sink" | "light";
 export declare const ResourceTypes: readonly [
 	"vfs",
 	"literal",
@@ -1569,6 +1686,7 @@ export interface RunPHPWithOptionsStep {
  */
 export declare const runPHPWithOptions: StepHandler<RunPHPWithOptionsStep>;
 /**
+ * @private
  * @inheritDoc request
  * @needsLogin
  * @hasRunnableExample
@@ -2045,7 +2163,6 @@ export type WithAPIState = {
 export type RemoteAPI<T> = Comlink.Remote<T> & WithAPIState;
 export interface PHPWebLoaderOptions {
 	emscriptenOptions?: EmscriptenOptions;
-	requestHandler?: PHPRequestHandlerConfiguration;
 	onPhpLoaderModuleLoaded?: (module: PHPLoaderModule) => void;
 	/** @deprecated To be replaced with `extensions` in the future */
 	loadAllExtensions?: boolean;
@@ -2066,26 +2183,35 @@ declare class WebPHP extends BasePHP {
 	static load(phpVersion: SupportedPHPVersion, options?: PHPWebLoaderOptions): Promise<WebPHP>;
 	static loadRuntime(phpVersion: SupportedPHPVersion, options?: PHPWebLoaderOptions): Promise<number>;
 }
-declare class WebPHPEndpoint implements IsomorphicLocalPHP {
+declare class WebPHPEndpoint implements Omit<IsomorphicLocalPHP, "setSapiName" | "setPhpIniEntry" | "setPhpIniPath"> {
 	/** @inheritDoc @php-wasm/universal!RequestHandler.absoluteUrl  */
 	absoluteUrl: string;
 	/** @inheritDoc @php-wasm/universal!RequestHandler.documentRoot  */
 	documentRoot: string;
 	/** @inheritDoc */
-	constructor(php: BasePHP, monitor?: EmscriptenDownloadMonitor);
-	/** @inheritDoc @php-wasm/universal!RequestHandler.pathToInternalUrl  */
+	constructor(requestHandler: PHPRequestHandler<WebPHP>, monitor?: EmscriptenDownloadMonitor);
+	/**
+	 * @internal
+	 * @deprecated
+	 * Do not use this method directly in the code consuming
+	 * the web API. It will change or even be removed without
+	 * a warning.
+	 */
+	protected __internal_getPHP(): WebPHP | undefined;
+	setPrimaryPHP(php: WebPHP): Promise<void>;
+	/** @inheritDoc @php-wasm/universal!PHPRequestHandler.pathToInternalUrl  */
 	pathToInternalUrl(path: string): string;
-	/** @inheritDoc @php-wasm/universal!RequestHandler.internalUrlToPath  */
+	/** @inheritDoc @php-wasm/universal!PHPRequestHandler.internalUrlToPath  */
 	internalUrlToPath(internalUrl: string): string;
 	/**
 	 * The onDownloadProgress event listener.
 	 */
 	onDownloadProgress(callback: (progress: CustomEvent<ProgressEvent>) => void): Promise<void>;
 	/** @inheritDoc @php-wasm/universal!IsomorphicLocalPHP.mv  */
-	mv(fromPath: string, toPath: string): void;
+	mv(fromPath: string, toPath: string): Promise<void>;
 	/** @inheritDoc @php-wasm/universal!IsomorphicLocalPHP.rmdir  */
-	rmdir(path: string, options?: RmDirOptions): void;
-	/** @inheritDoc @php-wasm/universal!RequestHandler.request */
+	rmdir(path: string, options?: RmDirOptions): Promise<void>;
+	/** @inheritDoc @php-wasm/universal!PHPRequestHandler.request */
 	request(request: PHPRequest): Promise<PHPResponse>;
 	/** @inheritDoc @php-wasm/web!WebPHP.run */
 	run(request: PHPRunOptions): Promise<PHPResponse>;
@@ -2124,6 +2250,13 @@ declare class WebPHPEndpoint implements IsomorphicLocalPHP {
 	/** @inheritDoc @php-wasm/web!WebPHP.removeEventListener */
 	removeEventListener(eventType: PHPEvent["type"], listener: PHPEventListener): void;
 }
+export type SyncProgress = {
+	/** The number of files that have been synced. */
+	files: number;
+	/** The number of all files that need to be synced. */
+	total: number;
+};
+export type SyncProgressCallback = (progress: SyncProgress) => void;
 /**
  * Represents the type of node in PHP file system.
  */
@@ -2173,13 +2306,6 @@ export type RenameOperation = {
 	nodeType: FSNodeType;
 };
 export type FilesystemOperation = CreateOperation | UpdateFileOperation | DeleteOperation | RenameOperation;
-export type SyncProgress = {
-	/** The number of files that have been synced. */
-	files: number;
-	/** The number of all files that need to be synced. */
-	total: number;
-};
-export type SyncProgressCallback = (progress: SyncProgress) => void;
 declare class PlaygroundWorkerEndpoint extends WebPHPEndpoint {
 	/**
 	 * A string representing the scope of the Playground instance.
@@ -2189,11 +2315,7 @@ declare class PlaygroundWorkerEndpoint extends WebPHPEndpoint {
 	 * A string representing the version of WordPress being used.
 	 */
 	wordPressVersion: string;
-	/**
-	 * A string representing the version of PHP being used.
-	 */
-	phpVersion: string;
-	constructor(php: WebPHP, monitor: EmscriptenDownloadMonitor, scope: string, wordPressVersion: string, phpVersion: string);
+	constructor(requestHandler: PHPRequestHandler<WebPHP>, monitor: EmscriptenDownloadMonitor, scope: string, wordPressVersion: string);
 	/**
 	 * @returns WordPress module details, including the static assets directory and default theme.
 	 */