@sentry/roach 0.2.0 → 0.3.0

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@sentry/roach",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A recording HTTPS proxy for tests, as a shared service.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/getsentry/roach.git"
+    "url": "git+https://github.com/getsentry/roach.git",
+    "directory": "packages/roach"
   },
   "files": [
     "src"
@@ -14,7 +15,6 @@
   "exports": {
     "./client": "./src/client.ts",
     "./report": "./src/report.ts",
-    "./service": "./src/service.ts",
     "./types": "./src/types.ts",
     "./values": "./src/values.ts",
     "./vitest": "./src/vitest.ts",
@@ -23,22 +23,10 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@sentry/node": "11.6.0"
-  },
   "devDependencies": {
-    "@sentry/dotagents": "^3.3.0",
     "@types/node": "^24.19.1",
-    "@vitest/coverage-v8": "^5.0.3",
-    "knip": "^6.40.0",
-    "lint-staged": "^17.6.0",
-    "oxfmt": "^0.72.0",
-    "oxlint": "^1.87.0",
-    "oxlint-tsgolint": "^7.0.2003",
-    "simple-git-hooks": "^2.14.0",
     "typescript": "^7.0.2",
-    "undici": "^8.11.2",
-    "vitest": "^5.0.3"
+    "vitest": "^5.1.0"
   },
   "peerDependencies": {
     "vitest": ">=3"
@@ -48,30 +36,11 @@
       "optional": true
     }
   },
-  "simple-git-hooks": {
-    "pre-commit": "pnpm exec lint-staged",
-    "pre-push": "pnpm typecheck"
-  },
-  "lint-staged": {
-    "*.{ts,mts,js,mjs}": [
-      "oxlint --fix --deny-warnings",
-      "oxfmt --no-error-on-unmatched-pattern"
-    ],
-    "*.{json,jsonc,md,yml,yaml}": "oxfmt --no-error-on-unmatched-pattern"
-  },
   "engines": {
     "node": ">=24"
   },
   "scripts": {
-    "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm knip && pnpm test",
-    "format": "oxfmt",
-    "format:check": "oxfmt --check",
-    "knip": "knip",
-    "lint": "oxlint --deny-warnings",
-    "lint:fix": "oxlint --fix",
-    "skills:install": "dotagents --project install",
     "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
     "typecheck": "tsc -p ."
   }
 }

package/src/action.ts

@@ -14,9 +14,11 @@ import { writeRunReport } from "./report.ts";
 
 /**
  * Variables that the command does not get: the inputs, which have the token,
- * and the proxy variables of the job.
+ * the tokens of the runner (`ACTIONS_*`, such as `ACTIONS_RUNTIME_TOKEN` and
+ * `ACTIONS_ID_TOKEN_REQUEST_TOKEN`), and the proxy variables of the job.
  */
-const HIDDEN_VARIABLE = /^(INPUT_.*|https?_proxy|no_proxy|all_proxy)$/i;
+const HIDDEN_VARIABLE =
+  /^(INPUT_.*|ACTIONS_.*|https?_proxy|no_proxy|all_proxy)$/i;
 
 /** Run the command in bash, and return its exit code. */
 function runCommand(command: string, env: NodeJS.ProcessEnv): Promise<number> {
@@ -49,7 +51,7 @@ function runCommand(command: string, env: NodeJS.ProcessEnv): Promise<number> {
 }
 
 const command = process.env.INPUT_RUN;
-if (!command) throw new Error("The run input is required");
+if (!command) throw new Error("Roach: the run input is required");
 // The runner gives an empty string for an input that the step does not set.
 const token = readEnv("INPUT_TOKEN");
 const file = await readRoachFile();

package/src/client.ts

@@ -1,16 +1,17 @@
 /**
  * The client of Roach. See `README.md`.
  *
- * `startRemoteRun()` starts a run on a Roach service (`service.ts`). It
- * returns `env`, the variables that send the traffic of a process through
- * the run. `connectRoach()` controls a run from another process, such as a
- * test worker.
+ * `startRemoteRun()` starts a run on a Roach service
+ * (`@sentry/roach-service`). It returns `env`, the variables that send the
+ * traffic of a process through the run. `connectRoach()` controls a run
+ * from another process, such as a test worker.
  */
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import http from "node:http";
 import https from "node:https";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import { DEFAULT_NO_PROXY } from "./config.ts";
 import {
   CONTROL_PATH,
   type OpenedSession,
@@ -46,6 +47,16 @@ export interface RoachControl {
   stats(): Promise<RecordingStats>;
 }
 
+/**
+ * The request functions of `node:http` and `node:https` as this module
+ * loads. In-process HTTP mocks, such as MSW and nock, replace them when they
+ * start. Control calls go to the service, never to a mock, so they use the
+ * originals. Load the setup file of Roach before a setup file that starts a
+ * mock.
+ */
+const httpRequest = http.request;
+const httpsRequest = https.request;
+
 /**
  * Call the control API at `base`, and return the JSON of the response.
  * `token` is the bearer token.
@@ -59,9 +70,9 @@ function callControl<T>(
 ): Promise<T> {
   const payload = body === undefined ? undefined : JSON.stringify(body);
   const url = route ? `${base}/${route}` : base;
-  const client = url.startsWith("https:") ? https : http;
+  const send = url.startsWith("https:") ? httpsRequest : httpRequest;
   return new Promise((resolve, reject) => {
-    const request = client.request(
+    const request = send(
       url,
       {
         // Its own agent, so that a proxy agent of the process is not used.
@@ -81,7 +92,7 @@ function callControl<T>(
           if (status >= 400) {
             reject(
               new Error(
-                `Roach ${method} ${route} failed with HTTP ${status}: ${text}`,
+                `Roach: ${method} ${route} failed with HTTP ${status}: ${text}`,
               ),
             );
           } else {
@@ -96,6 +107,12 @@ function callControl<T>(
   });
 }
 
+/**
+ * The first service version that returns the proxy URL of a session. An
+ * older service answers `POST /session` with an empty body.
+ */
+const SESSION_URL_VERSION = "0.2.0";
+
 /** Control a run, for example from a test worker. */
 export function connectRoach({
   controlUrl,
@@ -103,13 +120,19 @@ export function connectRoach({
 }: Pick<RemoteRun, "controlUrl" | "token">): RoachControl {
   return {
     async startSession(name) {
-      const { url } = await callControl<OpenedSession>(
+      const opened = await callControl<OpenedSession | undefined>(
         controlUrl,
         token,
         "POST",
         "session",
         { name },
       );
+      const url = opened?.url;
+      if (typeof url !== "string") {
+        throw new Error(
+          `Roach: the service at ${new URL(controlUrl).origin} is older than this client: it returned no session URL. Deploy the service at ${SESSION_URL_VERSION} or later.`,
+        );
+      }
       return {
         url,
         end: (passed) =>
@@ -123,7 +146,7 @@ export function connectRoach({
   };
 }
 
-/** A run on a Roach service (`service.ts`). */
+/** A run on a Roach service (`@sentry/roach-service`). */
 export interface RemoteRoach extends RemoteRun, RoachControl {
   /**
    * The variables that send the HTTP traffic of a process through the run:
@@ -146,7 +169,7 @@ export interface RemoteRoach extends RemoteRun, RoachControl {
 export async function startRemoteRun(
   service: { url: string; token?: string | undefined },
   config: RunConfig,
-  { noProxy = "localhost,127.0.0.1,::1" }: { noProxy?: string } = {},
+  { noProxy = DEFAULT_NO_PROXY }: { noProxy?: string } = {},
 ): Promise<RemoteRoach> {
   const run = await callControl<RemoteRun>(
     `${service.url.replace(/\/$/, "")}${CONTROL_PATH}`,

package/src/config.ts

@@ -6,12 +6,20 @@
  */
 import { access, readFile } from "node:fs/promises";
 import path from "node:path";
-import type { RecordingMode, RecordingRule, RunConfig } from "./types.ts";
+import type {
+  RecordingMode,
+  RecordingRule,
+  RunCi,
+  RunConfig,
+} from "./types.ts";
 import { VALUE_PATTERNS } from "./values.ts";
 
 /** The Roach service of Sentry. See "Deploy" in `README.md`. */
 export const DEFAULT_SERVICE_URL = "https://roach-proxy.getsentry.net";
 
+/** The hosts that do not use the proxy when `roach.json` sets no `noProxy`. */
+export const DEFAULT_NO_PROXY = "localhost,127.0.0.1,::1";
+
 /** The name of the config file. */
 const FILE_NAME = "roach.json";
 
@@ -43,6 +51,14 @@ export interface RoachFile {
 
 const MODES = new Set<string>(["auto", "off", "record", "replay"]);
 
+/** The variable of each field of `RunConfig.ci`. */
+const CI_VARIABLES: Record<keyof RunCi, string> = {
+  runId: "GITHUB_RUN_ID",
+  job: "GITHUB_JOB",
+  repo: "GITHUB_REPOSITORY",
+  ref: "GITHUB_REF",
+};
+
 /** A variable of `env`, or `undefined` when it is not set or is blank. */
 export function readEnv(
   name: string,
@@ -52,6 +68,23 @@ export function readEnv(
   return value === "" ? undefined : value;
 }
 
+/**
+ * Set the variables `values` in `process.env`. Returns a function that
+ * sets each of them back. A variable that was not set before is deleted.
+ */
+export function swapEnv(values: Record<string, string>): () => void {
+  const previous = Object.keys(values).map(
+    (name) => [name, process.env[name]] as const,
+  );
+  Object.assign(process.env, values);
+  return () => {
+    for (const [name, value] of previous) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  };
+}
+
 /**
  * Find `roach.json` in `from` or the closest parent directory, and read
  * it. Throws when no directory has one.
@@ -66,10 +99,17 @@ export async function readRoachFile(
       () => false,
     );
     if (found) {
-      return {
-        ...(JSON.parse(await readFile(file, "utf8")) as RoachFile),
-        path: file,
-      };
+      const text = await readFile(file, "utf8");
+      let parsed: RoachFile;
+      try {
+        parsed = JSON.parse(text) as RoachFile;
+      } catch (error) {
+        throw new Error(
+          `Roach: ${file} is not valid JSON: ${(error as Error).message}`,
+          { cause: error },
+        );
+      }
+      return { ...parsed, path: file };
     }
     const parent = path.dirname(directory);
     if (parent === directory) {
@@ -137,5 +177,12 @@ export function runConfigOf(
   if (runId) {
     config.name = `${runId}-${readEnv("GITHUB_RUN_ATTEMPT", env) ?? "1"}`;
   }
+  const ci = Object.fromEntries(
+    Object.entries(CI_VARIABLES).flatMap(([field, name]) => {
+      const value = readEnv(name, env);
+      return value ? [[field, value]] : [];
+    }),
+  );
+  if (Object.keys(ci).length > 0) config.ci = ci;
   return config;
 }

package/src/report.ts

@@ -2,7 +2,19 @@
  * Text reports of a Roach run, for logs and CI summaries.
  */
 import { appendFile } from "node:fs/promises";
-import type { RecordingMiss, RecordingStats } from "./types.ts";
+import type {
+  RecordingChange,
+  RecordingMiss,
+  RecordingStats,
+  RefusalReason,
+} from "./types.ts";
+
+/** What to fix for each refusal reason. */
+const REFUSAL_HINTS: Record<RefusalReason, string> = {
+  notAllowed: "not in allow",
+  notPublic: "not a public address",
+  replayOnly: "no rule records it, and the run can only replay",
+};
 
 /** Describe the totals of a run in one line. */
 export function describeRecordingStats(stats: RecordingStats): string {
@@ -16,14 +28,30 @@ export function describeRecordingStats(stats: RecordingStats): string {
     Object.entries(stats.passthrough)
       .map(([origin, count]) => `${origin} ${count}`)
       .join(", ") || "none";
-  return `${rules}. ${stats.written} recordings new or changed, ${stats.discarded} dropped from failed sessions. Not recorded: ${passthrough}.`;
+  const refused = Object.entries(stats.refused ?? {}).flatMap(
+    ([reason, origins]) =>
+      Object.entries(origins).map(
+        ([origin, count]) =>
+          `${origin} ${count} (${REFUSAL_HINTS[reason as RefusalReason]})`,
+      ),
+  );
+  return `${rules}. ${stats.written} recordings new or changed, ${stats.discarded} dropped from failed sessions. Not recorded: ${passthrough}.${refused.length ? ` Refused: ${refused.join(", ")}.` : ""}`;
 }
 
 /**
- * Describe the first request without a recording of each test, one line
- * each. The first miss of a test is the one to fix. Each later miss of the
- * test usually follows from it, because the live response differs from
- * the recording.
+ * Describe the first change of a miss, in an indented line. The report
+ * goes to public CI logs, so it never shows the text of a request. Sentry
+ * has it.
+ */
+const describeChange = ({ file, at }: RecordingChange) =>
+  `\n  Changed at character ${at} of the request of ${file}. See miss.recorded and miss.request on the roach.request span in Sentry.`;
+
+/**
+ * Describe the first request without a recording of each test. The first
+ * miss of a test is the one to fix. Each later miss of the test usually
+ * follows from it, because the live response differs from the recording.
+ * When the proxy has the text of the closest recorded request, the
+ * description also shows where it first changed, in an indented line.
  */
 export function describeRecordingMisses(misses: RecordingMiss[]): string[] {
   const seen = new Set<string | undefined>();
@@ -33,7 +61,10 @@ export function describeRecordingMisses(misses: RecordingMiss[]): string[] {
       seen.add(miss.session);
       return first;
     })
-    .map((miss) => `${miss.session ?? "outside a test"}: ${miss.file}`);
+    .map(
+      (miss) =>
+        `${miss.session ?? "outside a test"}: ${miss.file}${miss.change ? describeChange(miss.change) : ""}`,
+    );
 }
 
 /**

package/src/types.ts

@@ -29,8 +29,13 @@ export interface RecordingRule {
   match: {
     /** The method, such as `POST`. */
     method?: string;
-    /** The start of the URL, such as `https://ai-gateway.vercel.sh/`. */
-    url?: string;
+    /**
+     * The start of the URL, such as `https://ai-gateway.vercel.sh/`. A list
+     * matches a URL that starts with one of its prefixes, so one rule can
+     * record the same API on many hosts. The key does not use `match`, so a
+     * string and a list with that string give the same keys.
+     */
+    url?: string | string[];
     /** Header values. Names are lowercase. */
     headers?: Record<string, string>;
   };
@@ -46,6 +51,19 @@ export interface RecordingRule {
   values?: ValuePatterns;
 }
 
+/**
+ * Where a request without a recording first differs from the request of
+ * the closest recording, in the texts that the keys hash. It has no text:
+ * the texts go only to the `roach.request` span in Sentry, as
+ * `miss.recorded` and `miss.request`.
+ */
+export interface RecordingChange {
+  /** The key of the recording that the request is compared with. */
+  file: string;
+  /** The offset of the first different character. */
+  at: number;
+}
+
 /** A request that a rule matched, but that had no recording. */
 export interface RecordingMiss {
   rule: string;
@@ -53,6 +71,12 @@ export interface RecordingMiss {
   session?: string | undefined;
   /** The key of the recording that the request needed. */
   file: string;
+  /**
+   * The first change from the request of the closest recording. Only the
+   * first miss of each session in a run with the write token has it, and
+   * only when the proxy has the text of that request.
+   */
+  change?: RecordingChange;
 }
 
 /** The totals of a run. */
@@ -73,8 +97,21 @@ export interface RecordingStats {
    * recorded. Use this to find traffic that a rule misses.
    */
   passthrough: Record<string, number>;
+  /**
+   * Requests that the proxy refused with HTTP 403 and sent nowhere, by
+   * reason and origin. An older service does not send it.
+   */
+  refused?: Partial<Record<RefusalReason, Record<string, number>>>;
 }
 
+/**
+ * Why the proxy refused a request:
+ * - `notAllowed`: its origin is not in `allow`.
+ * - `notPublic`: its origin is in `allow`, but its address is not public.
+ * - `replayOnly`: the run can only replay, and no rule records the request.
+ */
+export type RefusalReason = "notAllowed" | "notPublic" | "replayOnly";
+
 /** The configuration of one run. The client sends it. */
 export interface RunConfig {
   /**
@@ -101,6 +138,20 @@ export interface RunConfig {
    * config, keeps them only in memory, and forgets them when the run ends.
    */
   secrets?: string[];
+  /**
+   * The CI job of the run, for Sentry. `runConfigOf()` takes it from
+   * `GITHUB_RUN_ID`, `GITHUB_JOB`, `GITHUB_REPOSITORY`, and `GITHUB_REF`.
+   * An older service ignores it.
+   */
+  ci?: RunCi;
+}
+
+/** The CI job of a run. Each field is a string of at most 256 characters. */
+export interface RunCi {
+  runId?: string;
+  job?: string;
+  repo?: string;
+  ref?: string;
 }
 
 /** A run that the service created. */

package/src/values.ts

@@ -107,7 +107,7 @@ function compile(patterns: ValuePatterns): CompiledValues {
  * Run `fn` with a time limit. A slow pattern cannot stop itself, but the
  * `timeout` of `vm` stops any code that runs too long, also code outside
  * the context that the script calls. A timeout throws an error with HTTP
- * status 400.
+ * status 400 and `timedOut`.
  */
 export function withTimeLimit<T>(ms: number, fn: () => T): T {
   try {
@@ -118,7 +118,7 @@ export function withTimeLimit<T>(ms: number, fn: () => T): T {
     if ((error as { code?: string }).code === "ERR_SCRIPT_EXECUTION_TIMEOUT") {
       throw Object.assign(
         new Error(`the value patterns took over ${ms} ms. Make them simpler.`),
-        { status: 400 },
+        { status: 400, timedOut: true },
       );
     }
     throw error;
@@ -153,11 +153,16 @@ export type KnownValues = ReadonlyMap<string, string>;
  * model repeats the short commit id of a `git push` range in its reply,
  * and a later request sends that reply back. A pattern wins over a known
  * value at the same place.
+ *
+ * Past `maxValues` values, it stops and throws an error with HTTP status
+ * 400. It counts each value when it finds it, so a text with millions of
+ * values cannot fill the memory before the error.
  */
 export function extractValues(
   text: string,
   patterns: ValuePatterns | undefined,
   known?: KnownValues,
+  maxValues = Infinity,
 ): { text: string; values: RequestValues } {
   const values: RequestValues = new Map();
   if (!patterns || Object.keys(patterns).length === 0) {
@@ -170,20 +175,53 @@ export function extractValues(
   const search = hasKnown
     ? new RegExp(`${pattern.source}|(${literals([...known.keys()])})`, "g")
     : pattern;
-  const result = text.replace(search, (...match: unknown[]) => {
-    const value = match[0] as string;
-    const name =
-      hasKnown && match[knownGroup] !== undefined
-        ? known.get(value)!
-        : names[groups.findIndex((group) => match[group] !== undefined)]!;
-    const list = values.get(name) ?? [];
-    list.push(value);
-    values.set(name, list);
-    return `<<${name}>>`;
-  });
-  return { text: result, values };
+  // An `exec()` loop, not `replace()`: `replace()` finds all matches
+  // before it calls its function, so it cannot stop at `maxValues`. The
+  // loop finds the same matches, also the empty ones.
+  const parts: string[] = [];
+  let count = 0;
+  let end = 0;
+  search.lastIndex = 0;
+  try {
+    for (let match = search.exec(text); match; match = search.exec(text)) {
+      count += 1;
+      if (count > maxValues) {
+        throw Object.assign(
+          new Error("the request has too many changing values"),
+          { status: 400 },
+        );
+      }
+      const value = match[0];
+      const name =
+        hasKnown && match[knownGroup] !== undefined
+          ? known.get(value)!
+          : names[groups.findIndex((group) => match[group] !== undefined)]!;
+      const list = values.get(name) ?? [];
+      list.push(value);
+      values.set(name, list);
+      parts.push(text.slice(end, match.index), `<<${name}>>`);
+      end = match.index + value.length;
+      if (value.length === 0) search.lastIndex += 1;
+    }
+  } finally {
+    // `pattern` is shared, so it must not keep a position.
+    search.lastIndex = 0;
+  }
+  parts.push(text.slice(end));
+  return { text: parts.join(""), values };
 }
 
+/**
+ * Whether `value` can be in `known` or in a template (`templateValues()`).
+ * V8 cannot run a pattern with a literal of over 32,767 characters on
+ * any text, also on a text of 5 characters. (A literal with a character
+ * over U+00FF fails only on a text with such a character, and only such a
+ * text can hold it.) Such a value in `known` failed each later request of
+ * its session, so those requests had no key, and to leave it out changes
+ * no key.
+ */
+export const canBeKnown = (value: string): boolean => value.length <= 32_767;
+
 const escape = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
 /**
@@ -200,13 +238,13 @@ const literals = (values: string[]) =>
 /**
  * Write each value of the request that a recorded response repeats as
  * `<<name:n>>`. A value is replaced only where it is not part of a longer
- * word or number.
+ * word or number. A value that `canBeKnown()` refuses stays as it is.
  */
 export function templateValues(text: string, values: RequestValues): string {
   const placeholders = new Map<string, string>();
   for (const [name, list] of values) {
     list.forEach((value, index) => {
-      if (!placeholders.has(value)) {
+      if (!placeholders.has(value) && canBeKnown(value)) {
         placeholders.set(value, `<<${name}:${index + 1}>>`);
       }
     });

package/src/vitest-setup.ts

@@ -19,6 +19,7 @@ import {
   type ProvidedContext,
 } from "vitest";
 import { connectRoach } from "./client.ts";
+import { swapEnv } from "./config.ts";
 
 const provided = inject("roach");
 if (provided === undefined) {
@@ -36,12 +37,10 @@ function useRun(run: NonNullable<ProvidedContext["roach"]>): void {
     // The full name starts with the file, so tests of two files never share
     // a session.
     const session = await control.startSession(task.fullName);
-    const previous = {
-      HTTP_PROXY: process.env.HTTP_PROXY,
-      HTTPS_PROXY: process.env.HTTPS_PROXY,
-    };
-    process.env.HTTP_PROXY = session.url;
-    process.env.HTTPS_PROXY = session.url;
+    const restoreEnv = swapEnv({
+      HTTP_PROXY: session.url,
+      HTTPS_PROXY: session.url,
+    });
     const restoreProxy = http.setGlobalProxyFromEnv({
       HTTP_PROXY: session.url,
       HTTPS_PROXY: session.url,
@@ -49,10 +48,7 @@ function useRun(run: NonNullable<ProvidedContext["roach"]>): void {
     });
     onTestFinished(async ({ task: finished }) => {
       restoreProxy();
-      for (const [name, value] of Object.entries(previous)) {
-        if (value === undefined) delete process.env[name];
-        else process.env[name] = value;
-      }
+      restoreEnv();
       const { missed } = await session.end(finished.result?.state === "pass");
       // `replay` mode failed these requests, so nothing went live. The test
       // must fail, also when it recovered from the error.

package/src/vitest.ts

@@ -19,10 +19,12 @@ import tls from "node:tls";
 import type { TestProject } from "vitest/node";
 import { startRemoteRun } from "./client.ts";
 import {
+  DEFAULT_NO_PROXY,
   DEFAULT_SERVICE_URL,
   readEnv,
   readRoachFile,
   runConfigOf,
+  swapEnv,
 } from "./config.ts";
 import { writeRunReport } from "./report.ts";
 import type { RemoteRun } from "./types.ts";
@@ -44,9 +46,6 @@ declare module "vitest" {
 export async function startRoach(
   project: Pick<TestProject, "provide">,
 ): Promise<() => Promise<void>> {
-  if (typeof http.setGlobalProxyFromEnv !== "function") {
-    throw new Error("Roach needs Node 24.14 or later for vitest");
-  }
   const token = readEnv("ROACH_TOKEN");
   delete process.env.ROACH_TOKEN;
   const file = await readRoachFile();
@@ -55,7 +54,11 @@ export async function startRoach(
     project.provide("roach", null);
     return async () => {};
   }
-  const noProxy = file.noProxy ?? "localhost,127.0.0.1,::1";
+  // Only a run needs it, so `off` mode works on older Node too.
+  if (typeof http.setGlobalProxyFromEnv !== "function") {
+    throw new Error("Roach: vitest needs Node 24.14 or later");
+  }
+  const noProxy = file.noProxy ?? DEFAULT_NO_PROXY;
   const run = await startRemoteRun(
     { url: readEnv("ROACH_URL") ?? DEFAULT_SERVICE_URL, token },
     config,
@@ -65,11 +68,8 @@ export async function startRoach(
   if (process.env.GITHUB_ACTIONS) {
     process.stdout.write(`::add-mask::${run.token}\n`);
   }
-  const previousEnv = Object.keys(run.env).map(
-    (name) => [name, process.env[name]] as const,
-  );
   // Test workers and their child processes start later and inherit these.
-  Object.assign(process.env, run.env);
+  const restoreEnv = swapEnv(run.env);
   // This process started before them, so it reads neither the proxy nor
   // the CA file. Set both here.
   const previousCa = tls.getCACertificates("default");
@@ -94,10 +94,7 @@ export async function startRoach(
     } finally {
       restoreProxy();
       tls.setDefaultCACertificates(previousCa);
-      for (const [name, value] of previousEnv) {
-        if (value === undefined) delete process.env[name];
-        else process.env[name] = value;
-      }
+      restoreEnv();
     }
   };
 }