@specific.dev/spectest 0.44.0 → 0.46.0

package/src/daemon.ts

@@ -57,6 +57,12 @@ import {
   sanitizeSegment,
 } from "./harness/volume-paths.js";
 import { pollUntilReady } from "./harness/ready-poll.js";
+import {
+  isTextualContentType,
+  looksBinary,
+  omittedBody,
+  parseContentLength,
+} from "./harness/http-body.js";
 import { encodeRegistry } from "./harness/names-registry.js";
 import {
   HOP_BY_HOP_HEADERS,
@@ -120,6 +126,7 @@ import {
   stopRecording,
   truncateUtf8,
   type TestEvent,
+  type OmittedBody,
 } from "./recorder.js";
 import { deepUnwrap, wrap, wrapResponse } from "./inspect.js";
 import type { Wrapped, WrappedResponse } from "./inspect.js";
@@ -3800,16 +3807,33 @@ function installFetchWrapper(): () => void {
     const reqBody = describeRequestBody(input, init);
     try {
       const res = await original(input as RequestInfo, init);
-      let responseBody: string | undefined;
+      let responseBody: string | OmittedBody | undefined;
       let responseBodyTruncated: boolean | undefined;
-      try {
-        const cloned = res.clone();
-        const text = await cloned.text();
-        const t = truncateUtf8(text);
-        responseBody = t.value;
-        responseBodyTruncated = t.truncated;
-      } catch {
-        // Binary or unreadable body — leave 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
+      // ./harness/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());
+        }
       }
       const seq = recordHttp({
         method,

package/src/harness/http-body.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  isTextualContentType,
+  looksBinary,
+  omittedBody,
+  parseContentLength,
+} from "./http-body";
+
+describe("isTextualContentType", () => {
+  test("records text types", () => {
+    for (const ct of [
+      "text/plain",
+      "text/html; charset=utf-8",
+      "TEXT/CSS",
+      "application/json",
+      "application/problem+json",
+      "application/vnd.api+json",
+      "application/xml",
+      "application/x-ndjson",
+      "application/x-www-form-urlencoded",
+      "application/javascript",
+    ]) {
+      expect(isTextualContentType(ct)).toBe(true);
+    }
+  });
+
+  /** An SVG is an image by name and text by content. The suffix rule must
+   *  win, or the recorder stops keeping a body a user can read. */
+  test("keeps svg, which is text under an image type", () => {
+    expect(isTextualContentType("image/svg+xml")).toBe(true);
+  });
+
+  test("refuses binary types", () => {
+    for (const ct of [
+      "image/png",
+      "image/jpeg",
+      "application/octet-stream",
+      "application/pdf",
+      "application/zip",
+      "audio/mpeg",
+      "video/mp4",
+      "font/woff2",
+    ]) {
+      expect(isTextualContentType(ct)).toBe(false);
+    }
+  });
+
+  /** Both of these must read the body and look at it: absent says nothing,
+   *  and a multipart body holds text fields and file parts together. */
+  test("gives no answer without a usable type", () => {
+    expect(isTextualContentType(null)).toBeUndefined();
+    expect(isTextualContentType(undefined)).toBeUndefined();
+    expect(isTextualContentType("")).toBeUndefined();
+    expect(isTextualContentType("  ")).toBeUndefined();
+    expect(isTextualContentType("multipart/form-data; boundary=x")).toBeUndefined();
+  });
+});
+
+describe("looksBinary", () => {
+  test("passes ordinary text, including empty and unicode", () => {
+    expect(looksBinary("")).toBe(false);
+    expect(looksBinary('{"ok":true}')).toBe(false);
+    expect(looksBinary("héllo — ok ✓")).toBe(false);
+    // A lone replacement character is not enough. A text reply with broken
+    // encoding still belongs in the timeline.
+    expect(looksBinary("caf\ufffd")).toBe(false);
+  });
+
+  /** The exact shape that reached production: a PNG decoded by `.text()`. */
+  test("catches a decoded PNG", () => {
+    const png = "\ufffdPNG\r\n\u001a\n\u0000\u0000\u0000\rIHDR";
+    expect(looksBinary(png)).toBe(true);
+  });
+});
+
+describe("omittedBody", () => {
+  test("carries the type and the size as values", () => {
+    expect(omittedBody("binary", "image/png", 70)).toEqual({
+      reason: "binary",
+      contentType: "image/png",
+      bytes: 70,
+    });
+  });
+
+  test("drops the charset parameter", () => {
+    expect(omittedBody("binary", "image/png; charset=binary", 1).contentType).toBe("image/png");
+  });
+
+  /** A missing key is what "the server never said" looks like. A zero or an
+   *  empty string would read as a fact the recorder does not have. */
+  test("omits what it does not know", () => {
+    expect(omittedBody("binary", "application/pdf", undefined)).toEqual({
+      reason: "binary",
+      contentType: "application/pdf",
+    });
+    expect(omittedBody("binary", null, 12)).toEqual({ reason: "binary", bytes: 12 });
+    expect(omittedBody("unreadable", null, null)).toEqual({ reason: "unreadable" });
+  });
+
+  test("keeps a declared zero-byte body", () => {
+    expect(omittedBody("binary", "image/png", 0).bytes).toBe(0);
+  });
+});
+
+describe("parseContentLength", () => {
+  test("reads a length", () => {
+    expect(parseContentLength("95")).toBe(95);
+    expect(parseContentLength(" 95 ")).toBe(95);
+    expect(parseContentLength("0")).toBe(0);
+  });
+
+  test("refuses anything it cannot trust", () => {
+    for (const v of [null, undefined, "", "abc", "-1", "1.5", "9".repeat(30)]) {
+      expect(parseContentLength(v)).toBeUndefined();
+    }
+  });
+});

package/src/harness/http-body.ts

@@ -0,0 +1,122 @@
+/**
+ * What to record for an HTTP response body.
+ *
+ * The fetch recorder used to call `Response.text()` on every reply. That is
+ * correct for text and wrong for bytes. `text()` decodes as UTF-8 and it
+ * does **not** throw on binary: each undecodable byte becomes U+FFFD and
+ * each NUL byte survives as U+0000. So a PNG was recorded as a string that
+ * can no longer rebuild the image, and that string was then stored, shipped
+ * to the CLI, and drawn in the dashboard as noise. The `catch` that was
+ * supposed to cover this case never ran.
+ *
+ * The response is never changed by any of this — the recorder reads a clone,
+ * and an image reply reaches the test exactly as the server sent it. Only
+ * the recorded description changes: `responseBody` carries an
+ * {@link OmittedBody} naming and measuring the reply, in place of the text
+ * it would otherwise hold.
+ *
+ * Pure, so the boundary cases are tested rather than inferred.
+ */
+
+import type { OmittedBody } from "../recorder.js";
+
+/**
+ * Is this content type text?
+ *
+ * `true` = record the body. `false` = record a placeholder and do not even
+ * read the body. `undefined` = the type does not say (it is absent, or it is
+ * `multipart/*`, which mixes both), so the caller must read the body and
+ * examine it with [`looksBinary`].
+ */
+export function isTextualContentType(contentType: string | null | undefined): boolean | undefined {
+  const essence = contentTypeEssence(contentType);
+  if (!essence) return undefined;
+  // Structured-syntax suffixes come first: `image/svg+xml` is text, and its
+  // type alone would call it an image.
+  if (essence.endsWith("+json") || essence.endsWith("+xml") || essence.endsWith("+yaml")) {
+    return true;
+  }
+  if (essence.startsWith("text/")) return true;
+  if (TEXTUAL_TYPES.has(essence)) return true;
+  // A multipart body holds text fields and file parts together. Only the
+  // bytes can say which one this is.
+  if (essence.startsWith("multipart/")) return undefined;
+  return false;
+}
+
+/**
+ * Does decoded text hold bytes that were never text?
+ *
+ * Only U+0000 counts. It cannot appear in a body that a server meant as
+ * text, and it is also the one character Postgres refuses inside a `jsonb`
+ * string, so a payload that holds it fails the event insert.
+ *
+ * A count of U+FFFD would find more binaries, and it would also condemn a
+ * text reply that carries a few characters of broken encoding. This runs
+ * only where the content type gave no answer, so the cheap test is enough.
+ */
+export function looksBinary(text: string): boolean {
+  return text.includes("\u0000");
+}
+
+/**
+ * What the body field carries when the body itself was not recorded.
+ *
+ * Separate fields, not a sentence: a reader can group by content type, sum
+ * the bytes, or count what was dropped. A rendered string like
+ * "[binary body: image/png, 70 bytes]" can do none of that, and every
+ * consumer would have to parse it back apart.
+ *
+ * It replaces the body rather than sitting beside it, so the two states
+ * cannot both be set and there is one key to read.
+ */
+export function omittedBody(
+  reason: OmittedBody["reason"],
+  contentType?: string | null,
+  byteLength?: number | null,
+): OmittedBody {
+  const out: OmittedBody = { reason };
+  const essence = contentTypeEssence(contentType);
+  if (essence) out.contentType = essence;
+  if (typeof byteLength === "number" && Number.isFinite(byteLength) && byteLength >= 0) {
+    out.bytes = byteLength;
+  }
+  return out;
+}
+
+/** `Content-Length` as a number, or `undefined` if it is absent or unusable. */
+export function parseContentLength(value: string | null | undefined): number | undefined {
+  if (!value) return undefined;
+  const n = Number(value.trim());
+  return Number.isSafeInteger(n) && n >= 0 ? n : undefined;
+}
+
+/** `image/png; charset=x` → `image/png`. Empty string → `undefined`. */
+function contentTypeEssence(contentType: string | null | undefined): string | undefined {
+  const essence = (contentType ?? "").split(";")[0]?.trim().toLowerCase();
+  return essence ? essence : undefined;
+}
+
+/**
+ * Text types whose name does not say so. Everything else is caught by
+ * `text/` or by a `+json`/`+xml`/`+yaml` suffix.
+ */
+const TEXTUAL_TYPES = new Set([
+  "application/json",
+  "application/xml",
+  "application/yaml",
+  "application/x-yaml",
+  "application/javascript",
+  "application/x-javascript",
+  "application/ecmascript",
+  "application/graphql",
+  "application/graphql-response+json",
+  "application/x-ndjson",
+  "application/ndjson",
+  "application/jsonl",
+  "application/x-www-form-urlencoded",
+  "application/x-sh",
+  "application/sql",
+  "application/csp-report",
+  "application/problem+json",
+]);

package/src/recorder.ts

@@ -206,6 +206,32 @@ export interface S3Event extends BaseEvent {
   error?: string;
 }
 
+/**
+ * A body that was not captured, described in place of the body itself.
+ *
+ * This is the object form of `requestBody` / `responseBody`: the field holds
+ * the text when the body was text, and this when it was not. One key, and
+ * the two states cannot both be set. A reader tells them apart with
+ * `typeof body === "string"` (`jsonb_typeof(...)` in SQL).
+ *
+ * A body that is not text is described rather than transcribed. The recorder
+ * used to force one into a string with `Response.text()`, which decodes
+ * lossily and cannot be reversed — see `harness/http-body.ts`. The fields are
+ * separate values, not a sentence, so a reader can group by content type,
+ * sum the bytes, or find every reply that was dropped.
+ */
+export interface OmittedBody {
+  /** `binary` — the body was not text. `unreadable` — the stream failed, or
+   *  something had already consumed it. */
+  reason: "binary" | "unreadable";
+  /** The content type the server declared, without its parameters. Absent
+   *  when the server declared none. */
+  contentType?: string;
+  /** Size from `Content-Length`. Absent when the server declared none — the
+   *  body is never read to count it. */
+  bytes?: number;
+}
+
 export interface HttpEvent extends BaseEvent {
   kind: "http";
   method: string;
@@ -214,7 +240,10 @@ export interface HttpEvent extends BaseEvent {
   requestBody?: string;
   requestBodyTruncated?: boolean;
   status?: number;
-  responseBody?: string;
+  /** The response body as text, or an {@link OmittedBody} describing what
+   *  was there when it was not text. */
+  responseBody?: string | OmittedBody;
+  /** Only meaningful for a text body. */
   responseBodyTruncated?: boolean;
   durationMs: number;
   /** Set if the request threw (network error, abort, etc.). */
@@ -259,7 +288,10 @@ export interface KubeEvent extends BaseEvent {
   requestBody?: string;
   requestBodyTruncated?: boolean;
   status?: number;
-  responseBody?: string;
+  /** The response body as text, or an {@link OmittedBody} describing what
+   *  was there when it was not text. */
+  responseBody?: string | OmittedBody;
+  /** Only meaningful for a text body. */
   responseBodyTruncated?: boolean;
   durationMs: number;
   error?: string;