@depup/mswjs__interceptors 0.41.3-depup.0

package/src/Interceptor.test.ts

@@ -0,0 +1,205 @@
+import { describe, vi, it, expect, afterEach } from 'vitest'
+import {
+  Interceptor,
+  getGlobalSymbol,
+  deleteGlobalSymbol,
+  InterceptorReadyState,
+} from './Interceptor'
+import { nextTickAsync } from './utils/nextTick'
+
+const symbol = Symbol('test')
+
+afterEach(() => {
+  deleteGlobalSymbol(symbol)
+})
+
+it('does not set a maximum listeners limit', () => {
+  const interceptor = new Interceptor(symbol)
+  expect(interceptor['emitter'].getMaxListeners()).toBe(0)
+})
+
+describe('on()', () => {
+  it('adds a new listener using "on()"', () => {
+    const interceptor = new Interceptor(symbol)
+    expect(interceptor['emitter'].listenerCount('event')).toBe(0)
+
+    const listener = vi.fn()
+    interceptor.on('event', listener)
+    expect(interceptor['emitter'].listenerCount('event')).toBe(1)
+  })
+})
+
+describe('once()', () => {
+  it('calls the listener only once', () => {
+    const interceptor = new Interceptor(symbol)
+    const listener = vi.fn()
+
+    interceptor.once('foo', listener)
+    expect(listener).not.toHaveBeenCalled()
+
+    interceptor['emitter'].emit('foo', 'bar')
+
+    expect(listener).toHaveBeenCalledTimes(1)
+    expect(listener).toHaveBeenCalledWith('bar')
+
+    listener.mockReset()
+
+    interceptor['emitter'].emit('foo', 'baz')
+    interceptor['emitter'].emit('foo', 'xyz')
+    expect(listener).toHaveBeenCalledTimes(0)
+  })
+})
+
+describe('off()', () => {
+  it('removes a listener using "off()"', () => {
+    const interceptor = new Interceptor(symbol)
+    expect(interceptor['emitter'].listenerCount('event')).toBe(0)
+
+    const listener = vi.fn()
+    interceptor.on('event', listener)
+    expect(interceptor['emitter'].listenerCount('event')).toBe(1)
+
+    interceptor.off('event', listener)
+    expect(interceptor['emitter'].listenerCount('event')).toBe(0)
+  })
+})
+
+describe('persistence', () => {
+  it('stores global reference to the applied interceptor', () => {
+    const interceptor = new Interceptor(symbol)
+    interceptor.apply()
+
+    expect(getGlobalSymbol(symbol)).toEqual(interceptor)
+  })
+
+  it('deletes global reference when the interceptor is disposed', () => {
+    const interceptor = new Interceptor(symbol)
+
+    interceptor.apply()
+    interceptor.dispose()
+
+    expect(getGlobalSymbol(symbol)).toBeUndefined()
+  })
+})
+
+describe('readyState', () => {
+  it('sets the state to "INACTIVE" when the interceptor is created', () => {
+    const interceptor = new Interceptor(symbol)
+    expect(interceptor.readyState).toBe(InterceptorReadyState.INACTIVE)
+  })
+
+  it('leaves state as "INACTIVE" if the interceptor failed the environment check', async () => {
+    class MyInterceptor extends Interceptor<any> {
+      protected checkEnvironment(): boolean {
+        return false
+      }
+    }
+    const interceptor = new MyInterceptor(symbol)
+    interceptor.apply()
+
+    expect(interceptor.readyState).toBe(InterceptorReadyState.INACTIVE)
+  })
+
+  it('performs state transition when the interceptor is applying', async () => {
+    const interceptor = new Interceptor(symbol)
+    interceptor.apply()
+
+    // The interceptor's state transitions to APPLIED immediately.
+    // The only exception is if something throws during the setup.
+    expect(interceptor.readyState).toBe(InterceptorReadyState.APPLIED)
+  })
+
+  it('performs state transition when disposing of the interceptor', async () => {
+    const interceptor = new Interceptor(symbol)
+    interceptor.apply()
+    interceptor.dispose()
+
+    // The interceptor's state transitions to DISPOSED immediately.
+    // The only exception is if something throws during the teardown.
+    expect(interceptor.readyState).toBe(InterceptorReadyState.DISPOSED)
+  })
+})
+
+describe('apply', () => {
+  it('does not apply the same interceptor multiple times', () => {
+    const interceptor = new Interceptor(symbol)
+    const setupSpy = vi.spyOn(
+      interceptor,
+      // @ts-expect-error Protected property spy.
+      'setup'
+    )
+
+    // Intentionally apply the same interceptor multiple times.
+    interceptor.apply()
+    interceptor.apply()
+    interceptor.apply()
+
+    // The "setup" must not be called repeatedly.
+    expect(setupSpy).toHaveBeenCalledTimes(1)
+
+    expect(getGlobalSymbol(symbol)).toEqual(interceptor)
+  })
+
+  it('does not call "apply" if the interceptor fails environment check', () => {
+    class MyInterceptor extends Interceptor<{}> {
+      checkEnvironment() {
+        return false
+      }
+    }
+
+    const interceptor = new MyInterceptor(Symbol('test'))
+    const setupSpy = vi.spyOn(
+      interceptor,
+      // @ts-expect-error Protected property spy.
+      'setup'
+    )
+    interceptor.apply()
+
+    expect(setupSpy).not.toHaveBeenCalled()
+  })
+
+  it('proxies listeners from new interceptor to already running interceptor', () => {
+    const firstInterceptor = new Interceptor(symbol)
+    const secondInterceptor = new Interceptor(symbol)
+
+    firstInterceptor.apply()
+    const firstListener = vi.fn()
+    firstInterceptor.on('test', firstListener)
+
+    secondInterceptor.apply()
+    const secondListener = vi.fn()
+    secondInterceptor.on('test', secondListener)
+
+    // Emitting event in the first interceptor will bubble to the second one.
+    firstInterceptor['emitter'].emit('test', 'hello world')
+
+    expect(firstListener).toHaveBeenCalledTimes(1)
+    expect(firstListener).toHaveBeenCalledWith('hello world')
+
+    expect(secondListener).toHaveBeenCalledTimes(1)
+    expect(secondListener).toHaveBeenCalledWith('hello world')
+
+    expect(secondInterceptor['emitter'].listenerCount('test')).toBe(0)
+  })
+})
+
+describe('dispose', () => {
+  it('removes all listeners when the interceptor is disposed', async () => {
+    const interceptor = new Interceptor(symbol)
+
+    interceptor.apply()
+    const listener = vi.fn()
+    interceptor.on('test', listener)
+    interceptor.dispose()
+
+    // Even after emitting an event, the listener must not get called.
+    interceptor['emitter'].emit('test')
+    expect(listener).not.toHaveBeenCalled()
+
+    // The listener must not be called on the next tick either.
+    await nextTickAsync(() => {
+      interceptor['emitter'].emit('test')
+      expect(listener).not.toHaveBeenCalled()
+    })
+  })
+})

package/src/Interceptor.ts

@@ -0,0 +1,249 @@
+import { Logger } from '@open-draft/logger'
+import { Emitter, Listener } from 'strict-event-emitter'
+
+export type InterceptorEventMap = Record<string, any>
+export type InterceptorSubscription = () => void
+
+/**
+ * Request header name to detect when a single request
+ * is being handled by nested interceptors (XHR -> ClientRequest).
+ * Obscure by design to prevent collisions with user-defined headers.
+ * Ideally, come up with the Interceptor-level mechanism for this.
+ * @see https://github.com/mswjs/interceptors/issues/378
+ */
+export const INTERNAL_REQUEST_ID_HEADER_NAME =
+  'x-interceptors-internal-request-id'
+
+export function getGlobalSymbol<V>(symbol: Symbol): V | undefined {
+  return (
+    // @ts-ignore https://github.com/Microsoft/TypeScript/issues/24587
+    globalThis[symbol] || undefined
+  )
+}
+
+function setGlobalSymbol(symbol: Symbol, value: any): void {
+  // @ts-ignore
+  globalThis[symbol] = value
+}
+
+export function deleteGlobalSymbol(symbol: Symbol): void {
+  // @ts-ignore
+  delete globalThis[symbol]
+}
+
+export enum InterceptorReadyState {
+  INACTIVE = 'INACTIVE',
+  APPLYING = 'APPLYING',
+  APPLIED = 'APPLIED',
+  DISPOSING = 'DISPOSING',
+  DISPOSED = 'DISPOSED',
+}
+
+export type ExtractEventNames<Events extends Record<string, any>> =
+  Events extends Record<infer EventName, any> ? EventName : never
+
+export class Interceptor<Events extends InterceptorEventMap> {
+  protected emitter: Emitter<Events>
+  protected subscriptions: Array<InterceptorSubscription>
+  protected logger: Logger
+
+  public readyState: InterceptorReadyState
+
+  constructor(private readonly symbol: symbol) {
+    this.readyState = InterceptorReadyState.INACTIVE
+
+    this.emitter = new Emitter()
+    this.subscriptions = []
+    this.logger = new Logger(symbol.description!)
+
+    // Do not limit the maximum number of listeners
+    // so not to limit the maximum amount of parallel events emitted.
+    this.emitter.setMaxListeners(0)
+
+    this.logger.info('constructing the interceptor...')
+  }
+
+  /**
+   * Determine if this interceptor can be applied
+   * in the current environment.
+   */
+  protected checkEnvironment(): boolean {
+    return true
+  }
+
+  /**
+   * Apply this interceptor to the current process.
+   * Returns an already running interceptor instance if it's present.
+   */
+  public apply(): void {
+    const logger = this.logger.extend('apply')
+    logger.info('applying the interceptor...')
+
+    if (this.readyState === InterceptorReadyState.APPLIED) {
+      logger.info('intercepted already applied!')
+      return
+    }
+
+    const shouldApply = this.checkEnvironment()
+
+    if (!shouldApply) {
+      logger.info('the interceptor cannot be applied in this environment!')
+      return
+    }
+
+    this.readyState = InterceptorReadyState.APPLYING
+
+    // Whenever applying a new interceptor, check if it hasn't been applied already.
+    // This enables to apply the same interceptor multiple times, for example from a different
+    // interceptor, only proxying events but keeping the stubs in a single place.
+    const runningInstance = this.getInstance()
+
+    if (runningInstance) {
+      logger.info('found a running instance, reusing...')
+
+      // Proxy any listeners you set on this instance to the running instance.
+      this.on = (event, listener) => {
+        logger.info('proxying the "%s" listener', event)
+
+        // Add listeners to the running instance so they appear
+        // at the top of the event listeners list and are executed first.
+        runningInstance.emitter.addListener(event, listener)
+
+        // Ensure that once this interceptor instance is disposed,
+        // it removes all listeners it has appended to the running interceptor instance.
+        this.subscriptions.push(() => {
+          runningInstance.emitter.removeListener(event, listener)
+          logger.info('removed proxied "%s" listener!', event)
+        })
+
+        return this
+      }
+
+      this.readyState = InterceptorReadyState.APPLIED
+
+      return
+    }
+
+    logger.info('no running instance found, setting up a new instance...')
+
+    // Setup the interceptor.
+    this.setup()
+
+    // Store the newly applied interceptor instance globally.
+    this.setInstance()
+
+    this.readyState = InterceptorReadyState.APPLIED
+  }
+
+  /**
+   * Setup the module augments and stubs necessary for this interceptor.
+   * This method is not run if there's a running interceptor instance
+   * to prevent instantiating an interceptor multiple times.
+   */
+  protected setup(): void {}
+
+  /**
+   * Listen to the interceptor's public events.
+   */
+  public on<EventName extends ExtractEventNames<Events>>(
+    event: EventName,
+    listener: Listener<Events[EventName]>
+  ): this {
+    const logger = this.logger.extend('on')
+
+    if (
+      this.readyState === InterceptorReadyState.DISPOSING ||
+      this.readyState === InterceptorReadyState.DISPOSED
+    ) {
+      logger.info('cannot listen to events, already disposed!')
+      return this
+    }
+
+    logger.info('adding "%s" event listener:', event, listener)
+
+    this.emitter.on(event, listener)
+    return this
+  }
+
+  public once<EventName extends ExtractEventNames<Events>>(
+    event: EventName,
+    listener: Listener<Events[EventName]>
+  ): this {
+    this.emitter.once(event, listener)
+    return this
+  }
+
+  public off<EventName extends ExtractEventNames<Events>>(
+    event: EventName,
+    listener: Listener<Events[EventName]>
+  ): this {
+    this.emitter.off(event, listener)
+    return this
+  }
+
+  public removeAllListeners<EventName extends ExtractEventNames<Events>>(
+    event?: EventName
+  ): this {
+    this.emitter.removeAllListeners(event)
+    return this
+  }
+
+  /**
+   * Disposes of any side-effects this interceptor has introduced.
+   */
+  public dispose(): void {
+    const logger = this.logger.extend('dispose')
+
+    if (this.readyState === InterceptorReadyState.DISPOSED) {
+      logger.info('cannot dispose, already disposed!')
+      return
+    }
+
+    logger.info('disposing the interceptor...')
+    this.readyState = InterceptorReadyState.DISPOSING
+
+    if (!this.getInstance()) {
+      logger.info('no interceptors running, skipping dispose...')
+      return
+    }
+
+    // Delete the global symbol as soon as possible,
+    // indicating that the interceptor is no longer running.
+    this.clearInstance()
+
+    logger.info('global symbol deleted:', getGlobalSymbol(this.symbol))
+
+    if (this.subscriptions.length > 0) {
+      logger.info('disposing of %d subscriptions...', this.subscriptions.length)
+
+      for (const dispose of this.subscriptions) {
+        dispose()
+      }
+
+      this.subscriptions = []
+
+      logger.info('disposed of all subscriptions!', this.subscriptions.length)
+    }
+
+    this.emitter.removeAllListeners()
+    logger.info('destroyed the listener!')
+
+    this.readyState = InterceptorReadyState.DISPOSED
+  }
+
+  private getInstance(): this | undefined {
+    const instance = getGlobalSymbol<this>(this.symbol)
+    this.logger.info('retrieved global instance:', instance?.constructor?.name)
+    return instance
+  }
+
+  private setInstance(): void {
+    setGlobalSymbol(this.symbol, this)
+    this.logger.info('set global instance!', this.symbol.description)
+  }
+
+  private clearInstance(): void {
+    deleteGlobalSymbol(this.symbol)
+    this.logger.info('cleared global instance!', this.symbol.description)
+  }
+}

package/src/InterceptorError.ts

@@ -0,0 +1,7 @@
+export class InterceptorError extends Error {
+  constructor(message?: string) {
+    super(message)
+    this.name = 'InterceptorError'
+    Object.setPrototypeOf(this, InterceptorError.prototype)
+  }
+}

package/src/RemoteHttpInterceptor.ts

@@ -0,0 +1,251 @@
+import { ChildProcess } from 'child_process'
+import { HttpRequestEventMap } from './glossary'
+import { Interceptor } from './Interceptor'
+import { BatchInterceptor } from './BatchInterceptor'
+import { ClientRequestInterceptor } from './interceptors/ClientRequest'
+import { XMLHttpRequestInterceptor } from './interceptors/XMLHttpRequest'
+import { FetchInterceptor } from './interceptors/fetch'
+import { handleRequest } from './utils/handleRequest'
+import { RequestController } from './RequestController'
+import { FetchResponse } from './utils/fetchUtils'
+import { isResponseError } from './utils/responseUtils'
+
+export interface SerializedRequest {
+  id: string
+  url: string
+  method: string
+  headers: Array<[string, string]>
+  credentials: RequestCredentials
+  body: string
+}
+
+interface RevivedRequest extends Omit<SerializedRequest, 'url' | 'headers'> {
+  url: URL
+  headers: Headers
+}
+
+export interface SerializedResponse {
+  status: number
+  statusText: string
+  headers: Array<[string, string]>
+  body: string
+}
+
+export class RemoteHttpInterceptor extends BatchInterceptor<
+  [ClientRequestInterceptor, XMLHttpRequestInterceptor, FetchInterceptor]
+> {
+  constructor() {
+    super({
+      name: 'remote-interceptor',
+      interceptors: [
+        new ClientRequestInterceptor(),
+        new XMLHttpRequestInterceptor(),
+        new FetchInterceptor(),
+      ],
+    })
+  }
+
+  protected setup() {
+    super.setup()
+
+    let handleParentMessage: NodeJS.MessageListener
+
+    this.on('request', async ({ request, requestId, controller }) => {
+      // Send the stringified intercepted request to
+      // the parent process where the remote resolver is established.
+      const serializedRequest = JSON.stringify({
+        id: requestId,
+        method: request.method,
+        url: request.url,
+        headers: Array.from(request.headers.entries()),
+        credentials: request.credentials,
+        body: ['GET', 'HEAD'].includes(request.method)
+          ? null
+          : await request.text(),
+      } as SerializedRequest)
+
+      this.logger.info(
+        'sent serialized request to the child:',
+        serializedRequest
+      )
+
+      process.send?.(`request:${serializedRequest}`)
+
+      const responsePromise = new Promise<void>((resolve) => {
+        handleParentMessage = (message) => {
+          if (typeof message !== 'string') {
+            return resolve()
+          }
+
+          if (message.startsWith(`response:${requestId}`)) {
+            const [, serializedResponse] =
+              message.match(/^response:.+?:(.+)$/) || []
+
+            if (!serializedResponse) {
+              return resolve()
+            }
+
+            const responseInit = JSON.parse(
+              serializedResponse
+            ) as SerializedResponse
+
+            const mockedResponse = new FetchResponse(responseInit.body, {
+              url: request.url,
+              status: responseInit.status,
+              statusText: responseInit.statusText,
+              headers: responseInit.headers,
+            })
+
+            /**
+             * @todo Support "errorWith" as well.
+             * This response handling from the child is incomplete.
+             */
+
+            controller.respondWith(mockedResponse)
+            return resolve()
+          }
+        }
+      })
+
+      // Listen for the mocked response message from the parent.
+      this.logger.info(
+        'add "message" listener to the parent process',
+        handleParentMessage
+      )
+      process.addListener('message', handleParentMessage)
+
+      return responsePromise
+    })
+
+    this.subscriptions.push(() => {
+      process.removeListener('message', handleParentMessage)
+    })
+  }
+}
+
+export function requestReviver(key: string, value: any) {
+  switch (key) {
+    case 'url':
+      return new URL(value)
+
+    case 'headers':
+      return new Headers(value)
+
+    default:
+      return value
+  }
+}
+
+export interface RemoveResolverOptions {
+  process: ChildProcess
+}
+
+export class RemoteHttpResolver extends Interceptor<HttpRequestEventMap> {
+  static symbol = Symbol('remote-resolver')
+  private process: ChildProcess
+
+  constructor(options: RemoveResolverOptions) {
+    super(RemoteHttpResolver.symbol)
+    this.process = options.process
+  }
+
+  protected setup() {
+    const logger = this.logger.extend('setup')
+
+    const handleChildMessage: NodeJS.MessageListener = async (message) => {
+      logger.info('received message from child!', message)
+
+      if (typeof message !== 'string' || !message.startsWith('request:')) {
+        logger.info('unknown message, ignoring...')
+        return
+      }
+
+      const [, serializedRequest] = message.match(/^request:(.+)$/) || []
+      if (!serializedRequest) {
+        return
+      }
+
+      const requestJson = JSON.parse(
+        serializedRequest,
+        requestReviver
+      ) as RevivedRequest
+
+      logger.info('parsed intercepted request', requestJson)
+
+      const request = new Request(requestJson.url, {
+        method: requestJson.method,
+        headers: new Headers(requestJson.headers),
+        credentials: requestJson.credentials,
+        body: requestJson.body,
+      })
+
+      const controller = new RequestController(request, {
+        passthrough: () => {},
+        respondWith: async (response) => {
+          if (isResponseError(response)) {
+            this.logger.info('received a network error!', { response })
+            throw new Error('Not implemented')
+          }
+
+          this.logger.info('received mocked response!', { response })
+
+          const responseClone = response.clone()
+          const responseText = await responseClone.text()
+
+          // // Send the mocked response to the child process.
+          const serializedResponse = JSON.stringify({
+            status: response.status,
+            statusText: response.statusText,
+            headers: Array.from(response.headers.entries()),
+            body: responseText,
+          } as SerializedResponse)
+
+          this.process.send(
+            `response:${requestJson.id}:${serializedResponse}`,
+            (error) => {
+              if (error) {
+                return
+              }
+
+              // Emit an optimistic "response" event at this point,
+              // not to rely on the back-and-forth signaling for the sake of the event.
+              this.emitter.emit('response', {
+                request,
+                requestId: requestJson.id,
+                response: responseClone,
+                isMockedResponse: true,
+              })
+            }
+          )
+
+          logger.info(
+            'sent serialized mocked response to the parent:',
+            serializedResponse
+          )
+        },
+        errorWith: (reason) => {
+          this.logger.info('request has errored!', { error: reason })
+          throw new Error('Not implemented')
+        },
+      })
+
+      await handleRequest({
+        request,
+        requestId: requestJson.id,
+        controller,
+        emitter: this.emitter,
+      })
+    }
+
+    this.subscriptions.push(() => {
+      this.process.removeListener('message', handleChildMessage)
+      logger.info('removed the "message" listener from the child process!')
+    })
+
+    logger.info('adding a "message" listener to the child process')
+    this.process.addListener('message', handleChildMessage)
+
+    this.process.once('error', () => this.dispose())
+    this.process.once('exit', () => this.dispose())
+  }
+}