@depup/mswjs__interceptors 0.41.3-depup.0

package/src/interceptors/WebSocket/index.ts

@@ -0,0 +1,191 @@
+import { Interceptor } from '../../Interceptor'
+import {
+  WebSocketClientConnectionProtocol,
+  WebSocketClientConnection,
+  type WebSocketClientEventMap,
+} from './WebSocketClientConnection'
+import {
+  WebSocketServerConnectionProtocol,
+  WebSocketServerConnection,
+  type WebSocketServerEventMap,
+} from './WebSocketServerConnection'
+import { WebSocketClassTransport } from './WebSocketClassTransport'
+import {
+  kClose,
+  kPassthroughPromise,
+  WebSocketOverride,
+} from './WebSocketOverride'
+import { bindEvent } from './utils/bindEvent'
+import { hasConfigurableGlobal } from '../../utils/hasConfigurableGlobal'
+import { emitAsync } from '../../utils/emitAsync'
+
+export {
+  type WebSocketData,
+  type WebSocketTransport,
+} from './WebSocketTransport'
+export {
+  WebSocketClientEventMap,
+  WebSocketClientConnectionProtocol,
+  WebSocketClientConnection,
+  WebSocketServerEventMap,
+  WebSocketServerConnectionProtocol,
+  WebSocketServerConnection,
+}
+
+export {
+  CloseEvent,
+  CancelableCloseEvent,
+  CancelableMessageEvent,
+} from './utils/events'
+
+export type WebSocketEventMap = {
+  connection: [args: WebSocketConnectionData]
+}
+
+export type WebSocketConnectionData = {
+  /**
+   * The incoming WebSocket client connection.
+   */
+  client: WebSocketClientConnection
+
+  /**
+   * The original WebSocket server connection.
+   */
+  server: WebSocketServerConnection
+
+  /**
+   * The connection information.
+   */
+  info: {
+    /**
+     * The protocols supported by the WebSocket client.
+     */
+    protocols: string | Array<string> | undefined
+  }
+}
+
+/**
+ * Intercept the outgoing WebSocket connections created using
+ * the global `WebSocket` class.
+ */
+export class WebSocketInterceptor extends Interceptor<WebSocketEventMap> {
+  static symbol = Symbol('websocket')
+
+  constructor() {
+    super(WebSocketInterceptor.symbol)
+  }
+
+  protected checkEnvironment(): boolean {
+    return hasConfigurableGlobal('WebSocket')
+  }
+
+  protected setup(): void {
+    const originalWebSocketDescriptor = Object.getOwnPropertyDescriptor(
+      globalThis,
+      'WebSocket'
+    )
+
+    const WebSocketProxy = new Proxy(globalThis.WebSocket, {
+      construct: (
+        target,
+        args: ConstructorParameters<typeof globalThis.WebSocket>,
+        newTarget
+      ) => {
+        const [url, protocols] = args
+
+        const createConnection = (): WebSocket => {
+          return Reflect.construct(target, args, newTarget)
+        }
+
+        // All WebSocket instances are mocked and don't forward
+        // any events to the original server (no connection established).
+        // To forward the events, the user must use the "server.send()" API.
+        const socket = new WebSocketOverride(url, protocols)
+        const transport = new WebSocketClassTransport(socket)
+
+        // Emit the "connection" event to the interceptor on the next tick
+        // so the client can modify WebSocket options, like "binaryType"
+        // while the connection is already pending.
+        queueMicrotask(async () => {
+          try {
+            const server = new WebSocketServerConnection(
+              socket,
+              transport,
+              createConnection
+            )
+
+            const hasConnectionListeners =
+              this.emitter.listenerCount('connection') > 0
+
+            // The "globalThis.WebSocket" class stands for
+            // the client-side connection. Assume it's established
+            // as soon as the WebSocket instance is constructed.
+            await emitAsync(this.emitter, 'connection', {
+              client: new WebSocketClientConnection(socket, transport),
+              server,
+              info: {
+                protocols,
+              },
+            })
+
+            if (hasConnectionListeners) {
+              socket[kPassthroughPromise].resolve(false)
+            } else {
+              socket[kPassthroughPromise].resolve(true)
+
+              server.connect()
+
+              // Forward the "open" event from the original server
+              // to the mock WebSocket client in the case of a passthrough connection.
+              server.addEventListener('open', () => {
+                socket.dispatchEvent(bindEvent(socket, new Event('open')))
+
+                // Forward the original connection protocol to the
+                // mock WebSocket client.
+                if (server['realWebSocket']) {
+                  socket.protocol = server['realWebSocket'].protocol
+                }
+              })
+            }
+          } catch (error) {
+            /**
+             * @note Translate unhandled exceptions during the connection
+             * handling (i.e. interceptor exceptions) as WebSocket connection
+             * closures with error. This prevents from the exceptions occurring
+             * in `queueMicrotask` from being process-wide and uncatchable.
+             */
+            if (error instanceof Error) {
+              socket.dispatchEvent(new Event('error'))
+
+              // No need to close the connection if it's already being closed.
+              // E.g. the interceptor called `client.close()` and then threw an error.
+              if (
+                socket.readyState !== WebSocket.CLOSING &&
+                socket.readyState !== WebSocket.CLOSED
+              ) {
+                socket[kClose](1011, error.message, false)
+              }
+
+              console.error(error)
+            }
+          }
+        })
+
+        return socket
+      },
+    })
+
+    Object.defineProperty(globalThis, 'WebSocket', {
+      value: WebSocketProxy,
+      configurable: true,
+    })
+
+    this.subscriptions.push(() => {
+      Object.defineProperty(
+        globalThis,
+        'WebSocket',
+        originalWebSocketDescriptor!
+      )
+    })
+  }
+}

package/src/interceptors/WebSocket/utils/bindEvent.test.ts

@@ -0,0 +1,27 @@
+/**
+ * @vitest-environment node
+ */
+import { it, expect } from 'vitest'
+import { bindEvent } from './bindEvent'
+
+it('sets the "target" on the given event', () => {
+  class Target {}
+  const target = new Target()
+  const event = new Event('open')
+  bindEvent(target, event)
+
+  expect(event.type).toBe('open')
+  expect(event.target).toEqual(target)
+})
+
+it('overrides existing "target" on the given event', () => {
+  class Target {}
+  const oldTarget = new Target()
+  const newTarget = new Target()
+  const event = new Event('open')
+  bindEvent(oldTarget, event)
+  bindEvent(newTarget, event)
+
+  expect(event.type).toBe('open')
+  expect(event.target).toEqual(newTarget)
+})

package/src/interceptors/WebSocket/utils/bindEvent.ts

@@ -0,0 +1,21 @@
+type EventWithTarget<E extends Event, T> = E & { target: T }
+
+export function bindEvent<E extends Event, T>(
+  target: T,
+  event: E
+): EventWithTarget<E, T> {
+  Object.defineProperties(event, {
+    target: {
+      value: target,
+      enumerable: true,
+      writable: true,
+    },
+    currentTarget: {
+      value: target,
+      enumerable: true,
+      writable: true,
+    },
+  })
+
+  return event as EventWithTarget<E, T>
+}

package/src/interceptors/WebSocket/utils/events.test.ts

@@ -0,0 +1,101 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, it, expect } from 'vitest'
+import { CancelableMessageEvent, CloseEvent } from './events'
+
+describe(CancelableMessageEvent, () => {
+  it('initiates with the right defaults', () => {
+    const event = new CancelableMessageEvent('message', {
+      data: 'hello',
+    })
+
+    expect(event).toBeInstanceOf(MessageEvent)
+    expect(event.type).toBe('message')
+    expect(event.data).toBe('hello')
+    expect(event.cancelable).toBe(false)
+    expect(event.defaultPrevented).toBe(false)
+  })
+
+  it('initiates a cancelable event', () => {
+    const event = new CancelableMessageEvent('message', {
+      data: 'hello',
+      cancelable: true,
+    })
+
+    expect(event).toBeInstanceOf(MessageEvent)
+    expect(event.type).toBe('message')
+    expect(event.data).toBe('hello')
+    expect(event.cancelable).toBe(true)
+    expect(event.defaultPrevented).toBe(false)
+  })
+
+  it('cancels a cancelable event when calling "preventDefault()"', () => {
+    const event = new CancelableMessageEvent('message', {
+      data: 'hello',
+      cancelable: true,
+    })
+
+    expect(event.defaultPrevented).toBe(false)
+    event.preventDefault()
+    expect(event.defaultPrevented).toBe(true)
+  })
+
+  it('does nothing when calling "preventDefault()" on a non-cancelable event', () => {
+    const event = new CancelableMessageEvent('message', {
+      data: 'hello',
+    })
+
+    expect(event.defaultPrevented).toBe(false)
+    event.preventDefault()
+    expect(event.defaultPrevented).toBe(false)
+  })
+
+  it('supports setting the "cancelable" value directly', () => {
+    const event = new CancelableMessageEvent('message', {})
+    /**
+     * @note HappyDOM sets the "cancelable" and "preventDefault"
+     * event properties directly. That's no-op as far as I know
+     * but they do it and we have to account for that.
+     */
+    event.cancelable = true
+    expect(event.cancelable).toBe(true)
+  })
+
+  it('supports setting the "defaultPrevented" value directly', () => {
+    const event = new CancelableMessageEvent('message', {})
+    /**
+     * @note HappyDOM sets the "cancelable" and "preventDefault"
+     * event properties directly. That's no-op as far as I know
+     * but they do it and we have to account for that.
+     */
+    event.defaultPrevented = true
+    expect(event.defaultPrevented).toBe(true)
+  })
+})
+
+describe(CloseEvent, () => {
+  it('initiates with the right defaults', () => {
+    const event = new CloseEvent('close')
+
+    expect(event).toBeInstanceOf(Event)
+    expect(event.type).toBe('close')
+    expect(event.code).toBe(0)
+    expect(event.reason).toBe('')
+    expect(event.wasClean).toBe(false)
+  })
+
+  it('initiates with custom values', () => {
+    const event = new CloseEvent('close', {
+      code: 1003,
+      reason: 'close reason',
+      wasClean: true,
+    })
+
+    expect(event).toBeInstanceOf(Event)
+    expect(event.type).toBe('close')
+    expect(event.code).toBe(1003)
+    expect(event.reason).toBe('close reason')
+    expect(event.wasClean).toBe(true)
+  })
+})

package/src/interceptors/WebSocket/utils/events.ts

@@ -0,0 +1,94 @@
+const kCancelable = Symbol('kCancelable')
+const kDefaultPrevented = Symbol('kDefaultPrevented')
+
+/**
+ * A `MessageEvent` superset that supports event cancellation
+ * in Node.js. It's rather non-intrusive so it can be safely
+ * used in the browser as well.
+ *
+ * @see https://github.com/nodejs/node/issues/51767
+ */
+export class CancelableMessageEvent<T = any> extends MessageEvent<T> {
+  [kCancelable]: boolean;
+  [kDefaultPrevented]: boolean
+
+  constructor(type: string, init: MessageEventInit<T>) {
+    super(type, init)
+    this[kCancelable] = !!init.cancelable
+    this[kDefaultPrevented] = false
+  }
+
+  get cancelable() {
+    return this[kCancelable]
+  }
+
+  set cancelable(nextCancelable) {
+    this[kCancelable] = nextCancelable
+  }
+
+  get defaultPrevented() {
+    return this[kDefaultPrevented]
+  }
+
+  set defaultPrevented(nextDefaultPrevented) {
+    this[kDefaultPrevented] = nextDefaultPrevented
+  }
+
+  public preventDefault(): void {
+    if (this.cancelable && !this[kDefaultPrevented]) {
+      this[kDefaultPrevented] = true
+    }
+  }
+}
+
+interface CloseEventInit extends EventInit {
+  code?: number
+  reason?: string
+  wasClean?: boolean
+}
+
+export class CloseEvent extends Event {
+  public code: number
+  public reason: string
+  public wasClean: boolean
+
+  constructor(type: string, init: CloseEventInit = {}) {
+    super(type, init)
+    this.code = init.code === undefined ? 0 : init.code
+    this.reason = init.reason === undefined ? '' : init.reason
+    this.wasClean = init.wasClean === undefined ? false : init.wasClean
+  }
+}
+
+export class CancelableCloseEvent extends CloseEvent {
+  [kCancelable]: boolean;
+  [kDefaultPrevented]: boolean
+
+  constructor(type: string, init: CloseEventInit = {}) {
+    super(type, init)
+    this[kCancelable] = !!init.cancelable
+    this[kDefaultPrevented] = false
+  }
+
+  get cancelable() {
+    return this[kCancelable]
+  }
+
+  set cancelable(nextCancelable) {
+    this[kCancelable] = nextCancelable
+  }
+
+  get defaultPrevented() {
+    return this[kDefaultPrevented]
+  }
+
+  set defaultPrevented(nextDefaultPrevented) {
+    this[kDefaultPrevented] = nextDefaultPrevented
+  }
+
+  public preventDefault(): void {
+    if (this.cancelable && !this[kDefaultPrevented]) {
+      this[kDefaultPrevented] = true
+    }
+  }
+}