@specific.dev/spectest 0.44.0 → 0.46.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.46.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/supabase-config.test.ts

@@ -0,0 +1,261 @@
+import { describe, expect, test } from "bun:test";
+
+import { mapSupabaseConfig } from "./supabase-config.js";
+
+const toml = (s: string): unknown =>
+  (globalThis as unknown as { Bun: { TOML: { parse(s: string): unknown } } }).Bun.TOML.parse(s);
+
+describe("mapSupabaseConfig", () => {
+  test("maps the auth settings a test can observe", () => {
+    const out = mapSupabaseConfig(
+      toml(`
+[auth]
+jwt_expiry = 7200
+minimum_password_length = 10
+
+[auth.email]
+otp_length = 8
+
+[auth.hook.before_user_created]
+enabled = true
+uri = "pg-functions://postgres/public/hook_restrict_signup"
+`),
+    );
+
+    expect(out.auth).toMatchObject({
+      GOTRUE_JWT_EXP: "7200",
+      GOTRUE_PASSWORD_MIN_LENGTH: "10",
+      GOTRUE_MAILER_OTP_LENGTH: "8",
+      GOTRUE_HOOK_BEFORE_USER_CREATED_ENABLED: "true",
+      GOTRUE_HOOK_BEFORE_USER_CREATED_URI: "pg-functions://postgres/public/hook_restrict_signup",
+    });
+    expect(out.warnings).toEqual([]);
+  });
+
+  // The two mappings a copy-paste gets backwards without anyone noticing.
+  test("negates enable_signup and enable_confirmations", () => {
+    const on = mapSupabaseConfig(
+      toml(`
+[auth]
+enable_signup = true
+[auth.email]
+enable_confirmations = true
+`),
+    );
+    expect(on.auth.GOTRUE_DISABLE_SIGNUP).toBe("false");
+    expect(on.auth.GOTRUE_MAILER_AUTOCONFIRM).toBe("false");
+
+    const off = mapSupabaseConfig(
+      toml(`
+[auth]
+enable_signup = false
+[auth.email]
+enable_confirmations = false
+`),
+    );
+    expect(off.auth.GOTRUE_DISABLE_SIGNUP).toBe("true");
+    expect(off.auth.GOTRUE_MAILER_AUTOCONFIRM).toBe("true");
+  });
+
+  test("collects mail templates by id", () => {
+    const out = mapSupabaseConfig(
+      toml(`
+[auth.email.template.invite]
+subject = "You've been invited"
+content_path = "./supabase/templates/invite.html"
+`),
+    );
+    expect(out.templates.invite).toEqual({
+      path: "./supabase/templates/invite.html",
+      subject: "You've been invited",
+    });
+  });
+
+  // A subject with no content_path is how the CLI spells "default body, custom
+  // subject" — it must not invent a template path.
+  test("keeps a subject-only template out of the served set", () => {
+    const out = mapSupabaseConfig(
+      toml(`
+[auth.email.template.recovery]
+subject = "Reset it"
+content_path = ""
+`),
+    );
+    expect(out.templates.recovery).toEqual({ path: "", subject: "Reset it" });
+  });
+
+  test("reads per-function verify_jwt and the api schemas", () => {
+    const out = mapSupabaseConfig(
+      toml(`
+[api]
+schemas = ["public", "graphql_public"]
+max_rows = 500
+port = 54321
+
+[functions.invoice-api]
+verify_jwt = false
+[functions.account-api]
+verify_jwt = true
+`),
+    );
+    expect(out.functionVerifyJwt).toEqual({ "invoice-api": false, "account-api": true });
+    expect(out.rest).toEqual({ PGRST_DB_SCHEMAS: "public,graphql_public", PGRST_DB_MAX_ROWS: "500" });
+  });
+
+  // Addresses are this environment's, not the file's: its URLs name the
+  // developer's machine, where nothing is listening inside a VM.
+  test("never takes site_url or the redirect allow list from the file", () => {
+    const out = mapSupabaseConfig(
+      toml(`
+[auth]
+site_url = "http://localhost:3000"
+additional_redirect_urls = ["http://localhost:3000/**"]
+`),
+    );
+    expect(out.auth).toEqual({});
+    expect(out.unsupported).toEqual([]);
+    expect(out.warnings).toEqual([]);
+  });
+
+  // Reported, never fatal — the file belongs to the project and describes more
+  // environments than this one.
+  test("reports a setting it cannot apply, with the reason", () => {
+    const out = mapSupabaseConfig(
+      toml(`
+[auth.captcha]
+enabled = true
+provider = "hcaptcha"
+secret = "env(HCAPTCHA_SECRET)"
+`),
+    );
+    expect(out.unsupported).toHaveLength(1);
+    expect(out.unsupported[0]!.key).toBe("auth.captcha");
+    expect(out.unsupported[0]!.reason).toMatch(/captcha/);
+  });
+
+  // Social sign-in is collected, not refused: the component serves each
+  // provider it has an emulator for at that provider's real endpoints.
+  test("collects the social providers and where their credentials come from", () => {
+    const out = mapSupabaseConfig(
+      toml(`
+[auth.external.google]
+enabled = true
+client_id = "env(GOOGLE_OAUTH_CLIENT_ID)"
+secret = "env(GOOGLE_OAUTH_SECRET)"
+
+[auth.external.azure]
+enabled = true
+client_id = "literal-azure-id"
+url = "https://login.microsoftonline.com/tenant-1/v2.0"
+
+[auth.external.facebook]
+enabled = false
+`),
+    );
+    expect(out.externalProviders.google).toEqual({
+      enabled: true,
+      clientIdFrom: "GOOGLE_OAUTH_CLIENT_ID",
+      secretFrom: "GOOGLE_OAUTH_SECRET",
+    });
+    expect(out.externalProviders.azure).toEqual({
+      enabled: true,
+      clientId: "literal-azure-id",
+      url: "https://login.microsoftonline.com/tenant-1/v2.0",
+    });
+    expect(out.externalProviders.facebook!.enabled).toBe(false);
+    expect(out.unsupported).toEqual([]);
+  });
+
+  // The common shape: a config lists a dozen providers with every one off.
+  // Nothing is lost by not applying them, so nothing is said.
+  test("stays quiet about an unsupported feature that is switched off", () => {
+    const out = mapSupabaseConfig(
+      toml(`
+[auth.captcha]
+enabled = false
+provider = "hcaptcha"
+
+[auth.sms]
+enable_signup = false
+template = "code {{ .Code }}"
+`),
+    );
+    expect(out.unsupported).toEqual([]);
+  });
+
+  test("reports a section where only one feature is enabled", () => {
+    const out = mapSupabaseConfig(
+      toml(`
+[auth.mfa.phone]
+enroll_enabled = true
+verify_enabled = false
+`),
+    );
+    expect(out.unsupported.map((u) => u.key)).toEqual(["auth.mfa.phone"]);
+  });
+
+  // Both ways the file defers a value to the surrounding environment. Passing
+  // either through would hand a function the string `env(NAME)` or a base64
+  // ciphertext — the latter looking enough like a value to go unnoticed.
+  test("separates literal secrets from the two deferred forms", () => {
+    const out = mapSupabaseConfig(
+      toml(`
+[edge_runtime.secrets]
+FEATURE_FLAG = "true"
+STRIPE_KEY = "env(STRIPE_SECRET_KEY)"
+SENDGRID_KEY = "encrypted:c2VjcmV0LXZhbHVl"
+`),
+    );
+    expect(out.functionSecrets).toEqual({ FEATURE_FLAG: "true" });
+    // `env(NAME)` records the name to read it from…
+    expect(out.deferredSecrets).toEqual({ STRIPE_KEY: "STRIPE_SECRET_KEY" });
+    // …while an inline ciphertext names nothing and cannot be supplied here.
+    expect(out.encryptedValues).toEqual(["edge_runtime.secrets.SENDGRID_KEY"]);
+  });
+
+  // A provider credential reads from the same `.env` as everything else — it
+  // is a field on the project's auth settings rather than a named secret, but
+  // the value gets there the same way.
+  test("records where a provider credential is read from", () => {
+    const out = mapSupabaseConfig(
+      toml(`
+[auth.external.google]
+enabled = true
+client_id = "env(GOOGLE_OAUTH_CLIENT_ID)"
+secret = "encrypted:c2hoaA=="
+`),
+    );
+    expect(out.externalProviders.google).toEqual({
+      enabled: true,
+      clientIdFrom: "GOOGLE_OAUTH_CLIENT_ID",
+    });
+    // The ciphertext names nothing, so it is reported instead of guessed at.
+    expect(out.encryptedValues).toEqual(["auth.external.google.secret"]);
+  });
+
+  test("warns rather than fails on a key it has never seen", () => {
+    const out = mapSupabaseConfig(toml(`\n[auth]\nfuture_option = true\n`));
+    expect(out.warnings).toEqual(["auth.future_option"]);
+  });
+
+  // Sections spectest owns outright never reach the user as noise.
+  test("drops the topology sections in silence", () => {
+    const out = mapSupabaseConfig(
+      toml(`
+project_id = "test"
+[db]
+port = 54322
+[db.pooler]
+enabled = true
+[studio]
+port = 54323
+[inbucket]
+port = 54324
+[remotes.production.auth]
+site_url = "https://example.com"
+`),
+    );
+    expect(out.warnings).toEqual([]);
+    expect(out.auth).toEqual({});
+  });
+});