@sentry/roach 0.0.0-stage → 0.2.0

package/src/config.ts

@@ -0,0 +1,141 @@
+/**
+ * `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, 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 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"]);
+
+/** 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;
+}
+
+/**
+ * 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) {
+      return {
+        ...(JSON.parse(await readFile(file, "utf8")) as RoachFile),
+        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"}`;
+  }
+  return config;
+}

package/src/gcs.ts

@@ -0,0 +1,145 @@
+/**
+ * The GCS store: the recordings of the shared service (`service.ts`) in a
+ * Google Cloud Storage bucket.
+ *
+ * Each recording is the object `<prefix><key>`. A lifecycle rule of the
+ * bucket deletes it 30 days after it was written (`deploy/gcp/`), so
+ * nothing here deletes recordings.
+ *
+ * The store calls the JSON API with `fetch`, and takes its access token
+ * from the metadata server of the VM. So it needs no key file and no
+ * Google SDK. Two standard variables change the hosts, for local tests:
+ * `STORAGE_EMULATOR_HOST` (a URL) and `GCE_METADATA_HOST` (a host).
+ */
+import {
+  formatRecording,
+  type Recording,
+  type RecordingStore,
+} from "./store.ts";
+
+/** A call that takes longer than this fails. */
+const TIMEOUT_MS = 30_000;
+/** Tries of one call. GCS asks clients to retry 429 and 5xx. */
+const TRIES = 3;
+/** Get a new token when the current one expires within this time. */
+const TOKEN_MARGIN_MS = 60_000;
+
+const isTemporary = (status: number) => status === 429 || status >= 500;
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** `fetch`, with a timeout and retries of temporary failures. */
+async function call(url: string, init: RequestInit): Promise<Response> {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      const response = await fetch(url, {
+        ...init,
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+      });
+      if (!isTemporary(response.status) || attempt === TRIES) return response;
+      await response.body?.cancel();
+    } catch (error) {
+      if (attempt === TRIES) throw error;
+    }
+    await wait(250 * 2 ** attempt);
+  }
+}
+
+/** The access token of the VM service account, from the metadata server. */
+function createTokenSource(metadataHost: string): () => Promise<string> {
+  let cached: { token: string; expires: number } | undefined;
+  return async () => {
+    if (cached && cached.expires - TOKEN_MARGIN_MS > Date.now()) {
+      return cached.token;
+    }
+    const response = await call(
+      `http://${metadataHost}/computeMetadata/v1/instance/service-accounts/default/token`,
+      { headers: { "metadata-flavor": "Google" } },
+    );
+    if (!response.ok) {
+      throw new Error(
+        `GCE metadata token failed with HTTP ${response.status}: ${await response.text()}`,
+      );
+    }
+    const body = (await response.json()) as {
+      access_token: string;
+      expires_in: number;
+    };
+    cached = {
+      token: body.access_token,
+      expires: Date.now() + body.expires_in * 1000,
+    };
+    return cached.token;
+  };
+}
+
+/** Where the store sends its calls. */
+interface GcsHosts {
+  /** The base URL of the storage API. */
+  storage: string;
+  /** The host of the metadata server. */
+  metadata: string;
+}
+
+/** The hosts of GCS, or the ones of the standard variables. */
+function gcsHosts(env = process.env): GcsHosts {
+  return {
+    storage: (
+      env.STORAGE_EMULATOR_HOST ?? "https://storage.googleapis.com"
+    ).replace(/\/$/, ""),
+    metadata: env.GCE_METADATA_HOST ?? "metadata.google.internal",
+  };
+}
+
+/** The store of the recordings in `bucket`, under `prefix`. */
+export function createGcsStore(bucket: string, prefix: string): RecordingStore {
+  const hosts = gcsHosts();
+  const token = createTokenSource(hosts.metadata);
+  const bucketPath = `b/${encodeURIComponent(bucket)}/o`;
+
+  const writeOne = async ([key, recording]: [string, Recording]) => {
+    const name = encodeURIComponent(`${prefix}${key}`);
+    const response = await call(
+      `${hosts.storage}/upload/storage/v1/${bucketPath}?uploadType=media&name=${name}`,
+      {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${await token()}`,
+          "content-type": "application/json",
+        },
+        body: formatRecording(recording),
+      },
+    );
+    if (!response.ok) {
+      throw new Error(
+        `GCS write of ${key} failed with HTTP ${response.status}: ${await response.text()}`,
+      );
+    }
+    await response.body?.cancel();
+  };
+
+  return {
+    async read(key) {
+      const name = encodeURIComponent(`${prefix}${key}`);
+      const response = await call(
+        `${hosts.storage}/storage/v1/${bucketPath}/${name}?alt=media`,
+        { headers: { authorization: `Bearer ${await token()}` } },
+      );
+      if (response.status === 404) {
+        await response.body?.cancel();
+        return undefined;
+      }
+      if (!response.ok) {
+        throw new Error(
+          `GCS read of ${key} failed with HTTP ${response.status}: ${await response.text()}`,
+        );
+      }
+      return (await response.json()) as Recording;
+    },
+
+    // GCS does not say if an object changed, so each write counts.
+    async write(recordings) {
+      await Promise.all(recordings.map(writeOne));
+      return recordings.length;
+    },
+  };
+}