@specific.dev/spectest 0.115.1 → 0.116.0

package/README.md

@@ -49,6 +49,50 @@ shown in a collapsed **Instructions** section in the dashboard and PR
 comment. Blank instructions are omitted.
 
 
+## Live APIs in interactive environments
+
+Add `live` to a scripted fake to forward its entire HTTP and WebSocket surface
+in interactive environments, without recording requests or responses:
+
+```ts
+const soniox = defineFake({
+  name: "soniox",
+  hostnames: ["api.eu.soniox.com", "stt-rt.eu.soniox.com"],
+  state: createState,
+  helpers: createHelpers,
+  handler: handleHttp,
+  websocket: handleWebSocket,
+  live: {
+    inject: [{
+      headers: { authorization: "Bearer {{secret:SONIOX_API_KEY}}" },
+    }],
+  },
+});
+```
+
+Tests and shared baseline setup always use the scripted handlers, even when
+credentials are available. Interactive forwarding starts after the shared
+baseline and before interactive seeding. Every declared hostname forwards to
+that same real host over HTTPS/WSS on port 443. Scripted handlers are bypassed;
+helpers remain available but do not observe or control live provider traffic.
+
+`live: {}` forwards without credential overrides. `live.inject` uses the same
+first-matching header rules as `replayFake` for HTTP requests and WebSocket
+handshakes; matches select credentials, not which traffic is forwarded.
+`live.sign` supports the same AWS SigV4 signing for HTTP (not WebSockets).
+Secret references are resolved from the project's Secrets store. Missing
+credentials and upstream failures surface as errors without scripted fallback.
+
+For Soniox, use header authentication and omit `api_key` from the initial
+WebSocket message. The application can use a dummy key; Spectest overwrites
+its outbound Authorization header with the real one. Provider callbacks and
+provider-fetched audio URLs must separately be reachable in the environment.
+
+Unlike `replayFake`, live fakes have no cassette state or recording helpers.
+HTTP payloads may be buffered during forwarding and WebSocket opening buffers
+are bounded; neither is retained as a recording. Application-level storage and
+logs remain under application control.
+
 ## Microphone fixtures and WebSocket fakes (0.103.0)
 
 Supply a 16-bit PCM mono/stereo WAV when creating a browser session:

package/dist/components/replay-websocket.d.ts

@@ -2,6 +2,8 @@ import type { FakeWebSocketHandlers } from "../fake-websocket.js";
 import type { CassetteRequest } from "./replayFake.js";
 import { FakeWebSocketLifetime } from "../harness/fake-websocket-lifetime.js";
 import { type MatchKey } from "./replay-key.js";
+import { type WebSocketSession } from "../fake-upstream-websocket.js";
+export type { WebSocketSession } from "../fake-upstream-websocket.js";
 export type ReplayWebSocketMessage = string | Uint8Array;
 export type WebSocketKey<S = unknown> = ((message: ReplayWebSocketMessage) => MatchKey) | {
     initial: S;
@@ -63,9 +65,6 @@ export declare function validateWebSocketKey<S>(key: WebSocketKey<S> | undefined
 /** Clone once per connection; never retain incoming payloads. */
 export declare function websocketMatcher<S>(key?: WebSocketKey<S>): WebSocketMatcher;
 export declare function validateWebSocketRecording(record: CassetteWebSocket): void;
-export interface WebSocketSession {
-    cancel(): void;
-}
 export declare function replayWebSocket(args: {
     recording: CassetteWebSocket;
     match: WebSocketMatcher;

package/dist/components/replay-websocket.js

@@ -1,12 +1,7 @@
 import { createHash } from "node:crypto";
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
 import { FakeWebSocketLifetime, bindWebSocketLifetime } from "../harness/fake-websocket-lifetime.js";
 import { hashKey } 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"));
-const MAX_BUFFER = 16 * 1024 * 1024;
+import { MAX_BUFFER, closeSocket, forwardWebSocket } from "../fake-upstream-websocket.js";
 const MAX_PENDING = 1024;
 const MAX_CANDIDATE_KEYS = 65536;
 function occurrence(counts, key) {
@@ -144,15 +139,6 @@ export function validateWebSocketRecording(record) {
 function validCloseCode(code) {
     return Number.isInteger(code) && ((code >= 1000 && code <= 1014 && ![1004, 1005, 1006].includes(code)) || (code >= 3000 && code <= 4999) || code === 1005 || code === 1006);
 }
-function closeSocket(socket, code, reason) {
-    // 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 function replayWebSocket(args) {
     const { recording: record, label } = args;
     if ((record.inputMode === "anchors") !== !!args.match.candidates)
@@ -321,27 +307,12 @@ export function replayWebSocket(args) {
 }
 /** Open upstream before accepting downstream, retaining only a bounded opening queue. */
 export async function recordWebSocket(args) {
-    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, options, callback) => {
-            if (options.all)
-                callback(null, [{ address: args.ip, family: 4 }]);
-            else
-                callback(null, args.ip, 4);
-        }),
-    });
     const record = { request: args.request, inputs: [], messages: [],
         ...(args.match.candidates ? { inputMode: "anchors", inputOccurrences: [] } : {}),
     };
     const occurrences = new Map();
     let candidate;
     let candidateIndex = 0, selectedIndex = 0;
-    let socket;
     let anchor = performance.now();
     const selectCandidate = () => {
         if (!candidate || candidate.index === selectedIndex)
@@ -351,14 +322,6 @@ export async function recordWebSocket(args) {
         anchor = candidate.at;
         selectedIndex = candidate.index;
     };
-    let stopped = false;
-    let clientClosed = false;
-    let upstreamClosure;
-    let queue = [];
-    let queuedBytes = 0;
-    let openingTimer;
-    let opened = false;
-    let rejectOpen = () => { };
     const timing = () => ({ afterInput: record.inputs.length, delayMs: Math.max(0, performance.now() - anchor) });
     const scrub = (value) => {
         const result = args.redact(value);
@@ -367,120 +330,14 @@ export async function recordWebSocket(args) {
                 throw new Error(`secret ${secret.ref} survived WebSocket redaction`);
         return result;
     };
-    const finish = (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) => {
-        if (stopped)
-            return;
-        const failure = new Error(`${args.label}: ${error.message}`);
-        rejectOpen(failure);
-        finish(failure);
-        socket?.close(1011, "WebSocket recording failed");
-    };
-    const session = {
-        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);
-            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()) };
-            }
-            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((resolve, reject) => {
-        rejectOpen = reject;
-        upstream.once("open", () => {
-            try {
-                opened = true;
+    return forwardWebSocket({ ...args, observe: {
+            open(protocol) {
                 anchor = performance.now();
-                if (upstream.protocol)
-                    record.protocol = scrub(upstream.protocol);
+                if (protocol)
+                    record.protocol = scrub(protocol);
                 args.captured(record);
-                openingTimer = setTimeout(() => fail(new Error("downstream did not open")), 10_000);
-                resolve();
-            }
-            catch (error) {
-                fail(error);
-            }
-        });
-    });
-    const handlers = {
-        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 {
+            },
+            input(message) {
                 const input = typeof message === "string" ? message : Uint8Array.from(message);
                 if (args.match.candidates) {
                     const at = performance.now();
@@ -494,42 +351,19 @@ export async function recordWebSocket(args) {
                         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;
-            }
-        },
-        close(_ws, code, reason) {
-            if (stopped || clientClosed)
-                return;
-            try {
-                clientClosed = true;
+            },
+            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(code, reason, initiator) {
                 selectCandidate();
-                record.close = { ...timing(), initiator: "client", code, reason: scrub(reason) };
-                closeSocket(upstream, code, reason);
-                openingTimer = setTimeout(() => finish(), 1_000);
-            }
-            catch (error) {
-                fail(error);
-            }
-        },
-    };
-    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) };
+                record.close = { ...timing(), initiator, code, reason: scrub(reason) };
+            },
+        } });
 }
 function redactBinary(bytes, redact, secrets) {
     // Preserve arbitrary bytes; textual patterns can only safely apply to valid UTF-8.

package/dist/components/replayFake.d.ts

@@ -3,59 +3,8 @@ import { type WebSocketKey, type CassetteWebSocket, type WebSocketSession } from
 export type { WebSocketKey, ReplayWebSocketMessage, CassetteWebSocket, CassetteWebSocketMessage, WebSocketTiming } from "./replay-websocket.js";
 import { type ReplayKey } from "./replay-key.js";
 export type { JsonValue, MatchKey, ReplayRequest, ReplayKey } from "./replay-key.js";
-/** Match one request dimension. A bare string is an exact match; the
- *  object forms cover prefix and regex matching. */
-export type StringMatch = string | {
-    exact: string;
-} | {
-    startsWith: string;
-} | {
-    regex: string;
-};
-/** Request matchers for a credential-injection rule. A rule applies only
- *  when EVERY specified dimension matches; omit `match` to always apply. */
-export interface InjectMatch {
-    /** Match the request path (no query). */
-    path?: StringMatch;
-    /** HTTP method(s) — any one matching satisfies it. */
-    method?: string | string[];
-    /** Query-param matchers (ANDed); each key's value(s) must match. */
-    query?: Record<string, StringMatch>;
-    /** Header matchers (ANDed; header names case-insensitive). */
-    headers?: Record<string, StringMatch>;
-}
-/** One credential-brokering rule. When it matches a request, these headers
- *  are SET on the egress forward — overwriting whatever the app sent (so app
- *  code can't smuggle a different value past the broker). Header VALUES may
- *  embed `{{secret:REF}}` tokens; each `REF` is resolved server-side from the
- *  project's Secrets store and supplied for the environment lifetime. Values
- *  never enter project files, the warm-cache hash, or a cassette (redaction
- *  fails closed). */
-export interface InjectRule {
-    match?: InjectMatch;
-    headers: Record<string, string>;
-}
-/** SigV4 request-signing broker. Unlike `inject` (which SETs a static header
- *  value), this RE-SIGNS the outbound request: the app signs with throwaway
- *  dummy credentials, we strip that signature and re-sign the exact outbound
- *  request with the real credentials — the only way to broker AWS auth, whose
- *  signature is a keyed HMAC over the whole request, not a static token.
- *
- *  The three fields are **secret refs, resolved directly** from the project's
- *  Secrets store (NOT `{{secret:}}` templates), with the same lifetime and
- *  fail-closed redaction as `inject`. Region + service are inferred from the
- *  incoming request (its credential scope, else the host); the app never
- *  configures them. */
-export interface AwsSigV4Sign {
-    type: "awsSigv4";
-    /** Secret ref for the AWS access key id. */
-    accessKeyId: string;
-    /** Secret ref for the AWS secret access key. */
-    secretAccessKey: string;
-    /** Optional secret ref for a session token (temporary credentials). */
-    sessionToken?: string;
-}
-export type SignConfig = AwsSigV4Sign;
+import { type InjectRule, type SignConfig } from "../fake-upstream.js";
+export type { StringMatch, InjectMatch, InjectRule, AwsSigV4Sign, SignConfig } from "../fake-upstream.js";
 /** A normal fake context with explicit delegation to recording/replay. */
 export interface ReplayFakeContext extends FakeContext {
     /** Record against the real upstream in record mode, or consume a matching