@forge-ops/tracker 0.3.0 → 0.5.0

package/README.md

@@ -7,11 +7,8 @@ events to ForgeOps over HTTP without blocking the request or process that raised
 
 ## Installation
 
-Not yet published to npm: install directly from this path (or a local checkout, once split into
-its own repo):
-
 ```bash
-npm install /path/to/forge_ops/sdks/node
+npm install @forge-ops/tracker
 ```
 
 ## Configuration
@@ -37,10 +34,11 @@ overridden by passing it in the options object.
 ```js
 import { forgeOpsTrackerSessionTrackingExpressMiddleware } from "@forge-ops/tracker/integrations/session-tracking";
 import { forgeOpsTrackerPerformanceExpressMiddleware } from "@forge-ops/tracker/integrations/performance";
-import { forgeOpsTrackerExpressMiddleware } from "@forge-ops/tracker/integrations/express";
+import { forgeOpsTrackerUserContextMiddleware, forgeOpsTrackerExpressMiddleware } from "@forge-ops/tracker/integrations/express";
 
 app.use(forgeOpsTrackerSessionTrackingExpressMiddleware); // first, before any routes
 app.use(forgeOpsTrackerPerformanceExpressMiddleware); // order relative to routes doesn't matter
+app.use(forgeOpsTrackerUserContextMiddleware); // after Passport's own session middleware, if used
 // ...routes...
 app.use(forgeOpsTrackerExpressMiddleware); // still last, after all routes
 ```
@@ -111,6 +109,40 @@ themselves, long before it would ever reach here.
 Every failure mode (network errors, timeouts, a full queue, a malformed DSN) is caught and
 dropped rather than thrown, so a broken or unreachable tracker can never take down the host app.
 
+## Identifying users
+
+```js
+captureException(error, {}, { id: user.id, email: user.email });
+```
+
+Or `runWithUser(user, callback)` to attach it to every `captureException()` call made anywhere in
+`callback`'s own async chain, rather than passing it by hand every time, e.g. from your own
+middleware:
+
+```js
+app.use((req, res, next) => runWithUser({ id: req.user?.id, email: req.user?.email }, next));
+```
+
+There's no imperative `setUser()` the way some other languages in this repo have: Node is
+single-threaded, so a plain module-level variable would leak across concurrent requests
+interleaved on the same event loop, exactly the bug the other languages' own thread-local choice
+avoids for their own concurrency model. `AsyncLocalStorage` (Node's own built-in mechanism for
+this) only propagates a value through an async call chain that was explicitly wrapped, so
+`runWithUser`'s wrapping shape is the correct, idiomatic choice here, not a limitation being
+worked around. `id`/`email`/`username` are all independently optional. Shows up on an issue's own
+detail page, and as its own affected-users count alongside the regular event count.
+
+**Express apps get this automatically**: add `forgeOpsTrackerUserContextMiddleware` (see the
+Express snippet above), after whatever middleware actually sets `req.user` (Passport's own session
+middleware, the closest thing Express has to a single dominant auth library, the same role Warden
+plays for Rails). A no-op when `req.user` is never set, whether that's because nobody's signed in
+or Passport isn't installed. Confirmed directly, with a real Express app and a real async route
+handler, that the `AsyncLocalStorage` context this sets survives all the way through to
+`forgeOpsTrackerExpressMiddleware` later in the same request, including across an `await`, not
+just through a synchronous call chain. Composes with the manual API above rather than replacing
+it: call `runWithUser` yourself for a route (or a custom auth setup this can't detect) that needs
+to override what was auto-detected.
+
 ## Delivery: an async loop, not a thread
 
 `DeliveryQueue` here isn't a background *thread*: Node is single-threaded. But a Node process is
@@ -143,7 +175,9 @@ By default, the message, backtrace, and any context/tags you attach are scanned
 for likely personal data: email addresses, formatted SSNs/credit cards, known API key/token
 formats, and anything under a suspiciously-named key (`password`, `apiKey`, `ssn`, and similar),
 and redacted before the payload ever leaves this process. ForgeOps itself scrubs again on arrival
-regardless, so this is a second, earlier layer, not the only one.
+regardless, so this is a second, earlier layer, not the only one. The user attached via
+`captureException`'s third argument or `runWithUser` above is a deliberate exception: it's never
+scrubbed, since redacting it would defeat the whole point of identifying users in the first place.
 
 To disable it:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forge-ops/tracker",
-  "version": "0.3.0",
+  "version": "0.5.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.",
   "type": "module",
   "main": "src/index.js",

package/src/eventBuilder.js

@@ -46,8 +46,9 @@ export class EventBuilder {
   /**
    * @param {Error} error
    * @param {Record<string, unknown>} [context]
+   * @param {Record<string, unknown> | null} [user]
    */
-  build(error, context = {}) {
+  build(error, context = {}, user = null) {
     const payload = {
       exception_class: error?.name ?? "Error",
       message: error?.message ?? "",
@@ -60,14 +61,20 @@ export class EventBuilder {
       tags: {},
       sdk_name: SDK_NAME,
     };
+    if (user && Object.keys(user).length > 0) {
+      payload.user = { ...user };
+    }
 
     return this.#configuration.scrubPii ? this.#scrub(payload) : payload;
   }
 
-  // exception_class/occurred_at/environment/release/server_name are left
-  // alone: structured fields this client or the host app sets
+  // exception_class/occurred_at/environment/release/server_name/user are
+  // left alone: structured fields this client or the host app sets
   // deliberately, not free text an exception or its context could
-  // accidentally spill sensitive data into.
+  // accidentally spill sensitive data into. user specifically is a
+  // deliberate exemption, not an oversight: the scrubber's own email
+  // pattern would otherwise redact the exact thing this field exists to
+  // carry.
   #scrub(payload) {
     return {
       ...payload,

package/src/index.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { Client } from "./client.js";
 import { Configuration } from "./configuration.js";
 import { DeliveryQueue } from "./deliveryQueue.js";
@@ -16,6 +17,17 @@ let processHandlersInstalled = false;
 let uncaughtExceptionListener = null;
 let unhandledRejectionListener = null;
 
+// Request-scoped affected-user storage. AsyncLocalStorage, not a plain module-level variable the
+// way gems/forge_ops_tracker uses Thread.current or Python uses threading.local: Node is
+// single-threaded, so a plain variable would leak across concurrent requests being interleaved
+// on the same event loop, exactly the bug those other languages' own thread-local choice avoids
+// for their own concurrency model. AsyncLocalStorage is the Node-idiomatic equivalent, but its
+// API shape is different on purpose: it only propagates a value through an async call chain that
+// was explicitly wrapped via runWithUser() below (there's no imperative "just set it from
+// anywhere" the way Thread.current allows), which is why this SDK's own set_user-equivalent is a
+// wrapping function, not a bare setter.
+const userStorage = new AsyncLocalStorage();
+
 function getConfiguration() {
   if (configuration === null) {
     configuration = new Configuration();
@@ -104,13 +116,37 @@ export function init(options = {}) {
 }
 
 /**
- * Report an exception you've already caught.
+ * Report an exception you've already caught. `user` defaults to whatever runWithUser() below
+ * established for this async call chain, if anything; pass one explicitly to override that for
+ * this one report.
  *
  * @param {Error} error
  * @param {Record<string, unknown>} [context]
+ * @param {Record<string, unknown> | null} [user]
+ */
+export function captureException(error, context = {}, user = null) {
+  getReporter().report(error, context, user ?? userStorage.getStore()?.user ?? null);
+}
+
+/**
+ * Runs `callback` (sync or async) with an affected user attached to every `captureException()`
+ * call made anywhere in its call chain that doesn't pass its own explicit `user`, e.g. from your
+ * own middleware:
+ *
+ *     app.use((req, res, next) => runWithUser({ id: req.user?.id }, next));
+ *
+ * There's no imperative `setUser()` the way other languages in this repo have: AsyncLocalStorage
+ * (see this module's own comment on `userStorage`) only propagates a value through an async call
+ * chain that was explicitly wrapped like this, so wrapping is the correct, idiomatic shape here,
+ * not a limitation being worked around.
+ *
+ * @template T
+ * @param {Record<string, unknown>} user
+ * @param {() => T} callback
+ * @returns {T}
  */
-export function captureException(error, context = {}) {
-  getReporter().report(error, context);
+export function runWithUser(user, callback) {
+  return userStorage.run({ user }, callback);
 }
 
 /**

package/src/integrations/express.js

@@ -1,4 +1,4 @@
-import { captureException } from "../index.js";
+import { captureException, runWithUser } from "../index.js";
 
 /**
  * Express error-handling middleware. Register last, after all routes:
@@ -26,3 +26,52 @@ export function forgeOpsTrackerExpressMiddleware(err, req, res, next) {
   });
   next(err);
 }
+
+/**
+ * Automatically identifies the affected user for every error reported for the rest of this
+ * request, when `req.user` is present. Register early, before your routes (and after whatever
+ * middleware actually sets `req.user`, e.g. Passport's own session middleware):
+ *
+ *     app.use(passport.session());
+ *     app.use(forgeOpsTrackerUserContextMiddleware);
+ *     // ...routes...
+ *     app.use(forgeOpsTrackerExpressMiddleware);
+ *
+ * `req.user` is Passport's own convention (the closest thing Express has to a single dominant
+ * auth library, the same role Warden plays for Rails): set once `passport.authenticate()`/session
+ * deserialization succeeds, left `undefined` otherwise, so a plain truthy check is enough, the
+ * same duck-typed "is there a user object at all" check `gems/forge_ops_tracker`'s own Warden
+ * integration does for `env["warden"].user`. A no-op for an app that never set `req.user` at all,
+ * whether that's because nobody's signed in or Passport (or an equivalent) isn't installed.
+ *
+ * Wraps the rest of the request in `runWithUser()` (see that function's own doc comment for why
+ * this SDK has no imperative `setUser()`) rather than setting anything imperatively itself:
+ * confirmed directly, with a real Express app and a real async route handler, that
+ * `AsyncLocalStorage`'s context set by an early middleware like this one does survive all the way
+ * through to a later error-handling middleware (`forgeOpsTrackerExpressMiddleware`, typically
+ * registered last, after every route) in the same request, not just to handlers registered
+ * synchronously right after this one.
+ */
+export function forgeOpsTrackerUserContextMiddleware(req, res, next) {
+  if (!req.user) {
+    next();
+    return;
+  }
+  runWithUser(serializeUser(req.user), next);
+}
+
+function serializeUser(user) {
+  const result = {};
+  if (user.id !== undefined && user.id !== null) {
+    result.id = String(user.id);
+  }
+  if (user.email) {
+    result.email = user.email;
+  }
+  if (user.username) {
+    result.username = user.username;
+  } else if (user.name) {
+    result.username = user.name;
+  }
+  return result;
+}

package/src/reporter.js

@@ -20,14 +20,15 @@ export class Reporter {
   /**
    * @param {Error} error
    * @param {Record<string, unknown>} [context]
+   * @param {Record<string, unknown> | null} [user]
    */
-  report(error, context = {}) {
+  report(error, context = {}, user = null) {
     try {
       if (!this.#configuration.isEnabled()) {
         return;
       }
 
-      const payload = this.#eventBuilder.build(error, context);
+      const payload = this.#eventBuilder.build(error, context, user);
       this.#deliveryQueue.push(payload);
     } catch (e) {
       this.#configuration.log(`[forge-ops-tracker] report failed: ${e.name}: ${e.message}`);