@specific.dev/spectest 0.115.1 → 0.116.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.115.1",
+  "version": "0.116.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/replay-websocket.ts

@@ -1,16 +1,11 @@
 import { createHash } from "node:crypto";
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-import type WS from "ws";
 import type { FakeWebSocket, FakeWebSocketHandlers } from "../fake-websocket.js";
 import type { CassetteRequest } from "./replayFake.js";
 import { FakeWebSocketLifetime, bindWebSocketLifetime } from "../harness/fake-websocket-lifetime.js";
 import { hashKey, type MatchKey } from "./replay-key.js";
 
-// Bun's built-in ws shim does not support the external-DNS lookup option.
-const require = createRequire(import.meta.url);
-const { WebSocket } = require(join(dirname(require.resolve("ws/package.json")), "index.js")) as typeof import("ws");
-const MAX_BUFFER = 16 * 1024 * 1024;
+import { MAX_BUFFER, closeSocket, forwardWebSocket, type WebSocketSession } from "../fake-upstream-websocket.js";
+export type { WebSocketSession } from "../fake-upstream-websocket.js";
 const MAX_PENDING = 1024;
 export type ReplayWebSocketMessage = string | Uint8Array;
 export type WebSocketKey<S = unknown> =
@@ -181,17 +176,6 @@ export function validateWebSocketRecording(record: CassetteWebSocket): void {
 function validCloseCode(code: number): boolean {
   return Number.isInteger(code) && ((code >= 1000 && code <= 1014 && ![1004, 1005, 1006].includes(code)) || (code >= 3000 && code <= 4999) || code === 1005 || code === 1006);
 }
-function closeSocket(socket: FakeWebSocket | WS, code: number, reason: string): void {
-  // Reserved status codes describe transport closure and cannot go on the wire.
-  if (code === 1006 && socket.terminate) socket.terminate();
-  else if (code === 1005 || code === 1006) socket.close();
-  else socket.close(code, reason);
-}
-
-export interface WebSocketSession {
-  cancel(): void;
-}
-
 export function replayWebSocket(args: {
   recording: CassetteWebSocket;
   match: WebSocketMatcher;
@@ -352,24 +336,12 @@ export async function recordWebSocket(args: {
   lifetime?: FakeWebSocketLifetime;
   finished(session: WebSocketSession, error?: Error): void;
 }): Promise<{ handlers: FakeWebSocketHandlers; session: WebSocketSession }> {
-  const lifetime = args.lifetime ?? new FakeWebSocketLifetime();
-  if (lifetime.ended) throw new Error("WebSocket handshake aborted");
-  let detach = () => {};
-  const upstream = new WebSocket(args.url, args.protocols, {
-    headers: args.headers, maxPayload: MAX_BUFFER,
-    handshakeTimeout: 10_000,
-    lookup: ((_hostname: string, options: { all?: boolean }, callback: Function) => {
-      if (options.all) callback(null, [{ address: args.ip, family: 4 }]);
-      else callback(null, args.ip, 4);
-    }) as any,
-  });
   const record: CassetteWebSocket = { request: args.request, inputs: [], messages: [],
     ...(args.match.candidates ? { inputMode: "anchors" as const, inputOccurrences: [] } : {}),
   };
   const occurrences = new Map<string, number>();
   let candidate: { key: string; count: number; at: number; index: number } | undefined;
   let candidateIndex = 0, selectedIndex = 0;
-  let socket: FakeWebSocket | undefined;
   let anchor = performance.now();
   const selectCandidate = () => {
     if (!candidate || candidate.index === selectedIndex) return;
@@ -378,131 +350,39 @@ export async function recordWebSocket(args: {
     anchor = candidate.at;
     selectedIndex = candidate.index;
   };
-  let stopped = false;
-  let clientClosed = false;
-  let upstreamClosure: { code: number; reason: string } | undefined;
-  let queue: ReplayWebSocketMessage[] = [];
-  let queuedBytes = 0;
-  let openingTimer: ReturnType<typeof setTimeout> | undefined;
-  let opened = false;
-  let rejectOpen: (error: Error) => void = () => {};
   const timing = () => ({ afterInput: record.inputs.length, delayMs: Math.max(0, performance.now() - anchor) });
   const scrub = (value: string) => {
     const result = args.redact(value);
     for (const secret of args.secrets) if (secret.value && result.includes(secret.value)) throw new Error(`secret ${secret.ref} survived WebSocket redaction`);
     return result;
   };
-  const finish = (error?: Error) => {
-    if (stopped) return;
-    stopped = true;
-    clearTimeout(openingTimer);
-    detach();
-    queue = [];
-    upstream.terminate();
-    lifetime.end(error ? { kind: "failed", error } : { kind: "aborted" });
-    args.finished(session, error);
-  };
-  const fail = (error: unknown) => {
-    if (stopped) return;
-    const failure = new Error(`${args.label}: ${(error as Error).message}`);
-    rejectOpen(failure);
-    finish(failure);
-    socket?.close(1011, "WebSocket recording failed");
-  };
-  const session: WebSocketSession = {
-    cancel() { rejectOpen(new Error("WebSocket handshake aborted")); finish(); socket?.close(1001, "recording cleanup"); },
-  };
-  upstream.on("error", fail);
-  upstream.on("message", (data, binary) => {
-    if (stopped || clientClosed) return;
-    try {
-      const bytes = Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data as ArrayBuffer);
-      const message = binary ? new Uint8Array(bytes) : bytes.toString();
-      // Redact bytes too: base64 encoding must not hide a brokered secret.
-      const redacted = binary ? redactBinary(bytes, args.redact, args.secrets) : scrub(bytes.toString());
-      // Apply the same redacted output reducer that replay will see.
-      if (args.match.output?.(binary ? new Uint8Array(Buffer.from(redacted, "base64")) : redacted)) selectCandidate();
-      record.messages.push({ ...timing(), type: binary ? "binary" : "text", data: redacted });
-      if (socket) socket.send(message);
-      else {
-        queuedBytes += bytes.length;
-        if (queue.length >= MAX_PENDING || queuedBytes > MAX_BUFFER) throw new Error("WebSocket opening buffer exceeded");
-        queue.push(message);
-      }
-    } catch (error) { fail(error); }
-  });
-  upstream.on("close", (code, reason) => {
-    if (stopped) return;
-    if (!opened) { fail(new Error("upstream closed before handshake completed")); return; }
-    try {
-      if (!clientClosed) {
-        selectCandidate();
-        upstreamClosure = { code, reason: reason.toString() };
-        record.close = { ...timing(), initiator: "server", code, reason: scrub(reason.toString()) };
+  return forwardWebSocket({ ...args, observe: {
+    open(protocol) {
+      anchor = performance.now();
+      if (protocol) record.protocol = scrub(protocol);
+      args.captured(record);
+    },
+    input(message) {
+      const input = typeof message === "string" ? message : Uint8Array.from(message);
+      if (args.match.candidates) {
+        const at = performance.now();
+        for (const key of args.match.candidates(input)) candidate = { key, count: occurrence(occurrences, key), at, index: ++candidateIndex };
+      } else {
+        const signature = args.match(input);
+        if (signature !== null) { record.inputs.push(signature); anchor = performance.now(); }
       }
-      if (socket) { closeSocket(socket, code, reason.toString()); finish(); }
-      // If the upstream closes before downstream open, open() flushes the queue.
-    } catch (error) { fail(error); }
-  });
-  const opening = new Promise<void>((resolve, reject) => {
-    rejectOpen = reject;
-    upstream.once("open", () => {
-      try {
-        opened = true;
-        anchor = performance.now();
-        if (upstream.protocol) record.protocol = scrub(upstream.protocol);
-        args.captured(record);
-        openingTimer = setTimeout(() => fail(new Error("downstream did not open")), 10_000);
-        resolve();
-      } catch (error) { fail(error); }
-    });
-  });
-  const handlers: FakeWebSocketHandlers = {
-    open(ws) {
-      socket = ws;
-      clearTimeout(openingTimer);
-      if (stopped) { ws.close(1011, "WebSocket recording failed"); return; }
-      try {
-        for (const message of queue) ws.send(message);
-        queue = []; queuedBytes = 0;
-        if (upstreamClosure) { closeSocket(ws, upstreamClosure.code, upstreamClosure.reason); finish(); }
-      } catch (error) { fail(error); }
     },
-    message(_ws, message) {
-      if (stopped) return;
-      try {
-        const input = typeof message === "string" ? message : Uint8Array.from(message);
-        if (args.match.candidates) {
-          const at = performance.now();
-          for (const key of args.match.candidates(input)) candidate = { key, count: occurrence(occurrences, key), at, index: ++candidateIndex };
-        } else {
-          const signature = args.match(input);
-          if (signature !== null) { record.inputs.push(signature); anchor = performance.now(); }
-        }
-        const size = typeof message === "string" ? Buffer.byteLength(message) : message.byteLength;
-        if (size + upstream.bufferedAmount > MAX_BUFFER) throw new Error("WebSocket upstream buffer exceeded");
-        if (upstream.readyState !== WebSocket.OPEN) throw new Error("upstream is not open");
-        upstream.send(message);
-      } catch (error) { fail(error); throw error; }
+    output(message) {
+      const binary = typeof message !== "string";
+      const redacted = binary ? redactBinary(Buffer.from(message), args.redact, args.secrets) : scrub(message);
+      if (args.match.output?.(binary ? new Uint8Array(Buffer.from(redacted, "base64")) : redacted)) selectCandidate();
+      record.messages.push({ ...timing(), type: binary ? "binary" : "text", data: redacted });
     },
-    close(_ws, code, reason) {
-      if (stopped || clientClosed) return;
-      try {
-        clientClosed = true;
-        selectCandidate();
-        record.close = { ...timing(), initiator: "client", code, reason: scrub(reason) };
-        closeSocket(upstream, code, reason);
-        openingTimer = setTimeout(() => finish(), 1_000);
-      } catch (error) { fail(error); }
+    close(code, reason, initiator) {
+      selectCandidate();
+      record.close = { ...timing(), initiator, code, reason: scrub(reason) };
     },
-  };
-  detach = lifetime.onEnd(event => {
-    if (event.kind === "closed" && socket) handlers.close!(socket, event.code, event.reason);
-    else session.cancel();
-  });
-  await opening;
-  handlers.protocol = upstream.protocol || undefined;
-  return { session, handlers: bindWebSocketLifetime(handlers, lifetime) };
+  } });
 }
 
 function redactBinary(bytes: Buffer, redact: (text: string) => string, secrets: { ref: string; value: string }[]): string {