@mswjs/interceptors 0.15.1 → 0.16.0

package/src/Interceptor.test.ts

@@ -0,0 +1,166 @@
+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('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 "IDLE" when the interceptor is created', () => {
+    const interceptor = new Interceptor(symbol)
+    expect(interceptor.readyState).toBe(InterceptorReadyState.IDLE)
+  })
+
+  it('leaves state as "IDLE" 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.IDLE)
+
+    await nextTickAsync(() => {
+      expect(interceptor.readyState).toBe(InterceptorReadyState.IDLE)
+    })
+  })
+
+  it('perfroms state transition when the interceptor is applying', async () => {
+    const interceptor = new Interceptor(symbol)
+    interceptor.apply()
+
+    expect(interceptor.readyState).toBe(InterceptorReadyState.APPLYING)
+
+    await nextTickAsync(() => {
+      expect(interceptor.readyState).toBe(InterceptorReadyState.APPLIED)
+    })
+  })
+
+  it('perfroms state transition when disposing of the interceptor', async () => {
+    const interceptor = new Interceptor(symbol)
+    interceptor.apply()
+    interceptor.dispose()
+
+    expect(interceptor.readyState).toBe(InterceptorReadyState.DISPOSING)
+
+    await nextTickAsync(() => {
+      expect(interceptor.readyState).toBe(InterceptorReadyState.DISPOSED)
+    })
+  })
+})
+
+describe('apply', () => {
+  it('does not apply the same interceptor multiple times', () => {
+    const interceptor = new Interceptor(symbol)
+    const setupSpy = jest.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 = jest.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 = jest.fn()
+    firstInterceptor.on('test', firstListener)
+
+    secondInterceptor.apply()
+    const secondListener = jest.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 = jest.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,226 @@
+import { Debugger, debug } from 'debug'
+import { AsyncEventEmitter } from './utils/AsyncEventEmitter'
+import { nextTick } from './utils/nextTick'
+
+export type InterceptorEventMap = Record<string, (...args: any[]) => void>
+export type InterceptorSubscription = () => void
+
+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 {
+  IDLE = 'IDLE',
+  APPLYING = 'APPLYING',
+  APPLIED = 'APPLIED',
+  DISPOSING = 'DISPOSING',
+  DISPOSED = 'DISPOSED',
+}
+
+export type ExtractEventNames<EventMap extends Record<string, any>> =
+  EventMap extends Record<infer EventName, any> ? EventName : never
+
+export class Interceptor<EventMap extends InterceptorEventMap> {
+  protected emitter: AsyncEventEmitter<EventMap>
+  protected subscriptions: InterceptorSubscription[]
+  protected log: Debugger
+
+  public readyState: InterceptorReadyState
+
+  constructor(private readonly symbol: Symbol) {
+    this.readyState = InterceptorReadyState.IDLE
+
+    this.emitter = new AsyncEventEmitter()
+    this.subscriptions = []
+    this.log = debug(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.log('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 log = this.log.extend('apply')
+    log('applying the interceptor...')
+
+    if (this.readyState === InterceptorReadyState.APPLIED) {
+      log('intercepted already applied!')
+      return
+    }
+
+    const shouldApply = this.checkEnvironment()
+
+    if (!shouldApply) {
+      log('the interceptor cannot be applied in this environment!')
+      return
+    }
+
+    this.readyState = InterceptorReadyState.APPLYING
+
+    // Always activate the emitter when applying the interceptor.
+    // This will ensure the interceptor can process events after it's
+    // been disposed and re-applied again (it may be a singleton).
+    this.emitter.activate()
+    log('activated the emiter!', this.emitter.readyState)
+
+    // 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) {
+      log('found a running instance, reusing...')
+
+      // Proxy any listeners you set on this instance to the running instance.
+      this.on = (event, listener) => {
+        log('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)
+          log('removed proxied "%s" listener!', event)
+        })
+      }
+
+      nextTick(() => {
+        this.readyState = InterceptorReadyState.APPLIED
+      })
+
+      return
+    }
+
+    log('no running instance found, setting up a new instance...')
+
+    // Setup the interceptor.
+    this.setup()
+
+    // Store the newly applied interceptor instance globally.
+    this.setInstance()
+
+    nextTick(() => {
+      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<Event extends ExtractEventNames<EventMap>>(
+    event: Event,
+    listener: EventMap[Event]
+  ): void {
+    const log = this.log.extend('on')
+
+    if (
+      this.readyState === InterceptorReadyState.DISPOSING ||
+      this.readyState === InterceptorReadyState.DISPOSED
+    ) {
+      log('cannot listen to events, already disposed!')
+      return
+    }
+
+    log('adding "%s" event listener:', event, listener.name)
+
+    this.emitter.on(event, listener)
+  }
+
+  /**
+   * Disposes of any side-effects this interceptor has introduced.
+   */
+  public dispose(): void {
+    const log = this.log.extend('dispose')
+
+    if (this.readyState === InterceptorReadyState.DISPOSED) {
+      log('cannot dispose, already disposed!')
+      return
+    }
+
+    log('disposing the interceptor...')
+    this.readyState = InterceptorReadyState.DISPOSING
+
+    if (!this.getInstance()) {
+      log('no interceptors running, skipping dispose...')
+      return
+    }
+
+    // Delete the global symbol as soon as possible,
+    // indicating that the interceptor is no longer running.
+    this.clearInstance()
+
+    log('global symbol deleted:', getGlobalSymbol(this.symbol))
+
+    if (this.subscriptions.length > 0) {
+      log('disposing of %d subscriptions...', this.subscriptions.length)
+
+      for (const dispose of this.subscriptions) {
+        dispose()
+      }
+
+      this.subscriptions = []
+
+      log('disposed of all subscriptions!', this.subscriptions.length)
+    }
+
+    this.emitter.deactivate()
+    log('destroyed the listener!')
+
+    nextTick(() => {
+      this.readyState = InterceptorReadyState.DISPOSED
+    })
+  }
+
+  private getInstance(): this | undefined {
+    const instance = getGlobalSymbol<this>(this.symbol)
+    this.log('retrieved global instance:', instance?.constructor?.name)
+    return instance
+  }
+
+  private setInstance(): void {
+    setGlobalSymbol(this.symbol, this)
+    this.log('set global instance!', this.symbol.description)
+  }
+
+  private clearInstance(): void {
+    deleteGlobalSymbol(this.symbol)
+    this.log('cleared global instance!', this.symbol.description)
+  }
+}

package/src/RemoteInterceptor.ts

@@ -0,0 +1,176 @@
+import { ChildProcess } from 'child_process'
+import { Headers } from 'headers-polyfill'
+import type {
+  HttpRequestEventMap,
+  InteractiveIsomorphicRequest,
+  IsomorphicRequest,
+} from './glossary'
+import { Interceptor } from './Interceptor'
+import { BatchInterceptor } from './BatchInterceptor'
+import { ClientRequestInterceptor } from './interceptors/ClientRequest'
+import { XMLHttpRequestInterceptor } from './interceptors/XMLHttpRequest'
+import { createLazyCallback } from './utils/createLazyCallback'
+import { toIsoResponse } from './utils/toIsoResponse'
+
+export class RemoteHttpInterceptor extends BatchInterceptor<
+  [ClientRequestInterceptor, XMLHttpRequestInterceptor]
+> {
+  constructor() {
+    super({
+      name: 'remote-interceptor',
+      interceptors: [
+        new ClientRequestInterceptor(),
+        new XMLHttpRequestInterceptor(),
+      ],
+    })
+  }
+
+  protected setup() {
+    super.setup()
+
+    let handleParentMessage: NodeJS.MessageListener
+
+    this.on('request', async (request) => {
+      // Send the stringified intercepted request to
+      // the parent process where the remote resolver is established.
+      const serializedRequest = JSON.stringify(request)
+
+      this.log('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:${request.id}`)) {
+            const [, serializedResponse] =
+              message.match(/^response:.+?:(.+)$/) || []
+
+            if (!serializedResponse) {
+              return resolve()
+            }
+
+            const mockedResponse = JSON.parse(serializedResponse)
+            request.respondWith(mockedResponse)
+            resolve()
+          }
+        }
+      })
+
+      // Listen for the mocked resopnse message from the parent.
+      this.log(
+        '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 log = this.log.extend('setup')
+
+    const handleChildMessage: NodeJS.MessageListener = async (message) => {
+      log('received message from child!', message)
+
+      if (typeof message !== 'string' || !message.startsWith('request:')) {
+        log('unknown message, ignoring...')
+        return
+      }
+
+      const [, serializedRequest] = message.match(/^request:(.+)$/) || []
+
+      if (!serializedRequest) {
+        return
+      }
+
+      const isomorphicRequest: IsomorphicRequest = JSON.parse(
+        serializedRequest,
+        requestReviver
+      )
+
+      log('parsed intercepted request', isomorphicRequest)
+
+      const interactiveIsomorphicRequest: InteractiveIsomorphicRequest = {
+        ...isomorphicRequest,
+        respondWith: createLazyCallback(),
+      }
+
+      this.emitter.emit('request', interactiveIsomorphicRequest)
+      await this.emitter.untilIdle('request')
+      const [mockedResponse] =
+        await interactiveIsomorphicRequest.respondWith.invoked()
+
+      log('event.respondWith called with:', mockedResponse)
+
+      // Send the mocked response to the child process.
+      const serializedResponse = JSON.stringify(mockedResponse)
+
+      this.process.send(
+        `response:${isomorphicRequest.id}:${serializedResponse}`,
+        (error) => {
+          if (error) {
+            return
+          }
+
+          if (mockedResponse) {
+            // Emit an optimistinc "response" event at this point,
+            // not to rely on the back-and-forth signaling for the sake of the event.
+            this.emitter.emit(
+              'response',
+              isomorphicRequest,
+              toIsoResponse(mockedResponse)
+            )
+          }
+        }
+      )
+
+      log('sent serialized mocked response to the parent:', serializedResponse)
+    }
+
+    this.subscriptions.push(() => {
+      this.process.removeListener('message', handleChildMessage)
+      log('removed the "message" listener from the child process!')
+    })
+
+    log('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())
+  }
+}

package/src/glossary.ts

@@ -0,0 +1,42 @@
+import type { HeadersObject, Headers } from 'headers-polyfill'
+import type { LazyCallback } from './utils/createLazyCallback'
+
+export type RequestCredentials = 'omit' | 'include' | 'same-origin'
+
+export interface IsomorphicRequest {
+  id: string
+  url: URL
+  method: string
+  headers: Headers
+  /**
+   * The value of the request client's "credentials" option
+   * or a compatible alternative (i.e. `withCredentials` for `XMLHttpRequest`).
+   * Always equals to "omit" in Node.js.
+   */
+  credentials: RequestCredentials
+  body?: string
+}
+
+export interface InteractiveIsomorphicRequest extends IsomorphicRequest {
+  respondWith: LazyCallback<(mockedResponse: MockedResponse) => void>
+}
+
+export interface IsomorphicResponse {
+  status: number
+  statusText: string
+  headers: Headers
+  body?: string
+}
+
+export interface MockedResponse
+  extends Omit<Partial<IsomorphicResponse>, 'headers'> {
+  headers?: HeadersObject
+}
+
+export type HttpRequestEventMap = {
+  request(request: InteractiveIsomorphicRequest): Promise<void> | void
+  response(
+    request: IsomorphicRequest,
+    response: IsomorphicResponse
+  ): Promise<void> | void
+}

package/src/index.ts

@@ -1,5 +1,5 @@
-export * from './createInterceptor'
-export * from './remote'
+export * from './glossary'
+export * from './RemoteInterceptor'
 
 /* Utils */
 export { getCleanUrl } from './utils/getCleanUrl'