@php-wasm/node 0.7.1 → 0.7.3

package/index.d.ts

@@ -36,6 +36,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;
 	/**
@@ -414,23 +415,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`.
@@ -445,18 +480,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 & ({
+	/**
+	 * 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 PHP instance
+	 * The maximum number of PHP instances that can exist at
+	 * the same time.
 	 */
-	php: BasePHP;
+	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.
@@ -473,7 +537,6 @@ declare class PHPRequestHandler {
 	 * @returns The relative path.
 	 */
 	internalUrlToPath(internalUrl: string): string;
-	get isRequestRunning(): boolean;
 	/**
 	 * The absolute URL of this PHPRequestHandler instance.
 	 */
@@ -533,57 +596,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.
@@ -594,9 +611,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;
@@ -621,7 +638,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>;
@@ -660,12 +680,102 @@ 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 declare function getPHPLoaderModule(version?: SupportedPHPVersion): Promise<PHPLoaderModule>;
 export declare function withNetworking(phpModuleArgs?: EmscriptenOptions): Promise<EmscriptenOptions>;
 export interface PHPLoaderOptions {
 	emscriptenOptions?: EmscriptenOptions;
-	requestHandler?: PHPRequestHandlerConfiguration;
 }
 export type MountSettings = {
 	root: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@php-wasm/node",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "PHP.wasm for Node.js",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
   "license": "GPL-2.0-or-later",
   "main": "index.cjs",
   "types": "index.d.ts",
-  "gitHead": "ed0ec39040ab4cd69dc48a8eac157436b30f9d55",
+  "gitHead": "e8fedf92bbead5cec963c8d6976e7143d8e68721",
   "engines": {
     "node": ">=18.18.0",
     "npm": ">=8.11.0"
@@ -37,8 +37,9 @@
     "comlink": "^4.4.1",
     "ws": "8.13.0",
     "yargs": "17.7.2",
-    "@php-wasm/node-polyfills": "0.7.1",
-    "@php-wasm/universal": "0.7.1",
-    "@php-wasm/util": "0.7.1"
+    "@php-wasm/node-polyfills": "0.7.3",
+    "@php-wasm/universal": "0.7.3",
+    "@php-wasm/logger": "0.7.3",
+    "@php-wasm/util": "0.7.3"
   }
 }