[PHP-wasm] Use statfs from NODEFS in the Node version (#94)

## Motivation for the change, related issues

This PR adds `statfs` support to the Emscripten root file system to
enable PHP-wasm Node to get real filesystem stats for the `/` path.

Currently, in PHP-wasm Node, PHP functions like `disk_total_space('/')`
return the default hardcoded value for MEMFS instead of the actual disk
space.

This happens because Emscripten automatically detects the filesystem for
a given path, and because the root path always uses the MEMFS
filesystem, Emscripten will use the MEMFS `statfs` implementation.

PHP-wasm Node includes two Emscripten filesystems, MEMFS and NODEFS.
MEMFS doesn't have access to the operating system's filesystem, so it
can only return a hardcoded value.
NODEFS has access to the OS filesystem through the `fs` module, and
specifically for `statfs` it uses `fs.statfsSync` to get real data.

## Implementation details

This PR uses Emscripten's `onRuntimeInitialized` event to override the
`statfs` implementation in the Emscripten root FS with the NODEFS
implementation of `statfs`.

It also defines the `FS.root.mount.opts.root` path as `.` to ensure the
root node has a path value defined.
Otherwise when we call `FS.statfs('/')` it would use the root node's
root path which is `undefined` and this would throw an error because it
would call `fs.statfsSync(undefined)` in the NODEFS implementation of
`statfs`.

I explored fixing this [issue in
Emscripten](emscripten-core/emscripten#23912),
but I wasn't able to find a working solution there, so I ended up
patching it in Playground.

## Testing Instructions (or ideally a Blueprint)

- CI

Author: bgrgicak

packages/php-wasm/node/src/test/php.spec.ts

@@ -8,9 +8,18 @@ import {
 	setPhpIniEntries,
 	SupportedPHPVersions,
 } from '@php-wasm/universal';
-import { existsSync, rmSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
+import {
+	existsSync,
+	rmSync,
+	readFileSync,
+	mkdirSync,
+	writeFileSync,
+	statfsSync,
+	mkdtempSync,
+} from 'fs';
 import { createSpawnHandler, joinPaths, phpVar } from '@php-wasm/util';
 import { createNodeFsMountHandler } from '../lib/node-fs-mount';
+import { tmpdir } from 'os';
 
 const testDirPath = '/__test987654321';
 const testFilePath = '/__test987654321.txt';
@@ -2142,4 +2151,48 @@ bar1
 			expect(response.text).toBe('bool(false)\n');
 		});
 	});
+	describe('Disk space', () => {
+		it('should return the correct total disk space', async () => {
+			const response = await php.run({
+				code: `<?php echo disk_total_space('/');`,
+			});
+			const expectedStatfs = statfsSync('/');
+			const expectedTotalDiskSpace =
+				expectedStatfs.blocks * expectedStatfs.bsize;
+			expect(response.text).toBe(expectedTotalDiskSpace.toString());
+		});
+
+		it('should return the correct free disk space', async () => {
+			const response = await php.run({
+				code: `<?php echo json_encode(disk_free_space('/'));`,
+			});
+			const expectedStatfs = statfsSync('/');
+			const expectedFreeDiskSpace =
+				expectedStatfs.bavail * expectedStatfs.bsize;
+			expect(response.text).toBe(expectedFreeDiskSpace.toString());
+		});
+
+		it('should return a hardcoded value from MEMFS for a file created in MEMFS', async () => {
+			php.writeFile('/test.txt', new Uint8Array(1024));
+			const response = await php.run({
+				code: `<?php echo json_encode(disk_total_space('/test.txt'));`,
+			});
+			expect(response.text).toBe('4096000000');
+		});
+
+		it('should return the correct total disk space when passing a subdirectory', async () => {
+			const tempDir = mkdtempSync(joinPaths(tmpdir(), 'php-wasm-test-'));
+			const filePath = joinPaths(tempDir, 'test.txt');
+			writeFileSync(filePath, new Uint8Array(1024));
+			php.mount('/tmp', createNodeFsMountHandler(tempDir));
+
+			const response = await php.run({
+				code: `<?php echo json_encode(disk_total_space('/tmp'));`,
+			});
+			const expectedStatfs = statfsSync('/');
+			const expectedTotalDiskSpace =
+				expectedStatfs.blocks * expectedStatfs.bsize;
+			expect(response.text).toBe(expectedTotalDiskSpace.toString());
+		});
+	});
 });

packages/php-wasm/universal/src/lib/load-php-runtime.ts

@@ -146,6 +146,50 @@ export async function loadPHPRuntime(
 		...phpModuleArgs,
 		noInitialRun: true,
 		onRuntimeInitialized() {
+			/**
+			 * Emscripten automatically detects the filesystem for a given path,
+			 * and because the root path always uses the MEMFS filesystem, `statfs`
+			 * will return the default hardcoded value for MEMFS instead of the
+			 * actual disk space.
+			 *
+			 * To ensure `statfs` works in the Node version of PHP-WASM,
+			 * we need to add `statfs` from NODEFS to the root FS.
+			 * Otherwise, `statfs` is undefined in the root FS and the NODEFS
+			 * implementation wouldn't be used for paths that exist in MEMFS.
+			 *
+			 * The only place `statfs` is used in PHP are the `disk_total_space`
+			 * and `disk_free_space` functions.
+			 * Both functions return the disk space for a given disk partition.
+			 * If a subdirectory is passed, the function will return the disk space
+			 * for its partition.
+			 */
+			if (currentJsRuntime === 'NODE') {
+				PHPRuntime.FS.root.node_ops = {
+					...PHPRuntime.FS.root.node_ops,
+					statfs: PHPRuntime.FS.filesystems.NODEFS.node_ops.statfs,
+				};
+				/**
+				 * By default FS.root node value of `mount.opts.root` is `undefined`.
+				 * As a result `FS.lookupPath` will return a node with a `undefined`
+				 * `mount.opts.root` path when looking up the `/` path using `FS.lookupPath`.
+				 *
+				 * The `NODEFS.realPath` function works with `undefined` because it uses
+				 * `path.join` to build the path and for the `[undefined]` it will
+				 * return the `.` path.
+				 *
+				 * Because the `node.mount.opts.root` path is `undefined`,
+				 * `fs.statfsSync` will throw an error when trying to get the
+				 * disk space for an undefined path.
+				 * For the `/` path to correctly resolve, we must set the
+				 * `mount.opts.root` path to the current working directory.
+				 *
+				 * We chose the current working directory over `/` because
+				 * NODERAWFS defines the root path as `.`.
+				 * Emscripten reference to setting the root path in NODERAWFS:
+				 * https://github.com/emscripten-core/emscripten/pull/19400/files#diff-456b6256111c90ca5e6bdb583ab87108cd51cbbefc812c4785ea315c0728b3a8R11
+				 */
+				PHPRuntime.FS.root.mount.opts.root = '.';
+			}
 			if (phpModuleArgs.onRuntimeInitialized) {
 				phpModuleArgs.onRuntimeInitialized();
 			}

packages/php-wasm/universal/src/lib/php-request-handler.ts

@@ -219,6 +219,14 @@ export class PHPRequestHandler {
 			});
 		}
 
+		/**
+		 * By default, config.cookieStore is undefined, so we use the
+		 * HttpCookieStore implementation, otherwise we use the one
+		 * provided in the config.
+		 *
+		 * By explicitly checking for `undefined` we allow the user to pass
+		 * `null` as config.cookieStore and disable the cookie store.
+		 */
 		this.#cookieStore =
 			config.cookieStore === undefined
 				? new HttpCookieStore()