msw 2.5.1 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "msw",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Seamless REST/GraphQL API mocking library for browser and Node.js.",
   "main": "./lib/core/index.js",
   "module": "./lib/core/index.mjs",
@@ -58,6 +58,12 @@
       "import": "./lib/core/graphql.mjs",
       "default": "./lib/core/graphql.js"
     },
+    "./core/ws": {
+      "types": "./lib/core/ws.d.ts",
+      "require": "./lib/core/ws.js",
+      "import": "./lib/core/ws.mjs",
+      "default": "./lib/core/ws.js"
+    },
     "./mockServiceWorker.js": "./lib/mockServiceWorker.js",
     "./package.json": "./package.json"
   },
@@ -118,6 +124,7 @@
     "@bundled-es-modules/tough-cookie": "^0.1.6",
     "@inquirer/confirm": "^5.0.0",
     "@mswjs/interceptors": "^0.36.5",
+    "@open-draft/deferred-promise": "^2.2.0",
     "@open-draft/until": "^2.1.0",
     "@types/cookie": "^0.6.0",
     "@types/statuses": "^2.0.4",
@@ -134,6 +141,7 @@
   "devDependencies": {
     "@commitlint/cli": "^18.4.4",
     "@commitlint/config-conventional": "^18.4.4",
+    "@fastify/websocket": "^8.3.1",
     "@open-draft/test-server": "^0.4.2",
     "@ossjs/release": "^0.8.1",
     "@playwright/test": "^1.48.0",
@@ -157,6 +165,7 @@
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-prettier": "^5.2.1",
     "express": "^5.0.0",
+    "fastify": "^4.26.0",
     "fs-extra": "^11.2.0",
     "fs-teardown": "^0.3.0",
     "glob": "^11.0.0",

package/src/browser/setupWorker/glossary.ts

@@ -5,13 +5,11 @@ import {
   SharedOptions,
 } from '~/core/sharedOptions'
 import { ServiceWorkerMessage } from './start/utils/createMessageChannel'
-import {
-  RequestHandler,
-  RequestHandlerDefaultInfo,
-} from '~/core/handlers/RequestHandler'
+import { RequestHandler } from '~/core/handlers/RequestHandler'
 import type { HttpRequestEventMap, Interceptor } from '@mswjs/interceptors'
-import { Path } from '~/core/utils/matching/matchRequestUrl'
-import { RequiredDeep } from '~/core/typeUtils'
+import type { Path } from '~/core/utils/matching/matchRequestUrl'
+import type { RequiredDeep } from '~/core/typeUtils'
+import type { WebSocketHandler } from '~/core/handlers/WebSocketHandler'
 
 export type ResolvedPath = Path | URL
 
@@ -92,7 +90,7 @@ export interface SetupWorkerInternalContext {
   startOptions: RequiredDeep<StartOptions>
   worker: ServiceWorker | null
   registration: ServiceWorkerRegistration | null
-  getRequestHandlers(): Array<RequestHandler>
+  getRequestHandlers(): Array<RequestHandler | WebSocketHandler>
   requests: Map<string, Request>
   emitter: Emitter<LifeCycleEventsMap>
   keepAliveInterval?: number
@@ -216,7 +214,7 @@ export interface SetupWorker {
    *
    * @see {@link https://mswjs.io/docs/api/setup-worker/use `worker.use()` API reference}
    */
-  use: (...handlers: RequestHandler[]) => void
+  use: (...handlers: Array<RequestHandler | WebSocketHandler>) => void
 
   /**
    * Marks all request handlers that respond using `res.once()` as unused.
@@ -231,14 +229,16 @@ export interface SetupWorker {
    *
    * @see {@link https://mswjs.io/docs/api/setup-worker/reset-handlers `worker.resetHandlers()` API reference}
    */
-  resetHandlers: (...nextHandlers: RequestHandler[]) => void
+  resetHandlers: (
+    ...nextHandlers: Array<RequestHandler | WebSocketHandler>
+  ) => void
 
   /**
    * Returns a readonly list of currently active request handlers.
    *
    * @see {@link https://mswjs.io/docs/api/setup-worker/list-handlers `worker.listHandlers()` API reference}
    */
-  listHandlers(): ReadonlyArray<RequestHandler<RequestHandlerDefaultInfo, any>>
+  listHandlers(): ReadonlyArray<RequestHandler | WebSocketHandler>
 
   /**
    * Life-cycle events.

package/src/browser/setupWorker/setupWorker.ts

@@ -18,9 +18,13 @@ import { createFallbackStop } from './stop/createFallbackStop'
 import { devUtils } from '~/core/utils/internal/devUtils'
 import { SetupApi } from '~/core/SetupApi'
 import { mergeRight } from '~/core/utils/internal/mergeRight'
-import { LifeCycleEventsMap } from '~/core/sharedOptions'
+import type { LifeCycleEventsMap } from '~/core/sharedOptions'
+import type { WebSocketHandler } from '~/core/handlers/WebSocketHandler'
 import { SetupWorker } from './glossary'
 import { supportsReadableStreamTransfer } from '../utils/supportsReadableStreamTransfer'
+import { webSocketInterceptor } from '~/core/ws/webSocketInterceptor'
+import { handleWebSocketEvent } from '~/core/ws/handleWebSocketEvent'
+import { attachWebSocketLogger } from '~/core/ws/utils/attachWebSocketLogger'
 
 interface Listener {
   target: EventTarget
@@ -37,7 +41,7 @@ export class SetupWorkerApi
   private stopHandler: StopHandler = null as any
   private listeners: Array<Listener>
 
-  constructor(...handlers: Array<RequestHandler>) {
+  constructor(...handlers: Array<RequestHandler | WebSocketHandler>) {
     super(...handlers)
 
     invariant(
@@ -176,6 +180,29 @@ export class SetupWorkerApi
       options,
     ) as SetupWorkerInternalContext['startOptions']
 
+    // Enable the WebSocket interception.
+    handleWebSocketEvent({
+      getUnhandledRequestStrategy: () => {
+        return this.context.startOptions.onUnhandledRequest
+      },
+      getHandlers: () => {
+        return this.handlersController.currentHandlers()
+      },
+      onMockedConnection: (connection) => {
+        if (!this.context.startOptions.quiet) {
+          // Attach the logger for mocked connections since
+          // those won't be visible in the browser's devtools.
+          attachWebSocketLogger(connection)
+        }
+      },
+      onPassthroughConnection() {},
+    })
+    webSocketInterceptor.apply()
+
+    this.subscriptions.push(() => {
+      webSocketInterceptor.dispose()
+    })
+
     return await this.startHandler(this.context.startOptions, options)
   }
 
@@ -193,6 +220,8 @@ export class SetupWorkerApi
  *
  * @see {@link https://mswjs.io/docs/api/setup-worker `setupWorker()` API reference}
  */
-export function setupWorker(...handlers: Array<RequestHandler>): SetupWorker {
+export function setupWorker(
+  ...handlers: Array<RequestHandler | WebSocketHandler>
+): SetupWorker {
   return new SetupWorkerApi(...handlers)
 }

package/src/browser/setupWorker/start/createRequestListener.ts

@@ -9,6 +9,8 @@ import {
 } from './utils/createMessageChannel'
 import { parseWorkerRequest } from '../../utils/parseWorkerRequest'
 import { RequestHandler } from '~/core/handlers/RequestHandler'
+import { HttpHandler } from '~/core/handlers/HttpHandler'
+import { GraphQLHandler } from '~/core/handlers/GraphQLHandler'
 import { handleRequest } from '~/core/utils/handleRequest'
 import { RequiredDeep } from '~/core/typeUtils'
 import { devUtils } from '~/core/utils/internal/devUtils'
@@ -43,7 +45,11 @@ export const createRequestListener = (
       await handleRequest(
         request,
         requestId,
-        context.getRequestHandlers(),
+        context.getRequestHandlers().filter((handler) => {
+          return (
+            handler instanceof HttpHandler || handler instanceof GraphQLHandler
+          )
+        }),
         options,
         context.emitter,
         {

package/src/browser/setupWorker/start/createStartHandler.ts

@@ -71,6 +71,11 @@ Please consider using a custom "serviceWorker.url" option to point to the actual
         // Make sure we're always clearing the interval - there are reports that not doing this can
         // cause memory leaks in headless browser environments.
         window.clearInterval(context.keepAliveInterval)
+
+        // Notify others about this client disconnecting.
+        // E.g. this will purge the in-memory WebSocket clients since
+        // starting the worker again will assign them new IDs.
+        window.postMessage({ type: 'msw/worker:stop' })
       })
 
       // Check if the active Service Worker has been generated

package/src/browser/setupWorker/stop/createStop.ts

@@ -24,6 +24,12 @@ export const createStop = (
     context.isMockingEnabled = false
     window.clearInterval(context.keepAliveInterval)
 
+    // Post the internal stop message on the window
+    // to let any logic know when the worker has stopped.
+    // E.g. the WebSocket client manager needs this to know
+    // when to clear its in-memory clients list.
+    window.postMessage({ type: 'msw/worker:stop' })
+
     printStopMessage({ quiet: context.startOptions?.quiet })
   }
 }

package/src/core/SetupApi.ts

@@ -1,38 +1,42 @@
 import { invariant } from 'outvariant'
 import { EventMap, Emitter } from 'strict-event-emitter'
-import {
-  RequestHandler,
-  RequestHandlerDefaultInfo,
-} from './handlers/RequestHandler'
+import { RequestHandler } from './handlers/RequestHandler'
 import { LifeCycleEventEmitter } from './sharedOptions'
 import { devUtils } from './utils/internal/devUtils'
 import { pipeEvents } from './utils/internal/pipeEvents'
 import { toReadonlyArray } from './utils/internal/toReadonlyArray'
 import { Disposable } from './utils/internal/Disposable'
+import type { WebSocketHandler } from './handlers/WebSocketHandler'
 
 export abstract class HandlersController {
-  abstract prepend(runtimeHandlers: Array<RequestHandler>): void
-  abstract reset(nextHandles: Array<RequestHandler>): void
-  abstract currentHandlers(): Array<RequestHandler>
+  abstract prepend(
+    runtimeHandlers: Array<RequestHandler | WebSocketHandler>,
+  ): void
+  abstract reset(nextHandles: Array<RequestHandler | WebSocketHandler>): void
+  abstract currentHandlers(): Array<RequestHandler | WebSocketHandler>
 }
 
 export class InMemoryHandlersController implements HandlersController {
-  private handlers: Array<RequestHandler>
+  private handlers: Array<RequestHandler | WebSocketHandler>
 
-  constructor(private initialHandlers: Array<RequestHandler>) {
+  constructor(
+    private initialHandlers: Array<RequestHandler | WebSocketHandler>,
+  ) {
     this.handlers = [...initialHandlers]
   }
 
-  public prepend(runtimeHandles: Array<RequestHandler>): void {
+  public prepend(
+    runtimeHandles: Array<RequestHandler | WebSocketHandler>,
+  ): void {
     this.handlers.unshift(...runtimeHandles)
   }
 
-  public reset(nextHandlers: Array<RequestHandler>): void {
+  public reset(nextHandlers: Array<RequestHandler | WebSocketHandler>): void {
     this.handlers =
       nextHandlers.length > 0 ? [...nextHandlers] : [...this.initialHandlers]
   }
 
-  public currentHandlers(): Array<RequestHandler> {
+  public currentHandlers(): Array<RequestHandler | WebSocketHandler> {
     return this.handlers
   }
 }
@@ -47,7 +51,7 @@ export abstract class SetupApi<EventsMap extends EventMap> extends Disposable {
 
   public readonly events: LifeCycleEventEmitter<EventsMap>
 
-  constructor(...initialHandlers: Array<RequestHandler>) {
+  constructor(...initialHandlers: Array<RequestHandler | WebSocketHandler>) {
     super()
 
     invariant(
@@ -71,12 +75,14 @@ export abstract class SetupApi<EventsMap extends EventMap> extends Disposable {
     })
   }
 
-  private validateHandlers(handlers: ReadonlyArray<RequestHandler>): boolean {
+  private validateHandlers(handlers: ReadonlyArray<unknown>): boolean {
     // Guard against incorrect call signature of the setup API.
     return handlers.every((handler) => !Array.isArray(handler))
   }
 
-  public use(...runtimeHandlers: Array<RequestHandler>): void {
+  public use(
+    ...runtimeHandlers: Array<RequestHandler | WebSocketHandler>
+  ): void {
     invariant(
       this.validateHandlers(runtimeHandlers),
       devUtils.formatMessage(
@@ -89,17 +95,19 @@ export abstract class SetupApi<EventsMap extends EventMap> extends Disposable {
 
   public restoreHandlers(): void {
     this.handlersController.currentHandlers().forEach((handler) => {
-      handler.isUsed = false
+      if ('isUsed' in handler) {
+        handler.isUsed = false
+      }
     })
   }
 
-  public resetHandlers(...nextHandlers: Array<RequestHandler>): void {
+  public resetHandlers(
+    ...nextHandlers: Array<RequestHandler | WebSocketHandler>
+  ): void {
     this.handlersController.reset(nextHandlers)
   }
 
-  public listHandlers(): ReadonlyArray<
-    RequestHandler<RequestHandlerDefaultInfo, any, any>
-  > {
+  public listHandlers(): ReadonlyArray<RequestHandler | WebSocketHandler> {
     return toReadonlyArray(this.handlersController.currentHandlers())
   }
 

package/src/core/handlers/WebSocketHandler.ts

@@ -0,0 +1,142 @@
+import { Emitter } from 'strict-event-emitter'
+import { createRequestId } from '@mswjs/interceptors'
+import type { WebSocketConnectionData } from '@mswjs/interceptors/WebSocket'
+import {
+  type Match,
+  type Path,
+  type PathParams,
+  matchRequestUrl,
+} from '../utils/matching/matchRequestUrl'
+import { getCallFrame } from '../utils/internal/getCallFrame'
+
+type WebSocketHandlerParsedResult = {
+  match: Match
+}
+
+export type WebSocketHandlerEventMap = {
+  connection: [args: WebSocketHandlerConnection]
+}
+
+export interface WebSocketHandlerConnection extends WebSocketConnectionData {
+  params: PathParams
+}
+
+export const kEmitter = Symbol('kEmitter')
+export const kDispatchEvent = Symbol('kDispatchEvent')
+export const kSender = Symbol('kSender')
+const kStopPropagationPatched = Symbol('kStopPropagationPatched')
+const KOnStopPropagation = Symbol('KOnStopPropagation')
+
+export class WebSocketHandler {
+  public id: string
+  public callFrame?: string
+
+  protected [kEmitter]: Emitter<WebSocketHandlerEventMap>
+
+  constructor(private readonly url: Path) {
+    this.id = createRequestId()
+
+    this[kEmitter] = new Emitter()
+    this.callFrame = getCallFrame(new Error())
+  }
+
+  public parse(args: {
+    event: MessageEvent<WebSocketConnectionData>
+  }): WebSocketHandlerParsedResult {
+    const connection = args.event.data
+    const match = matchRequestUrl(connection.client.url, this.url)
+
+    return {
+      match,
+    }
+  }
+
+  public predicate(args: {
+    event: MessageEvent<WebSocketConnectionData>
+    parsedResult: WebSocketHandlerParsedResult
+  }): boolean {
+    return args.parsedResult.match.matches
+  }
+
+  async [kDispatchEvent](
+    event: MessageEvent<WebSocketConnectionData>,
+  ): Promise<void> {
+    const parsedResult = this.parse({ event })
+    const connection = event.data
+
+    const resolvedConnection: WebSocketHandlerConnection = {
+      ...connection,
+      params: parsedResult.match.params || {},
+    }
+
+    // Support `event.stopPropagation()` for various client/server events.
+    connection.client.addEventListener(
+      'message',
+      createStopPropagationListener(this),
+    )
+    connection.client.addEventListener(
+      'close',
+      createStopPropagationListener(this),
+    )
+
+    connection.server.addEventListener(
+      'open',
+      createStopPropagationListener(this),
+    )
+    connection.server.addEventListener(
+      'message',
+      createStopPropagationListener(this),
+    )
+    connection.server.addEventListener(
+      'error',
+      createStopPropagationListener(this),
+    )
+    connection.server.addEventListener(
+      'close',
+      createStopPropagationListener(this),
+    )
+
+    // Emit the connection event on the handler.
+    // This is what the developer adds listeners for.
+    this[kEmitter].emit('connection', resolvedConnection)
+  }
+}
+
+function createStopPropagationListener(handler: WebSocketHandler) {
+  return function stopPropagationListener(event: Event) {
+    const propagationStoppedAt = Reflect.get(event, 'kPropagationStoppedAt') as
+      | string
+      | undefined
+
+    if (propagationStoppedAt && handler.id !== propagationStoppedAt) {
+      event.stopImmediatePropagation()
+      return
+    }
+
+    Object.defineProperty(event, KOnStopPropagation, {
+      value(this: WebSocketHandler) {
+        Object.defineProperty(event, 'kPropagationStoppedAt', {
+          value: handler.id,
+        })
+      },
+      configurable: true,
+    })
+
+    // Since the same event instance is shared between all client/server objects,
+    // make sure to patch its `stopPropagation` method only once.
+    if (!Reflect.get(event, kStopPropagationPatched)) {
+      event.stopPropagation = new Proxy(event.stopPropagation, {
+        apply: (target, thisArg, args) => {
+          Reflect.get(event, KOnStopPropagation)?.call(handler)
+          return Reflect.apply(target, thisArg, args)
+        },
+      })
+
+      Object.defineProperty(event, kStopPropagationPatched, {
+        value: true,
+        // If something else attempts to redefine this, throw.
+        configurable: false,
+      })
+    }
+  }
+}

package/src/core/index.ts

@@ -2,13 +2,21 @@ import { checkGlobals } from './utils/internal/checkGlobals'
 
 export { SetupApi } from './SetupApi'
 
-/* Request handlers */
+/* HTTP handlers */
 export { RequestHandler } from './handlers/RequestHandler'
 export { http } from './http'
 export { HttpHandler, HttpMethods } from './handlers/HttpHandler'
 export { graphql } from './graphql'
 export { GraphQLHandler } from './handlers/GraphQLHandler'
 
+/* WebSocket handler */
+export { ws, type WebSocketLink } from './ws'
+export {
+  WebSocketHandler,
+  type WebSocketHandlerEventMap,
+  type WebSocketHandlerConnection,
+} from './handlers/WebSocketHandler'
+
 /* Utils */
 export { matchRequestUrl } from './utils/matching/matchRequestUrl'
 export * from './utils/handleRequest'
@@ -45,6 +53,8 @@ export type {
 } from './handlers/GraphQLHandler'
 export type { GraphQLRequestHandler, GraphQLResponseResolver } from './graphql'
 
+export type { WebSocketData, WebSocketEventListener } from './ws'
+
 export type { Path, PathParams, Match } from './utils/matching/matchRequestUrl'
 export type { ParsedGraphQLRequest } from './utils/internal/parseGraphQLRequest'
 

package/src/core/utils/executeHandlers.ts

@@ -1,6 +1,6 @@
 import {
   RequestHandler,
-  RequestHandlerExecutionResult,
+  type RequestHandlerExecutionResult,
 } from '../handlers/RequestHandler'
 
 export interface HandlersExecutionResult {
@@ -18,7 +18,7 @@ export interface ResponseResolutionContext {
  * Returns the execution result object containing any matching request
  * handler and any mocked response it returned.
  */
-export const executeHandlers = async <Handlers extends Array<RequestHandler>>({
+export const executeHandlers = async <Handlers extends Array<unknown>>({
   request,
   requestId,
   handlers,
@@ -33,6 +33,10 @@ export const executeHandlers = async <Handlers extends Array<RequestHandler>>({
   let result: RequestHandlerExecutionResult<any> | null = null
 
   for (const handler of handlers) {
+    if (!(handler instanceof RequestHandler)) {
+      continue
+    }
+
     result = await handler.run({ request, requestId, resolutionContext })
 
     // If the handler produces some result for this request,

package/src/core/utils/handleRequest.ts

@@ -1,8 +1,8 @@
 import { until } from '@open-draft/until'
 import { Emitter } from 'strict-event-emitter'
-import { RequestHandler } from '../handlers/RequestHandler'
 import { LifeCycleEventsMap, SharedOptions } from '../sharedOptions'
 import { RequiredDeep } from '../typeUtils'
+import type { RequestHandler } from '../handlers/RequestHandler'
 import { HandlersExecutionResult, executeHandlers } from './executeHandlers'
 import { onUnhandledRequest } from './request/onUnhandledRequest'
 import { storeResponseCookies } from './request/storeResponseCookies'

package/src/core/utils/logging/getTimestamp.test.ts

@@ -1,18 +1,32 @@
 import { getTimestamp } from './getTimestamp'
 
 beforeAll(() => {
-  // Stub native `Date` prototype methods used in the tested module,
-  // to always produce a predictable value for testing purposes.
-  vi.spyOn(global.Date.prototype, 'getHours').mockImplementation(() => 12)
-  vi.spyOn(global.Date.prototype, 'getMinutes').mockImplementation(() => 4)
-  vi.spyOn(global.Date.prototype, 'getSeconds').mockImplementation(() => 8)
+  vi.useFakeTimers()
 })
 
 afterAll(() => {
-  vi.restoreAllMocks()
+  vi.useRealTimers()
 })
 
 test('returns a timestamp string of the invocation time', () => {
+  vi.setSystemTime(new Date('2024-01-01 12:4:8'))
   const timestamp = getTimestamp()
   expect(timestamp).toBe('12:04:08')
 })
+
+test('returns a timestamp with milliseconds', () => {
+  vi.setSystemTime(new Date('2024-01-01 12:4:8'))
+  expect(getTimestamp({ milliseconds: true })).toBe('12:04:08.000')
+
+  vi.setSystemTime(new Date('2024-01-01 12:4:8.000'))
+  expect(getTimestamp({ milliseconds: true })).toBe('12:04:08.000')
+
+  vi.setSystemTime(new Date('2024-01-01 12:4:8.4'))
+  expect(getTimestamp({ milliseconds: true })).toBe('12:04:08.400')
+
+  vi.setSystemTime(new Date('2024-01-01 12:4:8.123'))
+  expect(getTimestamp({ milliseconds: true })).toBe('12:04:08.123')
+
+  vi.setSystemTime(new Date('2024-01-01 12:00:00'))
+  expect(getTimestamp({ milliseconds: true })).toBe('12:00:00.000')
+})

package/src/core/utils/logging/getTimestamp.ts

@@ -1,12 +1,17 @@
+interface GetTimestampOptions {
+  milliseconds?: boolean
+}
+
 /**
  * Returns a timestamp string in a "HH:MM:SS" format.
  */
-export function getTimestamp(): string {
+export function getTimestamp(options?: GetTimestampOptions): string {
   const now = new Date()
+  const timestamp = `${now.getHours().toString().padStart(2, '0')}:${now.getMinutes().toString().padStart(2, '0')}:${now.getSeconds().toString().padStart(2, '0')}`
+
+  if (options?.milliseconds) {
+    return `${timestamp}.${now.getMilliseconds().toString().padStart(3, '0')}`
+  }
 
-  return [now.getHours(), now.getMinutes(), now.getSeconds()]
-    .map(String)
-    .map((chunk) => chunk.slice(0, 2))
-    .map((chunk) => chunk.padStart(2, '0'))
-    .join(':')
+  return timestamp
 }

package/src/core/utils/matching/matchRequestUrl.test.ts

@@ -72,6 +72,50 @@ describe('matchRequestUrl', () => {
       userId: undefined,
     })
   })
+
+  test('returns true for matching WebSocket URL', () => {
+    expect(
+      matchRequestUrl(new URL('ws://test.mswjs.io'), 'ws://test.mswjs.io'),
+    ).toEqual({
+      matches: true,
+      params: {},
+    })
+    expect(
+      matchRequestUrl(new URL('wss://test.mswjs.io'), 'wss://test.mswjs.io'),
+    ).toEqual({
+      matches: true,
+      params: {},
+    })
+  })
+
+  test('returns false for non-matching WebSocket URL', () => {
+    expect(
+      matchRequestUrl(new URL('ws://test.mswjs.io'), 'ws://foo.mswjs.io'),
+    ).toEqual({
+      matches: false,
+      params: {},
+    })
+    expect(
+      matchRequestUrl(new URL('wss://test.mswjs.io'), 'wss://completely.diff'),
+    ).toEqual({
+      matches: false,
+      params: {},
+    })
+  })
+
+  test('returns path parameters when matched a WebSocket URL', () => {
+    expect(
+      matchRequestUrl(
+        new URL('wss://test.mswjs.io'),
+        'wss://:service.mswjs.io',
+      ),
+    ).toEqual({
+      matches: true,
+      params: {
+        service: 'test',
+      },
+    })
+  })
 })
 
 describe('coercePath', () => {

package/src/core/utils/matching/matchRequestUrl.ts

@@ -71,3 +71,7 @@ export function matchRequestUrl(url: URL, path: Path, baseUrl?: string): Match {
     params,
   }
 }
+
+export function isPath(value: unknown): value is Path {
+  return typeof value === 'string' || value instanceof RegExp
+}