@php-wasm/universal 3.0.53 → 3.1.0

package/lib/api.d.ts

@@ -1,4 +1,6 @@
-import { type NodeEndpoint, type Remote, type IsomorphicMessagePort } from './comlink-sync';
+import { releaseProxy, type NodeEndpoint as NodeWorker, type Remote, type IsomorphicMessagePort, type ProxyMethods } from './comlink-sync';
+import { type NodeProcess } from './comlink-node-process-adapter';
+export declare const releaseApiProxy: typeof releaseProxy;
 export type WithAPIState = {
     /**
      * Resolves to true when the remote API is ready for
@@ -11,9 +13,9 @@ export type WithAPIState = {
      */
     isReady: () => Promise<void>;
 };
-export type RemoteAPI<T> = Remote<T> & WithAPIState;
+export type RemoteAPI<T> = Remote<T> & ProxyMethods & WithAPIState;
 export declare function consumeAPISync<APIType>(remote: IsomorphicMessagePort): Promise<APIType>;
-export declare function consumeAPI<APIType>(remote: Worker | Window | NodeEndpoint, context?: undefined | EventTarget): RemoteAPI<APIType>;
+export declare function consumeAPI<APIType>(remote: Worker | Window | NodeWorker | NodeProcess, context?: undefined | EventTarget): RemoteAPI<APIType>;
 export type PublicAPI<Methods, PipedAPI = unknown> = RemoteAPI<Methods & PipedAPI>;
-export declare function exposeAPI<Methods, PipedAPI>(apiMethods?: Methods, pipedApi?: PipedAPI, targetWorker?: NodeEndpoint): [() => void, (e: Error) => void, PublicAPI<Methods, PipedAPI>];
+export declare function exposeAPI<Methods, PipedAPI>(apiMethods?: Methods, pipedApi?: PipedAPI, targetWorker?: MessagePort | NodeWorker | NodeProcess): [() => void, (e: Error) => void, PublicAPI<Methods, PipedAPI>];
 export declare function exposeSyncAPI<Methods>(apiMethods: Methods, port: IsomorphicMessagePort): Promise<[() => void, (e: Error) => void, Methods]>;

package/lib/comlink-node-process-adapter.d.ts

@@ -0,0 +1,7 @@
+import type { Endpoint } from './comlink-sync';
+export interface NodeProcess {
+    send: (...args: any[]) => unknown;
+    addListener: (type: string, listener: EventListenerOrEventListenerObject) => void;
+    removeListener: (type: string, listener: EventListenerOrEventListenerObject) => void;
+}
+export declare function nodeProcessEndpoint(worker?: NodeProcess): Endpoint;

package/lib/emscripten-types.d.ts

@@ -116,7 +116,7 @@ export declare namespace Emscripten {
         }
         interface Mount {
             type: Emscripten.FileSystemType;
-            opts: object;
+            opts: Record<string, any>;
             mountpoint: string;
             mounts: Mount[];
             root: FSNode;
@@ -145,6 +145,7 @@ export declare namespace Emscripten {
             write: boolean;
             readonly isFolder: boolean;
             readonly isDevice: boolean;
+            readonly isSharedFS?: boolean;
         }
         interface ErrnoError extends Error {
             name: 'ErronoError';
@@ -220,6 +221,7 @@ export declare namespace Emscripten {
     export const MEMFS: Emscripten.FileSystemType;
     export const NODEFS: Emscripten.FileSystemType;
     export const IDBFS: Emscripten.FileSystemType;
+    export const PROXYFS: Emscripten.FileSystemType;
     type StringToType<R> = R extends Emscripten.JSType ? {
         number: number;
         string: string;

package/lib/file-lock-interval-tree.d.ts

@@ -0,0 +1,38 @@
+import type { ByteRange, LockedRange, RequestedRangeLock } from './file-lock-manager';
+export declare class FileLockIntervalTree {
+    private root;
+    isEmpty(): boolean;
+    /**
+     * Insert a new locked range into the tree
+     */
+    insert(range: LockedRange): void;
+    /**
+     * Find all ranges that overlap with the given range
+     */
+    findOverlapping(range: ByteRange): LockedRange[];
+    /**
+     * Remove a lock range from the tree
+     */
+    remove(range: RequestedRangeLock): void;
+    /**
+     * Find all ranges locked by the given process.
+     *
+     * @param pid The process ID to find locks for.
+     * @returns All locked ranges for the given process.
+     */
+    findLocksForProcess(pid: number): RequestedRangeLock[];
+    /**
+     * Find the strictest existing lock type in the range lock tree.
+     *
+     * @returns The strictest existing lock type, or 'unlocked' if no locks exist.
+     */
+    findStrictestExistingLockType(): RequestedRangeLock['type'];
+    private insertNode;
+    private bigintMax;
+    private findOverlappingRanges;
+    private doRangesOverlap;
+    private removeNode;
+    private findMin;
+    private areRangesEqual;
+    private findLocksForProcessInNode;
+}

package/lib/file-lock-manager-composite.d.ts

@@ -0,0 +1,14 @@
+import { type Path, type RequestedRangeLock, type WholeFileLockOp, type FileLockManager } from './file-lock-manager';
+export declare class FileLockManagerComposite implements FileLockManager {
+    nativeLockManager: FileLockManager;
+    wasmLockManager: FileLockManager;
+    constructor({ nativeLockManager, wasmLockManager, }: {
+        nativeLockManager: FileLockManager;
+        wasmLockManager: FileLockManager;
+    });
+    lockWholeFile(path: Path, op: WholeFileLockOp): boolean;
+    lockFileByteRange(path: Path, requestedLock: RequestedRangeLock, waitForLock: boolean): boolean;
+    findFirstConflictingByteRangeLock(path: Path, desiredLock: RequestedRangeLock): Omit<RequestedRangeLock, 'fd'> | undefined;
+    releaseLocksForProcess(pid: number): void;
+    releaseLocksOnFdClose(pid: number, fd: number, path: Path): void;
+}

package/lib/file-lock-manager-in-memory.d.ts

@@ -0,0 +1,169 @@
+import type { FileLockManager, RequestedRangeLock, WholeFileLockOp, Pid, Fd } from './file-lock-manager';
+import { type LockedRange } from './file-lock-manager';
+/**
+ * This is the file lock manager for use within JS runtimes like Node.js.
+ *
+ * A FileLockManagerInMemory is a wrapper around a Map of FileLock instances.
+ * It provides methods for locking and unlocking files, as well as finding conflicting locks.
+ */
+export declare class FileLockManagerInMemory implements FileLockManager {
+    locks: Map<string, FileLock>;
+    /**
+     * Create a new FileLockManagerInMemory instance.
+     *
+     * @param nativeFlockSync A synchronous flock() function to lock files via the host OS.
+     */
+    constructor();
+    /**
+     * Lock the whole file.
+     *
+     * @param path The path to the file to lock. This should be the path
+     *             of the file in the native filesystem.
+     * @param op The whole file lock operation to perform.
+     * @returns True if the lock was granted, false otherwise.
+     */
+    lockWholeFile(path: string, 
+    /**
+     * NOTE: FileLockManagerInMemory does not support waiting for a lock
+     * because it is intended to be used with a native file lock manager
+     * which does support waiting.
+     */
+    op: Omit<WholeFileLockOp, 'waitForLock'>): boolean;
+    /**
+     * Lock a byte range.
+     *
+     * @param path The path to the file to lock. This should be the path
+     *             of the file in the native filesystem.
+     * @param requestedLock The byte range lock to perform.
+     * @returns True if the lock was granted, false otherwise.
+     */
+    lockFileByteRange(path: string, 
+    /**
+     * NOTE: fcntl()-style F_SETLK/F_GETLK do not associate
+     * resulting locks with a file descrtiptor, so we ignore fd here.
+     */
+    requestedLock: Omit<RequestedRangeLock, 'fd'>
+    /**
+     * NOTE: FileLockManagerInMemory does not support waiting for a lock
+     * because it is intended to be used with a native file lock manager
+     * which does support waiting.
+     */
+    ): boolean;
+    /**
+     * Find the first conflicting byte range lock.
+     *
+     * @param path The path to the file to find the conflicting lock for.
+     * @param desiredLock The desired byte range lock.
+     * @returns The first conflicting byte range lock, or undefined if no conflicting lock exists.
+     */
+    findFirstConflictingByteRangeLock(path: string, 
+    /**
+     * NOTE: fcntl()-style F_SETLK/F_GETLK do not associate
+     * resulting locks with a file descrtiptor, so we ignore fd here.
+     */
+    desiredLock: Omit<RequestedRangeLock, 'fd'>): Omit<RequestedRangeLock, 'fd'> | undefined;
+    /**
+     * Release all locks for the given process.
+     *
+     * @param pid The process ID to release locks for.
+     */
+    releaseLocksForProcess(pid: number): void;
+    /**
+     * Release all locks for the given process and file descriptor.
+     *
+     * @param pid The process ID to release locks for.
+     * @param fd The file descriptor to release locks for.
+     * @param path The path to the file to release locks for.
+     */
+    releaseLocksOnFdClose(pid: number, fd: number, nativePath: string): void;
+    /**
+     * Forget the path if it is unlocked.
+     *
+     * @param path The path to the file to forget.
+     */
+    private forgetPathIfUnlocked;
+}
+/**
+ * A FileLock instance encapsulates a native whole-file lock and file locking between
+ * php-wasm processes.
+ *
+ * A FileLock supports php-wasm whole-file locks and byte range locks.
+ * Before granting a php-wasm lock, a FileLock ensures that it first holds a compatible
+ * native lock. If a compatible native lock cannot be acquired, the php-wasm lock is
+ * not granted.
+ */
+export declare class FileLock {
+    private wholeFileLock;
+    private rangeLocks;
+    constructor();
+    /**
+     * Lock the whole file.
+     *
+     * This method corresponds to the flock() function.
+     *
+     * @param op The whole file lock operation to perform.
+     * @returns True if the lock was granted, false otherwise.
+     */
+    lockWholeFile(op: Omit<WholeFileLockOp, 'waitForLock'>): boolean;
+    /**
+     * Lock a byte range.
+     *
+     * This method corresponds to the fcntl() F_SETLK command.
+     *
+     * @param requestedLock The byte range lock to perform.
+     * @returns True if the lock was granted, false otherwise.
+     */
+    lockFileByteRange(requestedLock: Omit<RequestedRangeLock, 'fd' | 'waitForLock'>): boolean;
+    /**
+     * Find the first conflicting byte range lock.
+     *
+     * This method corresponds to the fcntl() F_GETLK command.
+     *
+     * @param desiredLock The desired byte range lock.
+     * @returns The first conflicting byte range lock, or undefined if no conflicting lock exists.
+     */
+    findFirstConflictingByteRangeLock(
+    /**
+     * NOTE: fcntl()-style F_SETLK/F_GETLK do not associate
+     * resulting locks with a file descrtiptor, so we ignore fd here.
+     */
+    desiredLock: Omit<RequestedRangeLock, 'fd'>): LockedRange | {
+        type: "shared" | "exclusive";
+        start: bigint;
+        end: bigint;
+        pid: number;
+    } | undefined;
+    /**
+     * Release all locks for the given process.
+     *
+     * @param pid The process ID to release locks for.
+     */
+    releaseLocksForProcess(pid: Pid): void;
+    /**
+     * Release all locks for the given process and file descriptor.
+     *
+     * @param pid The process ID to release locks for.
+     * @param fd The file descriptor to release locks for.
+     */
+    releaseLocksOnFdClose(pid: Pid, fd: Fd): void;
+    /**
+     * Check if the file lock is unlocked.
+     *
+     * @returns True if the file lock is unlocked, false otherwise.
+     */
+    isUnlocked(): boolean;
+    /**
+     * Check if a lock exists that conflicts with the requested range lock.
+     *
+     * @param requestedLock The desired byte range lock.
+     * @returns True if a conflicting lock exists, false otherwise.
+     */
+    private isThereAConflictWithRequestedRangeLock;
+    /**
+     * Check if a lock exists that conflicts with the requested whole-file lock.
+     *
+     * @param requestedLock The desired whole-file lock.
+     * @returns True if a conflicting lock exists, false otherwise.
+     */
+    private isThereAConflictWithRequestedWholeFileLock;
+}

package/lib/file-lock-manager.d.ts

@@ -0,0 +1,117 @@
+export declare const MAX_ADDRESSABLE_FILE_OFFSET: bigint;
+export type Path = string;
+export type Pid = number;
+export type Fd = number;
+/**
+ * This is an interface used to abstract byte range locking like fcntl()
+ * and whole-file locking like flock().
+ */
+export type FileLockManager = {
+    /**
+     * Update the lock on the whole file.
+     *
+     * This method is for updating the lock on the whole file with the F_SETLKW fcntl() command.
+     * https://sourceware.org/glibc/manual/2.41/html_node/File-Locks.html#index-F_005fSETLKW-1
+     *
+     * @param path - The path of the file to lock. This should be the path of the file in the
+     *               underlying filesystem.
+     * @param op - The operation to perform, including 'shared', 'exclusive', or 'unlock'.
+     * @returns A promise for a boolean value.
+     */
+    lockWholeFile: (path: Path, op: WholeFileLockOp) => boolean;
+    /**
+     * Update the lock on a byte range of a file.
+     *
+     * This method is for locking with the F_SETLK fcntl() command.
+     * https://sourceware.org/glibc/manual/2.41/html_node/File-Locks.html#index-F_005fSETLK-1
+     *
+     * @param path - The path of the file to lock. This should be the path of the file in the
+     *               underlying filesystem.
+     * @param requestedLock - The lock to request, including start, end, type, and pid.
+     * @param waitForLock - Whether to block until the lock is acquired.
+     * @returns A promise for a boolean value.
+     *          When locking: True if the lock was acquired, false if it was not.
+     *          When unlocking: Always true.
+     */
+    lockFileByteRange: (path: Path, requestedLock: RequestedRangeLock, waitForLock: boolean) => boolean;
+    /**
+     * Get the first lock that would conflict with the specified lock.
+     *
+     * This method is meant to satisfy the needs of the F_GETLK fcntl() command.
+     * https://sourceware.org/glibc/manual/2.41/html_node/File-Locks.html#index-F_005fGETLK-1
+     *
+     * @param path - The path of the file to check for conflicts. This should be the path
+     *               of the file in the underlying filesystem.
+     * @param desiredLock - The lock to check for conflicts.
+     * @returns A promise for the first conflicting lock,
+     *          or undefined if there is no conflict.
+     */
+    findFirstConflictingByteRangeLock: (path: Path, desiredLock: RequestedRangeLock) => Omit<RequestedRangeLock, 'fd'> | undefined;
+    /**
+     * Release all locks for a given process.
+     *
+     * Used when a process exits or is otherwise terminated.
+     *
+     * @param pid - The PID of the process that wants to release the locks.
+     */
+    releaseLocksForProcess: (pid: number) => void;
+    /**
+     * Release all locks for the given process and file descriptor.
+     *
+     * @param pid The process ID to release locks for.
+     * @param fd The file descriptor to release locks for.
+     * @param path The path to the file to release locks for. This should be the path
+     *             of the file in the underlying filesystem.
+     */
+    releaseLocksOnFdClose: (pid: number, fd: number, path: Path) => void;
+};
+export type ByteRange = {
+    start: bigint;
+    end: bigint;
+};
+export type RequestedRangeLock = ByteRange & {
+    /**
+     * The type of lock request
+     */
+    type: 'shared' | 'exclusive' | 'unlocked';
+    /**
+     * The file descriptor to use. This should be the native file descriptor,
+     * not the Emscripten file descriptor because it may be used to lock the file
+     * using native OS file locking APIs.
+     */
+    fd: Fd;
+    /** The process ID that owns this lock */
+    pid: Pid;
+};
+export type LockedRange = RequestedRangeLock & {
+    type: Exclude<RequestedRangeLock['type'], 'unlocked'>;
+};
+export type ConflictingLockedRange = Omit<LockedRange, 'fd'>;
+export type WholeFileLock = Readonly<WholeFileLock_Exclusive | WholeFileLock_Shared | WholeFileLock_Unlocked>;
+export type WholeFileLock_Exclusive = {
+    type: 'exclusive';
+    pid: Pid;
+    fd: Fd;
+};
+export type WholeFileLock_Shared = {
+    type: 'shared';
+    /**
+     * NOTE: flock() locks are associated with open file descriptors and duplicated file descriptors.
+     * We do not currently recognize duplicate file descriptors.
+     */
+    pidFds: Map<Pid, Set<Fd>>;
+};
+export type WholeFileLock_Unlocked = {
+    type: 'unlocked';
+};
+export type WholeFileLockOp = {
+    pid: number;
+    fd: number;
+    type: 'shared' | 'exclusive';
+    /** Whether to block until the lock is acquired. */
+    waitForLock: boolean;
+} | {
+    pid: number;
+    fd: number;
+    type: 'unlock';
+};

package/lib/index.d.ts

@@ -40,4 +40,11 @@ export { proxyFileSystem, isPathToSharedFS } from './proxy-file-system';
 export { sandboxedSpawnHandlerFactory } from './sandboxed-spawn-handler-factory';
 export * from './api';
 export type { WithAPIState as WithIsReady } from './api';
+export type { NodeProcess } from './comlink-node-process-adapter';
+export * from './file-lock-manager';
+export * from './file-lock-manager-in-memory';
+export * from './file-lock-manager-composite';
+export * from './file-lock-interval-tree';
 export type { Remote } from './comlink-sync';
+export { createObjectPoolProxy } from './object-pool-proxy';
+export type { Pooled } from './object-pool-proxy';

package/lib/object-pool-proxy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Converts an object type to a promisified version where:
+ * - Methods return `Promise<Awaited<ReturnType>>` (no double-wrapping)
+ * - Properties become `Promise<Awaited<PropertyType>>`
+ */
+type Promisified<T extends object> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<Awaited<R>> : Promise<Awaited<T[K]>>;
+};
+/**
+ * The type returned by `createObjectPoolProxy`. All method calls and
+ * property accesses are wrapped in promises because acquiring a free
+ * pool instance is inherently async.
+ *
+ * Dispose/asyncDispose symbols are omitted because the pool proxy
+ * forwards calls to a single random instance — disposing one
+ * instance out of the pool is never the intended behavior. Pool
+ * lifecycle should be managed by the code that created the pool.
+ */
+export type Pooled<T extends object> = Omit<Promisified<T>, typeof Symbol.dispose | typeof Symbol.asyncDispose>;
+/**
+ * Creates a proxy that distributes method calls and property accesses
+ * across a pool of object instances. Only one ongoing access per
+ * instance is allowed at a time. If all instances are busy, accesses
+ * wait until one becomes free.
+ *
+ * The returned proxy provides a promisified version of the original
+ * interface: method calls and property accesses all return promises.
+ */
+export declare function createObjectPoolProxy<T extends object>(instances: T[]): Pooled<T>;
+export {};

package/lib/universal-php.d.ts

@@ -1,4 +1,5 @@
 import type { Remote } from './comlink-sync';
+import type { Pooled } from './object-pool-proxy';
 import type { LimitedPHPApi } from './php-worker';
 /**
  * Represents an event related to the PHP request.
@@ -43,7 +44,7 @@ export type PHPEvent = PHPRequestEndEvent | PHPRequestErrorEvent | PHPRuntimeIni
  * A callback function that handles PHP events.
  */
 export type PHPEventListener = (event: PHPEvent) => void;
-export type UniversalPHP = LimitedPHPApi | Remote<LimitedPHPApi>;
+export type UniversalPHP = LimitedPHPApi | Remote<LimitedPHPApi> | Pooled<LimitedPHPApi>;
 export type MessageListener = (data: string) => Promise<string | Uint8Array | void> | string | void;
 export interface EventEmitter {
     on(event: string, listener: (...args: any[]) => void): this;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@php-wasm/universal",
-  "version": "3.0.53",
+  "version": "3.1.0",
   "description": "PHP.wasm – emscripten bindings for PHP",
   "repository": {
     "type": "git",
@@ -37,18 +37,18 @@
   "module": "./index.js",
   "types": "index.d.ts",
   "license": "GPL-2.0-or-later",
-  "gitHead": "01ab4186302ca07b56ac54acd122d17b5350b3e2",
+  "gitHead": "be66d7e27ea9a8f09c2cc15e4470a6e28def5c58",
   "engines": {
     "node": ">=20.10.0",
     "npm": ">=10.2.3"
   },
   "dependencies": {
     "ini": "4.1.2",
-    "@php-wasm/node-polyfills": "3.0.53",
-    "@php-wasm/logger": "3.0.53",
-    "@php-wasm/util": "3.0.53",
-    "@php-wasm/stream-compression": "3.0.53",
-    "@php-wasm/progress": "3.0.53"
+    "@php-wasm/node-polyfills": "3.1.0",
+    "@php-wasm/logger": "3.1.0",
+    "@php-wasm/util": "3.1.0",
+    "@php-wasm/stream-compression": "3.1.0",
+    "@php-wasm/progress": "3.1.0"
   },
   "packageManager": "npm@10.9.2",
   "overrides": {
@@ -62,8 +62,5 @@
     "form-data": "^4.0.4",
     "lodash": "^4.17.23",
     "glob": "^9.3.0"
-  },
-  "optionalDependencies": {
-    "fs-ext": "2.1.1"
   }
 }