@php-wasm/web 0.7.1 → 0.7.4

package/index.d.ts

@@ -59,6 +59,7 @@ 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;
 	/**
@@ -437,23 +438,57 @@ export interface ListFilesOptions {
 	 */
 	prependPath: boolean;
 }
-declare const SupportedPHPVersions: readonly [
-	"8.3",
-	"8.2",
-	"8.1",
-	"8.0",
-	"7.4",
-	"7.3",
-	"7.2",
-	"7.1",
-	"7.0"
-];
-export type SupportedPHPVersion = (typeof SupportedPHPVersions)[number];
+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 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`.
@@ -468,18 +503,47 @@ export interface PHPRequestHandlerConfiguration {
 	 */
 	rewriteRules?: RewriteRule[];
 }
-declare class PHPRequestHandler {
-	#private;
-	rewriteRules: RewriteRule[];
+export type PHPRequestHandlerFactoryArgs<PHP extends BasePHP> = PHPFactoryOptions & {
+	requestHandler: PHPRequestHandler<PHP>;
+};
+export type PHPRequestHandlerConfiguration<PHP extends BasePHP> = BaseConfiguration & ({
 	/**
-	 * The PHP instance
+	 * 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.
 	 */
-	php: BasePHP;
+	processManager: PHPProcessManager<PHP>;
+} | {
+	phpFactory: (requestHandler: PHPRequestHandlerFactoryArgs<PHP>) => Promise<PHP>;
+	/**
+	 * The maximum number of PHP instances that can exist at
+	 * the same time.
+	 */
+	maxPhpInstances?: number;
+});
+declare class PHPRequestHandler<PHP extends BasePHP> {
+	#private;
+	rewriteRules: RewriteRule[];
+	processManager: PHPProcessManager<PHP>;
 	/**
+	 * 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.
@@ -496,7 +560,6 @@ declare class PHPRequestHandler {
 	 * @returns The relative path.
 	 */
 	internalUrlToPath(internalUrl: string): string;
-	get isRequestRunning(): boolean;
 	/**
 	 * The absolute URL of this PHPRequestHandler instance.
 	 */
@@ -556,57 +619,11 @@ declare class PHPRequestHandler {
 	 */
 	request(request: PHPRequest): Promise<PHPResponse>;
 }
-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>;
-}
 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.
@@ -617,9 +634,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;
@@ -644,7 +661,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>;
@@ -683,10 +703,100 @@ 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>;
+}
+declare const SupportedPHPVersions: readonly [
+	"8.3",
+	"8.2",
+	"8.1",
+	"8.0",
+	"7.4",
+	"7.3",
+	"7.2",
+	"7.1",
+	"7.0"
+];
+export type SupportedPHPVersion = (typeof SupportedPHPVersions)[number];
 export interface PHPWebLoaderOptions {
 	emscriptenOptions?: EmscriptenOptions;
-	requestHandler?: PHPRequestHandlerConfiguration;
 	onPhpLoaderModuleLoaded?: (module: PHPLoaderModule) => void;
 	/** @deprecated To be replaced with `extensions` in the future */
 	loadAllExtensions?: boolean;
@@ -715,26 +825,35 @@ declare class EmscriptenDownloadMonitor extends EventTarget {
 /**
  * A PHP client that can be used to run PHP code in the browser.
  */
-export declare class WebPHPEndpoint implements IsomorphicLocalPHP {
+export 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>;