msw 2.15.0 → 3.0.0

package/src/{core/ws/WebSocketClientManager.ts → ws/websocket-client-manager.ts}

@@ -1,18 +1,18 @@
 import type {
   WebSocketData,
-  WebSocketClientConnectionProtocol,
+  WebSocketClientHandle,
   WebSocketClientEventMap,
 } from '@mswjs/interceptors/WebSocket'
-import type { WebSocketClientStore } from './WebSocketClientStore'
-import { WebSocketMemoryClientStore } from './WebSocketMemoryClientStore'
-import { WebSocketIndexedDBClientStore } from './WebSocketIndexedDBClientStore'
+import type { WebSocketClientStore } from './websocket-client-store'
+import { WebSocketMemoryClientStore } from './websocket-memory-client-store'
+import { WebSocketIndexedDBClientStore } from './websocket-indexeddb-client-store'
 
-export type WebSocketBroadcastChannelMessage =
+export type WebSocketBroadcastChannelMessage<Message = WebSocketData> =
   | {
       type: 'extraneous:send'
       payload: {
         clientId: string
-        data: WebSocketData
+        data: Message
       }
     }
   | {
@@ -28,10 +28,10 @@ export type WebSocketBroadcastChannelMessage =
  * A manager responsible for accumulating WebSocket client
  * connections across different browser runtimes.
  */
-export class WebSocketClientManager {
+export class WebSocketClientManager<Message = WebSocketData> {
   private store: WebSocketClientStore
-  private runtimeClients: Map<string, WebSocketClientConnectionProtocol>
-  private allClients: Set<WebSocketClientConnectionProtocol>
+  private runtimeClients: Map<string, WebSocketClientHandle<Message>>
+  private allClients: Set<WebSocketClientHandle<Message>>
 
   constructor(private channel: BroadcastChannel) {
     // Store the clients in the IndexedDB in the browser,
@@ -74,7 +74,7 @@ export class WebSocketClientManager {
           return runtimeClient
         }
 
-        return new WebSocketRemoteClientConnection(
+        return new WebSocketRemoteClientConnection<Message>(
           client.id,
           new URL(client.url),
           this.channel,
@@ -93,7 +93,7 @@ export class WebSocketClientManager {
   /**
    * All active WebSocket client connections.
    */
-  get clients(): Set<WebSocketClientConnectionProtocol> {
+  get clients(): Set<WebSocketClientHandle<Message>> {
     return this.allClients
   }
 
@@ -105,9 +105,7 @@ export class WebSocketClientManager {
     this.channel.postMessage({ type: 'db:update' })
   }
 
-  private async addClient(
-    client: WebSocketClientConnectionProtocol,
-  ): Promise<void> {
+  private async addClient(client: WebSocketClientHandle): Promise<void> {
     await this.store.add(client)
     // Sync the in-memory clients in this runtime with the
     // updated database. This pulls in all the stored clients.
@@ -121,9 +119,7 @@ export class WebSocketClientManager {
    * connection object because `addConnection()` is called only
    * for the opened connections in the same runtime.
    */
-  public async addConnection(
-    client: WebSocketClientConnectionProtocol,
-  ): Promise<void> {
+  public async addConnection(client: WebSocketClientHandle): Promise<void> {
     // Store this client in the map of clients created in this runtime.
     // This way, the manager can distinguish between this runtime clients
     // and extraneous runtime clients when synchronizing clients storage.
@@ -136,7 +132,7 @@ export class WebSocketClientManager {
     // that attempt to control this runtime (via a remote connection wrapper).
     // E.g. another runtime calling `client.send()` for the client in this runtime.
     const handleExtraneousMessage = (
-      message: MessageEvent<WebSocketBroadcastChannelMessage>,
+      message: MessageEvent<WebSocketBroadcastChannelMessage<Message>>,
     ) => {
       const { type, payload } = message.data
 
@@ -183,23 +179,23 @@ export class WebSocketClientManager {
  * on the given `BroadcastChannel` to communicate instructions
  * with the client connections from other runtimes.
  */
-export class WebSocketRemoteClientConnection
-  implements WebSocketClientConnectionProtocol
-{
+class WebSocketRemoteClientConnection<
+  Message = WebSocketData,
+> implements WebSocketClientHandle<Message> {
   constructor(
     public readonly id: string,
     public readonly url: URL,
     private channel: BroadcastChannel,
   ) {}
 
-  send(data: WebSocketData): void {
+  send(data: Message): void {
     this.channel.postMessage({
       type: 'extraneous:send',
       payload: {
         clientId: this.id,
         data,
       },
-    } as WebSocketBroadcastChannelMessage)
+    } as WebSocketBroadcastChannelMessage<Message>)
   }
 
   close(code?: number | undefined, reason?: string | undefined): void {
@@ -210,14 +206,14 @@ export class WebSocketRemoteClientConnection
         code,
         reason,
       },
-    } as WebSocketBroadcastChannelMessage)
+    } as WebSocketBroadcastChannelMessage<Message>)
   }
 
-  addEventListener<EventType extends keyof WebSocketClientEventMap>(
+  addEventListener<EventType extends keyof WebSocketClientEventMap<Message>>(
     _type: EventType,
     _listener: (
       this: WebSocket,
-      event: WebSocketClientEventMap[EventType],
+      event: WebSocketClientEventMap<Message>[EventType],
     ) => void,
     _options?: AddEventListenerOptions | boolean,
   ): void {
@@ -226,11 +222,11 @@ export class WebSocketRemoteClientConnection
     )
   }
 
-  removeEventListener<EventType extends keyof WebSocketClientEventMap>(
+  removeEventListener<EventType extends keyof WebSocketClientEventMap<Message>>(
     _event: EventType,
     _listener: (
       this: WebSocket,
-      event: WebSocketClientEventMap[EventType],
+      event: WebSocketClientEventMap<Message>[EventType],
     ) => void,
     _options?: EventListenerOptions | boolean,
   ): void {

package/src/{core/ws/WebSocketClientStore.ts → ws/websocket-client-store.ts}

@@ -1,4 +1,4 @@
-import type { WebSocketClientConnectionProtocol } from '@mswjs/interceptors/WebSocket'
+import type { WebSocketClientHandle } from '@mswjs/interceptors/WebSocket'
 
 export interface SerializedWebSocketClient {
   id: string
@@ -6,7 +6,7 @@ export interface SerializedWebSocketClient {
 }
 
 export abstract class WebSocketClientStore {
-  public abstract add(client: WebSocketClientConnectionProtocol): Promise<void>
+  public abstract add(client: WebSocketClientHandle): Promise<void>
 
   public abstract getAll(): Promise<Array<SerializedWebSocketClient>>
 

package/src/{core/handlers/WebSocketHandler.test.ts → ws/websocket-handler.test.ts}

@@ -1,7 +1,7 @@
-import { WebSocketHandler } from './WebSocketHandler'
+import { WebSocketHandler } from './websocket-handler'
 
 describe('parse', () => {
-  it('matches an exact url', () => {
+  test('matches an exact url', () => {
     expect(
       new WebSocketHandler('ws://localhost:3000').parse({
         url: new URL('ws://localhost:3000'),
@@ -14,7 +14,7 @@ describe('parse', () => {
     })
   })
 
-  it('ignores trailing slash', () => {
+  test('ignores trailing slash', () => {
     expect(
       new WebSocketHandler('ws://localhost:3000').parse({
         url: new URL('ws://localhost:3000/'),
@@ -38,7 +38,7 @@ describe('parse', () => {
     })
   })
 
-  it('supports path parameters', () => {
+  test('supports path parameters', () => {
     expect(
       new WebSocketHandler('ws://localhost:3000/:serviceName').parse({
         url: new URL('ws://localhost:3000/auth'),
@@ -53,7 +53,7 @@ describe('parse', () => {
     })
   })
 
-  it('ignores "/socket.io/" prefix in the client url', () => {
+  test('ignores "/socket.io/" prefix in the client url', () => {
     expect(
       new WebSocketHandler('ws://localhost:3000').parse({
         url: new URL(
@@ -81,7 +81,7 @@ describe('parse', () => {
     })
   })
 
-  it('preserves non-prefix "/socket.io/" path segment', () => {
+  test('preserves non-prefix "/socket.io/" path segment', () => {
     /**
      * @note It is highly unlikely but we still shouldn't modify the
      * WebSocket client URL if it contains a user-defined "socket.io" segment.
@@ -109,7 +109,7 @@ describe('parse', () => {
     })
   })
 
-  it('supports a custom resolution context (base url)', () => {
+  test('supports a custom resolution context (base url)', () => {
     expect(
       new WebSocketHandler('/api/ws').parse({
         url: new URL('ws://localhost:3000/api/ws'),
@@ -127,19 +127,19 @@ describe('parse', () => {
 })
 
 describe('test', () => {
-  it('returns true for a matching string', () => {
+  test('returns true for a matching string', () => {
     expect(
       new WebSocketHandler('ws://localhost/ws').test('ws://localhost/ws'),
     ).toBe(true)
   })
 
-  it('returns false for a non-matching string', () => {
+  test('returns false for a non-matching string', () => {
     expect(
       new WebSocketHandler('ws://localhost/ws').test('ws://localhost/other'),
     ).toBe(false)
   })
 
-  it('returns true for a relative matching string', () => {
+  test('returns true for a relative matching string', () => {
     expect(
       new WebSocketHandler('ws://localhost/ws').test('/ws', {
         baseUrl: 'ws://localhost',
@@ -147,7 +147,7 @@ describe('test', () => {
     ).toBe(true)
   })
 
-  it('returns false for a relative non-matching string', () => {
+  test('returns false for a relative non-matching string', () => {
     expect(
       new WebSocketHandler('ws://localhost/ws').test('/other', {
         baseUrl: 'ws://localhost',
@@ -155,7 +155,7 @@ describe('test', () => {
     ).toBe(false)
   })
 
-  it('returns true for a matching URL', () => {
+  test('returns true for a matching URL', () => {
     expect(
       new WebSocketHandler('ws://localhost/ws').test(
         new URL('ws://localhost/ws'),
@@ -163,7 +163,7 @@ describe('test', () => {
     ).toBe(true)
   })
 
-  it('returns false for a non-matching URL', () => {
+  test('returns false for a non-matching URL', () => {
     expect(
       new WebSocketHandler('ws://localhost/ws').test(
         new URL('ws://localhost/other'),
@@ -171,13 +171,13 @@ describe('test', () => {
     ).toBe(false)
   })
 
-  it('returns true for a matching HTTP url string', () => {
+  test('returns true for a matching HTTP url string', () => {
     expect(
       new WebSocketHandler('ws://localhost/ws').test('http://localhost/ws'),
     ).toBe(true)
   })
 
-  it('returns false for a non-matching HTTP url string', () => {
+  test('returns false for a non-matching HTTP url string', () => {
     expect(
       new WebSocketHandler('ws://localhost/ws').test('http://localhost/other'),
     ).toBe(false)

package/src/{core/handlers/WebSocketHandler.ts → ws/websocket-handler.ts}

@@ -1,56 +1,142 @@
-import { Emitter } from 'strict-event-emitter'
+import { Emitter, TypedEvent } from 'rettime'
 import { createRequestId, resolveWebSocketUrl } from '@mswjs/interceptors'
 import type {
-  WebSocketClientConnectionProtocol,
-  WebSocketConnectionData,
-  WebSocketServerConnectionProtocol,
+  WebSocketData,
+  WebSocketExtension,
+  WebSocketExtensionMessage,
+  WebSocketExtensionApi,
+  WebSocketConnectionInfo,
+  WebSocketConnectionEventData,
+  WebSocketClientHandle,
+  WebSocketServerHandle,
 } from '@mswjs/interceptors/WebSocket'
+/**
+ * @note A type-only import to prevent a runtime module cycle
+ * (the frame module imports this handler at runtime).
+ */
+import type { WebSocketNetworkFrameEventMap } from '#core/experimental/frames/websocket-frame'
 import {
   type Match,
   type Path,
   type PathParams,
   matchRequestUrl,
-} from '../utils/matching/matchRequestUrl'
-import { getCallFrame } from '../utils/internal/getCallFrame'
-import { attachWebSocketLogger } from '../ws/utils/attachWebSocketLogger'
+} from '#core/utils/matching/match-request-url'
+import { isAbsoluteUrl } from '#core/utils/url/is-absolute-url'
+import { Handler } from '#core/handlers/handler'
+import { getCallFrame } from '#core/utils/internal/get-call-frame'
+import { attachWebSocketLogger } from './utils/attach-websocket-logger'
 
 type WebSocketHandlerParsedResult = {
   match: Match
 }
 
-export type WebSocketHandlerEventMap = {
-  connection: [args: WebSocketHandlerConnection]
+export interface WebSocketHandlerOptions {
+  /**
+   * WebSocket extensions applied to every connection matched by this handler,
+   * left to right. The last one applied encodes and decodes the traffic,
+   * and every one of them extends the connection event with its own API.
+   */
+  extensions?: ReadonlyArray<AnyWebSocketExtension>
 }
 
-export interface WebSocketHandlerConnection {
-  client: WebSocketClientConnectionProtocol
-  server: WebSocketServerConnectionProtocol
-  info: WebSocketConnectionData['info']
+export type AnyWebSocketExtension = WebSocketExtension<unknown, unknown>
+
+/**
+ * The connection event of a handler with the given extension:
+ * the connection speaks the extension's messages and the event
+ * carries the extension's own API (e.g. rooms).
+ */
+export type WebSocketHandlerConnectionEvent<
+  Extension extends AnyWebSocketExtension = WebSocketExtension,
+> = WebSocketConnectionEvent<WebSocketExtensionMessage<Extension>> &
+  WebSocketExtensionApi<Extension>
+
+export type WebSocketHandlerEventMap<
+  Extension extends AnyWebSocketExtension = WebSocketExtension,
+> = {
+  connection: WebSocketHandlerConnectionEvent<Extension>
+}
+
+/**
+ * The connection matched by a handler.
+ *
+ * @note Typed against the connection handles, not the connection classes,
+ * so a handler accepts connections living anywhere (e.g. in another
+ * runtime, or a custom implementation of the handles).
+ */
+export interface WebSocketHandlerConnection<Message = WebSocketData> {
+  client: WebSocketClientHandle<Message>
+  server: WebSocketServerHandle<Message>
+  info: WebSocketConnectionInfo
   params: PathParams
 }
 
+export class WebSocketConnectionEvent<Message = WebSocketData>
+  extends TypedEvent<void, void, 'connection'>
+  implements WebSocketHandlerConnection<Message>
+{
+  public readonly client: WebSocketClientHandle<Message>
+  public readonly server: WebSocketServerHandle<Message>
+  public readonly info: WebSocketConnectionInfo
+  public readonly params: PathParams
+
+  constructor(connection: WebSocketHandlerConnection<Message>) {
+    super('connection')
+    this.client = connection.client
+    this.server = connection.server
+    this.info = connection.info
+    this.params = connection.params
+  }
+}
+
+/**
+ * The connection resolved by a handler: the matched connection
+ * extended with the handler extension's own API.
+ */
+export type WebSocketHandlerResolvedConnection<
+  Extension extends AnyWebSocketExtension = WebSocketExtension,
+> = WebSocketHandlerConnection<WebSocketExtensionMessage<Extension>> &
+  WebSocketExtensionApi<Extension>
+
 export interface WebSocketResolutionContext {
   baseUrl?: string
+
+  /**
+   * An emit-only reference to the network frame's events.
+   * Allows handlers to emit additional events not covered by the frame
+   * into the network's life-cycle event stream (e.g. `server.events`).
+   */
+  events?: Pick<Emitter<WebSocketNetworkFrameEventMap>, 'emit'>
+
   [kAutoConnect]?: boolean
 }
 
 export const kEmitter = Symbol('kEmitter')
-export const kSender = Symbol('kSender')
 export const kConnect = Symbol('kConnect')
 export const kAutoConnect = Symbol('kAutoConnect')
 
 const kStopPropagationPatched = Symbol('kStopPropagationPatched')
 const KOnStopPropagation = Symbol('KOnStopPropagation')
 
-export class WebSocketHandler {
+export class WebSocketHandler<
+  Extension extends AnyWebSocketExtension = WebSocketExtension,
+> extends Handler {
   public id: string
   public callFrame?: string
-  public kind = 'websocket' as const
 
-  protected [kEmitter]: Emitter<WebSocketHandlerEventMap>
+  public readonly kind = 'websocket'
+
+  protected [kEmitter]: Emitter<WebSocketHandlerEventMap<Extension>>
+  protected readonly extensions: ReadonlyArray<AnyWebSocketExtension>
+
+  constructor(
+    protected readonly url: Path,
+    options?: WebSocketHandlerOptions,
+  ) {
+    super()
 
-  constructor(protected readonly url: Path) {
     this.id = createRequestId()
+    this.extensions = options?.extensions ?? []
 
     this[kEmitter] = new Emitter()
     this.callFrame = getCallFrame(new Error())
@@ -63,11 +149,15 @@ export class WebSocketHandler {
     const clientUrl = new URL(args.url)
 
     // Resolve the WebSocket handler path:
-    // - Plain string URLs resolved as per the specification (via Interceptors).
+    // - Relative string URLs are resolved against the base URL (via Interceptors).
+    // - Absolute string URLs are preserved. Parsing them as a URL would
+    //   percent-encode wildcards in the host (e.g. "ws://*" becomes "ws://%2A").
     // - String URLs starting with a wildcard are preserved (prepending a scheme there will break them).
     // - RegExp paths are preserved.
     const resolvedHandlerUrl =
-      this.url instanceof RegExp || this.url.startsWith('*')
+      this.url instanceof RegExp ||
+      isAbsoluteUrl(this.url) ||
+      this.url.startsWith('*')
         ? this.url
         : this.#resolveWebSocketUrl(this.url, args.resolutionContext?.baseUrl)
 
@@ -104,20 +194,38 @@ export class WebSocketHandler {
   }
 
   public async run(
-    connection: WebSocketConnectionData,
+    connection: WebSocketConnectionEventData,
     resolutionContext?: WebSocketResolutionContext,
-  ): Promise<WebSocketHandlerConnection | null> {
+  ): Promise<WebSocketHandlerResolvedConnection<Extension> | null> {
     const parsedResult = this.#match(connection.client.url, resolutionContext)
 
     if (parsedResult == null) {
       return null
     }
 
-    const resolvedConnection: WebSocketHandlerConnection = {
-      ...connection,
-      params: parsedResult.match.params || {},
+    // Every consumer of the connection objects (listeners, `link.broadcast()`,
+    // the logger) speaks the extensions' message domain from here on.
+    for (const extension of this.extensions) {
+      extension.apply(connection)
     }
 
+    /**
+     * @note Expose the extensions' own APIs (e.g. rooms) on the connection
+     * event, merged left to right. The link infers the merged type from the
+     * extensions it was given; `Object.assign` with a spread of sources is
+     * untyped, which is what allows the merged value to take that type.
+     */
+    const resolvedConnection: WebSocketHandlerResolvedConnection<Extension> =
+      Object.assign(
+        {
+          client: connection.client,
+          server: connection.server,
+          info: connection.info,
+          params: parsedResult.match.params || {},
+        },
+        ...this.extensions.map((extension) => extension.extend?.(connection)),
+      )
+
     if (resolutionContext?.[kAutoConnect] ?? true) {
       if (this[kConnect](resolvedConnection)) {
         return resolvedConnection
@@ -154,7 +262,9 @@ export class WebSocketHandler {
     return null
   }
 
-  protected [kConnect](connection: WebSocketHandlerConnection): boolean {
+  protected [kConnect](
+    connection: WebSocketHandlerResolvedConnection<Extension>,
+  ): boolean {
     // Support `event.stopPropagation()` for various client/server events.
     connection.client.addEventListener(
       'message',
@@ -183,13 +293,16 @@ export class WebSocketHandler {
     )
 
     /**
-     * @fixme Use "rettime" and await these events to have
-     * exceptions propagate properly.
+     * @fixme Await these events (e.g. via `.emitAsPromise()`) to have
+     * exceptions from asynchronous listeners propagate properly.
      */
-    return this[kEmitter].emit('connection', connection)
+    return this[kEmitter].emit(
+      // Carry the extension's own API (e.g. rooms) over to the event.
+      Object.assign(new WebSocketConnectionEvent(connection), connection),
+    )
   }
 
-  public log(connection: WebSocketConnectionData): () => void {
+  public log(connection: WebSocketConnectionEventData): () => void {
     return attachWebSocketLogger(connection)
   }
 
@@ -217,8 +330,7 @@ export class WebSocketHandler {
 function createStopPropagationListener(handler: WebSocketHandler) {
   return function stopPropagationListener(event: Event) {
     const propagationStoppedAt = Reflect.get(event, 'kPropagationStoppedAt') as
-      | string
-      | undefined
+      string | undefined
 
     if (propagationStoppedAt && handler.id !== propagationStoppedAt) {
       event.stopImmediatePropagation()

package/src/{core/ws/WebSocketIndexedDBClientStore.ts → ws/websocket-indexeddb-client-store.ts}

@@ -1,7 +1,6 @@
-import { DeferredPromise } from '@open-draft/deferred-promise'
-import type { WebSocketClientConnectionProtocol } from '@mswjs/interceptors/WebSocket'
-import type { WebSocketClientStore } from './WebSocketClientStore'
-import { type SerializedWebSocketClient } from './WebSocketClientStore'
+import type { WebSocketClientHandle } from '@mswjs/interceptors/WebSocket'
+import type { WebSocketClientStore } from './websocket-client-store'
+import type { SerializedWebSocketClient } from './websocket-client-store'
 
 const DB_NAME = 'msw-websocket-clients'
 const DB_STORE_NAME = 'clients'
@@ -13,8 +12,8 @@ export class WebSocketIndexedDBClientStore implements WebSocketClientStore {
     this.db = this.createDatabase()
   }
 
-  public async add(client: WebSocketClientConnectionProtocol): Promise<void> {
-    const promise = new DeferredPromise<void>()
+  public async add(client: WebSocketClientHandle): Promise<void> {
+    const promise = Promise.withResolvers<void>()
     const store = await this.getStore()
 
     /**
@@ -40,11 +39,11 @@ export class WebSocketIndexedDBClientStore implements WebSocketClientStore {
       )
     }
 
-    return promise
+    return promise.promise
   }
 
   public async getAll(): Promise<Array<SerializedWebSocketClient>> {
-    const promise = new DeferredPromise<Array<SerializedWebSocketClient>>()
+    const promise = Promise.withResolvers<Array<SerializedWebSocketClient>>()
     const store = await this.getStore()
     const request = store.getAll() as IDBRequest<
       Array<SerializedWebSocketClient>
@@ -62,11 +61,11 @@ export class WebSocketIndexedDBClientStore implements WebSocketClientStore {
       )
     }
 
-    return promise
+    return promise.promise
   }
 
   public async deleteMany(clientIds: Array<string>): Promise<void> {
-    const promise = new DeferredPromise<void>()
+    const promise = Promise.withResolvers<void>()
     const store = await this.getStore()
 
     for (const clientId of clientIds) {
@@ -85,11 +84,11 @@ export class WebSocketIndexedDBClientStore implements WebSocketClientStore {
       )
     }
 
-    return promise
+    return promise.promise
   }
 
   private async createDatabase(): Promise<IDBDatabase> {
-    const promise = new DeferredPromise<IDBDatabase>()
+    const promise = Promise.withResolvers<IDBDatabase>()
     const request = indexedDB.open(DB_NAME, 1)
 
     request.onsuccess = ({ currentTarget }) => {
@@ -128,7 +127,7 @@ export class WebSocketIndexedDBClientStore implements WebSocketClientStore {
       )
     }
 
-    return promise
+    return promise.promise
   }
 
   private async getStore(): Promise<IDBObjectStore> {

package/src/{core/ws/WebSocketMemoryClientStore.ts → ws/websocket-memory-client-store.ts}

@@ -1,6 +1,6 @@
-import type { WebSocketClientConnectionProtocol } from '@mswjs/interceptors/WebSocket'
-import type { WebSocketClientStore } from './WebSocketClientStore'
-import { type SerializedWebSocketClient } from './WebSocketClientStore'
+import type { WebSocketClientHandle } from '@mswjs/interceptors/WebSocket'
+import type { WebSocketClientStore } from './websocket-client-store'
+import type { SerializedWebSocketClient } from './websocket-client-store'
 
 export class WebSocketMemoryClientStore implements WebSocketClientStore {
   private store: Map<string, SerializedWebSocketClient>
@@ -9,7 +9,7 @@ export class WebSocketMemoryClientStore implements WebSocketClientStore {
     this.store = new Map()
   }
 
-  public async add(client: WebSocketClientConnectionProtocol): Promise<void> {
+  public async add(client: WebSocketClientHandle): Promise<void> {
     this.store.set(client.id, { id: client.id, url: client.url.href })
   }