@specific.dev/spectest 0.79.1 → 0.80.0

package/src/harness/fetch.ts

@@ -0,0 +1,174 @@
+import { wrapResponse, type WrappedResponse } from "../inspect.js";
+import { recordHttp, reserveEvent, truncateUtf8, type OmittedBody } from "../recorder.js";
+import { isTextualContentType, looksBinary, omittedBody, parseContentLength } from "./http-body.js";
+import { currentInstrumentationScope } from "./instrumentation-scope.js";
+import { setRawFetch } from "./raw-fetch.js";
+
+function describeFetchInput(input: Parameters<typeof fetch>[0]): {
+  url: string;
+  methodFromInput?: string;
+} {
+  if (typeof input === "string") return { url: input };
+  if (input instanceof URL) return { url: input.toString() };
+  // Request instance
+  const req = input as Request;
+  return { url: req.url, methodFromInput: req.method };
+}
+
+function describeRequestBody(
+  input: Parameters<typeof fetch>[0],
+  init: Parameters<typeof fetch>[1],
+): { body?: string; truncated?: boolean } {
+  // For Request objects, body has already been consumed into the request;
+  // we can't read it back without cloning, which costs. Skip unless init.body
+  // is provided directly.
+  const body = init?.body;
+  if (body === undefined || body === null) {
+    if (input instanceof Request && input.bodyUsed === false) {
+      // Don't drain the request's body here — leaving it for the actual
+      // fetch. Return a marker.
+      return { body: "[Request body not captured]", truncated: false };
+    }
+    return {};
+  }
+  if (typeof body === "string") {
+    const t = truncateUtf8(body);
+    return { body: t.value, truncated: t.truncated };
+  }
+  if (body instanceof URLSearchParams) {
+    const t = truncateUtf8(body.toString());
+    return { body: t.value, truncated: t.truncated };
+  }
+  return { body: `[non-text body: ${body.constructor?.name ?? typeof body}]` };
+}
+
+/**
+ * Marks an error thrown by the instrumented fetch as *transport-level* —
+ * the connection itself failed (refused, unresolvable, reset) before any
+ * HTTP reply existed. `fetch` never rejects for an HTTP status, so every
+ * rejection short of an abort is transport. `Symbol.for` so a duplicated
+ * SDK module instance (the bun hardlink landmine) still recognises it.
+ *
+ * Why it exists: `ctx.poll` waits for convergence, and right after a fork
+ * restore the guest can serve a ~10 s window where a connect or a DNS
+ * lookup fails once and then heals (measured 2026-08-21: a poll's first
+ * fetch hung 12 s in resolution, threw, and killed a 60 s poll on attempt
+ * 1 while attempt 2 would have passed). During a poll, a dead connection
+ * is just "not ready yet"; outside one it stays a hard error.
+ */
+const TRANSPORT_ERROR = Symbol.for("spectest.transportError");
+
+export function isTransportError(err: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    (err as Record<symbol, unknown>)[TRANSPORT_ERROR] === true
+  );
+}
+
+/** Install a dispatcher: only code in an active test/setup/eval scope gets
+ * wrapped responses. Fake handlers and background tasks use native fetch,
+ * without cloning bodies, tagging errors, or touching the recorder. */
+export function installFetchWrapper(): () => void {
+  const original = globalThis.fetch;
+  // SDK internals (the MCP client, its OAuth flow) must not see the
+  // wrapper: a wrapped `res.ok` is an object, and the wrapper reads every
+  // body to the end, which never finishes for an SSE stream.
+  setRawFetch(original);
+  const wrappedFn = async (
+    input: Parameters<typeof fetch>[0],
+    init?: Parameters<typeof fetch>[1],
+  ): Promise<Response | WrappedResponse> => {
+    const scope = currentInstrumentationScope();
+    if (!scope?.active) return original(input, init);
+    const start = Date.now();
+    const resv = reserveEvent();
+    const { url, methodFromInput } = describeFetchInput(input);
+    const method = (init?.method ?? methodFromInput ?? "GET").toUpperCase();
+    const reqBody = describeRequestBody(input, init);
+    try {
+      const res = await original(input as RequestInfo, init);
+      if (!scope.active) return res;
+      let responseBody: string | OmittedBody | undefined;
+      let responseBodyTruncated: boolean | undefined;
+      // The reply the test gets is untouched: everything here reads a clone,
+      // and a body known to be binary is not read at all. See
+      // ./http-body.ts for why a blanket `.text()` was wrong.
+      const contentType = res.headers.get("content-type");
+      const contentLength = () => parseContentLength(res.headers.get("content-length"));
+      const textual = isTextualContentType(contentType);
+      if (textual === false) {
+        responseBody = omittedBody("binary", contentType, contentLength());
+      } else {
+        try {
+          const cloned = res.clone();
+          const text = await cloned.text();
+          if (textual === undefined && looksBinary(text)) {
+            // No content type (or a multipart one), and the bytes say this
+            // was never text.
+            responseBody = omittedBody("binary", contentType, contentLength());
+          } else {
+            const t = truncateUtf8(text);
+            responseBody = t.value;
+            responseBodyTruncated = t.truncated;
+          }
+        } catch {
+          // The stream failed, or something had already consumed the body.
+          responseBody = omittedBody("unreadable", contentType, contentLength());
+        }
+      }
+      // The test may have timed out while we awaited the response body.
+      if (!scope.active) return res;
+      const seq = recordHttp({
+        method,
+        url,
+        requestBody: reqBody.body,
+        requestBodyTruncated: reqBody.truncated,
+        status: res.status,
+        responseBody,
+        responseBodyTruncated,
+        durationMs: Date.now() - start,
+      }, resv);
+      return wrapResponse(res, seq);
+    } catch (err) {
+      if (!scope.active) throw err;
+      const e = err as Error;
+      recordHttp({
+        method,
+        url,
+        requestBody: reqBody.body,
+        requestBodyTruncated: reqBody.truncated,
+        durationMs: Date.now() - start,
+        error: e?.message ?? String(err),
+      }, resv);
+      // Tag transport failures for ctx.poll (see TRANSPORT_ERROR). An abort
+      // is the caller's own signal (their AbortController or their
+      // AbortSignal.timeout) — their semantics, never retried for them.
+      if (
+        typeof err === "object" &&
+        err !== null &&
+        e?.name !== "AbortError" &&
+        e?.name !== "TimeoutError"
+      ) {
+        try {
+          (err as Record<symbol, unknown>)[TRANSPORT_ERROR] = true;
+        } catch {
+          /* frozen error object — stays a hard error */
+        }
+      }
+      throw err;
+    }
+  };
+  // Preserve any provider-specific statics on `fetch` (e.g. Bun's
+  // `fetch.preconnect`) so consumers that touch them keep working.
+  const wrapped = wrappedFn as unknown as typeof fetch;
+  for (const key of Object.keys(original) as (keyof typeof original)[]) {
+    (wrapped as unknown as Record<string, unknown>)[key as string] = (
+      original as unknown as Record<string, unknown>
+    )[key as string];
+  }
+  globalThis.fetch = wrapped;
+  return () => {
+    globalThis.fetch = original;
+  };
+}

package/src/harness/instrumentation-scope.ts

@@ -0,0 +1,46 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** One test (or setup/eval invocation). Close it even on timeout: detached
+ * work retains its async context and must not write into the next test. */
+export interface InstrumentationScope {
+  active: boolean;
+  recording: boolean;
+}
+
+// No scope means native fetch. `null` explicitly isolates fake execution,
+// including helpers called directly from an instrumented test.
+const scopes = new AsyncLocalStorage<InstrumentationScope | null>();
+
+export function createInstrumentationScope(recording = true): InstrumentationScope {
+  return { active: true, recording };
+}
+
+export function currentInstrumentationScope(): InstrumentationScope | null | undefined {
+  return scopes.getStore();
+}
+
+export function runInstrumented<T>(scope: InstrumentationScope, fn: () => T): T {
+  return scopes.run(scope, fn);
+}
+
+/** Preserve native behavior through awaits, timers, and nested helpers without
+ * changing the instrumentation of concurrent test work. */
+export function runUninstrumented<T>(fn: () => T): T {
+  return scopes.run(null, fn);
+}
+
+/** Test-authored callbacks invoked later by ingress (ctx.intercept) keep
+ * their registration scope, even though the incoming request has none. */
+export function bindInstrumentationScope<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => R {
+  const scope = scopes.getStore();
+  return function (this: unknown, ...args: A): R {
+    return scopes.run(scope ?? null, () => fn.apply(this, args));
+  };
+}
+
+/** Unscoped SDK sites (browser/interceptor callbacks, final drains) still use
+ * the active recorder. Fake internals and expired test contexts cannot. */
+export function scopeAllowsRecording(): boolean {
+  const scope = scopes.getStore();
+  return scope === undefined || (scope !== null && scope.active && scope.recording);
+}

package/src/harness/raw-fetch.ts

@@ -1,8 +1,8 @@
 // The real `fetch`, for SDK internals that must not go through the test
 // recorder's wrapper.
 //
-// While a test (or an eval) runs, the daemon replaces `globalThis.fetch`
-// with an instrumented one: it records an `http` event, and it hands back
+// The daemon's `globalThis.fetch` dispatcher instruments calls in the async
+// scope of a test (or setup/eval): it records an `http` event, and hands back
 // a WRAPPED response whose `ok` / `status` are provenance handles rather
 // than a boolean and a number. That is exactly right for a test's own
 // calls, and exactly wrong inside the SDK, in two ways:
@@ -17,8 +17,9 @@
 //      handed its response only after the stream it was waiting to read
 //      has already ended. A long-lived stream deadlocks.
 //
-// So SDK-internal HTTP goes through `rawFetch`. The daemon publishes the
-// original here when it installs its wrapper.
+// Fake execution is explicitly outside that scope. SDK-internal HTTP that
+// runs WITHIN a test's scope goes through `rawFetch` instead. The daemon
+// publishes the original here when it installs its wrapper.
 
 let original: typeof fetch | undefined;
 

package/src/index.ts

@@ -2053,6 +2053,9 @@ export interface FakeDefinition<
    * real backing instance, `ctx.dnsName(...)` to name it). Return any
    * `Response`. Thrown errors surface as 500s. The request URL is the
    * absolute URL the client used — useful for routing on the path.
+   * Fake code uses native `fetch`: responses are ordinary `Response` objects
+   * and internal requests are not added to a running test's timeline. This
+   * also applies to state/helper factories and helper implementations.
    */
   handler: (req: Request, state: S, ctx: FakeContext) => Response | Promise<Response>;
   /**
@@ -2068,6 +2071,8 @@ export interface FakeDefinition<
    * Every call is tracked in the test timeline: it records a `fake` step
    * and the return value is tagged so a later `expect(...)` on it nests
    * under that step in the UI (same provenance as `fetch`/db results).
+   * Operations inside the helper are uninstrumented, including across awaits;
+   * concurrent operations in test code continue to record normally.
    * The step renders the return value as JSON; wrap it in {@link annotate}
    * to add a richer view (an email, today) that the step's panel leads with,
    * the JSON one tab away — the test still receives the raw value, unchanged

package/src/recorder.ts

@@ -9,6 +9,7 @@
 // callers can invoke them unconditionally.
 
 import { clearPendingNullish } from "./inspect.js";
+import { scopeAllowsRecording } from "./harness/instrumentation-scope.js";
 
 const OUTPUT_SNIPPET_BYTES = 256 * 1024;
 
@@ -747,7 +748,7 @@ export function resumeRecording(): void {
 }
 
 function active(): boolean {
-  return current !== null && paused === 0;
+  return current !== null && paused === 0 && scopeAllowsRecording();
 }
 
 export function startRecording(): void {