@forge-ops/tracker 0.9.0 → 0.10.0

package/README.md

@@ -1,6 +1,6 @@
 # @forge-ops/tracker
 
-Node.js error reporting client for a [ForgeOps](../../) instance.
+Node.js error reporting client for [ForgeOps](https://getforgeops.net).
 Requires Node 18+ (for global `fetch`). It captures uncaught exceptions, unhandled promise
 rejections, and explicitly reported errors, builds a backtrace, scrubs likely PII, and delivers
 events to ForgeOps over HTTP without blocking the request or process that raised them.
@@ -20,7 +20,7 @@ variable or explicitly:
 import * as forgeOpsTracker from "@forge-ops/tracker";
 
 forgeOpsTracker.init({
-  dsn: "https://<api_key>@your-forgeops-host/api/v1/events", // or leave unset to read FORGE_OPS_DSN
+  dsn: "https://<api_key>@getforgeops.net/api/v1/events", // or leave unset to read FORGE_OPS_DSN
   release: "...",
   environment: "production",
 });
@@ -418,6 +418,32 @@ of any kind yet to extend) and no Redis span capture (no existing Redis hook or
 here either); a database call or Redis call inside a traced request just won't show up as its own
 span for now.
 
+## Database errors
+
+When an error carries the SQL behind a failed database call, the event includes the names of the stored procedure, table and view that SQL touched, so the issue tells you where to start looking. This is on by default and sends identifiers only, never values. The statement is read from a `.sql` or `.query` string on the error or anything it wraps (`cause`, and Sequelize's `parent`/`original`), which covers Sequelize, mysql2 and TypeORM. node-postgres, better-sqlite3 and Prisma errors carry none, so attach it where you ran the query with `withSql`.
+
+To also send the SQL statement itself, opt in. Every string and number is replaced by `?` before it
+leaves your process (`WHERE email = 'a@b.co' AND id = 42` is sent as `WHERE email = ? AND id = ?`),
+and ForgeOps masks it again on arrival:
+
+```js
+import { withSql } from "@forge-ops/tracker";
+
+try {
+  await pool.query(sql, params);
+} catch (error) {
+  throw withSql(error, sql);
+}
+
+// Opt in to also sending the masked statement (default false).
+forgeOpsTracker.init({ dsn: "...", captureSqlStatement: true });
+```
+
+Each ForgeOps project also has its own "Capture the SQL behind database errors" setting. Turn it off
+there and the statement is never stored for that project, whatever this flag says; the names are
+still kept. A view and a table are written the same way in SQL, so both show as tables/views; the
+database's own error message usually settles which it was.
+
 ## Running the tests
 
 ```bash

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@forge-ops/tracker",
-  "version": "0.9.0",
-  "description": "ForgeOps error tracking client: captures unhandled exceptions (Express/Fastify integration, plus explicit capture anywhere else) and delivers them to a ForgeOps instance over HTTP.",
+  "version": "0.10.0",
+  "description": "ForgeOps error tracking client: captures unhandled exceptions (Express/Fastify integration, plus explicit capture anywhere else) and delivers them to ForgeOps over HTTP.",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/configuration.js

@@ -42,6 +42,21 @@ export class Configuration {
    */
   captureSourceContext = true;
 
+  /**
+   * When an error comes from a database call (Sequelize, TypeORM, mysql2, and anything that wraps
+   * one), send the names of the stored procedure, table and view its SQL touched, so an issue says
+   * where to start looking. Names are identifiers, never values, which is why this defaults on.
+   * captureSqlStatement is the separate, opt-in step of also sending the statement itself, with
+   * every string and number replaced by "?"; off by default because even a masked statement
+   * describes your schema, and ForgeOps' own per-project setting is what durably governs whether
+   * the server stores it. See sqlStatement.js.
+   * @type {boolean}
+   */
+  captureSqlObjects = true;
+
+  /** @type {boolean} */
+  captureSqlStatement = false;
+
   /** @type {((message: string) => void) | null} */
   logger = null;
 

package/src/eventBuilder.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import { scrub, scrubString } from "./piiScrubber.js";
+import * as sqlStatement from "./sqlStatement.js";
 
 const MAX_FRAMES = 500;
 
@@ -68,6 +69,7 @@ export class EventBuilder {
     if (breadcrumbs && breadcrumbs.length > 0) {
       payload.breadcrumbs = [...breadcrumbs];
     }
+    this.#attachSql(payload, error);
 
     return this.#configuration.scrubPii ? this.#scrub(payload) : payload;
   }
@@ -94,9 +96,35 @@ export class EventBuilder {
     if ("breadcrumbs" in payload) {
       scrubbed.breadcrumbs = scrub(payload.breadcrumbs);
     }
+    if ("sql_statement" in payload) {
+      scrubbed.sql_statement = scrubString(payload.sql_statement);
+    }
     return scrubbed;
   }
 
+  // See sqlStatement.js for what's read off the error and how it's masked. The statement itself
+  // only goes out when captureSqlStatement is on; the extracted names go out on their own
+  // (captureSqlObjects) so an issue can still name the procedure or view involved.
+  #attachSql(payload, error) {
+    const config = this.#configuration;
+    if (!config.captureSqlObjects && !config.captureSqlStatement) {
+      return;
+    }
+
+    const masked = sqlStatement.mask(sqlStatement.findIn(error));
+    if (masked === null) {
+      return;
+    }
+
+    const found = sqlStatement.objects(masked);
+    if (found && config.captureSqlObjects) {
+      payload.sql_objects = found;
+    }
+    if (config.captureSqlStatement) {
+      payload.sql_statement = masked;
+    }
+  }
+
   #scrubFrame(frame) {
     const scrubbed = {
       ...frame,

package/src/index.js

@@ -12,6 +12,7 @@ import { SessionFlusher } from "./sessionFlusher.js";
 import { randomSpanId, SpanBuffer } from "./spanBuffer.js";
 
 export { Configuration };
+export { withSql } from "./sqlStatement.js";
 
 let configuration = null;
 let reporter = null;

package/src/sqlStatement.js

@@ -0,0 +1,159 @@
+// Finds the SQL behind a database error and reduces it to something safe to send: the names of
+// the stored procedures, tables and views it touched, and (only if configuration.
+// captureSqlStatement is on) the statement itself with every string and number replaced by "?".
+// Ported from gems/forge_ops_tracker's SqlStatement, which is itself ported from the server's own
+// SqlStatementMasker/SqlObjectExtractor: same rules everywhere, and the server applies them again
+// on arrival, so a difference here can only ever mean less is masked client-side, never that
+// something unmasked gets stored.
+//
+// Deliberately a single pass over a few patterns, not a SQL parser. No regex lookbehind either:
+// the same source is shared with the browser and React Native SDKs, where an older engine would
+// fail to even parse one, so the "not part of an identifier" check on numbers captures the
+// preceding character and puts it back instead.
+
+const MASK = "?";
+const MAX_LENGTH = 4000;
+const MAX_NAMES = 10;
+const MAX_NAME_LENGTH = 200;
+const MAX_CAUSE_DEPTH = 5;
+
+// 1: string literal (or one cut off by truncation)  2: dollar-quote tag  3: char before a number
+// 4: the number, not part of an identifier or a $1 placeholder
+const LITERAL = /'(?:[^']|'')*(?:'|$)|(\$[A-Za-z_]*\$)[\s\S]*?(?:\1|$)|(^|[^\w$.])(\d+(?:\.\d+)?)(?!\w)/g;
+
+const PART = '(?:[\\w$#@]+|"[^"]+"|\\[[^\\]]+\\]|`[^`]+`)';
+const NAME = `${PART}(?:\\.${PART})*`;
+const OPERATIONS = new Set(["SELECT", "INSERT", "UPDATE", "DELETE", "MERGE", "WITH", "CALL", "EXEC", "EXECUTE", "CREATE", "ALTER", "DROP", "TRUNCATE"]);
+const PROCEDURE_CALL = new RegExp(`\\b(?:CALL|EXEC(?:UTE)?|PERFORM)\\s+(?!IMMEDIATE\\b|FUNCTION\\b|PROCEDURE\\b)(${NAME})`, "gi");
+const RELATION = new RegExp(`\\b(FROM|JOIN|INTO|UPDATE|TABLE)\\s+(${NAME})(\\s*\\()?`, "gi");
+const SELECT_FUNCTION = new RegExp(`^\\s*SELECT\\s+(${NAME})\\s*\\(`, "i");
+const BUILTINS = new Set([
+  "count", "sum", "min", "max", "avg", "now", "coalesce", "nullif", "lower", "upper", "length", "concat",
+  "cast", "date_trunc", "current_timestamp", "current_date", "row_number", "rank", "json_build_object",
+  "json_agg", "array_agg",
+]);
+const FROM_INSIDE_FUNCTION = /\b(?:EXTRACT|SUBSTRING|TRIM|OVERLAY)\s*\([^()]*\)/gi;
+const KEYWORDS_NOT_NAMES = new Set(["select", "set", "values", "where", "lateral", "only", "unnest", "generate_series"]);
+const FULL_NAME = new RegExp(`^${NAME}$`);
+const FROM_WORD = /\bFROM\b/i;
+
+// Properties that carry the statement on the errors Node database libraries raise: Sequelize and
+// mysql2 use .sql (Sequelize also nests the driver's own error under .parent/.original), TypeORM's
+// QueryFailedError uses .query. Only a string counts, never an object that happens to share the
+// name (a Sequelize query builder, say).
+const STATEMENT_PROPERTIES = ["sql", "query"];
+
+/**
+ * The raw statement off the error itself or, for an app that wraps a database error in its own
+ * exception, off whatever it was raised from (.cause, or Sequelize's .parent/.original).
+ * @param {unknown} error
+ * @returns {string | null}
+ */
+export function findIn(error) {
+  const seen = new Set();
+  const queue = [error];
+  let depth = 0;
+  while (queue.length > 0 && depth < MAX_CAUSE_DEPTH * 3) {
+    const current = queue.shift();
+    depth += 1;
+    if (!current || typeof current !== "object" || seen.has(current)) {
+      continue;
+    }
+    seen.add(current);
+    for (const property of STATEMENT_PROPERTIES) {
+      const value = current[property];
+      if (typeof value === "string" && value.trim() !== "") {
+        return value;
+      }
+    }
+    queue.push(current.cause, current.parent, current.original);
+  }
+  return null;
+}
+
+/**
+ * @param {string | null | undefined} statement
+ * @returns {string | null}
+ */
+export function mask(statement) {
+  if (typeof statement !== "string" || statement.trim() === "") {
+    return null;
+  }
+  const masked = statement.replace(LITERAL, (whole, _tag, before, number) => (number === undefined ? MASK : `${before}${MASK}`));
+  return masked.length > MAX_LENGTH ? `${masked.slice(0, MAX_LENGTH)}...` : masked;
+}
+
+/**
+ * Takes an already-masked statement (so a keyword inside a string value can't be mistaken for
+ * SQL). Returns null when nothing recognizable was found.
+ * @param {string | null} masked
+ * @returns {{ operation?: string, procedures: string[], relations: string[] } | null}
+ */
+export function objects(masked) {
+  if (typeof masked !== "string" || masked.trim() === "") {
+    return null;
+  }
+
+  const sql = masked.replace(FROM_INSIDE_FUNCTION, " ");
+  const procedures = [...sql.matchAll(PROCEDURE_CALL)].map((m) => m[1]);
+  const relations = [];
+
+  for (const [, keyword, name, paren] of sql.matchAll(RELATION)) {
+    if (KEYWORDS_NOT_NAMES.has(name.toLowerCase())) {
+      continue;
+    }
+    const functionCall = Boolean(paren) && ["FROM", "JOIN"].includes(keyword.toUpperCase());
+    (functionCall ? procedures : relations).push(name);
+  }
+
+  const fn = SELECT_FUNCTION.exec(sql)?.[1];
+  if (fn && !BUILTINS.has(fn.toLowerCase()) && !FROM_WORD.test(sql)) {
+    procedures.push(fn);
+  }
+
+  const operation = (/^\s*(\w+)/.exec(sql)?.[1] ?? "").toUpperCase();
+  const result = {};
+  if (OPERATIONS.has(operation)) {
+    result.operation = operation;
+  }
+  result.procedures = clean(procedures);
+  result.relations = clean(relations);
+  if (result.procedures.length === 0 && result.relations.length === 0 && !("operation" in result)) {
+    return null;
+  }
+  return result;
+}
+
+function clean(names) {
+  const cleaned = [];
+  for (const raw of names) {
+    const name = raw.trim().slice(0, MAX_NAME_LENGTH);
+    if (FULL_NAME.test(name) && !cleaned.includes(name)) {
+      cleaned.push(name);
+    }
+  }
+  return cleaned.slice(0, MAX_NAMES);
+}
+
+/**
+ * Attaches the SQL statement that caused `error` to it and returns the same error, so the code
+ * that ran the query can hand it over where the reporter finds it with no extra call. Use it when
+ * the database library's own errors don't carry the statement (node-postgres, better-sqlite3 and
+ * Prisma don't):
+ *
+ *     try { await pool.query(sql, params); }
+ *     catch (error) { throw withSql(error, sql); }
+ *
+ * Only the names of the stored procedure, table and view are sent by default, and the statement
+ * itself only with `captureSqlStatement` on, with every string and number replaced by "?" first;
+ * the raw statement never leaves the process. Non-enumerable, so it doesn't show up when the error
+ * is logged or serialized.
+ * @template {object} E
+ * @param {E} error
+ * @param {string} statement
+ * @returns {E}
+ */
+export function withSql(error, statement) {
+  Object.defineProperty(error, "sql", { value: statement, enumerable: false, configurable: true, writable: true });
+  return error;
+}