@php-wasm/node 1.1.3 → 1.1.4

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

@@ -0,0 +1,149 @@
+import type { FileLockManager, RequestedRangeLock, WholeFileLock, WholeFileLockOp, Pid, Fd } from './file-lock-manager';
+/**
+ * This is the file lock manager for use within JS runtimes like Node.js.
+ *
+ * A FileLockManagerForNode 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 FileLockManagerForNode implements FileLockManager {
+    locks: Map<string, FileLock>;
+    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, op: WholeFileLockOp): 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, requestedLock: RequestedRangeLock): 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, desiredLock: RequestedRangeLock): 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.
+     */
+    releaseLocksForProcessFd(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 {
+    /**
+     * Create a new FileLock instance for the given file and mode.
+     * Fail if the underlying native file lock cannot be acquired.
+     *
+     * @param path The path to the file to lock
+     * @param mode The type of lock to acquire
+     * @returns A FileLock instance if the lock was acquired, undefined otherwise
+     */
+    static maybeCreate(path: string, mode: Exclude<WholeFileLock['type'], 'unlocked'>): FileLock | undefined;
+    private nativeLock;
+    private wholeFileLock;
+    private rangeLocks;
+    private constructor();
+    /**
+     * Close the file descriptor and release the native lock.
+     *
+     * @TODO Replace this with a Symbol.dispose property once supported by all JS runtimes.
+     */
+    dispose(): void;
+    /**
+     * 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: WholeFileLockOp): 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: RequestedRangeLock): 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(desiredLock: RequestedRangeLock): RequestedRangeLock | 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.
+     */
+    releaseLocksForProcessFd(pid: Pid, fd: Fd): void;
+    /**
+     * Check if the file lock is unlocked.
+     *
+     * @returns True if the file lock is unlocked, false otherwise.
+     */
+    isUnlocked(): boolean;
+    /**
+     * Ensure that the native lock is compatible with the php-wasm lock,
+     * upgrading or downgrading as needed.
+     *
+     * @param overrideWholeFileLockType If provided, use this type for the whole file lock.
+     * @param overrideRangeLockType If provided, use this type for the range lock.
+     * @returns True if the native lock was upgraded or downgraded, false otherwise.
+     */
+    private ensureCompatibleNativeLock;
+    /**
+     * Check if a conflicting lock exists.
+     *
+     * @param requestedLock The desired byte range lock.
+     * @returns True if a conflicting lock exists, false otherwise.
+     */
+    private doesAConflictingLockExist;
+}

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

@@ -0,0 +1,96 @@
+/**
+ * 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: string, 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.
+     * @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: string, requestedLock: RequestedRangeLock) => 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: string, 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.
+     */
+    releaseLocksForProcessFd: (pid: number, fd: number, path: string) => void;
+};
+export type RequestedRangeLock = Readonly<{
+    /** The type of lock request */
+    type: 'shared' | 'exclusive' | 'unlocked';
+    /** The start offset of the lock range */
+    start: bigint;
+    /** The end of the lock range */
+    end: bigint;
+    /** The process ID that owns this lock */
+    pid: Pid;
+}>;
+export type WholeFileLock = Readonly<WholeFileLock_Exclusive | WholeFileLock_Shared | WholeFileLock_Unlocked>;
+export type Pid = number;
+export type Fd = number;
+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' | 'unlock';
+};

package/lib/index.d.ts

@@ -3,3 +3,5 @@ export * from './networking/with-networking';
 export * from './load-runtime';
 export * from './use-host-filesystem';
 export * from './node-fs-mount';
+export * from './file-lock-manager';
+export * from './file-lock-manager-for-node';

package/lib/load-runtime.d.ts

@@ -1,8 +1,36 @@
-import type { SupportedPHPVersion, EmscriptenOptions } from '@php-wasm/universal';
+import type { SupportedPHPVersion, EmscriptenOptions, RemoteAPI } from '@php-wasm/universal';
+import type { FileLockManager } from './file-lock-manager';
 export interface PHPLoaderOptions {
     emscriptenOptions?: EmscriptenOptions;
     followSymlinks?: boolean;
 }
+type PHPLoaderOptionsForNode = PHPLoaderOptions & {
+    emscriptenOptions?: EmscriptenOptions & {
+        /**
+         * The process ID for the PHP runtime.
+         *
+         * This is used to distinguish between php-wasm processes for the
+         * purpose of file locking and more informative trace messages.
+         *
+         * This ID is optional when running a single php-wasm process.
+         */
+        processId?: number;
+        /**
+         * An optional file lock manager to use for the PHP runtime.
+         *
+         * The lock manager is optional when running a single php-wasm process.
+         */
+        fileLockManager?: RemoteAPI<FileLockManager>;
+        /**
+         * An optional function to collect trace messages.
+         *
+         * @param processId - The process ID of the PHP runtime.
+         * @param format - A printf-style format string.
+         * @param args - Arguments to the format string.
+         */
+        trace?: (processId: number, format: string, ...args: any[]) => void;
+    };
+};
 /**
  * Does what load() does, but synchronously returns
  * an object with the PHP instance and a promise that
@@ -10,4 +38,5 @@ export interface PHPLoaderOptions {
  *
  * @see load
  */
-export declare function loadNodeRuntime(phpVersion: SupportedPHPVersion, options?: PHPLoaderOptions): Promise<number>;
+export declare function loadNodeRuntime(phpVersion: SupportedPHPVersion, options?: PHPLoaderOptionsForNode): Promise<number>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@php-wasm/node",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "PHP.wasm for Node.js",
   "repository": {
     "type": "git",
@@ -38,24 +38,25 @@
   },
   "license": "GPL-2.0-or-later",
   "types": "index.d.ts",
-  "gitHead": "977f8e90eabb2c8d4eed75677ddd9fb6c13274ae",
+  "gitHead": "ed646326d99ba84bad911d65b6634265f508f073",
   "engines": {
     "node": ">=20.18.3",
     "npm": ">=10.1.0"
   },
   "dependencies": {
-    "comlink": "^4.4.1",
+    "comlink": "^4.4.2",
     "express": "4.21.2",
+    "fs-ext": "2.1.1",
     "ini": "4.1.2",
     "wasm-feature-detect": "1.8.0",
     "ws": "8.18.1",
     "yargs": "17.7.2",
-    "@php-wasm/node-polyfills": "1.1.3",
-    "@php-wasm/universal": "1.1.3",
-    "@php-wasm/util": "1.1.3",
-    "@php-wasm/logger": "1.1.3",
-    "@wp-playground/common": "1.1.3",
-    "@wp-playground/wordpress": "1.1.3"
+    "@php-wasm/node-polyfills": "1.1.4",
+    "@php-wasm/universal": "1.1.4",
+    "@php-wasm/logger": "1.1.4",
+    "@php-wasm/util": "1.1.4",
+    "@wp-playground/common": "1.1.4",
+    "@wp-playground/wordpress": "1.1.4"
   },
   "overrides": {
     "rollup": "^4.34.6",