diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c319a36a2fc..7f3adc20b80 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -257,6 +257,50 @@ jobs: MYSQL_DATABASE: test_db MYSQL_USER: user MYSQL_PASSWORD: password + # Node.js enables JSPI by default from 24.20.0, so the test-unit-asyncify + # jobs above load the JSPI build too. Node 24.18.0, the oldest supported + # version, still loads the Asyncify build. Run the networking tests there. + test-networking-asyncify: + needs: set-nx-shas + if: github.repository == 'WordPress/wordpress-playground' || github.event_name == 'pull_request' + name: 'Networking tests with Asyncify (Node 24.18.0)' + runs-on: ubuntu-latest + timeout-minutes: 30 + permissions: + contents: read # Required to clone the repo. + env: + NX_BASE: ${{ needs.set-nx-shas.outputs.base }} + NX_HEAD: ${{ needs.set-nx-shas.outputs.head }} + services: + mysql: + image: mysql:5.7 + env: + MYSQL_DATABASE: test_db + MYSQL_USER: user + MYSQL_PASSWORD: password + MYSQL_ROOT_PASSWORD: rootpassword + ports: + - 3306:3306 + options: >- + --health-cmd="mysqladmin ping --silent" + --health-interval=10s + --health-timeout=5s + --health-retries=3 + steps: + - uses: actions/checkout@v4 + with: + submodules: true + # Install with Node 24 to reuse the shared dependency cache, then + # switch to the version that loads the Asyncify build. + - uses: ./.github/actions/prepare-playground + - uses: actions/setup-node@v4 + with: + node-version: 24.18.0 + - run: node --expose-gc node_modules/nx/bin/nx affected --target=test-networking-asyncify + env: + MYSQL_DATABASE: test_db + MYSQL_USER: user + MYSQL_PASSWORD: password test-playground-cli: needs: set-nx-shas if: github.repository == 'WordPress/wordpress-playground' || github.event_name == 'pull_request' diff --git a/AGENTS.md b/AGENTS.md index 0278718d068..2ae781872f4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -306,6 +306,11 @@ and runs PHP/SQLite, CLI multi-worker, and worker-wait tests with that addon mov out of resolution. The addon is restored before the shared dependency cache is saved. +Node.js enables JSPI by default from 24.20.0, so the `-asyncify` unit test targets +load the JSPI build in CI. The `test-networking-asyncify` job runs the +`@php-wasm/node` networking tests on Node 24.18.0, which loads the Asyncify build. +Its `vite.asyncify.config.ts` stops with an error on Node versions that enable JSPI. + Dependabot's daily version check opens PRs for `fs-ext-extra-prebuilt` patch releases. It raises the minimum package version and updates the lockfile; the existing Dependabot lockfile workflow preserves workspace links. An explicit diff --git a/packages/docs/site/docs/developers/05-local-development/03-php-wasm-node.md b/packages/docs/site/docs/developers/05-local-development/03-php-wasm-node.md index 9caa9080aaa..002e970089c 100644 --- a/packages/docs/site/docs/developers/05-local-development/03-php-wasm-node.md +++ b/packages/docs/site/docs/developers/05-local-development/03-php-wasm-node.md @@ -26,8 +26,8 @@ Consult the [complete list](/api/node) of Classes, Functions, Interfaces, and Ty Together, `@php-wasm/node` and a version-specific package provide the compiled PHP runtime and JavaScript API optimized for Node.js. PHP starts with an in-memory filesystem; use the Node.js filesystem helpers to mount host paths. -The runtime can access the network if you plug in a custom WebSocket-to-TCP -proxy. +PHP can open TCP connections and listen for them. The runtime uses Node.js +TCP sockets directly. ### Basic usage diff --git a/packages/docs/site/docs/developers/23-architecture/02-wasm-php-overview.md b/packages/docs/site/docs/developers/23-architecture/02-wasm-php-overview.md index 37d81c204b0..0d1fd7473f8 100644 --- a/packages/docs/site/docs/developers/23-architecture/02-wasm-php-overview.md +++ b/packages/docs/site/docs/developers/23-architecture/02-wasm-php-overview.md @@ -22,7 +22,7 @@ Because every PHP version is just a static .wasm file, the PHP version switcher When it comes to networking, WebAssembly programs are limited to calling JavaScript APIs. It is a safety feature, but also presents a challenge. How do you support low-level, synchronous networking code used by PHP with the high-level asynchronous APIs available in JavaScript? -In Node.js, the answer involves a WebSocket to TCP socket proxy, [Asyncify](https://emscripten.org/docs/porting/asyncify.html), and patching deep PHP internals like php_select. It's complex, but there's a reward. The Node.js-targeted PHP build can request web APIs, install composer packages, and even connect to a MySQL server. +In Node.js, the answer involves TCP sockets that stand in for Emscripten's WebSockets, [Asyncify](https://emscripten.org/docs/porting/asyncify.html), and patching deep PHP internals like php_select. It's complex, but there's a reward. The Node.js-targeted PHP build can request web APIs, install composer packages, and even connect to a MySQL server. In the browser, networking is supported in two ways: diff --git a/packages/php-wasm/node/README.md b/packages/php-wasm/node/README.md index bf24307c66a..1e335d600b6 100644 --- a/packages/php-wasm/node/README.md +++ b/packages/php-wasm/node/README.md @@ -9,8 +9,7 @@ This package ships WebAssembly PHP binaries and the JavaScript API optimized for - OpenSSL - MySQL -It uses the host filesystem directly and can access the network if you plug in a custom -WS proxy. +It uses the host filesystem and TCP sockets directly. Here's how to use it: @@ -27,6 +26,14 @@ const output = await php.runStream({ console.log(await output.stdoutText); ``` +On runtime exit, listening sockets close and TCP sockets have up to 30 seconds +to drain queued writes. The exited runtime cannot open new network connections. +As on previous runtimes, `php.exit()` does not provide general cancellation of +PHP code that was already executing. PHP waiting on a socket when the runtime +exits may resume and finish its script, including writes to mounted files, but +it can't open network connections. A `stream_socket_server()` call after exit +fails the request. + ## Loading PHP extensions Pass `extensions` to `loadNodeRuntime()` to load optional PHP extensions before diff --git a/packages/php-wasm/node/project.json b/packages/php-wasm/node/project.json index 66143cc7722..79edfe9de1e 100644 --- a/packages/php-wasm/node/project.json +++ b/packages/php-wasm/node/project.json @@ -233,7 +233,7 @@ "php-sqlite3.spec.ts", "php-networking.spec.ts", "networking-port-allocation.spec.ts", - "outbound-ws-to-tcp-proxy.spec.ts", + "tcp-socket.spec.ts", "php-dynamic-loading.spec.ts", "php-mysqli.spec.ts", "php-process-manager.spec.ts", @@ -252,7 +252,7 @@ "php-sqlite3.spec.ts", "php-networking.spec.ts", "networking-port-allocation.spec.ts", - "outbound-ws-to-tcp-proxy.spec.ts", + "tcp-socket.spec.ts", "php-dynamic-loading.spec.ts", "php-mysqli.spec.ts", "php-process-manager.spec.ts", @@ -312,6 +312,25 @@ "testFiles": ["php-part-2.spec.ts"] } }, + "test-networking-asyncify": { + "executor": "@nx/vitest:test", + "outputs": ["{workspaceRoot}/coverage/packages/php-wasm/node"], + "options": { + "configFile": "packages/php-wasm/node/vite.asyncify.config.ts", + "reportsDirectory": "../../../coverage/packages/php-wasm/node", + "testFiles": [ + "tcp-socket.spec.ts", + "networking-port-allocation.spec.ts", + "php-networking.spec.ts", + "php-fsockopen.spec.ts", + "php-socket-timeouts.spec.ts", + "php-file-get-contents.spec.ts", + "php-fopen.spec.ts", + "php-gethostbyname.spec.ts", + "php-mysqli.spec.ts" + ] + } + }, "test-redis-extension-jspi": { "executor": "@nx/vitest:test", "outputs": ["{workspaceRoot}/coverage/packages/php-wasm/node"], diff --git a/packages/php-wasm/node/src/lib/networking/inbound-tcp-to-ws-proxy.ts b/packages/php-wasm/node/src/lib/networking/inbound-tcp-to-ws-proxy.ts deleted file mode 100644 index ca2160a788e..00000000000 --- a/packages/php-wasm/node/src/lib/networking/inbound-tcp-to-ws-proxy.ts +++ /dev/null @@ -1,117 +0,0 @@ -import { createServer, type Server } from 'net'; -import type { WebSocketServer } from 'ws'; -import { WebSocket } from 'ws'; -import { debugLog, getServerPort } from './utils'; -function log(...args: any[]) { - debugLog('[TCP Server]', ...args); -} - -export function addTCPServerToWebSocketServerClass( - WSServer: typeof WebSocketServer -): any { - return class PHPWasmWebSocketServer extends WSServer { - private tcpToWsProxyServer?: Server; - - constructor(options: any, callback: any) { - const requestedPort = options.port; - options.port = 0; - super(options, undefined); - this.once('listening', () => { - this.tcpToWsProxyServer = listenTCPToWSProxy( - { - tcpListenPort: requestedPort, - wsConnectPort: getServerPort(this), - }, - () => callback?.call(this) - ); - }); - } - - override close(callback?: (err?: Error) => void) { - const tcpToWsProxyServer = this.tcpToWsProxyServer; - this.tcpToWsProxyServer = undefined; - - tcpToWsProxyServer?.close( - (error: NodeJS.ErrnoException | undefined) => { - if (error?.code !== 'ERR_SERVER_NOT_RUNNING') { - log('TCP server close error', error); - } - } - ); - - return super.close(callback); - } - }; -} - -export interface InboundTcpToWsProxyOptions { - tcpListenPort: number; - wsConnectHost?: string; - wsConnectPort: number; -} -export function listenTCPToWSProxy( - options: InboundTcpToWsProxyOptions, - onListening?: () => void -) { - options = { - wsConnectHost: '127.0.0.1', - ...options, - }; - const { tcpListenPort, wsConnectHost, wsConnectPort } = options; - const server = createServer(); - server.on('connection', function handleConnection(tcpSource) { - const inBuffer: Buffer[] = []; - - const wsTarget = new WebSocket( - `ws://${wsConnectHost}:${wsConnectPort}/` - ); - wsTarget.binaryType = 'arraybuffer'; - function wsSend(data: Buffer) { - wsTarget.send(new Uint8Array(data)); - } - - wsTarget.addEventListener('open', function () { - log('Outbound WebSocket connection established'); - while (inBuffer.length > 0) { - wsSend(inBuffer.shift()!); - } - }); - wsTarget.addEventListener('message', (e) => { - log( - 'WS->TCP message:', - new TextDecoder().decode(e.data as ArrayBuffer) - ); - // @ts-ignore-next-line - tcpSource.write(Buffer.from(e.data as ArrayBuffer)); - }); - wsTarget.addEventListener('close', () => { - log('WebSocket connection closed'); - tcpSource.end(); - }); - - tcpSource.on('data', function (data) { - log('TCP->WS message:', data); - if (wsTarget.readyState === WebSocket.OPEN) { - while (inBuffer.length > 0) { - wsSend(inBuffer.shift()!); - } - wsSend(data); - } else { - inBuffer.push(data); - } - }); - tcpSource.once('close', function () { - log('TCP connection closed'); - wsTarget.close(); - }); - tcpSource.on('error', function () { - log('TCP connection error'); - wsTarget.close(); - }); - }); - server.listen(tcpListenPort, function () { - log('TCP server listening'); - onListening?.(); - }); - return server; -} diff --git a/packages/php-wasm/node/src/lib/networking/outbound-ws-to-tcp-proxy.ts b/packages/php-wasm/node/src/lib/networking/outbound-ws-to-tcp-proxy.ts deleted file mode 100644 index bf952e1e754..00000000000 --- a/packages/php-wasm/node/src/lib/networking/outbound-ws-to-tcp-proxy.ts +++ /dev/null @@ -1,298 +0,0 @@ -/** - * This is a simple TCP proxy server that allows PHP to connect to a remote - * server via WebSockets. This is necessary because WebAssembly has no access - * to the network. - * - * This module was forked from the @maximegris/node-websockify npm package. - */ -'use strict'; - -import * as dns from 'dns'; -import * as http from 'http'; -import * as net from 'net'; -import { WebSocketServer } from 'ws'; -import { debugLog } from './utils'; - -function log(...args: any[]) { - debugLog('[WS Server]', ...args); -} - -/** - * Resolve a hostname to an IPv4 address. - * Prefers IPv4 because many services (including Redis) only listen on IPv4 - * by default, and macOS's dns.lookup returns IPv6 for 'localhost'. - */ -function lookupIPv4(hostname: string): Promise { - return new Promise((resolve, reject) => { - dns.lookup(hostname, { family: 4 }, (err, address) => { - if (err) { - reject(err); - } else { - resolve(address); - } - }); - }); -} - -function prependByte( - chunk: string | ArrayBuffer | ArrayLike, - byte: number -) { - if (typeof chunk === 'string') { - chunk = String.fromCharCode(byte) + chunk; - } else if ( - chunk instanceof ArrayBuffer || - 'byteLength' in chunk /* for Node.js */ - ) { - const buffer = new Uint8Array((chunk as ArrayBuffer).byteLength + 1); - buffer[0] = byte; - buffer.set(new Uint8Array(chunk), 1); - chunk = buffer.buffer; - } else { - log({ chunk }); - throw new Error('Unsupported chunk type: ' + typeof chunk); - } - return chunk; -} - -/** - * Send a chunk of data to the remote server. - */ -export const COMMAND_CHUNK = 0x01; -/** - * Set a TCP socket option. - */ -export const COMMAND_SET_SOCKETOPT = 0x02; - -/** - * Adds support for TCP socket options to WebSocket class. - * - * Socket options are implemented by adopting a specific data transmission - * protocol between WS client and WS server The first byte - * of every message is a command type, and the remaining bytes - * are the actual data. - * - * @param WebSocketConstructor - * @returns Decorated constructor - */ -export function addSocketOptionsSupportToWebSocketClass( - WebSocketConstructor: typeof WebSocket -) { - return class PHPWasmWebSocketConstructor extends WebSocketConstructor { - // @ts-ignore - send(chunk: any, callback: any) { - return this.sendCommand(COMMAND_CHUNK, chunk, callback); - } - - setSocketOpt( - optionClass: number, - optionName: number, - optionValue: number - ) { - return this.sendCommand( - COMMAND_SET_SOCKETOPT, - new Uint8Array([optionClass, optionName, optionValue]).buffer, - () => undefined - ); - } - sendCommand( - commandType: number, - chunk: string | ArrayBuffer | ArrayLike, - callback: any - ) { - return (WebSocketConstructor.prototype.send as any).call( - this, - prependByte(chunk, commandType), - callback - ); - } - }; -} - -export function initOutboundWebsocketProxyServer( - listenPort: number, - listenHost = '127.0.0.1' -): Promise { - log(`Binding the WebSockets server to ${listenHost}:${listenPort}...`); - const webServer = http.createServer((request, response) => { - response.writeHead(403, { 'Content-Type': 'text/plain' }); - response.write( - '403 Permission Denied\nOnly websockets are allowed here.\n' - ); - response.end(); - }); - return new Promise((resolve, reject) => { - webServer.once('error', reject); - webServer.listen(listenPort, listenHost, function () { - webServer.off('error', reject); - const wsServer = new WebSocketServer({ server: webServer }); - wsServer.on('connection', onWsConnect); - resolve(webServer); - }); - }); -} - -// Handle new WebSocket client -async function onWsConnect(client: any, request: http.IncomingMessage) { - // CAUTION: Do not accept connections that send an Origin header. - // Only the PHP runtime's own Node `ws` client may use this proxy. It sends - // no Origin header, while browsers always send one. A web page connected - // here would get raw TCP access to any host the Node process can reach, - // including services that only listen on localhost. Binding to 127.0.0.1 - // doesn't stop this because browsers can connect to loopback. Allowing an - // Origin, even a trusted one, gives that access to every page served from it. - // To prevent this, let's close any connection that has an Origin header - // before it can open a TCP connection. - if (request.headers.origin) { - client.close(1008, 'Origin not allowed'); - return; - } - const clientAddr = client?._socket?.remoteAddress || client.url; - const clientLog = function (...args: any[]) { - log(' ' + clientAddr + ': ', ...args); - }; - - clientLog( - 'WebSocket connection from : ' + - clientAddr + - ' at URL ' + - (request ? request.url : client.upgradeReq.url) - ); - clientLog( - 'Version ' + - client.protocolVersion + - ', subprotocol: ' + - client.protocol - ); - - // Parse the search params (the host doesn't matter): - const reqUrl = new URL(`ws://0.0.0.0` + request.url); - const reqTargetPort = Number(reqUrl.searchParams.get('port')); - const reqTargetHost = reqUrl.searchParams.get('host'); - if (!reqTargetPort || !reqTargetHost) { - clientLog('Missing host or port information'); - client.close(3000); - return; - } - - // Validate port range - if (reqTargetPort < 0 || reqTargetPort > 65535) { - clientLog('Invalid port number: ' + reqTargetPort); - // Send empty binary data to notify requester that connection failed - client.send([]); - client.close(3000); - return; - } - - // eslint-disable-next-line prefer-const - let target: any; - const recvQueue: Buffer[] = []; - function flushMessagesQueue() { - while (recvQueue.length > 0) { - const msg = recvQueue.pop()! as Buffer; - const commandType = msg[0]; - clientLog('flushing', { commandType }, msg); - if (commandType === COMMAND_CHUNK) { - target.write(msg.slice(1)); - } else if (commandType === COMMAND_SET_SOCKETOPT) { - const SOL_SOCKET = 1; - const SO_KEEPALIVE = 9; - - const IPPROTO_TCP = 6; - const TCP_NODELAY = 1; - if (msg[1] === SOL_SOCKET && msg[2] === SO_KEEPALIVE) { - target.setKeepAlive(msg[3]); - } else if (msg[1] === IPPROTO_TCP && msg[2] === TCP_NODELAY) { - target.setNoDelay(msg[3]); - } - } else { - clientLog('Unknown command type: ' + commandType); - client.close(3000); - target.end(); - return; - } - } - } - - client.on('message', function (msg: Buffer) { - // clientLog('PHP -> network buffer:', msg); - recvQueue.unshift(msg); - if (target) { - flushMessagesQueue(); - } - }); - client.on('close', function (code: any, reason: any) { - clientLog( - 'WebSocket client disconnected: ' + code + ' [' + reason + ']' - ); - if (target) { - target.end(); - } - } as any); - client.on('error', function (a: string | Buffer) { - clientLog('WebSocket client error: ' + a); - target.end(); - }); - - // Resolve the target host to an IP address if it isn't one already. - // Prefer IPv4 addresses because many services (including Redis) only listen - // on IPv4 by default, and macOS's dns.lookup returns IPv6 for 'localhost'. - let reqTargetIp; - if (net.isIP(reqTargetHost) === 0) { - clientLog('resolving ' + reqTargetHost + '... '); - try { - reqTargetIp = await lookupIPv4(reqTargetHost); - clientLog('resolved ' + reqTargetHost + ' -> ' + reqTargetIp); - } catch (e) { - clientLog("can't resolve " + reqTargetHost + ' due to:', e); - // Send empty binary data to notify requester that connection was - // initiated - client.send([]); - // Without this random timeout, PHP sometimes doesn't notice the socket - // disconnected. TODO: figure out why. - setTimeout(() => { - client.close(3000); - }); - return; - } - } else { - reqTargetIp = reqTargetHost; - } - clientLog( - 'Opening a socket connection to ' + reqTargetIp + ':' + reqTargetPort - ); - target = net.createConnection(reqTargetPort, reqTargetIp, function () { - clientLog('Connected to target'); - flushMessagesQueue(); - }); - target.on('data', function (data: any) { - // clientLog( - // 'network -> PHP buffer:', - // [...data.slice(0, 100)].join(', ') + '...' - // ); - try { - client.send(data); - } catch { - clientLog('Client closed, cleaning up target'); - target.end(); - } - }); - target.on('end', function () { - clientLog('target disconnected'); - client.close(); - }); - target.on('error', function (e: any) { - clientLog('target connection error', e); - client.send([]); - // Without this random timeout, PHP sometimes doesn't notice the socket - // disconnected. TODO: figure out why. - setTimeout(() => { - client.close(3000); - try { - target.end(); - } catch { - // Ignore - } - }); - }); -} diff --git a/packages/php-wasm/node/src/lib/networking/tcp-socket.ts b/packages/php-wasm/node/src/lib/networking/tcp-socket.ts new file mode 100644 index 00000000000..7edda3dc140 --- /dev/null +++ b/packages/php-wasm/node/src/lib/networking/tcp-socket.ts @@ -0,0 +1,353 @@ +/** + * Lets PHP open and accept TCP connections in Node.js. + * + * Emscripten implements sockets with WebSockets, and WebAssembly has no + * network access of its own. Emscripten creates WebSockets through the + * `websocket.decorator` option and WebSocket servers through + * `websocket.serverDecorator`. We give it classes with the subset of the `ws` + * API it uses, backed by TCP sockets and servers in the same process. + * + * CAUTION: Do not route PHP's connections through a local WebSocket server. + * Any program or web page on the machine could connect to it and use PHP's + * connections, or open TCP connections as this Node.js process. + */ +import * as dns from 'dns'; +import { EventEmitter } from 'events'; +import * as net from 'net'; +import { debugLog } from './utils'; + +function log(...args: any[]) { + debugLog('[TCP]', ...args); +} + +// How long a socket may keep sending after the runtime exits. It gives the peer +// time to read what PHP wrote, while bounding how long a peer that never reads +// or closes can hold the socket, the exited runtime's memory, and a process exit. +export const RELEASED_SOCKET_TIMEOUT_MS = 30_000; + +const SOL_SOCKET = 1; +const SO_KEEPALIVE = 9; +const IPPROTO_TCP = 6; +const TCP_NODELAY = 1; + +/** + * Builds the URL Emscripten passes to the socket constructor. + * + * Nothing listens at this URL. It only carries the target host and port. + */ +export function getOutboundTcpSocketUrl(host: string, port: string) { + const query = new URLSearchParams({ host, port }).toString(); + return `tcp://php-wasm/?${query}`; +} + +/** + * A TCP connection with the subset of the `ws` WebSocket API that + * Emscripten's SOCKFS and the php-wasm socket functions use. + */ +export class TcpSocket extends EventEmitter { + static readonly CONNECTING = 0; + static readonly OPEN = 1; + static readonly CLOSING = 2; + static readonly CLOSED = 3; + + // Emscripten compares readyState with these on the instance, like + // `ws.readyState === ws.OPEN`. + readonly CONNECTING = TcpSocket.CONNECTING; + readonly OPEN = TcpSocket.OPEN; + readonly CLOSING = TcpSocket.CLOSING; + readonly CLOSED = TcpSocket.CLOSED; + + readyState: number; + // Emscripten sets this. The socket always delivers binary data. + binaryType = 'arraybuffer'; + /** + * Emscripten reads the address of an accepted connection's peer from + * `_socket`, like it does for `ws` WebSockets. + */ + readonly _socket?: net.Socket; + private released = false; + + constructor(socket: net.Socket | undefined, readyState: number) { + super(); + this._socket = socket; + this.readyState = readyState; + socket?.on('data', (data: Buffer) => { + // The socket is closed, so nothing will read this data. Drop it rather + // than resetting the connection: a reset makes the kernel discard what + // PHP wrote but the peer hasn't received yet. The socket closes when + // the peer closes its side, or after a timeout once the runtime exits. + if ( + this.readyState === this.CLOSING || + this.readyState === this.CLOSED + ) { + return; + } + // There's no backpressure: data goes to Emscripten as it arrives, as it + // did with the WebSocket proxy. Emscripten doesn't tell us when PHP has + // read it, so we can't pause the socket until then. + // Emscripten ignores messages that aren't marked as binary. + this.emit('message', data, true); + }); + // Emscripten has no half-closed state. PHP reads the data it already + // received and then the end of the stream. + socket?.on('end', () => this.shutDown()); + // Close without emitting `error`, so PHP reads the end of the stream as it + // did with the WebSocket proxy. See the CAUTION on OutboundTcpSocket. + socket?.on('error', (error) => { + log('Connection error', error); + this.shutDown(true); + }); + } + + send(data: ArrayBuffer | ArrayBufferView) { + if (this.readyState !== this.OPEN || !this._socket) { + throw new Error('The TCP connection is not open'); + } + const bytes = ArrayBuffer.isView(data) + ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) + : new Uint8Array(data); + this._socket.write(bytes); + } + + /** + * For php-wasm's setsockopt() with SO_KEEPALIVE and TCP_NODELAY. The current + * PHP builds look the socket up by file descriptor and never find it, so + * this isn't called yet. They also pass a pointer to the option's value + * rather than the value, so a fixed lookup alone would turn every option on. + */ + setSocketOpt(level: number, optionName: number, optionValue: number) { + if (level === SOL_SOCKET && optionName === SO_KEEPALIVE) { + this._socket?.setKeepAlive(Boolean(optionValue)); + } else if (level === IPPROTO_TCP && optionName === TCP_NODELAY) { + this._socket?.setNoDelay(Boolean(optionValue)); + } + } + + close() { + this.shutDown(); + } + + /** + * Releases the TCP socket when the runtime exits. + * + * End the write side so queued writes can drain, including those on + * persistent sockets PHP left open. Unref the socket so it doesn't keep + * Node.js running once those writes are sent. A timeout bounds how long + * pending writes or a peer that never closes can retain the connection. + * + * Ending rather than destroying means the peer sees a normal end of stream, + * even for a connection PHP left open mid-conversation, because destroying + * would discard PHP's queued writes. Until the socket closes, its listeners + * keep the exited runtime alive, including its WebAssembly heap. The + * timeout bounds that, and the runtime is freed once the socket closes. + */ + release() { + if (this.released) { + return; + } + this.released = true; + const socket = this._socket; + // Don't wait for an unused connection attempt after the runtime exits. + // A connecting socket with queued writes still needs to drain them. + // Writes PHP made before the socket reported itself open are still in + // Emscripten's own queue, not Node.js's, and are lost, as they were with + // the WebSocket proxy. + this.shutDown(socket?.connecting && socket.writableLength === 0); + if (!socket || socket.destroyed) { + return; + } + socket.unref(); + const timeout = setTimeout( + () => socket.destroy(), + RELEASED_SOCKET_TIMEOUT_MS + ); + timeout.unref(); + // The socket's listeners retain the runtime, so cancel the timer as + // soon as TCP closes rather than retaining it for the whole timeout. + socket.once('close', () => clearTimeout(timeout)); + } + + // php-wasm's connect() listens with the DOM-style event API. + addEventListener(event: string, listener: (...args: any[]) => void) { + this.on(event, listener); + } + + removeEventListener(event: string, listener: (...args: any[]) => void) { + this.off(event, listener); + } + + /** + * Closes the connection and emits `close` on the next tick, like `ws`. + */ + protected shutDown(destroy = false) { + // Destroy even if the socket already closed for PHP: a close only ends + // the write side, so TCP can still be connecting or sending. release() + // relies on this to stop a connection attempt nothing will use. + if (destroy) { + this._socket?.destroy(); + } + if ( + this.readyState === this.CLOSING || + this.readyState === this.CLOSED + ) { + return; + } + this.readyState = this.CLOSING; + if (!destroy) { + this._socket?.end(); + } + process.nextTick(() => { + this.readyState = this.CLOSED; + this.emit('close'); + }); + } +} + +/** + * A TCP connection PHP opens. + * + * The socket reports itself open right away and buffers writes until the TCP + * connection is established, like the WebSocket proxy it replaces. A connection + * that fails then closes, and PHP reads the end of the stream. + * + * CAUTION: Reporting the failure from connect() instead breaks cURL with JSPI. + * php-wasm's connect() drops a socket whose connection fails, so cURL's polls + * never see the failure, and it waits until its timeout. + */ +export class OutboundTcpSocket extends TcpSocket { + readonly url: string; + + constructor(url: string) { + const { searchParams } = new URL(url); + const host = searchParams.get('host'); + const port = Number(searchParams.get('port')); + const isValid = + !!host && Number.isInteger(port) && port > 0 && port < 65536; + if (!isValid) { + log(`Invalid TCP address: ${host}:${port}`); + } + super(isValid ? connect(host, port) : undefined, TcpSocket.CONNECTING); + this.url = url; + // Emscripten attaches its listeners after the constructor returns. + process.nextTick(() => { + if (this.readyState !== this.CONNECTING) { + return; + } + this.readyState = this.OPEN; + this.emit('open'); + // Treat an invalid address like a failed connection: open, then close. + if (!this._socket) { + this.shutDown(); + } + }); + } +} + +export interface TcpServerOptions { + host?: string; + port?: number; +} + +/** + * A TCP server PHP listens on, with the subset of the `ws` WebSocketServer + * API that Emscripten's SOCKFS uses. + * + * It listens on the host and port PHP binds to, and emits each accepted + * connection as a `TcpSocket`. Listening only there, rather than on every + * interface like the WebSocket bridge, keeps a server bound to 127.0.0.1 off + * the network. As a result, a server bound to `localhost`, which PHP resolves + * to 127.0.0.1, doesn't accept IPv6 clients. + * + * CAUTION: An error before the server listens, such as EADDRINUSE, is left + * unhandled so that it stops the process. Emscripten's listen() has already + * returned by then, so PHP can't report it. If the error reached PHP's socket, + * PHP would wait for connections forever. The cost is that PHP code binding a + * busy port, an address that isn't local, or a hostname that doesn't resolve + * stops the whole process, such as a Playground CLI worker. + */ +export class TcpServer extends EventEmitter { + // php-wasm's poll() waits on these for data on a listening socket. Its + // select() also checks a read set for writability, and an open socket is + // always writable. A socket leaves this set only when it closes, so + // stream_select() reports the listening socket ready while any connection + // to it is open, including one PHP already accepted, and before its data + // arrives. `ws` servers' clients behaved the same way. + readonly clients = new Set(); + private readonly server: net.Server; + private closed = false; + + constructor({ host, port }: TcpServerOptions) { + super(); + this.server = net.createServer((socket) => { + if (this.closed) { + socket.destroy(); + return; + } + // A client that reset the connection before Node.js handled it has + // no address. Emscripten's accept() fails on that with a JavaScript + // error instead of an errno, so drop the connection. + if (!socket.remoteAddress) { + socket.destroy(); + return; + } + const client = new TcpSocket(socket, TcpSocket.OPEN); + this.clients.add(client); + client.once('close', () => this.clients.delete(client)); + this.emit('connection', client); + }); + // Forward errors only once the server listens. Earlier errors stay + // unhandled; see the CAUTION above. + this.server.on('listening', () => { + this.server.on('error', (error) => { + log('Server error', error); + this.emit('error', error); + }); + this.emit('listening'); + }); + this.server.on('close', () => this.emit('close')); + if (host && net.isIP(host) === 0) { + // Emscripten only represents IPv4 addresses. A hostname that resolves + // to IPv6 first would make PHP see every client as 0.0.0.0. + dns.lookup(host, { family: 4 }, (error, address) => { + // PHP or the runtime may have closed the server during the lookup. + if (this.closed) { + return; + } + if (error) { + // Unhandled, like an error from listen(). + this.server.emit('error', error); + } else { + this.listen(port, address); + } + }); + } else { + this.listen(port, host); + } + } + + address() { + return this.server.address(); + } + + /** + * Stops listening. Connections already made stay open, including ones PHP + * hasn't accepted yet. + */ + close(callback?: (error?: Error) => void) { + this.closed = true; + this.server.close(callback); + } + + private listen(port: number | undefined, host: string | undefined) { + log(`Listening on ${host}:${port}`); + this.server.listen(port, host); + } +} + +function connect(host: string, port: number) { + log(`Connecting to ${host}:${port}`); + // Prefer IPv4 because many services (including Redis) only listen on + // IPv4 by default, and macOS resolves 'localhost' to IPv6 first. `family` + // only affects hostname lookups; IPv6 addresses still connect directly. + return net.createConnection({ host, port, family: 4 }); +} diff --git a/packages/php-wasm/node/src/lib/networking/utils.ts b/packages/php-wasm/node/src/lib/networking/utils.ts index 3e3c70b4490..f4f2fc1a129 100644 --- a/packages/php-wasm/node/src/lib/networking/utils.ts +++ b/packages/php-wasm/node/src/lib/networking/utils.ts @@ -1,4 +1,3 @@ -import type { AddressInfo } from 'net'; import { logger } from '@php-wasm/logger'; export function debugLog(message: any, ...args: any[]) { @@ -6,14 +5,3 @@ export function debugLog(message: any, ...args: any[]) { logger.log(message, ...args); } } - -export function getServerPort(server: { - address(): AddressInfo | string | null; -}): number { - const address = server.address(); - if (address === null || typeof address === 'string') { - throw new Error('Server address is not available'); - } - - return address.port; -} diff --git a/packages/php-wasm/node/src/lib/networking/with-networking.ts b/packages/php-wasm/node/src/lib/networking/with-networking.ts index 3f334ff5cce..f5f27f3dfc1 100644 --- a/packages/php-wasm/node/src/lib/networking/with-networking.ts +++ b/packages/php-wasm/node/src/lib/networking/with-networking.ts @@ -1,33 +1,93 @@ +import { logger } from '@php-wasm/logger'; import type { EmscriptenOptions } from '@php-wasm/universal'; +// The compiled PHP runtime calls require('ws') before it passes the `ws` +// classes to the decorators below, so the package must keep depending on it. +import 'ws'; +import type { TcpServerOptions } from './tcp-socket'; import { - initOutboundWebsocketProxyServer, - addSocketOptionsSupportToWebSocketClass, -} from './outbound-ws-to-tcp-proxy'; -import { addTCPServerToWebSocketServerClass } from './inbound-tcp-to-ws-proxy'; -import { getServerPort } from './utils'; + OutboundTcpSocket, + TcpServer, + type TcpSocket, + getOutboundTcpSocketUrl, +} from './tcp-socket'; export async function withNetworking( phpModuleArgs: EmscriptenOptions = {} ): Promise { - const outboundNetworkProxyServer = - await initOutboundWebsocketProxyServer(0); - const outboundProxyWsServerPort = getServerPort(outboundNetworkProxyServer); + // The runtime releases these when it exits. + const openHandles = new Set(); + let closed = false; + const track = (handle: TcpSocket | TcpServer) => { + openHandles.add(handle); + // A socket that PHP closed stays open until the peer closes its side, + // so keep tracking it until the TCP socket itself closes. + const closeEvents = + handle instanceof TcpServer ? handle : (handle._socket ?? handle); + closeEvents.once('close', () => openHandles.delete(handle)); + }; + + // Each runtime gets its own classes, so it only releases its own sockets. + class RuntimeOutboundTcpSocket extends OutboundTcpSocket { + constructor(url: string) { + // Use the existing failed-address path after exit. Throwing here + // escapes PHP with Asyncify instead of reporting a failed connection. + super(closed ? getOutboundTcpSocketUrl('', '0') : url); + if (!closed) { + track(this); + } + } + } + + class RuntimeTcpServer extends TcpServer { + constructor(options: TcpServerOptions) { + // Unlike a failed connection, PHP has no way to see a failed listen, + // so stop the request instead: stream_socket_server() after exit + // rejects php.run() with this error. + if (closed) { + throw new Error('The PHP runtime has exited'); + } + super(options); + track(this); + this.on('connection', track); + } + } return { ...phpModuleArgs, - outboundNetworkProxyServer, + closeNetworkConnections: () => { + if (closed) { + return; + } + closed = true; + // Drain queued writes and bound the lifetime of connections whose + // peers keep them open. See TcpSocket.release(). + // Release each handle even if another one fails. + for (const handle of openHandles) { + try { + if (handle instanceof TcpServer) { + handle.close(); + } else { + handle.release(); + } + } catch (error) { + logger.error( + 'Failed to release a network connection', + error + ); + } + } + // The options above replace one the caller passed in, so call it too. + phpModuleArgs.closeNetworkConnections?.(); + }, websocket: { ...(phpModuleArgs['websocket'] || {}), - url: (_: any, host: string, port: string) => { - const query = new URLSearchParams({ - host, - port, - }).toString(); - return `ws://127.0.0.1:${outboundProxyWsServerPort}/?${query}`; - }, + url: (_: any, host: string, port: string) => + getOutboundTcpSocketUrl(host, port), subprotocol: 'binary', - decorator: addSocketOptionsSupportToWebSocketClass, - serverDecorator: addTCPServerToWebSocketServerClass, + // Emscripten passes the `ws` classes to these decorators. PHP's + // sockets use TCP directly instead of local WebSocket servers. + decorator: () => RuntimeOutboundTcpSocket, + serverDecorator: () => RuntimeTcpServer, }, }; } diff --git a/packages/php-wasm/node/src/test/networking-port-allocation.spec.ts b/packages/php-wasm/node/src/test/networking-port-allocation.spec.ts index ecf8ab998a0..5db2027efc9 100644 --- a/packages/php-wasm/node/src/test/networking-port-allocation.spec.ts +++ b/packages/php-wasm/node/src/test/networking-port-allocation.spec.ts @@ -1,133 +1,71 @@ -import http from 'node:http'; import net from 'node:net'; import { afterEach, describe, expect, it, vi } from 'vitest'; import { withNetworking } from '../lib/networking/with-networking'; -import { addTCPServerToWebSocketServerClass } from '../lib/networking/inbound-tcp-to-ws-proxy'; -import { getServerPort } from '../lib/networking/utils'; describe('networking port allocation', () => { afterEach(() => { vi.restoreAllMocks(); }); - it('binds the outbound websocket proxy directly on an automatic port', async () => { - const originalListen = http.Server.prototype.listen; - const listenCalls: unknown[][] = []; - const listenSpy = vi - .spyOn(http.Server.prototype, 'listen') - .mockImplementation(function ( - this: http.Server, - ...args: Parameters - ) { - listenCalls.push(args); - return originalListen.apply(this, args); - }); + it('does not listen on a port for outbound connections', async () => { + const listenSpy = vi.spyOn(net.Server.prototype, 'listen'); const emscriptenOptions = await withNetworking({}); - const server = - emscriptenOptions.outboundNetworkProxyServer as http.Server; + const OutboundSocket = emscriptenOptions['websocket'].decorator(); + const socket = new OutboundSocket( + emscriptenOptions['websocket'].url(null, '127.0.0.1', '9') + ); + socket.close(); - try { - expect(listenCalls).toContainEqual([ - 0, - '127.0.0.1', - expect.any(Function), - ]); - expect( - emscriptenOptions['websocket']?.url(null, 'example.com', '80') - ).toContain(`127.0.0.1:${getServerPort(server)}`); - expect(listenSpy).toHaveBeenCalled(); - } finally { - await new Promise((resolve) => server.close(resolve)); - } + expect(listenSpy).not.toHaveBeenCalled(); }); - it('binds the inbound websocket proxy directly on an automatic port', async () => { - class StubWebSocketServer extends EventTarget { - private readonly port = 43210; - public options: { port: number }; - - constructor(options: { port: number }) { - super(); - this.options = options; - process.nextTick(() => - this.dispatchEvent(new Event('listening')) - ); - } - - once(event: string, callback: () => void) { - this.addEventListener(event, callback, { once: true }); - } + it('keeps a closeNetworkConnections option passed in', async () => { + const closeNetworkConnections = vi.fn(); + const emscriptenOptions = await withNetworking({ + closeNetworkConnections, + }); - close(callback?: () => void) { - callback?.(); - } + emscriptenOptions.closeNetworkConnections!(); - address() { - return { - address: '127.0.0.1', - family: 'IPv4', - port: this.port, - }; - } - } + expect(closeNetworkConnections).toHaveBeenCalledOnce(); + }); - let closeCalled = false; - const listenCalls: unknown[][] = []; - const listenSpy = vi - .spyOn(net.Server.prototype, 'listen') - .mockImplementation(function ( - this: net.Server, - ...args: Parameters - ) { - listenCalls.push(args); - Object.defineProperty(this, 'listening', { - value: true, - configurable: true, - }); - process.nextTick(() => { - const callback = [...args] - .reverse() - .find( - (arg): arg is () => void => - typeof arg === 'function' - ); - callback?.(); - this.emit('listening'); - }); - return this; - }); - const closeSpy = vi - .spyOn(net.Server.prototype, 'close') - .mockImplementation(function (this: net.Server) { - closeCalled = true; - return this; - }); + it('does not open outbound or listening sockets after exit', async () => { + const emscriptenOptions = await withNetworking({}); + const OutboundSocket = emscriptenOptions['websocket'].decorator(); + const Server = emscriptenOptions['websocket'].serverDecorator(); + // tcp-socket.ts calls createConnection() through a namespace import, + // which a spy on it can't see, so spy on the socket's connect(). + const connectSpy = vi.spyOn(net.Socket.prototype, 'connect'); + const listenSpy = vi.spyOn(net.Server.prototype, 'listen'); + emscriptenOptions.closeNetworkConnections!(); - const DecoratedServer = addTCPServerToWebSocketServerClass( - StubWebSocketServer as any + const socket = new OutboundSocket( + emscriptenOptions['websocket'].url(null, '127.0.0.1', '9') ); - const onListening = vi.fn(function (this: unknown) { - expect(this).toBe(websocketServer); - }); - const websocketServer = new DecoratedServer( - { port: 12345 }, - onListening + await new Promise((resolve) => socket.once('close', resolve)); + expect(() => new Server({ host: '127.0.0.1', port: 0 })).toThrow( + 'The PHP runtime has exited' ); + expect(socket._socket).toBeUndefined(); + expect(connectSpy).not.toHaveBeenCalled(); + expect(listenSpy).not.toHaveBeenCalled(); + }); + + it('listens only on the host and port PHP binds to', async () => { + const listenSpy = vi.spyOn(net.Server.prototype, 'listen'); - await new Promise((resolve) => process.nextTick(resolve)); - await new Promise((resolve) => process.nextTick(resolve)); + const emscriptenOptions = await withNetworking({}); + const Server = emscriptenOptions['websocket'].serverDecorator(); + const server = new Server({ host: '127.0.0.1', port: 0 }); + await new Promise((resolve) => server.once('listening', resolve)); try { - expect(websocketServer.options.port).toBe(0); - expect(listenCalls).toContainEqual([12345, expect.any(Function)]); - expect(onListening).toHaveBeenCalledOnce(); - websocketServer.close(); - expect(closeCalled).toBe(true); - expect(listenSpy).toHaveBeenCalled(); + expect(listenSpy).toHaveBeenCalledOnce(); + expect(server.address()).toMatchObject({ address: '127.0.0.1' }); } finally { - listenSpy.mockRestore(); - closeSpy.mockRestore(); + await new Promise((resolve) => server.close(resolve)); } }); }); diff --git a/packages/php-wasm/node/src/test/outbound-ws-to-tcp-proxy.spec.ts b/packages/php-wasm/node/src/test/outbound-ws-to-tcp-proxy.spec.ts deleted file mode 100644 index 7105c3a3b05..00000000000 --- a/packages/php-wasm/node/src/test/outbound-ws-to-tcp-proxy.spec.ts +++ /dev/null @@ -1,93 +0,0 @@ -import type http from 'node:http'; -import net from 'node:net'; -import { afterEach, beforeEach, describe, expect, it } from 'vitest'; -import { WebSocket } from 'ws'; -import { - COMMAND_CHUNK, - initOutboundWebsocketProxyServer, -} from '../lib/networking/outbound-ws-to-tcp-proxy'; -import { getServerPort } from '../lib/networking/utils'; - -describe('outbound websocket to TCP proxy', () => { - let target: net.Server; - let proxy: http.Server; - - beforeEach(async () => { - target = net.createServer((socket) => socket.pipe(socket)); - await new Promise((resolve) => - target.listen(0, '127.0.0.1', resolve) - ); - proxy = await initOutboundWebsocketProxyServer(0); - }); - - afterEach(async () => { - proxy.closeAllConnections(); - await new Promise((resolve) => proxy.close(resolve)); - await new Promise((resolve) => target.close(resolve)); - }); - - it('relays TCP traffic for the owning runtime', async () => { - const client = connect(); - await opened(client); - - client.send(Buffer.from([COMMAND_CHUNK, ...Buffer.from('bar')])); - - expect(await nextMessage(client)).toBe('bar'); - client.close(); - }); - - it.each(['https://example.com', 'null'])( - 'closes the connection of the %s browser origin', - async (origin) => { - const client = connect(origin); - client.once('open', () => - client.send(Buffer.from([COMMAND_CHUNK, ...Buffer.from('bar')])) - ); - - expect(await closed(client)).toBe(1008); - expect(await connections(target)).toBe(0); - } - ); - - it('closes the connection on an unknown command', async () => { - const client = connect(); - await opened(client); - - client.send(Buffer.from([0xff])); - - expect(await closed(client)).toBe(3000); - }); - - function connect(origin?: string) { - const params = new URLSearchParams({ - host: '127.0.0.1', - port: String(getServerPort(target)), - }); - return new WebSocket( - `ws://127.0.0.1:${getServerPort(proxy)}/?${params}`, - { origin } - ); - } -}); - -function opened(client: WebSocket) { - return new Promise((resolve) => client.once('open', resolve)); -} - -function nextMessage(client: WebSocket) { - return new Promise((resolve) => - client.once('message', (data) => resolve(data.toString())) - ); -} - -function closed(client: WebSocket) { - return new Promise((resolve) => - client.once('close', (code) => resolve(code)) - ); -} - -function connections(server: net.Server) { - return new Promise((resolve) => - server.getConnections((_, count) => resolve(count)) - ); -} diff --git a/packages/php-wasm/node/src/test/php-networking.spec.ts b/packages/php-wasm/node/src/test/php-networking.spec.ts index 436eb55a9b6..95d2033e2a1 100644 --- a/packages/php-wasm/node/src/test/php-networking.spec.ts +++ b/packages/php-wasm/node/src/test/php-networking.spec.ts @@ -2,14 +2,13 @@ import { PHP, SupportedPHPVersions, setPhpIniEntries, - popLoadedRuntime, type SupportedPHPVersion, } from '@php-wasm/universal'; import express from 'express'; import { rootCertificates } from 'tls'; import { loadNodeRuntime } from '../lib'; import type { PHPLoaderOptions } from '../lib'; -import http from 'http'; +import net from 'net'; const phpVersions = 'PHP' in process.env @@ -416,28 +415,335 @@ describe.each(phpVersions)('PHP %s', (phpVersion) => { }, { timeout: 15000 } ); + }); - it('should close server when runtime is exited', async () => { - const id = await loadNodeRuntime(phpVersion, options); - const rt = popLoadedRuntime(id, { - dangerouslyKeepTheRuntimeInTheMap: true, + describe('Runtime exit', () => { + it('should not open connections after the runtime exits', async () => { + const connections: net.Socket[] = []; + let notifyWaiting: () => void; + const waiting = new Promise( + (resolve) => (notifyWaiting = resolve) + ); + let notifyLateConnection: () => void; + const lateConnection = new Promise( + (resolve) => (notifyLateConnection = resolve) + ); + const tcpServer = net.createServer((socket) => { + connections.push(socket); + if (connections.length > 1) { + notifyLateConnection(); + } + socket.once('data', () => notifyWaiting()); }); - const php = new PHP(id); + await new Promise((resolve) => + tcpServer.listen(0, '127.0.0.1', resolve) + ); + const { port } = tcpServer.address() as net.AddressInfo; + let php: PHP | undefined; + try { + php = new PHP(await loadNodeRuntime(phpVersion, options)); + // Closing the socket at exit can wake PHP waiting in fread(), and + // PHP then runs the rest of its script. + const request = php.run({ + code: ` {}); + await waiting; + php.exit(); + // Without the guard, the late connection arrives within a few + // hundred milliseconds, and after the request settles. + await Promise.race([ + lateConnection, + new Promise((resolve) => setTimeout(resolve, 1000)), + ]); - expect(rt.outboundNetworkProxyServer).toBeDefined(); - expect(rt.outboundNetworkProxyServer).toBeInstanceOf( - http.Server + expect(connections).toHaveLength(1); + } finally { + php?.exit(); + connections.forEach((socket) => socket.destroy()); + await new Promise((resolve) => tcpServer.close(resolve)); + } + }); + + it('should flush persistent and closed connections when the runtime exits', async () => { + const size = 8 * 1024 * 1024; + const tcpServer = net.createServer(); + const connections: net.Socket[] = []; + const received: number[] = []; + const ended: Promise[] = []; + const bothConnected = new Promise((resolve) => + tcpServer.on('connection', (socket) => { + const index = connections.length; + connections.push(socket); + received.push(0); + // Keep writes queued until after the runtime exits. + socket.pause(); + socket.write('ready'); + socket.on('data', (data) => { + received[index] += data.length; + }); + ended.push( + new Promise((resolveEnd) => + socket.once('end', () => resolveEnd()) + ) + ); + if (connections.length === 2) { + resolve(); + } + }) + ); + await new Promise((resolve) => + tcpServer.listen(0, '127.0.0.1', resolve) ); - expect(rt.outboundNetworkProxyServer.listening).toBe(true); - php.exit(); + const { port } = tcpServer.address() as net.AddressInfo; + let php: PHP | undefined; + try { + php = new PHP(await loadNodeRuntime(phpVersion, options)); + const { text } = await php.run({ + code: ` socket.resume()); + await Promise.all(ended); - // Wait for the server to close - await new Promise((resolve) => { - rt.outboundNetworkProxyServer.on('close', resolve); - }); + expect(JSON.parse(text)).toEqual([size, size]); + expect(received).toEqual([size, size]); + } finally { + php?.exit(); + connections.forEach((socket) => socket.destroy()); + await new Promise((resolve) => tcpServer.close(resolve)); + } + }); + it('should unref every connection when the runtime exits', async () => { + // The server keeps its side open after the client closes, so a + // connection the runtime doesn't unref would keep Node.js running. + const tcpServer = net.createServer({ allowHalfOpen: true }); + const connections: net.Socket[] = []; + const bothConnected = new Promise((resolve) => + tcpServer.on('connection', (socket) => { + socket.resume(); + socket.write('ready'); + connections.push(socket); + if (connections.length === 2) { + resolve(); + } + }) + ); + await new Promise((resolve) => + tcpServer.listen(0, '127.0.0.1', resolve) + ); + const { port } = tcpServer.address() as net.AddressInfo; + let php: PHP | undefined; + try { + php = new PHP(await loadNodeRuntime(phpVersion, options)); + // Wait for both TCP connections. The runtime destroys a + // socket that's still connecting at exit instead of unrefing it. + await php.run({ + code: `(); + const unref = net.Socket.prototype.unref; + const unrefSpy = vi + .spyOn(net.Socket.prototype, 'unref') + .mockImplementation(function (this: net.Socket) { + if (!connections.includes(this)) { + unrefedPorts.add(this.localPort); + } + return unref.apply(this); + }); + try { + php.exit(); + } finally { + unrefSpy.mockRestore(); + } + + expect([...unrefedPorts].sort()).toEqual( + connections.map((socket) => socket.remotePort).sort() + ); + } finally { + php?.exit(); + connections.forEach((socket) => socket.destroy()); + tcpServer.close(); + } + }); + }); - expect(rt.outboundNetworkProxyServer.listening).toBe(false); + describe('Listening sockets', () => { + it('should accept a connection and report the real peer address', async () => { + const port = await getUnusedPort(); + const php = new PHP(await loadNodeRuntime(phpVersion, options)); + let clientPort = 0; + let received = ''; + let phpFinished = false; + // PHP's server starts during php.run(), so retry until it listens + // or PHP stops waiting for a connection. + const client = (async () => { + while (!phpFinished) { + try { + await new Promise((resolve, reject) => { + const socket = net.connect(port, '127.0.0.1'); + socket.once('error', reject); + socket.once('connect', () => { + clientPort = socket.localPort!; + socket.write('hello from node'); + }); + socket.on('data', (data) => (received += data)); + socket.once('close', () => resolve()); + }); + return; + } catch { + await new Promise((resolve) => + setTimeout(resolve, 20) + ); + } + } + })(); + try { + const { text } = await php.run({ + code: ` $data, 'peer' => $peer]); + `, + }); + phpFinished = true; + await client; + const { data, peer } = JSON.parse(text); + expect(data).toBe('hello from node'); + expect(peer).toBe(`127.0.0.1:${clientPort}`); + expect(received).toBe('hello from php'); + } finally { + phpFinished = true; + php.exit(); + } + }, 15000); + }); + + describe('Connection failures', () => { + it('should fail promptly when cURL connects to a closed port', async () => { + const port = await getUnusedPort(); + const php = new PHP(await loadNodeRuntime(phpVersion, options)); + try { + const { text } = await php.run({ + code: ` $result, + 'errno' => curl_errno($ch), + 'seconds' => microtime(true) - $start, + ]); + `, + }); + const { result, errno, seconds } = JSON.parse(text); + expect(result).toBe(false); + // 28 is CURLE_OPERATION_TIMEDOUT. + expect(errno).not.toBe(28); + expect(seconds).toBeLessThan(5); + } finally { + php.exit(); + } + }); + + it('should read the data and the end of the stream when the peer resets the connection', async () => { + const tcpServer = net.createServer((socket) => { + socket.write('partial'); + setTimeout(() => socket.resetAndDestroy(), 50); + }); + await new Promise((resolve) => + tcpServer.listen(0, '127.0.0.1', resolve) + ); + const { port } = tcpServer.address() as net.AddressInfo; + const php = new PHP(await loadNodeRuntime(phpVersion, options)); + try { + const { text } = await php.run({ + code: ` $data, + 'eof' => feof($socket), + 'seconds' => microtime(true) - $start, + ]); + `, + }); + const { data, eof, seconds } = JSON.parse(text); + expect(data).toBe('partial'); + expect(eof).toBe(true); + expect(seconds).toBeLessThan(5); + } finally { + php.exit(); + tcpServer.close(); + } }); }); }); }); + +async function getUnusedPort() { + const server = net.createServer(); + await new Promise((resolve) => + server.listen(0, '127.0.0.1', resolve) + ); + const { port } = server.address() as net.AddressInfo; + await new Promise((resolve) => server.close(resolve)); + return port; +} diff --git a/packages/php-wasm/node/src/test/php-redis.spec.ts b/packages/php-wasm/node/src/test/php-redis.spec.ts index 1af2a470d5f..aa9601e1f45 100644 --- a/packages/php-wasm/node/src/test/php-redis.spec.ts +++ b/packages/php-wasm/node/src/test/php-redis.spec.ts @@ -53,12 +53,12 @@ if (!isJspiAvailable) { /** * PHP helper function that creates a configured Redis instance with proper - * timeout settings for WebSocket-based TCP connections. + * timeout settings. */ const createRedisPHP = () => ` function createRedis() { $r = new Redis(); - // Set timeouts to give WebSocket proxy time to connect + // Allow time for the TCP connection to be established $r->connect('${REDIS_HOST}', ${REDIS_PORT}, 5.0); return $r; } diff --git a/packages/php-wasm/node/src/test/tcp-socket.spec.ts b/packages/php-wasm/node/src/test/tcp-socket.spec.ts new file mode 100644 index 00000000000..cccbe1ce9c0 --- /dev/null +++ b/packages/php-wasm/node/src/test/tcp-socket.spec.ts @@ -0,0 +1,365 @@ +import { execFile } from 'node:child_process'; +import * as dns from 'dns'; +import net from 'node:net'; +import path from 'node:path'; +import { afterEach, describe, expect, it, vi } from 'vitest'; +import { + RELEASED_SOCKET_TIMEOUT_MS, + OutboundTcpSocket, + TcpServer, + getOutboundTcpSocketUrl, +} from '../lib/networking/tcp-socket'; + +vi.mock('dns', async (importOriginal) => { + const original = await importOriginal(); + return { ...original, lookup: vi.fn(original.lookup) }; +}); + +describe('OutboundTcpSocket', () => { + it('opens and then closes when the connection is refused', async () => { + const port = await getClosedPort(); + const socket = new OutboundTcpSocket( + getOutboundTcpSocketUrl('127.0.0.1', String(port)) + ); + const events: string[] = []; + socket.on('open', () => events.push('open')); + socket.on('error', () => events.push('error')); + + await new Promise((resolve) => socket.once('close', resolve)); + + expect(events).toEqual(['open']); + expect(socket.readyState).toBe(OutboundTcpSocket.CLOSED); + }); + + it.each(['connecting', 'closed by PHP while connecting'])( + 'cancels an unused connection attempt when released while %s', + async (state) => { + const port = await getClosedPort(); + const socket = new OutboundTcpSocket( + getOutboundTcpSocketUrl('127.0.0.1', String(port)) + ); + const opened = vi.fn(); + socket.on('open', opened); + const closed = new Promise((resolve) => + socket.once('close', resolve) + ); + + // release() runs before the socket reports itself open. + if (state !== 'connecting') { + socket.close(); + } + socket.release(); + expect(socket._socket?.destroyed).toBe(true); + await closed; + expect(opened).not.toHaveBeenCalled(); + expect(socket.readyState).toBe(OutboundTcpSocket.CLOSED); + } + ); + + it('drops data after it closes, and stays open until the peer closes', async () => { + const server = net.createServer({ allowHalfOpen: true }); + const connection = new Promise((resolve) => + server.once('connection', resolve) + ); + await new Promise((resolve) => + server.listen(0, '127.0.0.1', resolve) + ); + const { port } = server.address() as net.AddressInfo; + const socket = new OutboundTcpSocket( + getOutboundTcpSocketUrl('127.0.0.1', String(port)) + ); + const messages: Buffer[] = []; + socket.on('message', (data: Buffer) => messages.push(data)); + const serverSocket = await connection; + const ended = new Promise((resolve) => + serverSocket.once('end', resolve) + ); + serverSocket.resume(); + + try { + socket.close(); + await ended; + await new Promise((resolve) => + serverSocket.write('sent after close', () => resolve()) + ); + await new Promise((resolve) => setTimeout(resolve, 50)); + + expect(messages).toEqual([]); + // A reset here could discard what PHP wrote before closing. + expect(socket._socket?.destroyed).toBe(false); + + const closed = new Promise((resolve) => + socket._socket!.once('close', resolve) + ); + serverSocket.end(); + await closed; + } finally { + serverSocket.destroy(); + server.close(); + } + }); + + it.each(['open', 'closed'])( + 'keeps sending queued writes when released while %s', + async (state) => { + // The server stops reading, so the writes are still buffered when the + // socket closes and the runtime releases it. + const size = 8 * 1024 * 1024; + const server = net.createServer(); + const connection = new Promise((resolve) => + server.once('connection', (socket) => { + socket.pause(); + resolve(socket); + }) + ); + await new Promise((resolve) => + server.listen(0, '127.0.0.1', resolve) + ); + const { port } = server.address() as net.AddressInfo; + const socket = new OutboundTcpSocket( + getOutboundTcpSocketUrl('127.0.0.1', String(port)) + ); + await new Promise((resolve) => socket.once('open', resolve)); + // The adapter opens before TCP connects. These writes must survive + // release even while the underlying connection is still in progress. + socket.send(new Uint8Array(size)); + if (state === 'closed') { + socket.close(); + } + socket.release(); + const serverSocket = await connection; + let received = 0; + const ended = new Promise((resolve) => { + serverSocket.on('data', (data) => (received += data.length)); + serverSocket.once('close', resolve); + }); + + try { + await new Promise((resolve) => setTimeout(resolve, 50)); + serverSocket.resume(); + await ended; + } finally { + serverSocket.destroy(); + server.close(); + } + + expect(received).toBe(size); + } + ); + + it('enforces the original release deadline if the peer never closes', async () => { + const { socket, cleanUp } = await closeWithPeerOpen(); + // Fake only the timer, so the socket itself keeps running for real. + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + try { + socket.release(); + vi.advanceTimersByTime(RELEASED_SOCKET_TIMEOUT_MS - 1); + // Repeated cleanup must neither extend the deadline nor add timers. + socket.release(); + expect(vi.getTimerCount()).toBe(1); + expect(socket._socket?.destroyed).toBe(false); + vi.advanceTimersByTime(1); + expect(socket._socket?.destroyed).toBe(true); + } finally { + vi.useRealTimers(); + cleanUp(); + } + }); + + it('cancels the release timeout when TCP closes', async () => { + const { socket, serverSocket, cleanUp } = await closeWithPeerOpen(); + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + try { + socket.release(); + expect(vi.getTimerCount()).toBe(1); + const closed = new Promise((resolve) => + socket._socket!.once('close', resolve) + ); + serverSocket.end(); + await closed; + + expect(vi.getTimerCount()).toBe(0); + } finally { + vi.useRealTimers(); + cleanUp(); + } + }); + + it('does not schedule cleanup for a destroyed TCP socket', async () => { + const { socket, cleanUp } = await closeWithPeerOpen(); + const closed = new Promise((resolve) => + socket._socket!.once('close', resolve) + ); + socket._socket!.destroy(); + await closed; + vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] }); + try { + socket.release(); + expect(vi.getTimerCount()).toBe(0); + } finally { + vi.useRealTimers(); + cleanUp(); + } + }); + + it('does not keep Node.js running while a released socket waits', async () => { + const { socket, cleanUp } = await closeWithPeerOpen(); + // Node.js doesn't count unref'd sockets and timers as keeping it running. + const countKeepingNodeRunning = () => + process + .getActiveResourcesInfo() + .filter( + (resource) => + resource === 'Timeout' || resource === 'TCPSocketWrap' + ).length; + try { + const before = countKeepingNodeRunning(); + socket.release(); + // The released socket stops counting, and its timeout never does. + expect(countKeepingNodeRunning()).toBe(before - 1); + } finally { + socket._socket?.destroy(); + cleanUp(); + } + }); +}); + +describe('TcpServer', () => { + afterEach(() => { + vi.restoreAllMocks(); + }); + + it('does not listen when it closes during a hostname lookup', () => { + let finishLookup = () => {}; + vi.mocked(dns.lookup).mockImplementationOnce((( + _hostname: string, + _options: dns.LookupOptions, + callback: (error: null, address: string, family: number) => void + ) => { + finishLookup = () => callback(null, '127.0.0.1', 4); + }) as typeof dns.lookup); + const listenSpy = vi.spyOn(net.Server.prototype, 'listen'); + + const server = new TcpServer({ host: 'php-wasm.test', port: 0 }); + server.close(); + finishLookup(); + + expect(dns.lookup).toHaveBeenCalled(); + expect(listenSpy).not.toHaveBeenCalled(); + }); + + it('drops a connection that has no remote address', async () => { + const server = new TcpServer({ host: '127.0.0.1', port: 0 }); + await new Promise((resolve) => server.once('listening', resolve)); + const onConnection = vi.fn(); + server.on('connection', onConnection); + // A connection reset before Node.js handles it has no remote address, + // like a socket that was never connected. + const socket = new net.Socket(); + const destroy = vi.spyOn(socket, 'destroy'); + + try { + (server as unknown as { server: net.Server }).server.emit( + 'connection', + socket + ); + } finally { + server.close(); + } + + expect(destroy).toHaveBeenCalled(); + expect(onConnection).not.toHaveBeenCalled(); + }); + + it('stops the process when the port is already in use', async () => { + const blocker = net.createServer(); + await new Promise((resolve) => + blocker.listen(0, '127.0.0.1', resolve) + ); + const { port } = blocker.address() as net.AddressInfo; + // The error is uncaught by design, so run the server in a child process. + // Like Emscripten, the script listens for the server's `error` events. + const repoRoot = path.resolve(__dirname, '../../../../..'); + const loader = path.join( + repoRoot, + 'packages/meta/src/node-es-module-loader/loader.mts' + ); + const module = path.join(__dirname, '../lib/networking/tcp-socket.ts'); + const script = ` + import { TcpServer } from ${JSON.stringify(module)}; + const server = new TcpServer({ host: '127.0.0.1', port: ${port} }); + server.on('error', () => {}); + setTimeout(() => process.exit(0), 5000); + `; + try { + const { code, stderr } = await new Promise<{ + code: number; + stderr: string; + }>((resolve) => { + execFile( + process.execPath, + [ + '--no-warnings', + `--loader=${loader}`, + '--input-type=module', + '-e', + script, + ], + (error, _stdout, stderr) => + resolve({ code: Number(error?.code ?? 0), stderr }) + ); + }); + + expect(code).not.toBe(0); + expect(stderr).toContain('EADDRINUSE'); + } finally { + blocker.close(); + } + }, 15000); +}); + +async function getClosedPort() { + const server = net.createServer(); + await new Promise((resolve) => + server.listen(0, '127.0.0.1', resolve) + ); + const { port } = server.address() as net.AddressInfo; + await new Promise((resolve) => server.close(resolve)); + return port; +} + +/** + * Opens a socket, closes it, and waits until the peer sees the close. The peer + * keeps its side open, so nothing but a timeout would ever close the socket. + */ +async function closeWithPeerOpen() { + const server = net.createServer({ allowHalfOpen: true }); + let serverSocket: net.Socket | undefined; + const cleanUp = () => { + serverSocket?.destroy(); + server.close(); + }; + try { + const connection = new Promise((resolve) => + server.once('connection', resolve) + ); + await new Promise((resolve) => + server.listen(0, '127.0.0.1', resolve) + ); + const { port } = server.address() as net.AddressInfo; + const socket = new OutboundTcpSocket( + getOutboundTcpSocketUrl('127.0.0.1', String(port)) + ); + serverSocket = await connection; + const ended = new Promise((resolve) => + serverSocket!.once('end', resolve) + ); + serverSocket.resume(); + socket.close(); + await ended; + return { socket, serverSocket, cleanUp }; + } catch (error) { + cleanUp(); + throw error; + } +} diff --git a/packages/php-wasm/node/vite.asyncify.config.ts b/packages/php-wasm/node/vite.asyncify.config.ts new file mode 100644 index 00000000000..ccb48c9330b --- /dev/null +++ b/packages/php-wasm/node/vite.asyncify.config.ts @@ -0,0 +1,20 @@ +import { defineConfig } from 'vite'; +import config from './vite.config'; + +/** + * For tests that must load the Asyncify PHP build. + * + * loadNodeRuntime() loads the JSPI build whenever Node.js supports JSPI. + * Node.js enables JSPI by default from 24.20.0, and it can't be turned off, + * so these tests need an older Node.js version. + */ +export default defineConfig((env) => { + if ('Suspending' in WebAssembly) { + throw new Error( + `Node.js ${process.version} enables JSPI, so PHP would load the JSPI ` + + 'build instead of Asyncify. Run these tests with Node.js 24.18 or ' + + '24.19, for example after `nvm install 24.18.0`.' + ); + } + return config(env); +}); diff --git a/packages/php-wasm/universal/src/lib/load-php-runtime.ts b/packages/php-wasm/universal/src/lib/load-php-runtime.ts index cfd1b0a230b..817db6c68c0 100644 --- a/packages/php-wasm/universal/src/lib/load-php-runtime.ts +++ b/packages/php-wasm/universal/src/lib/load-php-runtime.ts @@ -172,9 +172,16 @@ export async function loadPHPRuntime( PHPRuntime.originalExit = PHPRuntime._exit; PHPRuntime._exit = function (code: number) { - if (PHPRuntime.outboundNetworkProxyServer) { - PHPRuntime.outboundNetworkProxyServer.close(); - PHPRuntime.outboundNetworkProxyServer.closeAllConnections(); + // Exit even if closing the network fails. PHP.exit() swallows errors, + // so a throw here would leave the runtime running without notice. + try { + PHPRuntime.closeNetworkConnections?.(); + if (PHPRuntime.outboundNetworkProxyServer) { + PHPRuntime.outboundNetworkProxyServer.close(); + PHPRuntime.outboundNetworkProxyServer.closeAllConnections(); + } + } catch (error) { + logger.error('Failed to close network connections', error); } loadedRuntimes.delete(id); return PHPRuntime.originalExit(code); @@ -303,6 +310,22 @@ export type EmscriptenOptions = { onRuntimeInitialized?: (phpRuntime: PHPRuntime) => void; monitorRunDependencies?: (left: number) => void; onMessage?: (listener: EmscriptenMessageListener) => void; + /** + * Closes PHP's open TCP connections and listening sockets. The runtime + * calls it on exit. + */ + closeNetworkConnections?: () => void; + /** + * @deprecated php-wasm no longer sets this. Use `closeNetworkConnections`. + * + * Node.js runtimes used to start a WebSocket-to-TCP proxy server on + * 127.0.0.1 for PHP's outbound connections. Any program on the machine + * could connect to it and open TCP connections through the Node.js + * process, including programs blocked from the network themselves. + * Runtimes now open TCP connections in-process, without a listening port. + * + * A server passed here is still closed when the runtime exits. + */ outboundNetworkProxyServer?: Server< typeof IncomingMessage, typeof ServerResponse diff --git a/packages/playground/test-built-npm-packages/es-modules-and-vitest/run-tests.ts b/packages/playground/test-built-npm-packages/es-modules-and-vitest/run-tests.ts index d871ce2ffce..2ad28e6ac68 100644 --- a/packages/playground/test-built-npm-packages/es-modules-and-vitest/run-tests.ts +++ b/packages/playground/test-built-npm-packages/es-modules-and-vitest/run-tests.ts @@ -43,6 +43,7 @@ const testFiles = [ './tests/wp.spec.ts', './tests/git-directory.spec.ts', './tests/assets.spec.ts', + './tests/networking.spec.ts', ]; for (const phpVersion of SupportedPHPVersions) { diff --git a/packages/playground/test-built-npm-packages/es-modules-and-vitest/tests/networking.spec.ts b/packages/playground/test-built-npm-packages/es-modules-and-vitest/tests/networking.spec.ts new file mode 100644 index 00000000000..8e73a8d6b5d --- /dev/null +++ b/packages/playground/test-built-npm-packages/es-modules-and-vitest/tests/networking.spec.ts @@ -0,0 +1,59 @@ +import { describe, it } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFile } from 'node:fs/promises'; +import net from 'node:net'; +import { fileURLToPath } from 'node:url'; +import { loadNodeRuntime } from '@php-wasm/node'; +import type { SupportedPHPVersion } from '@php-wasm/universal'; +import { PHP, SupportedPHPVersions } from '@php-wasm/universal'; + +const phpVersion = process.env.PHP_VERSION as SupportedPHPVersion; +if (!phpVersion) { + throw new Error('PHP_VERSION is not set'); +} +if (!SupportedPHPVersions.includes(phpVersion)) { + throw new Error(`PHP_VERSION '${phpVersion}' is not supported`); +} + +describe(`PHP ${phpVersion}`, () => { + it('Should open a TCP connection', { timeout: 60000 }, async () => { + const server = net.createServer((socket) => socket.end('pong')); + await new Promise((resolve) => + server.listen(0, '127.0.0.1', resolve) + ); + const { port } = server.address() as net.AddressInfo; + const php = new PHP( + await loadNodeRuntime(phpVersion, { + emscriptenOptions: { processId: 1 }, + }) + ); + try { + const { text } = await php.run({ + code: ` { + const packageJsonPath = fileURLToPath( + import.meta.resolve('@php-wasm/node/package.json') + ); + const { dependencies } = JSON.parse( + await readFile(packageJsonPath, 'utf8') + ); + assert.ok(dependencies?.ws, '@php-wasm/node must depend on ws'); + }); +});