@specific.dev/spectest 0.44.0 → 0.45.0

package/dist/daemon.js

@@ -34,6 +34,7 @@ import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
 import { resolveHostPath as resolveVolumeHostPath, 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, augmentCorsResponse, corsPreflightResponse, isCorsPreflight, } from "./harness/http-proxy.js";
 import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, wildcardSuffix, } from "./harness/hostmatch.js";
@@ -3072,15 +3073,34 @@ function installFetchWrapper() {
             const res = await original(input, init);
             let responseBody;
             let responseBodyTruncated;
-            try {
-                const cloned = res.clone();
-                const text = await cloned.text();
-                const t = truncateUtf8(text);
-                responseBody = t.value;
-                responseBodyTruncated = t.truncated;
+            // 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());
             }
-            catch {
-                // Binary or unreadable body — leave undefined.
+            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/dist/harness/http-body.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 declare function isTextualContentType(contentType: string | null | undefined): boolean | undefined;
+/**
+ * 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 declare function looksBinary(text: string): boolean;
+/**
+ * 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 declare function omittedBody(reason: OmittedBody["reason"], contentType?: string | null, byteLength?: number | null): OmittedBody;
+/** `Content-Length` as a number, or `undefined` if it is absent or unusable. */
+export declare function parseContentLength(value: string | null | undefined): number | undefined;

package/dist/harness/http-body.js

@@ -0,0 +1,116 @@
+/**
+ * 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.
+ */
+/**
+ * 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) {
+    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) {
+    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, contentType, byteLength) {
+    const out = { 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) {
+    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) {
+    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/dist/recorder.d.ts

@@ -171,6 +171,31 @@ export interface S3Event extends BaseEvent {
     /** Set if the op threw. */
     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;
@@ -179,7 +204,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.). */
@@ -222,7 +250,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;

package/package.json

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

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;