| // Licensed to the Software Freedom Conservancy (SFC) under one | |
| // or more contributor license agreements. See the NOTICE file | |
| // distributed with this work for additional information | |
| // regarding copyright ownership. The SFC licenses this file | |
| // to you under the Apache License, Version 2.0 (the | |
| // "License"); you may not use this file except in compliance | |
| // with the License. You may obtain a copy of the License at | |
| // | |
| // http://www.apache.org/licenses/LICENSE-2.0 | |
| // | |
| // Unless required by applicable law or agreed to in writing, | |
| // software distributed under the License is distributed on an | |
| // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| // KIND, either express or implied. See the License for the | |
| // specific language governing permissions and limitations | |
| // under the License. | |
| const { EventEmitter } = require('node:events') | |
| const WebSocket = require('ws') | |
| const RESPONSE_TIMEOUT = 1000 * 30 | |
| class Index extends EventEmitter { | |
| id = 0 | |
| connected = false | |
| events = [] | |
| browsingContexts = [] | |
| /** | |
| * Create a new websocket connection | |
| * @param _webSocketUrl | |
| */ | |
| constructor(_webSocketUrl) { | |
| super() | |
| this.connected = false | |
| this._closed = false | |
| this._pending = new Map() | |
| this._connectWaiters = new Set() | |
| // removeCallback(id) only receives the subscriptionId — off() needs the event | |
| // name and the exact handler function too, so this holds what it needs to | |
| // detach the right listener without the caller having to keep them around. | |
| this._callbacks = new Map() | |
| this._ws = new WebSocket(_webSocketUrl) | |
| this._ws.on('open', () => { | |
| // The handshake can complete after close()/_failPending() has already | |
| // marked the connection closed. Don't flip connected back to true and | |
| // proactively close the now-orphan socket so it does not leak. | |
| if (this._closed) { | |
| try { | |
| this._ws.close() | |
| } catch { | |
| /* socket already closing */ | |
| } | |
| return | |
| } | |
| this.connected = true | |
| for (const { resolve } of this._connectWaiters) { | |
| resolve() | |
| } | |
| this._connectWaiters.clear() | |
| }) | |
| // Single shared response dispatcher. Avoids attaching a new 'message' | |
| // listener for every in-flight send(), which previously caused | |
| // MaxListenersExceededWarning under concurrent BiDi traffic | |
| // (e.g. network interception during a page navigation). | |
| this._ws.on('message', (data) => { | |
| // Frames can arrive after close() has cleared _pending; ignore them | |
| // rather than re-emitting parse errors or dispatching to nothing. | |
| if (this._closed) { | |
| return | |
| } | |
| let payload | |
| try { | |
| payload = JSON.parse(data.toString()) | |
| } catch (err) { | |
| // Surface protocol parse failures rather than silently dropping — | |
| // otherwise callers see misleading send() timeouts. | |
| this._emitOrWarn(new Error(`Failed to parse BiDi message: ${err.message}`), 'BiDiProtocolWarning') | |
| return | |
| } | |
| // Messages without a numeric id are BiDi events, not command responses. | |
| // Re-emit them on this EventEmitter by method name (e.g. | |
| // 'browsingContext.contextCreated') so that generated domain classes can | |
| // subscribe via bidi.on(methodName, callback) instead of each attaching | |
| // a new raw ws.on('message', ...) listener. The existing hand-written | |
| // modules (logInspector, network, etc.) continue to use their own | |
| // ws.on('message', ...) listeners unchanged — this emission is purely | |
| // additive and does not affect those code paths. | |
| if (payload == null || typeof payload.id !== 'number') { | |
| if (payload != null && typeof payload.method === 'string') { | |
| // 'error' is a reserved EventEmitter event — emitting it without a | |
| // listener throws and crashes the process. Route any peer-supplied | |
| // method named 'error' through the same guarded path used for JSON | |
| // parse failures rather than forwarding it directly. | |
| if (payload.method === 'error') { | |
| this._emitOrWarn( | |
| new Error(`BiDi protocol error event: ${JSON.stringify(payload.params)}`), | |
| 'BiDiProtocolWarning', | |
| ) | |
| } else { | |
| // A listener can throw synchronously — most notably a typed | |
| // addCallback() dispatcher's fromWire() rejecting a corrupted | |
| // payload, which is meant to error rather than warn. Dispatched | |
| // one listener at a time (not via a single this.emit() call) so a | |
| // throwing listener doesn't prevent a sibling listener registered | |
| // for the same event from still receiving this delivery — emit() | |
| // itself aborts the rest of its iteration once one listener throws. | |
| // rawListeners(), not listeners(): listeners() unwraps a once() | |
| // registration to the caller's original function, so invoking it | |
| // here directly (bypassing emit()) would skip the internal wrapper | |
| // that removes it after one call — rawListeners() returns that | |
| // wrapper itself, preserving once()'s self-removal. | |
| for (const listener of this.rawListeners(payload.method)) { | |
| try { | |
| listener(payload.params) | |
| } catch (err) { | |
| const wrapped = err instanceof Error ? err : new Error(String(err)) | |
| this._emitOrWarn(wrapped, 'BiDiEventHandlerWarning') | |
| } | |
| } | |
| } | |
| } | |
| return | |
| } | |
| const entry = this._pending.get(payload.id) | |
| if (entry === undefined) { | |
| return | |
| } | |
| clearTimeout(entry.timeoutId) | |
| this._pending.delete(payload.id) | |
| entry.resolve(payload) | |
| }) | |
| // Fail any in-flight send() calls promptly when the peer disconnects | |
| // or the socket errors, instead of waiting for RESPONSE_TIMEOUT. | |
| this._ws.on('close', () => { | |
| this._failPending(new Error('BiDi connection closed unexpectedly')) | |
| }) | |
| this._ws.on('error', (err) => { | |
| this._failPending(new Error(`BiDi connection error: ${err.message}`)) | |
| }) | |
| } | |
| /** | |
| * Reject any in-flight sends and mark the connection failed. Idempotent so | |
| * that close() and the underlying 'close'/'error' events do not double-reject. | |
| * @param {Error} error | |
| * @private | |
| */ | |
| _failPending(error) { | |
| if (this._closed) { | |
| return | |
| } | |
| this._closed = true | |
| this.connected = false | |
| for (const { reject, timeoutId } of this._pending.values()) { | |
| clearTimeout(timeoutId) | |
| reject(error) | |
| } | |
| this._pending.clear() | |
| // Reject any callers parked in waitForConnection() so close() (or an | |
| // unexpected disconnect) cannot leave them hanging forever. | |
| for (const { reject } of this._connectWaiters) { | |
| reject(error) | |
| } | |
| this._connectWaiters.clear() | |
| // Detach every addCallback() listener too. Once closed, removeCallback() | |
| // can no longer reach the remote end (send() would just throw), so nothing | |
| // else will ever detach these listeners. Drop them here instead of leaving | |
| // them attached to an EventEmitter nothing will ever emit on again. | |
| for (const { method, handler } of this._callbacks.values()) { | |
| this.off(method, handler) | |
| } | |
| this._callbacks.clear() | |
| } | |
| /** | |
| * Emits `err` as an 'error' event if anything is listening for one, | |
| * otherwise reports it as a process warning under `warningType` — never | |
| * emits 'error' with no listener attached, which would itself throw and | |
| * crash the process. Also guards against the 'error' listener itself | |
| * throwing, so a broken listener can't cause the exact kind of crash this | |
| * helper exists to prevent, just one level removed. | |
| * @param {Error} err | |
| * @param {string} warningType | |
| * @private | |
| */ | |
| _emitOrWarn(err, warningType) { | |
| if (this.listenerCount('error') === 0) { | |
| process.emitWarning(err.message, warningType) | |
| return | |
| } | |
| try { | |
| this.emit('error', err) | |
| } catch (listenerErr) { | |
| const wrapped = listenerErr instanceof Error ? listenerErr : new Error(String(listenerErr)) | |
| process.emitWarning(`BiDi 'error' listener threw: ${wrapped.message}`, warningType) | |
| } | |
| } | |
| /** | |
| * @returns {WebSocket} | |
| */ | |
| get socket() { | |
| return this._ws | |
| } | |
| /** | |
| * @returns {boolean|*} | |
| */ | |
| get isConnected() { | |
| return this.connected | |
| } | |
| /** | |
| * Get Bidi Status | |
| * @returns {Promise<*>} | |
| */ | |
| get status() { | |
| return this.send({ | |
| method: 'session.status', | |
| params: {}, | |
| }) | |
| } | |
| /** | |
| * Resolve connection | |
| * @returns {Promise<unknown>} | |
| */ | |
| async waitForConnection() { | |
| return new Promise((resolve, reject) => { | |
| if (this._closed) { | |
| reject(new Error('BiDi connection is closed')) | |
| return | |
| } | |
| if (this.connected) { | |
| resolve() | |
| return | |
| } | |
| // Park the waiter in a Set so the constructor's 'open' handler can | |
| // resolve it and _failPending() can reject it. Avoids attaching socket | |
| // listeners that close()'s removeAllListeners('close') would strip. | |
| this._connectWaiters.add({ resolve, reject }) | |
| }) | |
| } | |
| /** | |
| * Sends a bidi request | |
| * @param params | |
| * @returns {Promise<unknown>} | |
| */ | |
| async send(params) { | |
| if (this._closed) { | |
| throw new Error('BiDi connection is closed') | |
| } | |
| if (!this.connected) { | |
| await this.waitForConnection() | |
| } | |
| // Defense in depth: even after waitForConnection() resolves, the socket | |
| // may have transitioned to CLOSING/CLOSED (e.g. caller closed the raw | |
| // socket). Refuse rather than throwing from inside ws.send(). | |
| if (this._ws.readyState !== WebSocket.OPEN) { | |
| throw new Error('BiDi connection is not open') | |
| } | |
| const id = ++this.id | |
| this._ws.send(JSON.stringify({ id, ...params })) | |
| return new Promise((resolve, reject) => { | |
| const timeoutId = setTimeout(() => { | |
| this._pending.delete(id) | |
| reject(new Error(`Request with id ${id} timed out`)) | |
| }, RESPONSE_TIMEOUT) | |
| this._pending.set(id, { resolve, reject, timeoutId }) | |
| }) | |
| } | |
| /** | |
| * Subscribe to events. | |
| * | |
| * Not the correct implementation — this is not tied to a subscription id, so | |
| * {@link unsubscribe} below cancels by event/context name and can affect a | |
| * subscription made elsewhere (including via {@link addCallback}) for the | |
| * same event. Kept as-is only because the existing hand-written bidi/*.js | |
| * modules already depend on this exact shape; new code should use | |
| * {@link addCallback} instead, which is properly scoped by subscription id | |
| * (mirroring Java's BiDi#addListener/removeListener — see BiDi.java). Once | |
| * those hand-written modules are replaced by generated code built on | |
| * addCallback/removeCallback, this method (and unsubscribe) can be removed. | |
| * @param events | |
| * @param browsingContexts | |
| * @returns {Promise<void>} | |
| */ | |
| async subscribe(events, browsingContexts) { | |
| function toArray(arg) { | |
| if (arg === undefined) { | |
| return [] | |
| } | |
| return Array.isArray(arg) ? [...arg] : [arg] | |
| } | |
| const eventsArray = toArray(events) | |
| const contextsArray = toArray(browsingContexts) | |
| const params = { | |
| method: 'session.subscribe', | |
| params: {}, | |
| } | |
| if (eventsArray.length && eventsArray.some((event) => typeof event !== 'string')) { | |
| throw new TypeError('events should be string or string array') | |
| } | |
| if (contextsArray.length && contextsArray.some((context) => typeof context !== 'string')) { | |
| throw new TypeError('browsingContexts should be string or string array') | |
| } | |
| if (eventsArray.length) { | |
| params.params.events = eventsArray | |
| } | |
| if (contextsArray.length) { | |
| params.params.contexts = contextsArray | |
| } | |
| this.events.push(...eventsArray) | |
| await this.send(params) | |
| } | |
| /** | |
| * Unsubscribe to events. See the note on {@link subscribe} above — this | |
| * cancels by event/context name, not by subscription id, so it can affect a | |
| * subscription this same connection made elsewhere. New code should call | |
| * the returned handle's `unsubscribe()` from {@link addCallback} instead. | |
| * @param events | |
| * @param browsingContexts | |
| * @returns {Promise<void>} | |
| */ | |
| async unsubscribe(events, browsingContexts) { | |
| const eventsToRemove = typeof events === 'string' ? [events] : events | |
| // Check if the eventsToRemove are in the subscribed events array | |
| // Filter out events that are not in this.events before filtering | |
| const existingEvents = eventsToRemove.filter((event) => this.events.includes(event)) | |
| // Remove the events from the subscribed events array | |
| this.events = this.events.filter((event) => !existingEvents.includes(event)) | |
| if (typeof browsingContexts === 'string') { | |
| this.browsingContexts.pop() | |
| } else if (Array.isArray(browsingContexts)) { | |
| this.browsingContexts = this.browsingContexts.filter((id) => !browsingContexts.includes(id)) | |
| } | |
| if (existingEvents.length === 0) { | |
| return | |
| } | |
| const params = { | |
| method: 'session.unsubscribe', | |
| params: { | |
| events: existingEvents, | |
| }, | |
| } | |
| if (this.browsingContexts.length > 0) { | |
| params.params.contexts = this.browsingContexts | |
| } | |
| await this.send(params) | |
| } | |
| /** | |
| * Registers `handler` to be called on every delivered `method` event, | |
| * globally (no context/user-context scoping). This is the correct mechanism | |
| * — see the note on {@link subscribe}/{@link unsubscribe} above, which is a | |
| * separate, imprecise, event-name-scoped mechanism kept only for the | |
| * existing hand-written bidi/*.js modules until they're replaced by | |
| * generated code built on this method instead. | |
| * | |
| * Keyed by the server-assigned `subscription` id from `session.subscribe`'s | |
| * response, which the spec mints fresh on every call — so multiple | |
| * independent subscriptions to the same event coexist safely, and the | |
| * returned handle's `unsubscribe()` never affects another callback | |
| * registered for the same method. No client-side ref-counting is needed: | |
| * the protocol's own per-subscription id already gives each caller its own | |
| * independent, individually-cancellable registration. | |
| * | |
| * The local listener is attached before `session.subscribe` is awaited, not | |
| * after — so an event the browser starts sending as soon as it processes | |
| * the subscription can't arrive in a gap where nothing is listening yet. | |
| * If the subscribe call then fails (or returns no usable id), the listener | |
| * is removed again before the error propagates, so a failed subscription | |
| * doesn't leak one. | |
| * @param {string} method | |
| * @param {function(unknown): void} handler | |
| * @returns {Promise<{id: string, unsubscribe: function(): Promise<void>}>} | |
| */ | |
| async addCallback(method, handler) { | |
| this.on(method, handler) | |
| try { | |
| const response = await this.send({ | |
| method: 'session.subscribe', | |
| params: { events: [method] }, | |
| }) | |
| // send() resolves with the raw reply on any response, including a | |
| // wire-level error — check for one explicitly and surface it plainly, | |
| // rather than letting it fall through to the generic "no subscription | |
| // id" message below (matching how Domain#send() reports the same shape). | |
| if (response?.error !== undefined) { | |
| throw new Error(`${response.error}: ${response.message}`) | |
| } | |
| const subscriptionId = response?.result?.subscription | |
| if (typeof subscriptionId !== 'string' || subscriptionId === '') { | |
| throw new Error(`session.subscribe did not return a valid subscription id: ${JSON.stringify(response)}`) | |
| } | |
| this._callbacks.set(subscriptionId, { method, handler }) | |
| return { | |
| id: subscriptionId, | |
| unsubscribe: () => this.removeCallback(subscriptionId), | |
| } | |
| } catch (err) { | |
| this.off(method, handler) | |
| throw err | |
| } | |
| } | |
| /** | |
| * Removes exactly the callback registered under `subscriptionId` (as | |
| * returned by {@link addCallback}). A no-op if already removed — including | |
| * once the connection is closed, since _failPending() has already cleaned | |
| * up local state at that point (and there is no remote end left to reach: | |
| * entry is only ever defined here while _closed is still false, since | |
| * _failPending() clears every entry in the same synchronous call that sets | |
| * _closed). Never affects any other callback, including another one | |
| * registered for the same method. | |
| * | |
| * Local state is only cleaned up once the remote end has confirmed the | |
| * subscription is actually gone — not before sending session.unsubscribe, | |
| * and not on a wire-level error response. Cleaning up first would leave a | |
| * phantom "removed" subscription if the send failed or was rejected: local | |
| * delivery would stop while the browser kept sending it, and a retry would | |
| * silently no-op since this method's own early return above would find no | |
| * entry left to act on. | |
| * | |
| * Concurrent calls for the same subscriptionId share one in-flight removal | |
| * instead of each sending their own session.unsubscribe — a second, racing | |
| * call would otherwise find the subscription already gone (removed by the | |
| * first) and get a wire-level error for what was a perfectly valid call. | |
| * The in-flight marker is cleared once the attempt settles, either way, so | |
| * a later retry after a failure starts a fresh attempt rather than reusing | |
| * a rejected one. | |
| * @param {string} subscriptionId | |
| * @returns {Promise<void>} | |
| */ | |
| async removeCallback(subscriptionId) { | |
| const entry = this._callbacks.get(subscriptionId) | |
| if (entry === undefined) { | |
| return | |
| } | |
| if (entry.removing === undefined) { | |
| entry.removing = (async () => { | |
| const response = await this.send({ | |
| method: 'session.unsubscribe', | |
| params: { subscriptions: [subscriptionId] }, | |
| }) | |
| if (response?.error !== undefined) { | |
| throw new Error(`${response.error}: ${response.message}`) | |
| } | |
| this._callbacks.delete(subscriptionId) | |
| this.off(entry.method, entry.handler) | |
| })().finally(() => { | |
| entry.removing = undefined | |
| }) | |
| } | |
| return entry.removing | |
| } | |
| /** | |
| * Close ws connection. | |
| * @returns {Promise<unknown>} | |
| */ | |
| close() { | |
| this._failPending(new Error('BiDi connection closed before response was received')) | |
| const closeWebSocket = (callback) => { | |
| // don't close if it's already closed | |
| if (this._ws.readyState === 3) { | |
| callback() | |
| } else { | |
| // don't notify on user-initiated shutdown ('disconnect' event) | |
| this._ws.removeAllListeners('close') | |
| this._ws.once('close', () => { | |
| this._ws.removeAllListeners() | |
| callback() | |
| }) | |
| this._ws.close() | |
| } | |
| } | |
| return new Promise((fulfill, _) => { | |
| closeWebSocket(fulfill) | |
| }) | |
| } | |
| } | |
| /** | |
| * API | |
| * @type {function(*): Promise<Index>} | |
| */ | |
| module.exports = Index |