fix(WebSocket): resolve relative connection urls (#763)

Author: kettanaito

.github/workflows/compat.yml

@@ -22,7 +22,6 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 22
-          cache: 'pnpm'
 
       - name: Install dependencies
         run: pnpm install

src/interceptors/WebSocket/WebSocketClientConnection.ts

@@ -19,15 +19,15 @@ export abstract class WebSocketClientConnectionProtocol {
   public abstract close(code?: number, reason?: string): void
 
   public abstract addEventListener<
-    EventType extends keyof WebSocketClientEventMap
+    EventType extends keyof WebSocketClientEventMap,
   >(
     type: EventType,
     listener: WebSocketEventListener<WebSocketClientEventMap[EventType]>,
     options?: AddEventListenerOptions | boolean
   ): void
 
   public abstract removeEventListener<
-    EventType extends keyof WebSocketClientEventMap
+    EventType extends keyof WebSocketClientEventMap,
   >(
     event: EventType,
     listener: WebSocketEventListener<WebSocketClientEventMap[EventType]>,
@@ -40,9 +40,7 @@ export abstract class WebSocketClientConnectionProtocol {
  * client connection. The user can control the connection,
  * send and receive events.
  */
-export class WebSocketClientConnection
-  implements WebSocketClientConnectionProtocol
-{
+export class WebSocketClientConnection implements WebSocketClientConnectionProtocol {
   public readonly id: string
   public readonly url: URL
 

src/interceptors/WebSocket/WebSocketOverride.ts

@@ -1,11 +1,11 @@
 import { invariant } from 'outvariant'
+import { DeferredPromise } from '@open-draft/deferred-promise'
 import type { WebSocketData } from './WebSocketTransport'
 import { bindEvent } from './utils/bindEvent'
 import { CloseEvent } from './utils/events'
-import { DeferredPromise } from '@open-draft/deferred-promise'
 
 export type WebSocketEventListener<
-  EventType extends WebSocketEventMap[keyof WebSocketEventMap] = Event
+  EventType extends WebSocketEventMap[keyof WebSocketEventMap] = Event,
 > = (this: WebSocket, event: EventType) => void
 
 const WEBSOCKET_CLOSE_CODE_RANGE_ERROR =
@@ -44,7 +44,7 @@ export class WebSocketOverride extends EventTarget implements WebSocket {
 
   constructor(url: string | URL, protocols?: string | Array<string>) {
     super()
-    this.url = url.toString()
+    this.url = resolveWebSocketUrl(url)
     this.protocol = ''
     this.extensions = ''
     this.binaryType = 'blob'
@@ -62,8 +62,8 @@ export class WebSocketOverride extends EventTarget implements WebSocket {
         typeof protocols === 'string'
           ? protocols
           : Array.isArray(protocols) && protocols.length > 0
-          ? protocols[0]
-          : ''
+            ? protocols[0]
+            : ''
 
       /**
        * @note Check that nothing has prevented this connection
@@ -249,3 +249,49 @@ function getDataSize(data: WebSocketData): number {
 
   return data.byteLength
 }
+
+/**
+ * Resolve potentially relative WebSocket URLs the same way
+ * the browser does (replace the protocol, use the origin, etc).
+ *
+ * @see https://websockets.spec.whatwg.org//#dom-websocket-websocket
+ */
+function resolveWebSocketUrl(url: string | URL): string {
+  if (typeof url === 'string') {
+    /**
+     * @note Cast the string to a URL first so the parsing errors
+     * are thrown as a part of the WebSocket constructor, not consumers.
+     */
+    const urlRecord = new URL(
+      url,
+      typeof location !== 'undefined' ? location.href : undefined
+    )
+
+    return resolveWebSocketUrl(urlRecord)
+  }
+
+  if (url.protocol === 'http:') {
+    url.protocol = 'ws:'
+  } else if (url.protocol === 'https:') {
+    url.protocol = 'wss:'
+  }
+
+  if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
+    /**
+     * @note These errors are modeled after the browser errors.
+     * The exact error messages aren't provided in the specification.
+     * Node.js uses more obscure error messages that I don't wish to replicate.
+     */
+    throw new SyntaxError(
+      `Failed to construct 'WebSocket': The URL's scheme must be either 'http', 'https', 'ws', or 'wss'. '${url.protocol}' is not allowed.`
+    )
+  }
+
+  if (url.hash !== '') {
+    throw new SyntaxError(
+      `Failed to construct 'WebSocket': The URL contains a fragment identifier ('${url.hash}'). Fragment identifiers are not allowed in WebSocket URLs.`
+    )
+  }
+
+  return url.href
+}

src/interceptors/WebSocket/WebSocketServerConnection.ts

@@ -30,15 +30,15 @@ export abstract class WebSocketServerConnectionProtocol {
   public abstract close(): void
 
   public abstract addEventListener<
-    EventType extends keyof WebSocketServerEventMap
+    EventType extends keyof WebSocketServerEventMap,
   >(
     event: EventType,
     listener: WebSocketEventListener<WebSocketServerEventMap[EventType]>,
     options?: AddEventListenerOptions | boolean
   ): void
 
   public abstract removeEventListener<
-    EventType extends keyof WebSocketServerEventMap
+    EventType extends keyof WebSocketServerEventMap,
   >(
     event: EventType,
     listener: WebSocketEventListener<WebSocketServerEventMap[EventType]>,
@@ -51,9 +51,7 @@ export abstract class WebSocketServerConnectionProtocol {
  * WebSocket server connection. It's idle by default but you can
  * establish it by calling `server.connect()`.
  */
-export class WebSocketServerConnection
-  implements WebSocketServerConnectionProtocol
-{
+export class WebSocketServerConnection implements WebSocketServerConnectionProtocol {
   /**
    * A WebSocket instance connected to the original server.
    */

test/modules/WebSocket/compliance/websocket.constructor.browser.test.ts

@@ -0,0 +1,124 @@
+import { test, expect } from '../../../playwright.extend'
+
+test('uses the "ws" scheme as-is', async ({ loadExample, page }) => {
+  await loadExample(require.resolve('../websocket.runtime.js'))
+
+  await page.evaluate(() => {
+    const { interceptor } = window
+
+    interceptor.apply()
+    interceptor.on('connection', () => {})
+  })
+
+  const url = await page.evaluate(() => {
+    return new WebSocket('ws://localhost:5678/api').url
+  })
+
+  expect(url).toBe('ws://localhost:5678/api')
+})
+
+test('uses the "wss" scheme as-is', async ({ loadExample, page }) => {
+  await loadExample(require.resolve('../websocket.runtime.js'))
+
+  await page.evaluate(() => {
+    const { interceptor } = window
+
+    interceptor.apply()
+    interceptor.on('connection', () => {})
+  })
+
+  const url = await page.evaluate(() => {
+    return new WebSocket('wss://localhost:5678/api').url
+  })
+
+  expect(url).toBe('wss://localhost:5678/api')
+})
+
+test('replaces the "http" scheme with "ws"', async ({ loadExample, page }) => {
+  await loadExample(require.resolve('../websocket.runtime.js'))
+
+  await page.evaluate(() => {
+    const { interceptor } = window
+
+    interceptor.apply()
+    interceptor.on('connection', () => {})
+  })
+
+  const url = await page.evaluate(() => {
+    return new WebSocket('http://localhost:5678/api').url
+  })
+
+  expect(url).toBe('ws://localhost:5678/api')
+})
+
+test('replaces the "https" scheme with "wss"', async ({
+  loadExample,
+  page,
+}) => {
+  await loadExample(require.resolve('../websocket.runtime.js'))
+
+  await page.evaluate(() => {
+    const { interceptor } = window
+
+    interceptor.apply()
+    interceptor.on('connection', () => {})
+  })
+
+  const url = await page.evaluate(() => {
+    return new WebSocket('https://localhost:5678/api').url
+  })
+
+  expect(url).toBe('wss://localhost:5678/api')
+})
+
+test('throws an error on not allowed schemes', async ({
+  loadExample,
+  page,
+}) => {
+  await loadExample(require.resolve('../websocket.runtime.js'))
+
+  await page.evaluate(() => {
+    const { interceptor } = window
+
+    interceptor.apply()
+    interceptor.on('connection', () => {})
+  })
+
+  const constructorError = await page.evaluate(() => {
+    try {
+      new WebSocket('invalid-protocol://localhost').url
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        return error.message
+      }
+
+      throw new Error(`Thrown error is not a SyntaxError`)
+    }
+  })
+
+  expect(constructorError).toBe(
+    `Failed to construct 'WebSocket': The URL's scheme must be either 'http', 'https', 'ws', or 'wss'. 'invalid-protocol:' is not allowed.`
+  )
+})
+
+test('resolves a relative WebSocket URL against location', async ({
+  loadExample,
+  page,
+}) => {
+  const { previewUrl } = await loadExample(
+    require.resolve('../websocket.runtime.js')
+  )
+
+  await page.evaluate(() => {
+    const { interceptor } = window
+
+    interceptor.apply()
+    interceptor.on('connection', () => {})
+  })
+
+  const url = await page.evaluate(() => {
+    return new WebSocket('/api').url
+  })
+
+  expect(url).toBe(`ws://${new URL(previewUrl).host}/api`)
+})

test/modules/WebSocket/compliance/websocket.constructor.test.ts

@@ -0,0 +1,86 @@
+/**
+ * @vitest-environment node-with-websocket
+ * @see https://websockets.spec.whatwg.org//#dom-websocket-websocket
+ */
+import { it, expect, beforeAll, afterAll } from 'vitest'
+import { WebSocketInterceptor } from '../../../../src/interceptors/WebSocket'
+
+const interceptor = new WebSocketInterceptor()
+
+beforeAll(() => {
+  interceptor.apply()
+})
+
+afterAll(() => {
+  interceptor.dispose()
+})
+
+it('uses the "ws" scheme as-is', () => {
+  expect(new WebSocket('ws://localhost:5678/api').url).toBe(
+    'ws://localhost:5678/api'
+  )
+})
+
+it('uses the "wss" scheme as-is', () => {
+  expect(new WebSocket('wss://localhost:5678/api').url).toBe(
+    'wss://localhost:5678/api'
+  )
+})
+
+it('replaces the "http" scheme with "ws"', () => {
+  expect(new WebSocket('http://localhost:5678/api').url).toBe(
+    'ws://localhost:5678/api'
+  )
+})
+
+it('replaces the "https" scheme with "wss"', () => {
+  expect(new WebSocket('https://localhost:5678/api').url).toBe(
+    'wss://localhost:5678/api'
+  )
+})
+
+it('throws an error on not allowed schemes', () => {
+  expect(() => new WebSocket('invalid-protocol://localhost')).toThrow(
+    expect.objectContaining({
+      name: 'SyntaxError',
+      message: `Failed to construct 'WebSocket': The URL's scheme must be either 'http', 'https', 'ws', or 'wss'. 'invalid-protocol:' is not allowed.`,
+    })
+  )
+})
+
+it('throws on a relative URL in Node.js', () => {
+  expect(() => new WebSocket('/not-allowed')).toThrow(
+    expect.objectContaining({
+      name: 'TypeError',
+      code: 'ERR_INVALID_URL',
+      message: 'Invalid URL',
+    })
+  )
+})
+
+it('ensures trailing slash where appropriate', () => {
+  expect(new WebSocket('wss://localhost:5678').url).toBe(
+    'wss://localhost:5678/'
+  )
+  expect(new WebSocket('wss://localhost:5678/').url).toBe(
+    'wss://localhost:5678/'
+  )
+
+  expect(new WebSocket('wss://127.0.0.1:5678').url).toBe(
+    'wss://127.0.0.1:5678/'
+  )
+  expect(new WebSocket('wss://127.0.0.1:5678/').url).toBe(
+    'wss://127.0.0.1:5678/'
+  )
+
+  expect(new WebSocket('wss://non-existing.com').url).toBe(
+    'wss://non-existing.com/'
+  )
+  expect(new WebSocket('wss://non-existing.com/').url).toBe(
+    'wss://non-existing.com/'
+  )
+
+  expect(new WebSocket('wss://localhost:5678/foo').url).toBe(
+    'wss://localhost:5678/foo'
+  )
+})

test/modules/WebSocket/compliance/websocket.default.test.ts

@@ -33,7 +33,7 @@ it('sets the instance ready state properties', () => {
 it('sets the "url" property to the passed URL', () => {
   expect(new WebSocket('wss://example.com')).toHaveProperty(
     'url',
-    'wss://example.com'
+    'wss://example.com/'
   )
   expect(new WebSocket(new URL('wss://example.com'))).toHaveProperty(
     'url',
@@ -42,7 +42,7 @@ it('sets the "url" property to the passed URL', () => {
 
   expect(new WebSocket('ws://example.com')).toHaveProperty(
     'url',
-    'ws://example.com'
+    'ws://example.com/'
   )
   expect(new WebSocket(new URL('ws://example.com'))).toHaveProperty(
     'url',

test/modules/WebSocket/compliance/websocket.events.test.ts

@@ -108,7 +108,7 @@ it('emits "message" event on incoming original server data', async () => {
   expect(messageEvent.data).toBe('hello')
   expect(messageEvent.target).toBe(ws)
   expect(messageEvent.currentTarget).toBe(ws)
-  expect(messageEvent.origin).toBe(ws.url)
+  expect(messageEvent.origin + '/').toBe(ws.url)
 })
 
 it('emits "close" event when the mocked client closes the connection', async () => {

test/modules/WebSocket/compliance/websocket.server.close.test.ts

@@ -41,7 +41,7 @@ it('throws if closing the unconnected server', async () => {
   const server = await serverPromise
 
   expect(() => server.close()).toThrow(
-    `Failed to close server connection for "wss://example.com": the connection is not open. Did you forget to call "server.connect()"?`
+    `Failed to close server connection for "wss://example.com/": the connection is not open. Did you forget to call "server.connect()"?`
   )
 })