Feature: Support for namespaces

README.md

@@ -30,9 +30,42 @@ interceptor.on('connection', (connection) => {
 
 > You can also use this package with [Mock Service Worker](https://github.com/mswjs/msw) directly.
 
+
+### Namespaces
+
+Every message delivered through the wrapper carries the namespace that it was sent on. Access it via `event.socketio.namespace` to make assertions or branch per namespace during tests:
+
+```js
+io.client.on('power_on', (event, deviceId) => {
+  if (event.socketio.namespace === '/bedroom/ceiling_fan') {
+    console.log('fan turned on:', deviceId)
+  }
+})
+```
+
+When mocking outgoing traffic with `emit()`, you can pass an object in the first argument to specify the namespace in addition to the event name:
+
+```js
+io.client.emit({ event: 'power_on', namespace: '/bedroom/ceiling_fan' })
+```
+
+By default, connections on all namespaces are accepted when a mocked server. This can be customized by setting a custom authorizer:
+
+```js
+interceptor.on('connection', (connection) => {
+  const io = toSocketIo(connection)
+  io.setAuthorizer((namespace) => {
+    return (namespace !== '/forbidden')
+  })
+})
+```
+
+Note that multiple Socket.IO namespaces will use a single underlying WebSocket, so this connection handler will only run once even if multiple Socket.IO sockets are created.
+
+
 ## Limitations
 
-This wrapper is not meant to provide full feature parity with the Socket.IO client API. Some features may be missing (like rooms, namespaces, broadcasting). If you rely of any of the missing features, open a pull request and implement it. Thank you.
+This wrapper is not meant to provide full feature parity with the Socket.IO client API. Some features may be missing (like rooms or broadcasting). If you rely of any of the missing features, open a pull request and implement it. Thank you.
 
 > Note that feature parity only concerns the _connection wrapper_. You can still use the entire of the Socket.IO feature set in the actual application code.
 

src/index.ts

@@ -8,6 +8,7 @@ import {
   Encoder,
   Decoder,
   PacketType as SocketIoPacketType,
+  type Packet as SocketIoPacket,
 } from 'socket.io-parser'
 import type { WebSocketHandlerConnection } from 'msw'
 import type {
@@ -18,7 +19,48 @@ import type {
 const encoder = new Encoder()
 const decoder = new Decoder()
 
-type BoundMessageListener = (event: MessageEvent, ...data: Array<any>) => void
+interface SocketIoMessageDetails {
+  namespace: string
+}
+
+interface SocketIoMessageEvent<T = any> extends MessageEvent<T> {
+  socketio: SocketIoMessageDetails
+}
+
+type BoundMessageListener = (
+  event: SocketIoMessageEvent,
+  ...data: Array<any>
+) => void
+type ConnectionAuthorizer = (
+  namespace: string,
+  auth: Record<string, unknown>,
+) => boolean | Promise<boolean>
+type EventEnvelope = {
+  event: string
+  namespace?: string
+}
+
+function createSocketIoMessageEvent(
+  event: MessageEvent,
+  details: SocketIoMessageDetails,
+): SocketIoMessageEvent {
+  return new Proxy(event, {
+    get(target, property, receiver) {
+      if (property === 'socketio') {
+        return details
+      }
+
+      return Reflect.get(target, property, receiver)
+    },
+    has(target, property) {
+      if (property === 'socketio') {
+        return true
+      }
+
+      return Reflect.has(target, property)
+    },
+  }) as SocketIoMessageEvent
+}
 
 class SocketIoConnection {
   constructor(
@@ -27,7 +69,9 @@ class SocketIoConnection {
       | WebSocketServerConnectionProtocol,
   ) {}
 
-  public on(event: string, listener: BoundMessageListener): void {
+  public _onSocketIoPacket(
+    callback: (messageEvent: MessageEvent, packet: SocketIoPacket) => void,
+  ): void {
     const addEventListener = this.connection.addEventListener.bind(
       this.connection,
     ) as WebSocketClientConnectionProtocol['addEventListener']
@@ -62,33 +106,51 @@ class SocketIoConnection {
 
       for (const packet of engineIoPackets) {
         decoder.once('decoded', (decodedSocketIoPacket) => {
-          /**
-           * @note Ignore any non-event messages.
-           * To forward all Socket.IO messages one must listen
-           * to the raw outgoing client events:
-           * client.on('message', (event) => server.send(event.data))
-           */
-          if (decodedSocketIoPacket.type !== SocketIoPacketType.EVENT) {
-            return
-          }
-
-          const [sentEvent, ...data] = decodedSocketIoPacket.data
-
-          if (sentEvent === event) {
-            listener.call(undefined, messageEvent, ...data)
-          }
+          callback(messageEvent, decodedSocketIoPacket)
         })
 
         decoder.add(packet.data)
       }
     })
   }
 
+  public on(event: string, listener: BoundMessageListener): void {
+    this._onSocketIoPacket((messageEvent, decodedSocketIoPacket) => {
+      /**
+       * @note Ignore any non-event messages.
+       * To forward all Socket.IO messages one must listen
+       * to the raw outgoing client events:
+       * client.on('message', (event) => server.send(event.data))
+       */
+      if (decodedSocketIoPacket.type !== SocketIoPacketType.EVENT) {
+        return
+      }
+
+      const [sentEvent, ...data] = decodedSocketIoPacket.data
+
+      if (sentEvent === event) {
+        // Create a proxy wrapper around the original MessageEvent object,
+        // adding a `socketio` property with our namespace details.
+        const extendedEvent = createSocketIoMessageEvent(messageEvent, {
+          namespace: decodedSocketIoPacket.nsp,
+        })
+
+        listener.call(undefined, extendedEvent, ...data)
+      }
+    })
+  }
+
   public send(...data: Array<any>): void {
     this.emit('message', ...data)
   }
 
-  public emit(event: string, ...data: Array<any>): void {
+  public emit(event: string, ...data: Array<any>): void
+  public emit(envelope: EventEnvelope, ...data: Array<any>): void
+  public emit(envelope: string | EventEnvelope, ...data: Array<any>): void {
+    const event = typeof envelope === 'string' ? envelope : envelope.event
+    const namespace =
+      typeof envelope === 'string' ? '/' : envelope.namespace ?? '/'
+
     /**
      * @todo Check if this correctly encodes Blob
      * and ArrayBuffer data.
@@ -98,7 +160,7 @@ class SocketIoConnection {
       /**
        * @todo Support custom namespaces.
        */
-      nsp: '/',
+      nsp: namespace,
       data: [event].concat(data),
     })
 
@@ -124,35 +186,110 @@ class SocketIoDuplexConnection {
   public client: SocketIoConnection
   public server: SocketIoConnection
 
+  private hasAuthorizer = false
+
   constructor(
     readonly rawClient: WebSocketClientConnectionProtocol,
     readonly rawServer: WebSocketServerConnectionProtocol,
   ) {
     queueMicrotask(() => {
-      try {
-        // Accessing the "socket" property on the server
-        // throws if the actual server connection hasn't been established.
-        // If it doesn't throw, don't mock the namespace approval message.
-        // That becomes the responsibility of the server.
-        Reflect.get(this.rawServer, 'socket').readyState
-        return
-      } catch {
-        this.rawClient.send(
-          '0' +
-            JSON.stringify({
-              sid: 'test',
-              upgrades: [],
-              pingInterval: 25000,
-              pingTimeout: 5000,
-            }),
-        )
-        this.rawClient.send('40' + JSON.stringify({ sid: 'test' }))
+      // If the actual server connection hasn't been established yet, send
+      // a mock Engine.IO handshake.
+      if (!this.hasUpstreamServer()) {
+        // Set a default authorizer that always allows connections.
+        if (!this.hasAuthorizer) {
+          this.setAuthorizer(() => true)
+        }
+
+        this.sendMockEngineIoOpen()
       }
     })
 
     this.client = new SocketIoConnection(this.rawClient)
     this.server = new SocketIoConnection(this.rawServer)
   }
+
+  private hasUpstreamServer(): boolean {
+    try {
+      // Accessing the "socket" property on the server throws if the actual
+      // server connection hasn't been established.
+      Reflect.get(this.rawServer, 'socket').readyState
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  public setAuthorizer(authorizer: ConnectionAuthorizer): void {
+    this.client._onSocketIoPacket((_event, packet) => {
+      if (packet.type !== SocketIoPacketType.CONNECT) {
+        return
+      }
+
+      Promise.resolve(authorizer(packet.nsp, packet.data)).then((allowed) => {
+        // Allow the authorizer to bounce connections before the actual server
+        // even sees it.
+        if (!allowed) {
+          this.sendMockSocketIoConnectError(packet.nsp, 'Not authorized')
+          return
+        }
+
+        this.sendMockSocketIoConnect(packet.nsp)
+      })
+    })
+
+    this.hasAuthorizer = true
+  }
+
+  private sendMockEngineIoOpen(): void {
+    const openPacket: EngineIoPacket = {
+      type: 'open',
+      data: JSON.stringify({
+        sid: 'test',
+        upgrades: [],
+        pingInterval: 25000,
+        pingTimeout: 5000,
+      }),
+    }
+
+    encodePayload([openPacket], (encodedPayload) => {
+      this.rawClient.send(encodedPayload)
+    })
+  }
+
+  private sendMockSocketIoConnect(namespace: string): void {
+    this.sendSocketIoPacket({
+      type: SocketIoPacketType.CONNECT,
+      nsp: namespace,
+      data: { sid: 'test' },
+    })
+  }
+
+  private sendMockSocketIoConnectError(
+    namespace: string,
+    message: string,
+  ): void {
+    this.sendSocketIoPacket({
+      type: SocketIoPacketType.CONNECT_ERROR,
+      nsp: namespace,
+      data: { message },
+    })
+  }
+
+  private sendSocketIoPacket(packet: SocketIoPacket): void {
+    const socketIoPackets = encoder.encode(packet)
+
+    const engineIoPackets = socketIoPackets.map<EngineIoPacket>((encoded) => {
+      return {
+        type: 'message',
+        data: encoded,
+      }
+    })
+
+    encodePayload(engineIoPackets, (encodedPayload) => {
+      this.rawClient.send(encodedPayload)
+    })
+  }
 }
 
 /**

tests/socket.io-client.ts

@@ -10,5 +10,5 @@ import { Socket } from 'socket.io-client'
 import { io } from 'socket.io-client/dist/socket.io.js'
 
 export function createSocketClient(uri: string): Socket {
-  return io(uri, { transports: ['websocket'] })
+  return io(uri, { transports: ['websocket'], forceNew: true })
 }