Add symlink manager

Add a symlink manager

Remove old comments

Fix issues and ensure that links are mounted on instance rotation

Fixes for abortController

Revert unnecessary change

Update vendor/wp-now/src/symlink-manager.ts

Co-authored-by: Carlos Garcia <fluiddot@gmail.com>

Update vendor/wp-now/src/symlink-manager.ts

Co-authored-by: Carlos Garcia <fluiddot@gmail.com>

capitalize type name

Init maps in constructor

Always remove symlink from map on removal

Exit php when server is stopped

Refactor the symlink manager and move it to the lib directory

Small fixes

Force usage of POSIX compliant paths when dealing with VFS paths

Prevent loading symlink manager on windows platforms

Add unit tests for symlink creation/deletion

Remove unused import

Specifically check for win32 before using SymlinkManager

src/lib/symlink-manager.ts

@@ -0,0 +1,248 @@
+import fs, { FileChangeInfo } from 'node:fs/promises';
+import path from 'path';
+import { createNodeFsMountHandler } from '@php-wasm/node';
+import { PHP, UnmountFunction } from '@php-wasm/universal';
+import { pathExists } from './fs-utils';
+
+type MountedTarget = {
+	preExisting: boolean;
+	referenceCount: number;
+	unmountFunction?: UnmountFunction | null;
+};
+
+/**
+ * Manages symlinks within a PHP WebAssembly runtime environment. In this setup,
+ * a site's directory from the host system is mounted inside the WebAssembly runtime.
+ * However, symlink targets are not automatically mounted, leaving symlinks pointing to nothing.
+ * This class resolves that issue by mounting the actual targets of symlinks.
+ *
+ * Key functionalities:
+ * 1. Scans for symlinks in the mounted directory
+ * 2. Mounts symlink targets in the WebAssembly runtime
+ * 3. Manages reference counting for mounted targets
+ * 4. Watches for file system changes and updates mounts accordingly
+ *
+ * The class ensures that symlinks within the PHP WebAssembly environment correctly
+ * reference their targets, maintaining the integrity of the file system structure
+ * across the host and WebAssembly boundary.
+ */
+export class SymlinkManager {
+	private symlinks: Map< string, string >; // Store relative path of symlink and its vfs realpath
+	private mountedTargets: Map< string, MountedTarget >; // Store the target of the symlink and its reference count
+	private php: PHP;
+	readonly projectPath: string;
+	private watcher?: AsyncIterable< FileChangeInfo< string > > | null;
+	private watcherAbortController?: AbortController | null;
+
+	/**
+	 * Create a new symlink manager.
+	 * @param php
+	 * @param projectPath
+	 *
+	 */
+	constructor( php: PHP, projectPath: string ) {
+		this.symlinks = new Map< string, string >();
+		this.mountedTargets = new Map< string, MountedTarget >();
+		this.php = php;
+		this.projectPath = projectPath;
+	}
+
+	/**
+	 * Scan the project path for symlinks and mount their targets in the PHP runtime.
+	 */
+	async scanAndCreateSymlinks() {
+		for await ( const symlink of this.collectSymlinks( this.projectPath ) ) {
+			const relativePath = path.relative( this.projectPath, symlink );
+			await this.addSymlink( relativePath );
+		}
+	}
+
+	/**
+	 * Watches the project path for changes and update symlinks accordingly.
+	 */
+	startWatching() {
+		this.watcherAbortController = new AbortController();
+		const { signal } = this.watcherAbortController;
+		this.watcher = fs.watch( this.projectPath, { recursive: true, signal } );
+
+		return new Promise< void >( ( resolve, reject ) => {
+			( async () => {
+				try {
+					if ( ! this.watcher ) {
+						return resolve();
+					}
+					for await ( const change of this.watcher ) {
+						await this.handleFileChange( change );
+					}
+					resolve();
+				} catch ( err ) {
+					// AbortError is expected when the watcher is stopped intentionally
+					if ( err instanceof Error && err.name === 'AbortError' ) {
+						return resolve();
+					}
+					reject( err );
+				}
+			} )();
+		} );
+	}
+
+	/**
+	 * Stop watching the project path for changes.
+	 */
+	async stopWatching() {
+		if ( ! this.watcherAbortController ) {
+			return;
+		}
+		this.watcherAbortController.abort( 'Watcher stopped' );
+		this.watcher = null;
+		this.watcherAbortController = null;
+	}
+
+	/**
+	 * Handle a file change event.
+	 * @param change
+	 */
+	private async handleFileChange( change: FileChangeInfo< string > ) {
+		const { filename } = change;
+
+		if ( filename === null ) {
+			return;
+		}
+
+		// Check if the file exists
+		const fullPath = path.join( this.projectPath, filename );
+
+		const fileExistsOnHost = await pathExists( fullPath );
+
+		// If the file does not exist, it was deleted. Check if it was a symlink and remove it.
+		if ( ! fileExistsOnHost && this.symlinks.has( filename ) ) {
+			await this.deleteMountedTarget( filename );
+		}
+
+		if ( ! fileExistsOnHost ) {
+			return;
+		}
+
+		const stat = await fs.lstat( fullPath );
+		if ( ! stat.isSymbolicLink() ) {
+			return;
+		}
+
+		await this.addSymlink( filename );
+	}
+
+	/**
+	 * Add a symlink to the PHP runtime by mounting the target path.
+	 * @param filename
+	 */
+	private async addSymlink( filename: string ) {
+		const fullPath = path.join( this.projectPath, filename );
+		const target = await fs.realpath( fullPath );
+
+		if ( ! this.php.requestHandler ) {
+			throw new Error( 'Request handler is not set' );
+		}
+
+		const vfsPath = path.posix.join( this.php.requestHandler.documentRoot, filename );
+
+		// Double check to ensure the symlink exists
+		if ( ! this.php.fileExists( vfsPath ) ) {
+			return;
+		}
+
+		// Get the realpath of the symlink within the PHP runtime.
+		const vfsTarget = this.php.readlink( vfsPath );
+		this.symlinks.set( filename, vfsTarget );
+
+		await this.mountTarget( vfsTarget, target );
+	}
+
+	/**
+	 * Mount a target path in the PHP runtime.
+	 * @param vfsTarget
+	 * @param hostTarget
+	 * @private
+	 */
+	private async mountTarget( vfsTarget: string, hostTarget: string ) {
+		let mountInfo = this.mountedTargets.get( vfsTarget );
+
+		if ( typeof mountInfo === 'undefined' ) {
+			mountInfo = {
+				preExisting: this.php.fileExists( vfsTarget ),
+				referenceCount: 0,
+				unmountFunction: null,
+			};
+			this.mountedTargets.set( vfsTarget, mountInfo );
+		}
+
+		mountInfo.referenceCount++;
+
+		if ( mountInfo.preExisting || mountInfo.unmountFunction !== null ) {
+			return;
+		}
+
+		this.php.mkdir( vfsTarget );
+		mountInfo.unmountFunction = await this.php.mount(
+			vfsTarget,
+			createNodeFsMountHandler( hostTarget )
+		);
+	}
+
+	/**
+	 * Delete a symlink from the PHP runtime.
+	 *
+	 * @param filename
+	 */
+	private async deleteMountedTarget( filename: string ) {
+		const vfsTarget = this.symlinks.get( filename );
+
+		if ( vfsTarget === undefined ) {
+			return;
+		}
+
+		// Get the mount info for the target
+		const mountInfo = this.mountedTargets.get( vfsTarget );
+		if ( typeof mountInfo === 'undefined' ) {
+			return;
+		}
+
+		mountInfo.referenceCount--;
+
+		// We can delete the symlink now as it is no longer needed.
+		this.symlinks.delete( filename );
+
+		// If the reference count is 0 and the unmount function is set, we can unmount the target
+		if ( mountInfo.referenceCount === 0 && mountInfo.unmountFunction && ! mountInfo.preExisting ) {
+			await mountInfo.unmountFunction();
+
+			// After unmounting, clear the mount target
+			if ( this.php.isFile( vfsTarget ) ) {
+				this.php.unlink( vfsTarget );
+			}
+
+			if ( this.php.isDir( vfsTarget ) ) {
+				this.php.rmdir( vfsTarget );
+			}
+
+			this.mountedTargets.delete( vfsTarget );
+		}
+	}
+
+	/**
+	 * Collect all symlinks in a directory.
+	 * @param dir
+	 * @private
+	 */
+	private async *collectSymlinks( dir: string ): AsyncGenerator< string > {
+		const files = await fs.readdir( dir );
+		for ( const file of files ) {
+			const filePath = path.join( dir, file );
+			const stats = await fs.lstat( filePath );
+			if ( stats.isSymbolicLink() ) {
+				yield filePath;
+			} else if ( stats.isDirectory() ) {
+				yield* this.collectSymlinks( filePath );
+			}
+		}
+	}
+}