// 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