feat: treat unhandled exceptions in handlers as 500 error responses

package.json

@@ -137,7 +137,7 @@
     "@bundled-es-modules/statuses": "^1.0.1",
     "@inquirer/confirm": "^3.0.0",
     "@mswjs/cookies": "^1.1.0",
-    "@mswjs/interceptors": "^0.26.14",
+    "@mswjs/interceptors": "^0.29.0",
     "@open-draft/until": "^2.1.0",
     "@types/cookie": "^0.6.0",
     "@types/statuses": "^2.0.4",

src/core/utils/internal/devUtils.test.ts

@@ -0,0 +1,21 @@
+import { InternalError } from './devUtils'
+
+describe(InternalError, () => {
+  it('creates an InternalError instance', () => {
+    const error = new InternalError('Message')
+
+    expect(error.name).toBe('InternalError')
+    expect(error.message).toBe('Message')
+    expect(error.toString()).toBe('InternalError: Message')
+    expect(error.stack).toMatch(/\w+/)
+  })
+
+  it('passes the identity check', () => {
+    const error = new InternalError('Message')
+    expect(error instanceof InternalError).toBe(true)
+    expect(error instanceof Error).toBe(true)
+
+    const extraneousError = new Error('Message')
+    expect(extraneousError).not.toBeInstanceOf(InternalError)
+  })
+})

src/core/utils/internal/devUtils.ts

@@ -29,3 +29,16 @@ export const devUtils = {
   warn,
   error,
 }
+
+/**
+ * Internal error instance.
+ * Used to differentiate the library errors that must be forwarded
+ * to the user from the unhandled exceptions. Use this if you don't
+ * wish for the error to be coerced to a 500 fallback response.
+ */
+export class InternalError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'InternalError'
+  }
+}

src/core/utils/request/onUnhandledRequest.ts

@@ -1,5 +1,5 @@
 import { toPublicUrl } from './toPublicUrl'
-import { devUtils } from '../internal/devUtils'
+import { InternalError, devUtils } from '../internal/devUtils'
 
 export interface UnhandledRequestPrint {
   warning(): void
@@ -33,7 +33,7 @@ export async function onUnhandledRequest(
         devUtils.error('Error: %s', unhandledRequestMessage)
 
         // Throw an exception to halt request processing and not perform the original request.
-        throw new Error(
+        throw new InternalError(
           devUtils.formatMessage(
             'Cannot bypass a request when using the "error" strategy for the "onUnhandledRequest" option.',
           ),
@@ -49,7 +49,7 @@ export async function onUnhandledRequest(
         break
 
       default:
-        throw new Error(
+        throw new InternalError(
           devUtils.formatMessage(
             'Failed to react to an unhandled request: unknown strategy "%s". Please provide one of the supported strategies ("bypass", "warn", "error") or a custom callback function as the value of the "onUnhandledRequest" option.',
             strategy,

src/node/SetupServerCommonApi.ts

@@ -15,7 +15,7 @@ import { SetupApi } from '~/core/SetupApi'
 import { handleRequest } from '~/core/utils/handleRequest'
 import type { RequestHandler } from '~/core/handlers/RequestHandler'
 import { mergeRight } from '~/core/utils/internal/mergeRight'
-import { devUtils } from '~/core/utils/internal/devUtils'
+import { InternalError, devUtils } from '~/core/utils/internal/devUtils'
 import type { SetupServerCommon } from './glossary'
 
 export const DEFAULT_LISTEN_OPTIONS: RequiredDeep<SharedOptions> = {
@@ -68,6 +68,12 @@ export class SetupServerCommonApi
       return
     })
 
+    this.interceptor.on('unhandledException', ({ error }) => {
+      if (error instanceof InternalError) {
+        throw error
+      }
+    })
+
     this.interceptor.on(
       'response',
       ({ response, isMockedResponse, request, requestId }) => {