@sentry/roach 0.0.0-stage → 0.3.0

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@sentry/roach",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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",
+    "directory": "packages/roach"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    "./client": "./src/client.ts",
+    "./report": "./src/report.ts",
+    "./types": "./src/types.ts",
+    "./values": "./src/values.ts",
+    "./vitest": "./src/vitest.ts",
+    "./vitest/setup": "./src/vitest-setup.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  },
+  "peerDependencies": {
+    "vitest": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p ."
+  }
 }

package/src/action.ts

@@ -0,0 +1,83 @@
+/**
+ * The GitHub Action of Roach (`action.yml`). See "Use the GitHub Action" in
+ * `README.md`.
+ *
+ * It starts a run, runs the command of the step with the proxy variables of
+ * the run, and ends the run. The run config comes from `roach.json`
+ * (`config.ts`).
+ * The runner gives each input as `INPUT_<NAME>`.
+ */
+import { spawn } from "node:child_process";
+import { startRemoteRun } from "./client.ts";
+import { readEnv, readRoachFile, runConfigOf } from "./config.ts";
+import { writeRunReport } from "./report.ts";
+
+/**
+ * Variables that the command does not get: the inputs, which have the token,
+ * 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_.*|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> {
+  // `detached` puts bash and its children in a new process group.
+  const child = spawn("bash", ["-e", "-o", "pipefail", "-c", command], {
+    detached: true,
+    env,
+    stdio: "inherit",
+  });
+  // A canceled job sends a signal. Bash does not pass it to its children, so
+  // send it to the whole process group. Then end the run.
+  const stop = (signal: NodeJS.Signals) => {
+    try {
+      process.kill(-child.pid!, signal);
+    } catch {
+      // The process group has already stopped.
+    }
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  return new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code) => {
+      // Stop what the command left in the background, such as `cmd &`. Bash
+      // makes it ignore `SIGINT`, and the run ends next.
+      stop("SIGTERM");
+      resolve(code ?? 1);
+    });
+  });
+}
+
+const command = process.env.INPUT_RUN;
+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();
+const config = runConfigOf(file, { canWrite: token !== undefined });
+const run = await startRemoteRun(
+  { url: process.env.INPUT_URL!, token },
+  config,
+  file.noProxy ? { noProxy: file.noProxy } : {},
+);
+// The proxy URL has the run token. Keep it out of the log.
+process.stdout.write(`::add-mask::${run.token}\n`);
+
+let exitCode = 1;
+try {
+  const session = await run.startSession(process.env.GITHUB_JOB ?? "command");
+  exitCode = await runCommand(command, {
+    ...Object.fromEntries(
+      Object.entries(process.env).filter(
+        ([name]) => !HIDDEN_VARIABLE.test(name),
+      ),
+    ),
+    ...run.env,
+  });
+  const { missed } = await session.end(exitCode === 0);
+  if (missed > 0 && exitCode === 0) exitCode = 1;
+} finally {
+  await writeRunReport(`Roach (${config.mode})`, await run.close());
+}
+process.exitCode = exitCode;

package/src/client.ts

@@ -0,0 +1,234 @@
+/**
+ * The client of Roach. See `README.md`.
+ *
+ * `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,
+  type RecordingStats,
+  type RemoteRun,
+  type RunConfig,
+} from "./types.ts";
+
+/** The open session of one test. */
+export interface RecordingSession {
+  /**
+   * The proxy URL of the session. Send the requests of the test through
+   * it when other sessions of the run can be open at the same time.
+   */
+  url: string;
+  /**
+   * End the session. A passed session writes its new recordings, and a
+   * failed one drops them. `missed` counts the requests of the session that
+   * `replay` mode failed. A test with a miss must fail.
+   */
+  end(passed: boolean): Promise<{ missed: number }>;
+}
+
+/** The control API of a run. */
+export interface RoachControl {
+  /**
+   * Open the session of one test. Many sessions can be open at once. A
+   * request through `url` of the run belongs to the open session only when
+   * one is open, so concurrent tests send through `url` of their session.
+   */
+  startSession(name: string): Promise<RecordingSession>;
+  /** The totals of the run. */
+  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.
+ */
+function callControl<T>(
+  base: string,
+  token: string | undefined,
+  method: "DELETE" | "GET" | "POST",
+  route: string,
+  body?: unknown,
+): Promise<T> {
+  const payload = body === undefined ? undefined : JSON.stringify(body);
+  const url = route ? `${base}/${route}` : base;
+  const send = url.startsWith("https:") ? httpsRequest : httpRequest;
+  return new Promise((resolve, reject) => {
+    const request = send(
+      url,
+      {
+        // Its own agent, so that a proxy agent of the process is not used.
+        agent: false,
+        method,
+        headers: {
+          ...(token ? { authorization: `Bearer ${token}` } : {}),
+          ...(payload ? { "content-type": "application/json" } : {}),
+        },
+      },
+      (response) => {
+        const chunks: Buffer[] = [];
+        response.on("data", (chunk: Buffer) => chunks.push(chunk));
+        response.on("end", () => {
+          const text = Buffer.concat(chunks).toString("utf8");
+          const status = response.statusCode ?? 500;
+          if (status >= 400) {
+            reject(
+              new Error(
+                `Roach: ${method} ${route} failed with HTTP ${status}: ${text}`,
+              ),
+            );
+          } else {
+            resolve((text ? JSON.parse(text) : undefined) as T);
+          }
+        });
+        response.on("error", reject);
+      },
+    );
+    request.on("error", reject);
+    request.end(payload);
+  });
+}
+
+/**
+ * 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,
+  token,
+}: Pick<RemoteRun, "controlUrl" | "token">): RoachControl {
+  return {
+    async startSession(name) {
+      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) =>
+          callControl(controlUrl, token, "POST", "session/end", {
+            name,
+            passed,
+          }),
+      };
+    },
+    stats: () => callControl(controlUrl, token, "GET", "stats"),
+  };
+}
+
+/** 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:
+   * `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, `NODE_USE_ENV_PROXY`, and
+   * `NODE_EXTRA_CA_CERTS`. Give them to a process when it starts. Node
+   * reads the last two only at startup.
+   */
+  env: Record<string, string>;
+  /** End the run. Returns its stats. */
+  close(): Promise<RecordingStats>;
+}
+
+/**
+ * Start a run on a Roach service, such as `https://roach.example.com`.
+ *
+ * `token` is the write token of the service. Only this call uses it. Without it,
+ * the service only allows `replay` mode, so CI jobs of forks can replay
+ * without a secret. The run and its workers use the run token.
+ */
+export async function startRemoteRun(
+  service: { url: string; token?: string | undefined },
+  config: RunConfig,
+  { noProxy = DEFAULT_NO_PROXY }: { noProxy?: string } = {},
+): Promise<RemoteRoach> {
+  const run = await callControl<RemoteRun>(
+    `${service.url.replace(/\/$/, "")}${CONTROL_PATH}`,
+    service.token,
+    "POST",
+    "runs",
+    config,
+  );
+  const proxyEnv = await createProxyEnv(run, noProxy).catch(async (error) => {
+    // End the run, or it stays open until the service times it out.
+    await callControl(run.controlUrl, run.token, "DELETE", "").catch(() => {});
+    throw error;
+  });
+  return {
+    ...run,
+    ...connectRoach(run),
+    env: proxyEnv.env,
+    async close() {
+      try {
+        return await callControl<RecordingStats>(
+          run.controlUrl,
+          run.token,
+          "DELETE",
+          "",
+        );
+      } finally {
+        await proxyEnv.remove();
+      }
+    },
+  };
+}
+
+/**
+ * The proxy variables of a process, with the CA certificate in a file. The
+ * file also has the certificates of `NODE_EXTRA_CA_CERTS` of this process,
+ * so the process still trusts them.
+ */
+async function createProxyEnv(
+  address: Pick<RemoteRun, "caCert" | "url">,
+  noProxy: string,
+): Promise<{ env: Record<string, string>; remove(): Promise<void> }> {
+  // `NODE_EXTRA_CA_CERTS` takes a file.
+  const caDirectory = await mkdtemp(path.join(tmpdir(), "roach-"));
+  const caFile = path.join(caDirectory, "ca.pem");
+  const extra = process.env.NODE_EXTRA_CA_CERTS;
+  await writeFile(
+    caFile,
+    extra
+      ? `${address.caCert.trimEnd()}\n${await readFile(extra, "utf8")}`
+      : address.caCert,
+  );
+  return {
+    env: {
+      HTTP_PROXY: address.url,
+      HTTPS_PROXY: address.url,
+      NO_PROXY: noProxy,
+      NODE_USE_ENV_PROXY: "1",
+      NODE_EXTRA_CA_CERTS: caFile,
+    },
+    remove: () => rm(caDirectory, { force: true, recursive: true }),
+  };
+}

package/src/config.ts

@@ -0,0 +1,188 @@
+/**
+ * `roach.json`: the run config of a repository. The GitHub Action
+ * (`action.ts`) and the vitest integration (`vitest.ts`) both read it, so a
+ * repository writes its origins and rules once, as data. See "Config file"
+ * in `README.md`.
+ */
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+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";
+
+/**
+ * A changing value in `roach.json`: a regular expression source, or the
+ * name of a pattern in `VALUE_PATTERNS`, such as `{ "builtin": "uuid" }`.
+ */
+type FileValue = string | { builtin: keyof typeof VALUE_PATTERNS };
+
+/** A rule in `roach.json`. */
+interface FileRule extends Omit<RecordingRule, "values"> {
+  values?: Record<string, FileValue>;
+}
+
+/** The content of `roach.json`. */
+export interface RoachFile {
+  allow: string[];
+  rules: FileRule[];
+  /** Default: `GITHUB_REPOSITORY`. */
+  tenant?: string;
+  /**
+   * Environment variables that hold credentials, such as
+   * `ANTHROPIC_API_KEY`. The run never writes their values.
+   */
+  secretEnv?: string[];
+  /** Hosts that do not use the proxy. Default: loopback. */
+  noProxy?: string;
+}
+
+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,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const value = env[name]?.trim();
+  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.
+ */
+export async function readRoachFile(
+  from = process.cwd(),
+): Promise<RoachFile & { path: string }> {
+  for (let directory = path.resolve(from); ;) {
+    const file = path.join(directory, FILE_NAME);
+    const found = await access(file).then(
+      () => true,
+      () => false,
+    );
+    if (found) {
+      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) {
+      throw new Error(`Roach: no ${FILE_NAME} in ${from} or its parents`);
+    }
+    directory = parent;
+  }
+}
+
+function resolveValue(rule: string, name: string, value: FileValue): string {
+  if (typeof value === "string") return value;
+  const pattern = VALUE_PATTERNS[value.builtin];
+  if (!pattern) {
+    throw new Error(
+      `Roach: rule ${rule} value ${name} names no built-in pattern: ${value.builtin}`,
+    );
+  }
+  return pattern;
+}
+
+/**
+ * The run config of `file` in the environment `env`. Without the write
+ * token (`canWrite`), the mode is `replay`, as for forks. `ROACH_MODE`
+ * sets another mode.
+ */
+export function runConfigOf(
+  file: RoachFile,
+  {
+    canWrite,
+    env = process.env,
+  }: { canWrite: boolean; env?: NodeJS.ProcessEnv },
+): RunConfig {
+  const mode = readEnv("ROACH_MODE", env) ?? (canWrite ? "auto" : "replay");
+  if (!MODES.has(mode)) {
+    throw new Error(
+      `Roach: ROACH_MODE must be auto, replay, record, or off, got ${mode}`,
+    );
+  }
+  const tenant = file.tenant ?? env.GITHUB_REPOSITORY;
+  if (!tenant) {
+    throw new Error(
+      `Roach: set tenant in ${FILE_NAME}, or run with GITHUB_REPOSITORY`,
+    );
+  }
+  const config: RunConfig = {
+    tenant,
+    mode: mode as RecordingMode,
+    allow: file.allow,
+    rules: file.rules.map(({ values, ...rule }) =>
+      values
+        ? {
+            ...rule,
+            values: Object.fromEntries(
+              Object.entries(values).map(([name, value]) => [
+                name,
+                resolveValue(rule.name, name, value),
+              ]),
+            ),
+          }
+        : rule,
+    ),
+    secrets: (file.secretEnv ?? []).flatMap((name) => readEnv(name, env) ?? []),
+  };
+  const runId = readEnv("GITHUB_RUN_ID", env);
+  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

@@ -0,0 +1,86 @@
+/**
+ * Text reports of a Roach run, for logs and CI summaries.
+ */
+import { appendFile } from "node:fs/promises";
+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 {
+  const rules = Object.entries(stats.counts)
+    .map(
+      ([rule, { live, missed, replayed }]) =>
+        `${rule} ${replayed} replayed, ${live} live${missed ? `, ${missed} missed` : ""}`,
+    )
+    .join("; ");
+  const passthrough =
+    Object.entries(stats.passthrough)
+      .map(([origin, count]) => `${origin} ${count}`)
+      .join(", ") || "none";
+  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 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>();
+  return misses
+    .filter((miss) => {
+      const first = !seen.has(miss.session);
+      seen.add(miss.session);
+      return first;
+    })
+    .map(
+      (miss) =>
+        `${miss.session ?? "outside a test"}: ${miss.file}${miss.change ? describeChange(miss.change) : ""}`,
+    );
+}
+
+/**
+ * Write the report of a run to stdout, and in GitHub Actions also to the
+ * job summary. `title` names the run, such as `Roach (auto)`.
+ */
+export async function writeRunReport(
+  title: string,
+  stats: RecordingStats,
+): Promise<void> {
+  const report = [
+    `${title}: ${describeRecordingStats(stats)}`,
+    ...describeRecordingMisses(stats.misses).map((miss) => `- ${miss}`),
+  ].join("\n");
+  process.stdout.write(`${report}\n`);
+  if (process.env.GITHUB_STEP_SUMMARY) {
+    await appendFile(process.env.GITHUB_STEP_SUMMARY, `${report}\n`);
+  }
+}