@sentry/roach 0.2.0 → 0.3.0

package/src/recorder.ts

@@ -1,464 +0,0 @@
-/**
- * The recording logic of the proxy: modes, sessions, replay, and misses.
- *
- * `server.ts` owns the sockets. It gives the recorder each request that a
- * rule matches, with a function that sends the request live. The recorder
- * decides whether to replay, send live, or fail the request, and it owns
- * every read and write of the recordings. A store keeps them: the file
- * store (`recordings.ts`) or a GCS bucket (`gcs.ts`).
- *
- * A session groups the requests of one test. Many sessions can be open at
- * once, such as one for each test worker. A request names its session in
- * its proxy URL (`service.ts`). A request that names no session belongs to
- * the open session when only one is open. The recorder keeps the new
- * recordings of a session in memory until the session ends. A passed
- * session writes them, and a failed session drops them, so a bad sample is
- * never replayed. A request that ends after its session ended follows the
- * result of that session. A request outside a session is written at once.
- *
- * The recorder never writes a known credential (`secrets.ts`). It reports
- * spans and metrics through the `Telemetry` hooks of `service.ts`.
- */
-import { randomBytes } from "node:crypto";
-import type { IncomingHttpHeaders } from "node:http";
-import { keyRequest, type KeyedRequest } from "./request-key.ts";
-import { createSecrets } from "./secrets.ts";
-import {
-  recordingKey,
-  RULE_NAME,
-  type Recording,
-  type RecordingStore,
-} from "./store.ts";
-import {
-  isEventStream,
-  mapStreamEvents,
-  mergeStreamDeltas,
-} from "./streams.ts";
-import { usageAttributes } from "./usage.ts";
-import type {
-  RecordingMiss,
-  RecordingMode,
-  RecordingRule,
-  RecordingStats,
-} from "./types.ts";
-import { fillValues, templateValues, type RequestValues } from "./values.ts";
-
-/** A request with its whole body. */
-export interface ProxyRequest {
-  method: string;
-  url: URL;
-  headers: IncomingHttpHeaders;
-  body: Buffer;
-}
-
-/** A response with its whole body. */
-export interface ProxyResponse {
-  status: number;
-  headers: IncomingHttpHeaders;
-  body: Buffer;
-}
-
-/** Where the response to a recorded request came from. */
-export type ResponseSource = "live" | "missed" | "replayed";
-
-/** The attributes of a span or a metric. */
-type Attributes = Record<string, string | number | boolean>;
-
-/**
- * Hooks that report spans and metrics. `service.ts` gives hooks that send
- * them to Sentry, so this file and `server.ts` do not load the SDK. An
- * attribute must never hold a credential, a body, or the path or query of
- * a URL.
- */
-export interface Telemetry {
-  /** Run `fn` in a span. The span ends when `fn` returns or settles. */
-  span<T>(
-    options: { op: string; name?: string; attributes?: Attributes },
-    fn: () => T,
-  ): T;
-  /** Add attributes to the active span. */
-  annotate(attributes: Attributes): void;
-  /** Add `value` to the counter `name`. */
-  count(name: string, value: number, attributes: Attributes): void;
-  /** Add a time in milliseconds to the distribution `name`. */
-  time(name: string, ms: number, attributes: Attributes): void;
-}
-
-interface Session {
-  /** The id in the proxy URL of the session. */
-  id: string;
-  name: string;
-  /** New recordings, by key. */
-  recorded: Map<string, Recording>;
-  /** Requests that `replay` mode failed. */
-  missed: number;
-  /**
-   * Changing values of the requests so far, with their names. A later
-   * request can repeat one where no pattern finds it (`values.ts`).
-   */
-  known: Map<string, string>;
-  /** Set when the session ends. */
-  passed?: boolean;
-}
-
-const MAX_MISSES = 500;
-/**
- * Ended sessions that a run keeps, so that late requests follow their
- * result. The oldest ones go first, so memory stays bounded.
- */
-const MAX_ENDED_SESSIONS = 1000;
-/** Open sessions of a run, such as one for each test worker. */
-const MAX_OPEN_SESSIONS = 64;
-/** Response headers that a recording keeps. Other headers change each run. */
-const RECORDED_HEADERS = ["content-type", "location"];
-const NULL_BODY_STATUSES = new Set([101, 204, 205, 304]);
-
-/** Statuses that are never recorded, because they are temporary. */
-const isTemporaryStatus = (status: number) => status === 429 || status >= 500;
-
-function matches(
-  { match }: RecordingRule,
-  { method, url, headers }: ProxyRequest,
-): boolean {
-  if (match.method && match.method !== method) return false;
-  if (match.url && !url.href.startsWith(match.url)) return false;
-  return Object.entries(match.headers ?? {}).every(
-    ([name, value]) => headers[name] === value,
-  );
-}
-
-/**
- * The response as a recording keeps it. A stream gets one delta per content
- * block, and each value of the request becomes a placeholder.
- */
-function toRecording(
-  request: ProxyRequest,
-  keyed: KeyedRequest,
-  session: string | undefined,
-  response: ProxyResponse,
-): Recording {
-  const contentType = response.headers["content-type"];
-  const headers: Record<string, string> = {};
-  for (const name of RECORDED_HEADERS) {
-    const value = response.headers[name];
-    if (typeof value === "string") headers[name] = value;
-  }
-  let body = response.body.toString("base64");
-  let bodyEncoding: Recording["response"]["bodyEncoding"] = "base64";
-  if (/^text\/|json|xml/i.test(contentType ?? "")) {
-    const text = response.body.toString("utf8");
-    const template = (part: string) => templateValues(part, keyed.values);
-    body = isEventStream(contentType)
-      ? mapStreamEvents(mergeStreamDeltas(text), template)
-      : template(text);
-    bodyEncoding = "utf8";
-  }
-  return {
-    session,
-    request: { method: request.method, url: request.url.href },
-    response: { status: response.status, headers, body, bodyEncoding },
-  };
-}
-
-/** The response of a recording, with the values of the current request. */
-function fromRecording(
-  { response }: Recording,
-  values: RequestValues,
-): ProxyResponse {
-  const body = NULL_BODY_STATUSES.has(response.status)
-    ? Buffer.alloc(0)
-    : response.bodyEncoding === "utf8"
-      ? Buffer.from(fillValues(response.body, values))
-      : Buffer.from(response.body, "base64");
-  return { status: response.status, headers: response.headers, body };
-}
-
-/** The config of a recorder. */
-export interface RecorderConfig {
-  mode: RecordingMode;
-  rules: RecordingRule[];
-  /** Credentials to redact, in addition to the ones that it learns. */
-  secrets?: string[];
-  telemetry: Telemetry;
-}
-
-/** Create the recorder of one run, with the store of its recordings. */
-export function createRecorder(config: RecorderConfig, store: RecordingStore) {
-  for (const rule of config.rules) {
-    if (!RULE_NAME.test(rule.name)) {
-      throw new Error(`Roach rule name is not valid: ${rule.name}`);
-    }
-  }
-  /** Sessions by id. An ended session stays, so its late requests follow it. */
-  const sessions = new Map<string, Session>();
-  const open = () =>
-    [...sessions.values()].filter((s) => s.passed === undefined);
-  const { telemetry } = config;
-  const secrets = createSecrets(config.secrets);
-  const stats: RecordingStats = {
-    counts: Object.fromEntries(
-      config.rules.map((rule) => [
-        rule.name,
-        { live: 0, missed: 0, replayed: 0 },
-      ]),
-    ),
-    misses: [],
-    written: 0,
-    discarded: 0,
-    passthrough: {},
-  };
-  /** Count recordings by rule in `roach.recording.write`. */
-  const countRecordings = (keys: string[], result: "dropped" | "written") => {
-    const byRule = new Map<string, number>();
-    for (const key of keys) {
-      const rule = key.slice(0, key.indexOf("/"));
-      byRule.set(rule, (byRule.get(rule) ?? 0) + 1);
-    }
-    for (const [rule, value] of byRule) {
-      telemetry.count("roach.recording.write", value, { rule, result });
-    }
-  };
-  const write = async (recordings: Array<[string, Recording]>) => {
-    stats.written += await store.write(recordings);
-    countRecordings(
-      recordings.map(([key]) => key),
-      "written",
-    );
-  };
-  const drop = (keys: string[]) => {
-    stats.discarded += keys.length;
-    countRecordings(keys, "dropped");
-  };
-
-  const record = async (
-    owner: Session | undefined,
-    key: string,
-    recording: Recording,
-  ) => {
-    if (owner && owner.passed === undefined) {
-      owner.recorded.set(key, recording);
-    } else if (owner?.passed === false) {
-      drop([key]);
-    } else {
-      await write([[key, recording]]);
-    }
-  };
-
-  const reportMiss = (rule: RecordingRule, key: string, owner?: Session) => {
-    const miss: RecordingMiss = {
-      rule: rule.name,
-      session: owner?.name,
-      file: key,
-    };
-    if (stats.misses.length < MAX_MISSES) stats.misses.push(miss);
-    const where = owner ? ` in "${owner.name}"` : "";
-    process.stderr.write(`[roach] No ${rule.name} recording${where}: ${key}\n`);
-  };
-
-  /** End a session. Returns its requests that `replay` mode failed. */
-  const finish = async (ended: Session, passed: boolean): Promise<number> => {
-    ended.passed = passed;
-    const recorded = [...ended.recorded];
-    ended.recorded.clear();
-    ended.known.clear();
-    if (passed) await write(recorded);
-    else drop(recorded.map(([key]) => key));
-    return ended.missed;
-  };
-
-  /**
-   * The session of a request. `id` comes from its proxy URL. Without it,
-   * the request belongs to the open session when only one is open.
-   */
-  const sessionOf = (id: string | undefined): Session | undefined => {
-    if (id !== undefined) return sessions.get(id);
-    const current = open();
-    return current.length === 1 ? current[0] : undefined;
-  };
-
-  return {
-    /** The rule that records a request, or `undefined` when none does. */
-    ruleFor(request: ProxyRequest): RecordingRule | undefined {
-      if (config.mode === "off") return undefined;
-      return config.rules.find((rule) => matches(rule, request));
-    },
-
-    /** Count a request that no rule records, and learn its credentials. */
-    countPassthrough(origin: string, headers: IncomingHttpHeaders): void {
-      secrets.learn(headers);
-      stats.passthrough[origin] = (stats.passthrough[origin] ?? 0) + 1;
-      telemetry.annotate({ result: "passthrough" });
-      telemetry.count("roach.request", 1, { origin, result: "passthrough" });
-    },
-
-    /**
-     * Answer a request that `rule` records. `sendLive` sends it upstream.
-     * A live response goes through the same template as a recording, so
-     * the client gets the same body from a live run and from a replay.
-     */
-    async respond(
-      rule: RecordingRule,
-      request: ProxyRequest,
-      sendLive: () => Promise<ProxyResponse>,
-      sessionId?: string,
-    ): Promise<ProxyResponse & { source: ResponseSource }> {
-      const started = performance.now();
-      const origin = request.url.origin;
-      // A request belongs to the session that was open when it started.
-      const owner = sessionOf(sessionId);
-      const counts = stats.counts[rule.name]!;
-      secrets.learn(request.headers);
-      telemetry.annotate({ rule: rule.name });
-      const { keyed, key } = telemetry.span(
-        { op: "roach.key", attributes: { rule: rule.name } },
-        () => {
-          const result = keyRequest(
-            rule,
-            {
-              method: request.method,
-              url: request.url.href,
-              headers: request.headers,
-              body: request.body.toString("utf8"),
-            },
-            owner?.known,
-          );
-          const name = recordingKey(rule.name, result.key);
-          telemetry.annotate({ key: name });
-          return { keyed: result, key: name };
-        },
-      );
-      if (owner) {
-        for (const [name, list] of keyed.values) {
-          for (const value of list) {
-            if (!owner.known.has(value)) owner.known.set(value, name);
-          }
-        }
-      }
-      const report = (result: ResponseSource, response?: ProxyResponse) => {
-        const attributes = { rule: rule.name, origin, result };
-        telemetry.annotate({ result });
-        const usage =
-          response &&
-          usageAttributes(
-            request.body.toString("utf8"),
-            response.headers["content-type"],
-            response.body.toString("utf8"),
-          );
-        if (usage) telemetry.annotate(usage);
-        telemetry.count("roach.request", 1, attributes);
-        telemetry.time(
-          "roach.request.duration",
-          performance.now() - started,
-          attributes,
-        );
-      };
-
-      if (config.mode !== "record") {
-        const recording = await store.read(key);
-        if (recording) {
-          counts.replayed += 1;
-          const response = fromRecording(recording, keyed.values);
-          report("replayed", response);
-          return { ...response, source: "replayed" };
-        }
-        reportMiss(rule, key, owner);
-        if (config.mode === "replay") {
-          counts.missed += 1;
-          if (owner) owner.missed += 1;
-          report("missed");
-          return {
-            status: 412,
-            headers: { "content-type": "text/plain" },
-            body: Buffer.from(
-              `Roach: no ${rule.name} recording for this request in replay mode. Run in auto mode to record it.\n`,
-            ),
-            source: "missed",
-          };
-        }
-      }
-
-      counts.live += 1;
-      const live = await telemetry.span(
-        {
-          op: "roach.upstream",
-          name: `${request.method} ${origin}`,
-          attributes: { origin, "http.request.method": request.method },
-        },
-        async () => {
-          const response = await sendLive();
-          telemetry.annotate({ "http.response.status_code": response.status });
-          return response;
-        },
-      );
-      // The client gets the redacted response too, so a live run and a
-      // replay give the same body.
-      const recording = JSON.parse(
-        secrets.redact(
-          JSON.stringify(toRecording(request, keyed, owner?.name, live)),
-        ),
-      ) as Recording;
-      if (!isTemporaryStatus(recording.response.status)) {
-        await record(owner, key, recording);
-      }
-      const response = fromRecording(recording, keyed.values);
-      report("live", response);
-      return { ...response, source: "live" };
-    },
-
-    /**
-     * Open the session of one test, and return its id. An open session with
-     * the same name fails first. Throws when the run has too many open
-     * sessions.
-     */
-    async startSession(name: string): Promise<string> {
-      const same = open().find((other) => other.name === name);
-      if (same) {
-        process.stderr.write(
-          `[roach] Session "${name}" did not end, so its new recordings were dropped\n`,
-        );
-        await finish(same, false);
-      }
-      if (open().length >= MAX_OPEN_SESSIONS) {
-        throw new Error(`A run can have ${MAX_OPEN_SESSIONS} open sessions`);
-      }
-      const ended = [...sessions.values()].filter(
-        (other) => other.passed !== undefined,
-      );
-      const extra = ended.length - MAX_ENDED_SESSIONS + 1;
-      for (const old of ended.slice(0, Math.max(0, extra))) {
-        sessions.delete(old.id);
-      }
-      const id = randomBytes(8).toString("hex");
-      sessions.set(id, {
-        id,
-        name,
-        recorded: new Map(),
-        missed: 0,
-        known: new Map(),
-      });
-      return id;
-    },
-
-    /**
-     * End the open session `name`. Returns its requests that `replay` mode
-     * failed. Throws when no open session has that name.
-     */
-    async endSession(name: string, passed: boolean): Promise<number> {
-      const ended = open().find((other) => other.name === name);
-      if (!ended) throw new Error(`Session "${name}" is not open`);
-      return finish(ended, passed);
-    },
-
-    stats(): RecordingStats {
-      return stats;
-    },
-
-    /** Fail the open sessions. */
-    async close(): Promise<void> {
-      for (const session of open()) await finish(session, false);
-    },
-  };
-}
-
-/** The recorder of one run. */
-export type Recorder = ReturnType<typeof createRecorder>;

package/src/recordings.ts

@@ -1,42 +0,0 @@
-/**
- * The file store. It keeps each recording (`store.ts`) in
- * `<directory>/<key>`. The service uses it when its config has
- * `directory`, such as in tests.
- */
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
-import {
-  formatRecording,
-  type Recording,
-  type RecordingStore,
-} from "./store.ts";
-
-const readText = (file: string) =>
-  readFile(file, "utf8").catch((error: unknown) => {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
-    throw error;
-  });
-
-/** The store of the recordings in `directory`. */
-export function createFileStore(directory: string): RecordingStore {
-  return {
-    async read(key) {
-      const text = await readText(path.join(directory, key));
-      return text === undefined ? undefined : (JSON.parse(text) as Recording);
-    },
-
-    async write(recordings) {
-      const changed = await Promise.all(
-        recordings.map(async ([key, recording]) => {
-          const file = path.join(directory, key);
-          const content = formatRecording(recording);
-          if ((await readText(file)) === content) return false;
-          await mkdir(path.dirname(file), { recursive: true });
-          await writeFile(file, content);
-          return true;
-        }),
-      );
-      return changed.filter(Boolean).length;
-    },
-  };
-}

package/src/request-key.ts

@@ -1,165 +0,0 @@
-/**
- * The key of a recorded request.
- *
- * The key is the hash of the rule, the method, the URL, the key headers,
- * and the body. A JSON body has sorted object keys, so key order does not
- * matter. Each changing value of the rule is `<<name>>` in the key
- * (`values.ts`).
- *
- * The patterns of `values` come from the client, and all runs share one
- * process. A slow pattern would block every run, so a key has a time limit
- * (`KEY_TIME_LIMIT`).
- */
-import { createHash } from "node:crypto";
-import type { IncomingHttpHeaders } from "node:http";
-import { THINKING_BLOCK_TYPES } from "./streams.ts";
-import type { RecordingRule } from "./types.ts";
-import {
-  extractValues,
-  type KnownValues,
-  type RequestValues,
-  type ValuePatterns,
-  withTimeLimit,
-} from "./values.ts";
-
-/** Change this to make every recording a miss. */
-const KEY_VERSION = "http-v1";
-
-/**
- * The time that the key of one request can take: 1 s, and 0.5 s for each
- * MiB of the body. The built-in patterns take less than 0.1 s for each
- * MiB. A key that takes longer fails its request, and other runs go on.
- */
-const KEY_TIME_LIMIT = { baseMs: 1000, msPerMiB: 500 };
-
-/** The parts of a request that make its key. */
-interface RequestToKey {
-  method: string;
-  url: string;
-  headers: IncomingHttpHeaders;
-  body: string;
-}
-
-/** A request as the key sees it. */
-export interface KeyedRequest {
-  /** The name of the recording file, without `.json`. */
-  key: string;
-  /**
-   * The changing values of the request outside thinking blocks, in their
-   * order. They fill the placeholders of a replayed response.
-   */
-  values: RequestValues;
-}
-
-/** JSON with sorted object keys, so equal bodies give equal keys. */
-function stableStringify(value: unknown): string {
-  if (value === null || typeof value !== "object") {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) {
-    return `[${value.map(stableStringify).join(",")}]`;
-  }
-  const entries = Object.entries(value as Record<string, unknown>)
-    .filter(([, item]) => item !== undefined)
-    .toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-  return `{${entries
-    .map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`)
-    .join(",")}}`;
-}
-
-function parseJson(body: string): unknown {
-  try {
-    return body ? JSON.parse(body) : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/** Marks the place of a thinking block in the text of a body. */
-const THINKING_MARK = /"\uE000(\d+)"/g;
-
-/**
- * The text of a JSON value with `<<name>>` for each changing value, and the
- * values outside thinking blocks.
- *
- * A replay keeps the recorded text of a thinking block (`streams.ts`), and
- * a later request sends it back. So its values come from the recording
- * run. They are in the key, but they do not fill placeholders, and known
- * values of this run are not looked for in them.
- */
-function normalizeJson(
-  json: unknown,
-  patterns: ValuePatterns | undefined,
-  known: KnownValues | undefined,
-): { text: string; values: RequestValues } {
-  const thinking: string[] = [];
-  const mark = (value: unknown): unknown => {
-    if (Array.isArray(value)) return value.map(mark);
-    if (value === null || typeof value !== "object") return value;
-    const record = value as Record<string, unknown>;
-    if (THINKING_BLOCK_TYPES.has(String(record.type))) {
-      thinking.push(extractValues(stableStringify(record), patterns).text);
-      return `\uE000${thinking.length - 1}`;
-    }
-    return Object.fromEntries(
-      Object.entries(record).map(([name, item]) => [name, mark(item)]),
-    );
-  };
-  const { text, values } = extractValues(
-    stableStringify(mark(json)),
-    patterns,
-    known,
-  );
-  return {
-    text: text.replace(THINKING_MARK, (_, index) => thinking[Number(index)]!),
-    values,
-  };
-}
-
-const sha256 = (text: string) =>
-  createHash("sha256").update(text).digest("hex");
-/**
- * The key and the changing values of a request. `known` holds
- * the values of earlier requests in the same session (`values.ts`). It
- * throws an error with HTTP status 400 when it takes too long.
- */
-export function keyRequest(
-  rule: RecordingRule,
-  request: RequestToKey,
-  known?: KnownValues,
-): KeyedRequest {
-  const mib = Buffer.byteLength(request.body) / (1024 * 1024);
-  return withTimeLimit(
-    Math.ceil(KEY_TIME_LIMIT.baseMs + KEY_TIME_LIMIT.msPerMiB * mib),
-    () => keyRequestNow(rule, request, known),
-  );
-}
-
-function keyRequestNow(
-  rule: RecordingRule,
-  request: RequestToKey,
-  known?: KnownValues,
-): KeyedRequest {
-  const headers = Object.fromEntries(
-    (rule.keyHeaders ?? []).map((name) => [
-      name,
-      String(request.headers[name] ?? ""),
-    ]),
-  );
-  const json = parseJson(request.body);
-  const { text, values } =
-    json === undefined
-      ? extractValues(request.body, rule.values, known)
-      : normalizeJson(json, rule.values, known);
-  const key = sha256(
-    [
-      KEY_VERSION,
-      rule.name,
-      request.method,
-      request.url,
-      ...Object.entries(headers).map(([name, value]) => `${name}: ${value}`),
-      text,
-    ].join("\n"),
-  );
-  return { key, values };
-}