@depup/mswjs__interceptors 0.41.3-depup.0

package/src/interceptors/Socket/MockSocket.test.ts

@@ -0,0 +1,264 @@
+/**
+ * @vitest-environment node
+ */
+import { Socket } from 'node:net'
+import { vi, it, expect } from 'vitest'
+import { MockSocket } from './MockSocket'
+
+it(`keeps the socket connecting until it's destroyed`, () => {
+  const socket = new MockSocket({
+    write: vi.fn(),
+    read: vi.fn(),
+  })
+
+  expect(socket.connecting).toBe(true)
+
+  socket.destroy()
+  expect(socket.connecting).toBe(false)
+})
+
+it('calls the "write" on "socket.write()"', () => {
+  const writeCallback = vi.fn()
+  const socket = new MockSocket({
+    write: writeCallback,
+    read: vi.fn(),
+  })
+
+  socket.write()
+  expect(writeCallback).toHaveBeenCalledWith(undefined, undefined, undefined)
+})
+
+it('calls the "write" on "socket.write(chunk)"', () => {
+  const writeCallback = vi.fn()
+  const socket = new MockSocket({
+    write: writeCallback,
+    read: vi.fn(),
+  })
+
+  socket.write('hello')
+  expect(writeCallback).toHaveBeenCalledWith('hello', undefined, undefined)
+})
+
+it('calls the "write" on "socket.write(chunk, encoding)"', () => {
+  const writeCallback = vi.fn()
+  const socket = new MockSocket({
+    write: writeCallback,
+    read: vi.fn(),
+  })
+
+  socket.write('hello', 'utf8')
+  expect(writeCallback).toHaveBeenCalledWith('hello', 'utf8', undefined)
+})
+
+it('calls the "write" on "socket.write(chunk, encoding, callback)"', () => {
+  const writeCallback = vi.fn()
+  const socket = new MockSocket({
+    write: writeCallback,
+    read: vi.fn(),
+  })
+
+  const callback = vi.fn()
+  socket.write('hello', 'utf8', callback)
+  expect(writeCallback).toHaveBeenCalledWith('hello', 'utf8', callback)
+})
+
+it('calls the "write" on "socket.end()"', () => {
+  const writeCallback = vi.fn()
+  const socket = new MockSocket({
+    write: writeCallback,
+    read: vi.fn(),
+  })
+
+  socket.end()
+  expect(writeCallback).toHaveBeenCalledWith(undefined, undefined, undefined)
+})
+
+it('calls the "write" on "socket.end(chunk)"', () => {
+  const writeCallback = vi.fn()
+  const socket = new MockSocket({
+    write: writeCallback,
+    read: vi.fn(),
+  })
+
+  socket.end('final')
+  expect(writeCallback).toHaveBeenCalledWith('final', undefined, undefined)
+})
+
+it('calls the "write" on "socket.end(chunk, encoding)"', () => {
+  const writeCallback = vi.fn()
+  const socket = new MockSocket({
+    write: writeCallback,
+    read: vi.fn(),
+  })
+
+  socket.end('final', 'utf8')
+  expect(writeCallback).toHaveBeenCalledWith('final', 'utf8', undefined)
+})
+
+it('calls the "write" on "socket.end(chunk, encoding, callback)"', () => {
+  const writeCallback = vi.fn()
+  const socket = new MockSocket({
+    write: writeCallback,
+    read: vi.fn(),
+  })
+
+  const callback = vi.fn()
+  socket.end('final', 'utf8', callback)
+  expect(writeCallback).toHaveBeenCalledWith('final', 'utf8', callback)
+})
+
+it('calls the "write" on "socket.end()" without any arguments', () => {
+  const writeCallback = vi.fn()
+  const socket = new MockSocket({
+    write: writeCallback,
+    read: vi.fn(),
+  })
+
+  socket.end()
+  expect(writeCallback).toHaveBeenCalledWith(undefined, undefined, undefined)
+})
+
+it('emits "finished" on .end() without any arguments', async () => {
+  const finishListener = vi.fn()
+  const socket = new MockSocket({
+    write: vi.fn(),
+    read: vi.fn(),
+  })
+  socket.on('finish', finishListener)
+  socket.end()
+
+  await vi.waitFor(() => {
+    expect(finishListener).toHaveBeenCalledTimes(1)
+  })
+})
+
+it('calls the "read" on "socket.read(chunk)"', () => {
+  const readCallback = vi.fn()
+  const socket = new MockSocket({
+    write: vi.fn(),
+    read: readCallback,
+  })
+
+  socket.push('hello')
+  expect(readCallback).toHaveBeenCalledWith('hello', undefined)
+})
+
+it('calls the "read" on "socket.read(chunk, encoding)"', () => {
+  const readCallback = vi.fn()
+  const socket = new MockSocket({
+    write: vi.fn(),
+    read: readCallback,
+  })
+
+  socket.push('world', 'utf8')
+  expect(readCallback).toHaveBeenCalledWith('world', 'utf8')
+})
+
+it('calls the "read" on "socket.read(null)"', () => {
+  const readCallback = vi.fn()
+  const socket = new MockSocket({
+    write: vi.fn(),
+    read: readCallback,
+  })
+
+  socket.push(null)
+  expect(readCallback).toHaveBeenCalledWith(null, undefined)
+})
+
+it('updates the writable state on "socket.end()"', async () => {
+  const finishListener = vi.fn()
+  const endListener = vi.fn()
+  const socket = new MockSocket({
+    write: vi.fn(),
+    read: vi.fn(),
+  })
+  socket.on('finish', finishListener)
+  socket.on('end', endListener)
+
+  expect(socket.writable).toBe(true)
+  expect(socket.writableEnded).toBe(false)
+  expect(socket.writableFinished).toBe(false)
+
+  socket.write('hello')
+  // Finish the writable stream.
+  socket.end()
+
+  expect(socket.writable).toBe(false)
+  expect(socket.writableEnded).toBe(true)
+
+  // The "finish" event is emitted when writable is done.
+  // I.e. "socket.end()" is called.
+  await vi.waitFor(() => {
+    expect(finishListener).toHaveBeenCalledTimes(1)
+  })
+  expect(socket.writableFinished).toBe(true)
+})
+
+it('updates the readable state on "socket.push(null)"', async () => {
+  const endListener = vi.fn()
+  const socket = new MockSocket({
+    write: vi.fn(),
+    read: vi.fn(),
+  })
+  socket.on('end', endListener)
+
+  expect(socket.readable).toBe(true)
+  expect(socket.readableEnded).toBe(false)
+
+  socket.push('hello')
+  socket.push(null)
+
+  expect(socket.readable).toBe(true)
+  expect(socket.readableEnded).toBe(false)
+
+  // Read the data to free the buffer and
+  // make Socket emit "end".
+  socket.read()
+
+  await vi.waitFor(() => {
+    expect(endListener).toHaveBeenCalledTimes(1)
+  })
+  expect(socket.readable).toBe(false)
+  expect(socket.readableEnded).toBe(true)
+})
+
+it('updates the readable/writable state on "socket.destroy()"', async () => {
+  const finishListener = vi.fn()
+  const endListener = vi.fn()
+  const closeListener = vi.fn()
+  const socket = new MockSocket({
+    write: vi.fn(),
+    read: vi.fn(),
+  })
+  socket.on('finish', finishListener)
+  socket.on('end', endListener)
+  socket.on('close', closeListener)
+
+  expect(socket.writable).toBe(true)
+  expect(socket.writableEnded).toBe(false)
+  expect(socket.writableFinished).toBe(false)
+  expect(socket.readable).toBe(true)
+
+  socket.destroy()
+
+  expect(socket.writable).toBe(false)
+  // The ".end()" wasn't called.
+  expect(socket.writableEnded).toBe(false)
+  expect(socket.writableFinished).toBe(false)
+  expect(socket.readable).toBe(false)
+
+  await vi.waitFor(() => {
+    expect(closeListener).toHaveBeenCalledTimes(1)
+  })
+
+  // Neither "finish" nor "end" events are emitted
+  // when you destroy the stream. If you want those,
+  // call ".end()", then destroy the stream.
+  expect(finishListener).not.toHaveBeenCalled()
+  expect(endListener).not.toHaveBeenCalled()
+  expect(socket.writableFinished).toBe(false)
+
+  // The "end" event was never emitted so "readableEnded"
+  // remains false.
+  expect(socket.readableEnded).toBe(false)
+})

package/src/interceptors/Socket/MockSocket.ts

@@ -0,0 +1,58 @@
+import net from 'node:net'
+import {
+  normalizeSocketWriteArgs,
+  type WriteArgs,
+  type WriteCallback,
+} from './utils/normalizeSocketWriteArgs'
+
+export interface MockSocketOptions {
+  write: (
+    chunk: Buffer | string,
+    encoding: BufferEncoding | undefined,
+    callback?: WriteCallback
+  ) => void
+
+  read: (chunk: Buffer, encoding: BufferEncoding | undefined) => void
+}
+
+export class MockSocket extends net.Socket {
+  public connecting: boolean
+
+  constructor(protected readonly options: MockSocketOptions) {
+    super()
+    this.connecting = false
+    this.connect()
+
+    this._final = (callback) => {
+      callback(null)
+    }
+  }
+
+  public connect() {
+    // The connection will remain pending until
+    // the consumer decides to handle it.
+    this.connecting = true
+    return this
+  }
+
+  public write(...args: Array<unknown>): boolean {
+    const [chunk, encoding, callback] = normalizeSocketWriteArgs(
+      args as WriteArgs
+    )
+    this.options.write(chunk, encoding, callback)
+    return true
+  }
+
+  public end(...args: Array<unknown>) {
+    const [chunk, encoding, callback] = normalizeSocketWriteArgs(
+      args as WriteArgs
+    )
+    this.options.write(chunk, encoding, callback)
+    return super.end.apply(this, args as any)
+  }
+
+  public push(chunk: any, encoding?: BufferEncoding): boolean {
+    this.options.read(chunk, encoding)
+    return super.push(chunk, encoding)
+  }
+}

package/src/interceptors/Socket/utils/baseUrlFromConnectionOptions.ts

@@ -0,0 +1,26 @@
+export function baseUrlFromConnectionOptions(options: any): URL {
+  if ('href' in options) {
+    return new URL(options.href)
+  }
+
+  const protocol = options.port === 443 ? 'https:' : 'http:'
+  const host = options.host
+
+  const url = new URL(`${protocol}//${host}`)
+
+  if (options.port) {
+    url.port = options.port.toString()
+  }
+
+  if (options.path) {
+    url.pathname = options.path
+  }
+
+  if (options.auth) {
+    const [username, password] = options.auth.split(':')
+    url.username = username
+    url.password = password
+  }
+
+  return url
+}

package/src/interceptors/Socket/utils/normalizeSocketWriteArgs.test.ts

@@ -0,0 +1,52 @@
+/**
+ * @vitest-environment node
+ */
+import { it, expect } from 'vitest'
+import { normalizeSocketWriteArgs } from './normalizeSocketWriteArgs'
+
+it('normalizes .write()', () => {
+  expect(normalizeSocketWriteArgs([undefined])).toEqual([
+    undefined,
+    undefined,
+    undefined,
+  ])
+  expect(normalizeSocketWriteArgs([null])).toEqual([null, undefined, undefined])
+})
+
+it('normalizes .write(chunk)', () => {
+  expect(normalizeSocketWriteArgs([Buffer.from('hello')])).toEqual([
+    Buffer.from('hello'),
+    undefined,
+    undefined,
+  ])
+  expect(normalizeSocketWriteArgs(['hello'])).toEqual([
+    'hello',
+    undefined,
+    undefined,
+  ])
+  expect(normalizeSocketWriteArgs([null])).toEqual([null, undefined, undefined])
+})
+
+it('normalizes .write(chunk, encoding)', () => {
+  expect(normalizeSocketWriteArgs([Buffer.from('hello'), 'utf8'])).toEqual([
+    Buffer.from('hello'),
+    'utf8',
+    undefined,
+  ])
+})
+
+it('normalizes .write(chunk, callback)', () => {
+  const callback = () => {}
+  expect(normalizeSocketWriteArgs([Buffer.from('hello'), callback])).toEqual([
+    Buffer.from('hello'),
+    undefined,
+    callback,
+  ])
+})
+
+it('normalizes .write(chunk, encoding, callback)', () => {
+  const callback = () => {}
+  expect(
+    normalizeSocketWriteArgs([Buffer.from('hello'), 'utf8', callback])
+  ).toEqual([Buffer.from('hello'), 'utf8', callback])
+})

package/src/interceptors/Socket/utils/normalizeSocketWriteArgs.ts

@@ -0,0 +1,33 @@
+export type WriteCallback = (error?: Error | null) => void
+
+export type WriteArgs =
+  | [chunk: unknown, callback?: WriteCallback]
+  | [chunk: unknown, encoding: BufferEncoding, callback?: WriteCallback]
+
+export type NormalizedSocketWriteArgs = [
+  chunk: any,
+  encoding?: BufferEncoding,
+  callback?: WriteCallback,
+]
+
+/**
+ * Normalizes the arguments provided to the `Writable.prototype.write()`
+ * and `Writable.prototype.end()`.
+ */
+export function normalizeSocketWriteArgs(
+  args: WriteArgs
+): NormalizedSocketWriteArgs {
+  const normalized: NormalizedSocketWriteArgs = [args[0], undefined, undefined]
+
+  if (typeof args[1] === 'string') {
+    normalized[1] = args[1]
+  } else if (typeof args[1] === 'function') {
+    normalized[2] = args[1]
+  }
+
+  if (typeof args[2] === 'function') {
+    normalized[2] = args[2]
+  }
+
+  return normalized
+}

package/src/interceptors/WebSocket/WebSocketClassTransport.ts

@@ -0,0 +1,116 @@
+import { bindEvent } from './utils/bindEvent'
+import {
+  StrictEventListenerOrEventListenerObject,
+  WebSocketData,
+  WebSocketTransport,
+  WebSocketTransportEventMap,
+} from './WebSocketTransport'
+import { kOnSend, kClose, WebSocketOverride } from './WebSocketOverride'
+import { CancelableMessageEvent, CloseEvent } from './utils/events'
+
+/**
+ * Abstraction over the given mock `WebSocket` instance that allows
+ * for controlling that instance (e.g. sending and receiving messages).
+ */
+export class WebSocketClassTransport
+  extends EventTarget
+  implements WebSocketTransport
+{
+  constructor(protected readonly socket: WebSocketOverride) {
+    super()
+
+    // Emit the "close" event on the transport if the close
+    // originates from the WebSocket client. E.g. the application
+    // calls "ws.close()", not the interceptor.
+    this.socket.addEventListener('close', (event) => {
+      this.dispatchEvent(bindEvent(this.socket, new CloseEvent('close', event)))
+    })
+
+    /**
+     * Emit the "outgoing" event on the transport
+     * whenever the WebSocket client sends data ("ws.send()").
+     */
+    this.socket[kOnSend] = (data) => {
+      this.dispatchEvent(
+        bindEvent(
+          this.socket,
+          // Dispatch this as cancelable because "client" connection
+          // re-creates this message event (cannot dispatch the same event).
+          new CancelableMessageEvent('outgoing', {
+            data,
+            origin: this.socket.url,
+            cancelable: true,
+          })
+        )
+      )
+    }
+  }
+
+  public addEventListener<EventType extends keyof WebSocketTransportEventMap>(
+    type: EventType,
+    callback: StrictEventListenerOrEventListenerObject<
+      WebSocketTransportEventMap[EventType]
+    > | null,
+    options?: boolean | AddEventListenerOptions
+  ): void {
+    return super.addEventListener(type, callback as EventListener, options)
+  }
+
+  public dispatchEvent<EventType extends keyof WebSocketTransportEventMap>(
+    event: WebSocketTransportEventMap[EventType]
+  ): boolean {
+    return super.dispatchEvent(event)
+  }
+
+  public send(data: WebSocketData): void {
+    queueMicrotask(() => {
+      if (
+        this.socket.readyState === this.socket.CLOSING ||
+        this.socket.readyState === this.socket.CLOSED
+      ) {
+        return
+      }
+
+      const dispatchEvent = () => {
+        this.socket.dispatchEvent(
+          bindEvent(
+            /**
+             * @note Setting this event's "target" to the
+             * WebSocket override instance is important.
+             * This way it can tell apart original incoming events
+             * (must be forwarded to the transport) from the
+             * mocked message events like the one below
+             * (must be dispatched on the client instance).
+             */
+            this.socket,
+            new MessageEvent('message', {
+              data,
+              origin: this.socket.url,
+            })
+          )
+        )
+      }
+
+      if (this.socket.readyState === this.socket.CONNECTING) {
+        this.socket.addEventListener(
+          'open',
+          () => {
+            dispatchEvent()
+          },
+          { once: true }
+        )
+      } else {
+        dispatchEvent()
+      }
+    })
+  }
+
+  public close(code: number, reason?: string): void {
+    /**
+     * @note Call the internal close method directly
+     * to allow closing the connection with the status codes
+     * that are non-configurable by the user (> 1000 <= 1015).
+     */
+    this.socket[kClose](code, reason)
+  }
+}

package/src/interceptors/WebSocket/WebSocketClientConnection.ts

@@ -0,0 +1,152 @@
+import type { WebSocketData, WebSocketTransport } from './WebSocketTransport'
+import type { WebSocketEventListener } from './WebSocketOverride'
+import { bindEvent } from './utils/bindEvent'
+import { CancelableMessageEvent, CloseEvent } from './utils/events'
+import { createRequestId } from '../../createRequestId'
+
+const kEmitter = Symbol('kEmitter')
+const kBoundListener = Symbol('kBoundListener')
+
+export interface WebSocketClientEventMap {
+  message: MessageEvent<WebSocketData>
+  close: CloseEvent
+}
+
+export abstract class WebSocketClientConnectionProtocol {
+  abstract id: string
+  abstract url: URL
+  public abstract send(data: WebSocketData): void
+  public abstract close(code?: number, reason?: string): void
+
+  public abstract addEventListener<
+    EventType extends keyof WebSocketClientEventMap,
+  >(
+    type: EventType,
+    listener: WebSocketEventListener<WebSocketClientEventMap[EventType]>,
+    options?: AddEventListenerOptions | boolean
+  ): void
+
+  public abstract removeEventListener<
+    EventType extends keyof WebSocketClientEventMap,
+  >(
+    event: EventType,
+    listener: WebSocketEventListener<WebSocketClientEventMap[EventType]>,
+    options?: EventListenerOptions | boolean
+  ): void
+}
+
+/**
+ * The WebSocket client instance represents an incoming
+ * client connection. The user can control the connection,
+ * send and receive events.
+ */
+export class WebSocketClientConnection implements WebSocketClientConnectionProtocol {
+  public readonly id: string
+  public readonly url: URL
+
+  private [kEmitter]: EventTarget
+
+  constructor(
+    public readonly socket: WebSocket,
+    private readonly transport: WebSocketTransport
+  ) {
+    this.id = createRequestId()
+    this.url = new URL(socket.url)
+    this[kEmitter] = new EventTarget()
+
+    // Emit outgoing client data ("ws.send()") as "message"
+    // events on the "client" connection.
+    this.transport.addEventListener('outgoing', (event) => {
+      const message = bindEvent(
+        this.socket,
+        new CancelableMessageEvent('message', {
+          data: event.data,
+          origin: event.origin,
+          cancelable: true,
+        })
+      )
+
+      this[kEmitter].dispatchEvent(message)
+
+      // This is a bit silly but forward the cancellation state
+      // of the "client" message event to the "outgoing" transport event.
+      // This way, other agens (like "server" connection) can know
+      // whether the client listener has pervented the default.
+      if (message.defaultPrevented) {
+        event.preventDefault()
+      }
+    })
+
+    /**
+     * Emit the "close" event on the "client" connection
+     * whenever the underlying transport is closed.
+     * @note "client.close()" does NOT dispatch the "close"
+     * event on the WebSocket because it uses non-configurable
+     * close status code. Thus, we listen to the transport
+     * instead of the WebSocket's "close" event.
+     */
+    this.transport.addEventListener('close', (event) => {
+      this[kEmitter].dispatchEvent(
+        bindEvent(this.socket, new CloseEvent('close', event))
+      )
+    })
+  }
+
+  /**
+   * Listen for the outgoing events from the connected WebSocket client.
+   */
+  public addEventListener<EventType extends keyof WebSocketClientEventMap>(
+    type: EventType,
+    listener: WebSocketEventListener<WebSocketClientEventMap[EventType]>,
+    options?: AddEventListenerOptions | boolean
+  ): void {
+    if (!Reflect.has(listener, kBoundListener)) {
+      const boundListener = listener.bind(this.socket)
+
+      // Store the bound listener on the original listener
+      // so the exact bound function can be accessed in "removeEventListener()".
+      Object.defineProperty(listener, kBoundListener, {
+        value: boundListener,
+        enumerable: false,
+        configurable: false,
+      })
+    }
+
+    this[kEmitter].addEventListener(
+      type,
+      Reflect.get(listener, kBoundListener) as EventListener,
+      options
+    )
+  }
+
+  /**
+   * Removes the listener for the given event.
+   */
+  public removeEventListener<EventType extends keyof WebSocketClientEventMap>(
+    event: EventType,
+    listener: WebSocketEventListener<WebSocketClientEventMap[EventType]>,
+    options?: EventListenerOptions | boolean
+  ): void {
+    this[kEmitter].removeEventListener(
+      event,
+      Reflect.get(listener, kBoundListener) as EventListener,
+      options
+    )
+  }
+
+  /**
+   * Send data to the connected client.
+   */
+  public send(data: WebSocketData): void {
+    this.transport.send(data)
+  }
+
+  /**
+   * Close the WebSocket connection.
+   * @param {number} code A status code (see https://www.rfc-editor.org/rfc/rfc6455#section-7.4.1).
+   * @param {string} reason A custom connection close reason.
+   */
+  public close(code?: number, reason?: string): void {
+    this.transport.close(code, reason)
+  }
+}