@php-wasm/universal 0.7.0 → 0.7.3

package/lib/base-php.d.ts

@@ -1,8 +1,8 @@
-import { PHPRequestHandler, PHPRequestHandlerConfiguration } from './php-request-handler';
 import { PHPResponse } from './php-response';
 import type { PHPRuntimeId } from './load-php-runtime';
 import { IsomorphicLocalPHP, MessageListener, PHPRequest, PHPRequestHeaders, PHPRunOptions, RmDirOptions, ListFilesOptions, SpawnHandler, PHPEventListener, PHPEvent } from './universal-php';
 import { Semaphore } from '../../../util/src/index.ts';
+import { PHPRequestHandler } from './php-request-handler';
 export declare const __private__dont__use: unique symbol;
 export declare class PHPExecutionFailureError extends Error {
     response: PHPResponse;
@@ -17,10 +17,10 @@ export declare class PHPExecutionFailureError extends Error {
  * It exposes a minimal set of methods to run PHP scripts and to
  * interact with the PHP filesystem.
  */
-export declare abstract class BasePHP implements IsomorphicLocalPHP {
+export 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.
@@ -31,9 +31,9 @@ export 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;
@@ -58,7 +58,10 @@ export 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>;
@@ -97,6 +100,7 @@ export declare abstract class BasePHP implements IsomorphicLocalPHP {
      */
     hotSwapPHPRuntime(runtime: number, cwd?: string): void;
     exit(code?: number): void;
+    [Symbol.dispose](): void;
 }
 export declare function normalizeHeaders(headers: PHPRequestHeaders): PHPRequestHeaders;
 type EmscriptenFS = any;

package/lib/index.d.ts

@@ -1,8 +1,11 @@
 export type { IsomorphicLocalPHP, IsomorphicRemotePHP, MessageListener, PHPOutput, PHPRunOptions, UniversalPHP, ListFilesOptions, RmDirOptions, PHPEvent, PHPEventListener, HTTPMethod, PHPRequest, PHPRequestHeaders, SpawnHandler, } from './universal-php';
 export { UnhandledRejectionsTarget } from './wasm-error-reporting';
+export { HttpCookieStore } from './http-cookie-store';
 export type { IteratePhpFilesOptions as IterateFilesOptions } from './iterate-files';
 export { iteratePhpFiles as iterateFiles } from './iterate-files';
 export { writeFilesStreamToPhp } from './write-files-stream-to-php';
+export { PHPProcessManager } from './php-process-manager';
+export type { MaxPhpInstancesError, PHPFactory, PHPFactoryOptions, ProcessManagerOptions, SpawnedPHP, } from './php-process-manager';
 export { PHPResponse } from './php-response';
 export type { PHPResponseData } from './php-response';
 export type { ErrnoError } from './rethrow-file-system-error';

package/lib/php-process-manager.d.ts

@@ -0,0 +1,104 @@
+import { BasePHP } from './base-php';
+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;
+}
+export declare class MaxPhpInstancesError extends Error {
+    constructor(limit: number);
+}
+/**
+ * A PHP Process manager.
+ *
+ * Maintains:
+ * * A single "primary" PHP instance that's never killed – it contains the
+ *   reference filesystem used by all other PHP instances.
+ * * A pool of disposable PHP instances that are spawned to handle a single
+ *   request and reaped immediately after.
+ *
+ * When a new request comes in, PHPProcessManager yields the idle instance to handle it,
+ * and immediately starts initializing a new idle instance. In other words, for n concurrent
+ * requests, there are at most n+1 PHP instances running at the same time.
+ *
+ * A slight nuance is that the first idle instance is not initialized until the first
+ * concurrent request comes in. This is because many use-cases won't involve parallel
+ * requests and, for those, we can avoid eagerly spinning up a second PHP instance.
+ *
+ * This strategy is inspired by Cowboy, an Erlang HTTP server. Handling a single extra
+ * request can happen immediately, while handling multiple extra requests requires
+ * extra time to spin up a few PHP instances. This is a more resource-friendly tradeoff
+ * than keeping 5 idle instances at all times.
+ */
+export 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>;
+}

package/lib/php-request-handler.d.ts

@@ -1,11 +1,12 @@
 import { BasePHP } from './base-php';
 import { PHPResponse } from './php-response';
 import { PHPRequest } from './universal-php';
+import { PHPFactoryOptions, PHPProcessManager } from './php-process-manager';
 export type RewriteRule = {
     match: RegExp;
     replacement: string;
 };
-export interface PHPRequestHandlerConfiguration {
+interface BaseConfiguration {
     /**
      * The directory in the PHP filesystem where the server will look
      * for the files to serve. Default: `/var/www`.
@@ -20,6 +21,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.
  *
@@ -74,18 +99,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.
@@ -102,7 +132,6 @@ export declare class PHPRequestHandler {
      * @returns The relative path.
      */
     internalUrlToPath(internalUrl: string): string;
-    get isRequestRunning(): boolean;
     /**
      * The absolute URL of this PHPRequestHandler instance.
      */
@@ -187,3 +216,4 @@ export declare function seemsLikeAPHPRequestHandlerPath(path: string): boolean;
  * @returns The path with the rules applied.
  */
 export declare function applyRewriteRules(path: string, rules: RewriteRule[]): string;
+export {};

package/lib/php-response.d.ts

@@ -41,6 +41,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;
     /**

package/lib/universal-php.d.ts

@@ -293,7 +293,13 @@ 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>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@php-wasm/universal",
-	"version": "0.7.0",
+	"version": "0.7.3",
 	"description": "PHP.wasm – emscripten bindings for PHP",
 	"repository": {
 		"type": "git",
@@ -36,7 +36,7 @@
 	"main": "./index.cjs",
 	"module": "./index.js",
 	"license": "GPL-2.0-or-later",
-	"gitHead": "c5eba3d709f2821c4303521e8c81b962e3bcca23",
+	"gitHead": "e8fedf92bbead5cec963c8d6976e7143d8e68721",
 	"engines": {
 		"node": ">=18.18.0",
 		"npm": ">=8.11.0"