chore: add socket recorder

kettanaito · kettanaito · commit 6f769778806a · 2025-08-04T20:04:09.000+02:00
diff --git a/src/interceptors/net/mock-socket.ts b/src/interceptors/net/mock-socket.ts
@@ -3,24 +3,30 @@ import {
   normalizeSocketWriteArgs,
   WriteArgs,
 } from '../Socket/utils/normalizeSocketWriteArgs'
+import { createSocketRecorder, type SocketRecorder } from './socket-recorder'
 
 export class MockSocket extends net.Socket {
   public connecting: boolean
 
-  constructor() {
-    super()
+  #recorder: SocketRecorder<MockSocket>
+
+  constructor(protected readonly options?: net.SocketConstructorOpts) {
+    super(options)
     this.connecting = false
     this.connect()
 
     this._final = (callback) => callback(null)
+
+    this.#recorder = createSocketRecorder(this)
+    return this.#recorder.socket
   }
 
   public connect() {
     this.connecting = true
     return this
   }
 
-  public write(...args: Array<unknown>): boolean {
+  public write(...args: any): boolean {
     const [chunk, encoding, callback] = normalizeSocketWriteArgs(
       args as WriteArgs
     )
@@ -33,11 +39,28 @@ export class MockSocket extends net.Socket {
     return super.push(chunk, encoding)
   }
 
-  public end(...args: Array<unknown>) {
+  public end(...args: any) {
     const [chunk, encoding, callback] = normalizeSocketWriteArgs(
       args as WriteArgs
     )
+
     this.emit('write', chunk, encoding, callback)
-    return super.end.apply(this, args as any)
+    return super.end.apply(this, args)
+  }
+
+  public passthrough(): net.Socket {
+    /**
+     * @fixme Get the means of creating a passthrough socket instance.
+     */
+    const socket = foo(this.options)
+    this.#recorder.replay(socket)
+
+    /**
+     * @todo Implement the inverse recorder: changes on the passthrough socket
+     * must be reflected on this MockSocket. Consumers getting properties from
+     * this MockSocket must receive their values from the passthrough socket.
+     */
+
+    return socket
   }
 }
diff --git a/src/interceptors/net/socket-recorder.test.ts b/src/interceptors/net/socket-recorder.test.ts
@@ -0,0 +1,160 @@
+// @vitest-environment node
+import net from 'node:net'
+import { vi, describe, it, expect } from 'vitest'
+import {
+  createSocketRecorder,
+  inspectSocketRecorder,
+  SocketRecorderEntry,
+} from './socket-recorder'
+
+describe('set', () => {
+  it('ignores unknown property setters', () => {
+    const { socket } = createSocketRecorder(new net.Socket())
+    Object.defineProperty(socket, 'foo', { value: 'abc' })
+
+    expect(
+      inspectSocketRecorder(socket),
+      'Must not record unknown property setters'
+    ).not.toEqual(
+      expect.arrayContaining<SocketRecorderEntry>([
+        {
+          type: 'set',
+          metadata: expect.objectContaining({ property: 'foo' }),
+          replay: expect.any(Function),
+        },
+      ])
+    )
+  })
+
+  it('ignores symbol setters', () => {
+    const { socket } = createSocketRecorder(new net.Socket())
+    // Calling `.setTimeout()` updates the value of the internal `[kTimeout]` symbol.
+    socket.setTimeout(1000)
+
+    expect(
+      inspectSocketRecorder(socket),
+      'Must not record symbol setters'
+    ).not.toEqual(
+      expect.arrayContaining<SocketRecorderEntry>([
+        {
+          type: 'set',
+          metadata: expect.objectContaining({
+            property: expect.any(Symbol),
+          }),
+          replay: expect.any(Function),
+        },
+      ])
+    )
+  })
+
+  it('ignores internal setters', () => {
+    const { socket } = createSocketRecorder(new net.Socket())
+    // Calling `.setTimeout()` updates the value of the internal `._timeout` property.
+    socket.setTimeout(1000)
+
+    expect(
+      inspectSocketRecorder(socket),
+      'Must not record implied internal setter'
+    ).not.toEqual(
+      expect.arrayContaining<SocketRecorderEntry>([
+        {
+          type: 'set',
+          metadata: expect.objectContaining({ property: '_timeout' }),
+          replay: expect.any(Function),
+        },
+      ])
+    )
+  })
+})
+
+describe('apply', () => {
+  it('records a single method call', () => {
+    const { socket } = createSocketRecorder(new net.Socket())
+    socket.setTimeout(1000)
+
+    expect(inspectSocketRecorder(socket)).toEqual<SocketRecorderEntry[]>([
+      {
+        type: 'apply',
+        metadata: { property: 'setTimeout' },
+        replay: expect.any(Function),
+      },
+    ])
+  })
+
+  it('records multiple method calls', () => {
+    const { socket } = createSocketRecorder(new net.Socket())
+    socket.setTimeout(1000)
+    socket.setKeepAlive(true)
+    socket.setEncoding('base64')
+
+    expect(inspectSocketRecorder(socket)).toEqual<SocketRecorderEntry[]>([
+      {
+        type: 'apply',
+        metadata: { property: 'setTimeout' },
+        replay: expect.any(Function),
+      },
+      {
+        type: 'apply',
+        metadata: { property: 'setKeepAlive' },
+        replay: expect.any(Function),
+      },
+      {
+        type: 'apply',
+        metadata: { property: 'setEncoding' },
+        replay: expect.any(Function),
+      },
+    ])
+  })
+
+  it('ignores internal method calls', () => {
+    const { socket } = createSocketRecorder(new net.Socket())
+    // Calling `.write()` triggers the internal `._write()`.
+    socket.write('hello')
+    socket.on('error', () => void 0)
+
+    expect(
+      inspectSocketRecorder(socket),
+      'Must not record internal method calls'
+    ).not.toEqual(
+      expect.arrayContaining<SocketRecorderEntry>([
+        {
+          type: 'apply',
+          metadata: { property: '_write' },
+          replay: expect.any(Function),
+        },
+      ])
+    )
+  })
+})
+
+describe('replay', () => {
+  it('replays method recordings', () => {
+    const { socket, replay } = createSocketRecorder(new net.Socket())
+    socket.setTimeout(123)
+
+    const target = new net.Socket()
+    replay(target)
+
+    expect(target.timeout, 'Must replay the recorded method call').toBe(123)
+    expect(
+      inspectSocketRecorder(socket),
+      'Must exhaust the records array'
+    ).toEqual([])
+  })
+
+  it('replays attached listeners', () => {
+    const { socket, replay } = createSocketRecorder(new net.Socket())
+    const connectListener = vi.fn()
+    socket.on('connect', connectListener)
+
+    const target = new net.Socket()
+    replay(target)
+    target.emit('connect')
+
+    expect(
+      target.listeners('connect'),
+      'Must replay attached listener'
+    ).toEqual([connectListener])
+    expect(connectListener).toHaveBeenCalledOnce()
+  })
+})
diff --git a/src/interceptors/net/socket-recorder.ts b/src/interceptors/net/socket-recorder.ts
@@ -0,0 +1,102 @@
+import net from 'node:net'
+
+const kSocketRecorder = Symbol('kSocketRecorder')
+
+export interface SocketRecorder<T extends net.Socket> {
+  socket: T
+  replay: (newSocket: net.Socket) => void
+}
+
+export interface SocketRecorderEntry {
+  type: 'get' | 'set' | 'apply'
+  metadata: Record<string, any>
+  replay: (newSocket: net.Socket) => void
+}
+
+/**
+ * Creates a proxy over the given mock `Socket` instance
+ * that records all the property setters and methods calls
+ * so they can later be replayed on the passthrough socket.
+ */
+export function createSocketRecorder<T extends net.Socket>(
+  socket: T
+): SocketRecorder<T> {
+  const entries: Array<SocketRecorderEntry> = []
+
+  Object.defineProperty(socket, kSocketRecorder, {
+    value: entries,
+    configurable: true,
+    enumerable: false,
+  })
+
+  const proxy = new Proxy(socket, {
+    get(target, property, receiver) {
+      if (
+        typeof property === 'string' &&
+        !property.startsWith('_') &&
+        typeof target[property as keyof T] === 'function'
+      ) {
+        return new Proxy(target[property as keyof T] as Function, {
+          apply(target, thisArg, argArray) {
+            if (target.name === 'destroy') {
+              entries.length = 0
+            }
+
+            if (target.name !== 'push') {
+              entries.push({
+                type: 'apply',
+                metadata: { property },
+                replay(newSocket) {
+                  Reflect.apply(target, newSocket, argArray)
+                },
+              })
+            }
+            return Reflect.apply(target, thisArg, argArray)
+          },
+        })
+      }
+
+      return Reflect.get(target, property, receiver)
+    },
+    set(target, property, newValue, receiver) {
+      const defaultSetter = () => {
+        return Reflect.set(target, property, newValue, receiver)
+      }
+
+      if (typeof property === 'symbol') {
+        return defaultSetter()
+      }
+
+      const attributes = Object.getOwnPropertyDescriptor(target, property)
+      if (attributes == null || !attributes.writable) {
+        return defaultSetter()
+      }
+
+      entries.push({
+        type: 'set',
+        metadata: { property, newValue },
+        replay(newSocket) {
+          Reflect.set(newSocket, property, newValue, newSocket)
+        },
+      })
+
+      return defaultSetter()
+    },
+  })
+
+  return {
+    socket: proxy,
+    replay(newSocket) {
+      for (const entry of entries) {
+        entry.replay(newSocket)
+      }
+      entries.length = 0
+    },
+  }
+}
+
+export function inspectSocketRecorder<T extends net.Socket>(
+  socket: net.Socket
+): SocketRecorder<T> | undefined {
+  return Reflect.get(socket, kSocketRecorder) as SocketRecorder<T>
+}
