peekinside 1.2.4 → 1.3.0

package/README.md

@@ -5,6 +5,7 @@ Debug Node.js from the inside: every error with the request that set it off, the
 [![npm](https://img.shields.io/npm/v/peekinside?color=18b69b)](https://www.npmjs.com/package/peekinside)
 ![License](https://img.shields.io/badge/license-MIT-18b69b)
 ![Node](https://img.shields.io/badge/node-%3E%3D18-18b69b)
+[![Buy me a coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-FFDD00?logo=buymeacoffee&logoColor=000000)](https://buymeacoffee.com/thejesbin)
 
 ## Install
 
@@ -20,11 +21,13 @@ const app = express();
 PeekInside.attach(app);
 ```
 
-Start your app, and PeekInside prints the link to its dashboard. It works with Express, Koa, Fastify and the native http module.
+Start your app, and PeekInside prints the link to its dashboard. It works with Express, Koa, Fastify, NestJS, Hono and the native http module.
 
 Check the setup before anything breaks on its own: `npx peekinside test` sends a test error from your project.
 
-Also recorded: background jobs (node-cron, cron, BullMQ, or `PeekInside.job()`, with an email when a scheduled job misses its run), log lines from the console, pino and winston, event-loop blocks and memory, the deploy each error came from, the user it happened to (`PeekInside.setUser()`), and TypeScript lines through your source maps.
+While you develop, `PeekInside.dump(value)` shows any value in the local dashboard instead of your terminal: as a tree you can open, under the request it belongs to, with the line that dumped it.
+
+Also recorded: background jobs (node-cron, cron, BullMQ, @nestjs/schedule, or `PeekInside.job()`, with an email when a scheduled job misses its run), log lines from the console, pino, winston and NestJS's Logger, event-loop blocks and memory, the deploy each error came from, the user it happened to (`PeekInside.setUser()`), and TypeScript lines through your source maps.
 
 ## Documentation
 
@@ -37,10 +40,18 @@ Everything else is in the docs: **[peekinside.dev/docs](https://peekinside.dev/d
 - [Timeline and queries](https://peekinside.dev/docs/timeline)
 - [Logs](https://peekinside.dev/docs/logs)
 - [Jobs and schedules](https://peekinside.dev/docs/jobs)
+- [Dumps](https://peekinside.dev/docs/dumps)
 - [Runtime](https://peekinside.dev/docs/runtime)
+- [Alerts](https://peekinside.dev/docs/alerts)
 - [Configuration](https://peekinside.dev/docs/configuration)
 - [API](https://peekinside.dev/docs/api)
 
+## Support
+
+If PeekInside saves you a debugging session, you can buy me a coffee:
+
+[![Buy me a coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=&slug=thejesbin&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://buymeacoffee.com/thejesbin)
+
 ## License
 
 MIT

package/index.d.ts

@@ -3,8 +3,8 @@
  * and the exceptions that happen while handling them. In development they go to the free local
  * dashboard; with an API key they are encrypted and sent to PeekInside Cloud.
  *
- * The signatures are structural, so Express, Connect, Koa, Fastify and node:http objects fit
- * without PeekInside depending on any of those packages.
+ * The signatures are structural, so Express, Connect, Koa, Fastify, NestJS, Hono and node:http
+ * objects fit without PeekInside depending on any of those packages.
  */
 
 import type { IncomingMessage, Server, ServerResponse } from "node:http";
@@ -67,8 +67,8 @@ export interface PeekInsideOptions {
   projectRoot?: string;
 
   /**
-   * Records exceptions automatically: errors that reach Express, Koa or Fastify error handling,
-   * uncaught exceptions and unhandled rejections. `report()` works either way.
+   * Records exceptions automatically: errors that reach Express, Koa, Fastify, NestJS or Hono error
+   * handling, uncaught exceptions and unhandled rejections. `report()` works either way.
    * @default true
    */
   captureExceptions?: boolean;
@@ -109,8 +109,8 @@ export interface PeekInsideOptions {
   captureOutgoing?: boolean;
 
   /**
-   * Records log lines from the console, pino and winston: on the timeline of the request (or job
-   * run) they are written in, and on the Logs page, from anywhere in the app.
+   * Records log lines from the console, pino, winston and NestJS's Logger: on the timeline of the
+   * request (or job run) they are written in, and on the Logs page, from anywhere in the app.
    * @default true
    */
   captureLogs?: boolean;
@@ -122,7 +122,8 @@ export interface PeekInsideOptions {
   logLevel?: "debug" | "info" | "warn" | "error";
 
   /**
-   * Records runs of node-cron, cron and BullMQ jobs automatically (see `job()` for other jobs).
+   * Records runs of node-cron, cron, BullMQ and @nestjs/schedule jobs automatically (see `job()`
+   * for other jobs).
    * @default true
    */
   captureJobs?: boolean;
@@ -208,6 +209,8 @@ export interface PeekInsideUser {
   id?: string | number;
   email?: string;
   name?: string;
+  /** As your app writes it, such as "+91 98765 43210". */
+  phone?: string | number;
 }
 
 /** Options that can still change after the instance is created (see `attachTo`). */
@@ -215,9 +218,14 @@ export type CaptureOptions = Pick<PeekInsideOptions, "maxBodySize" | "ignorePath
 
 /**
  * What `PeekInside.attach()` understands: an Express or Connect app, a Koa app, a Fastify
- * instance, or a node:http (or https) server.
+ * instance, a NestJS app or application context, a Hono app, or a node:http (or https) server.
  */
-export type AttachTarget = Server | { use(...args: any[]): unknown } | { addHook(...args: any[]): unknown };
+export type AttachTarget =
+  | Server
+  | { use(...args: any[]): unknown }
+  | { addHook(...args: any[]): unknown }
+  | { select(...args: any[]): unknown; useLogger(...args: any[]): unknown }
+  | { fetch(...args: any[]): unknown; onError(...args: any[]): unknown };
 
 /** Express and Connect style middleware. */
 export type NodeMiddleware = (req: IncomingMessage, res: ServerResponse, next: (error?: unknown) => void) => void;
@@ -234,7 +242,7 @@ export type KoaMiddleware = (
  * @example
  * import PeekInside from "peekinside";
  *
- * PeekInside.attach(app); // Express, Koa, Fastify or an http.Server
+ * PeekInside.attach(app); // Express, Koa, Fastify, NestJS, Hono or an http.Server
  */
 declare class PeekInside {
   /**
@@ -253,9 +261,11 @@ declare class PeekInside {
   readonly release: string | null;
 
   /**
-   * One-line setup: records every request the app handles.
+   * One-line setup: records every request the app handles. Attach a NestJS app before
+   * `app.listen()`, a Hono app before `serve()`, and a Fastify app before `fastify.listen()`.
    *
-   * @param app - Express or Connect app, Koa app, Fastify instance, or http.Server
+   * @param app - Express or Connect app, Koa app, Fastify instance, NestJS app or application
+   *   context, Hono app, or http.Server
    */
   static attach(app: AttachTarget, options?: PeekInsideOptions): PeekInside;
 
@@ -299,6 +309,27 @@ declare class PeekInside {
    */
   static measure<T>(name: string, fn: () => T): T;
 
+  /**
+   * Shows a value in the local dashboard instead of your terminal: on the Dumps page and under the
+   * request (or job run) it was dumped in, as a tree that opens level by level, with the line that
+   * dumped it. Returns the value, so it can wrap an expression in place.
+   *
+   * Dumps are for development: they go to the local dashboard only. With PeekInside Cloud, or when
+   * nothing is recorded, `dump()` just returns the value.
+   *
+   * @param label - Shown with the dump, such as `"cart before checkout"`
+   *
+   * @example
+   * const order = PeekInside.dump(await buildOrder(cart), "order");
+   */
+  dump<T>(value: T, label?: string): T;
+
+  /**
+   * `dump()` with the instance that tracks the current request, or else the most recently created
+   * instance that records.
+   */
+  static dump<T>(value: T, label?: string): T;
+
   /**
    * The id of the request the calling code runs for, as the dashboard knows it: put it in your
    * own logs to find the request from a log line. `null` outside a recorded request.
@@ -315,7 +346,7 @@ declare class PeekInside {
    *
    * @example
    * app.use((req, res, next) => {
-   *   if (req.user) PeekInside.setUser({ id: req.user.id, email: req.user.email });
+   *   if (req.user) PeekInside.setUser({ id: req.user.id, email: req.user.email, name: req.user.name, phone: req.user.phone });
    *   next();
    * });
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peekinside",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "description": "Debug Node.js from the inside: errors with the requests, queries, logs and jobs behind them. A free local dashboard, and encrypted monitoring for production",
   "main": "index.js",
   "types": "./index.d.ts",
@@ -57,6 +57,12 @@
   },
   "homepage": "https://peekinside.dev",
   "devDependencies": {
+    "@hono/node-server": "2.1.3",
+    "@nestjs/common": "12.1.3",
+    "@nestjs/core": "12.1.3",
+    "@nestjs/platform-express": "12.1.3",
+    "@nestjs/platform-fastify": "12.1.3",
+    "@nestjs/schedule": "12.0.2",
     "@types/express": "4.17.25",
     "@types/koa": "2.15.0",
     "@types/node": "24.10.1",
@@ -65,6 +71,7 @@
     "express": "4.22.3",
     "express5": "npm:express@5.1.0",
     "fastify": "5.12.5",
+    "hono": "4.13.13",
     "koa": "2.16.4",
     "mongodb": "6.21.0",
     "mongodb-memory-server-core": "11.3.0",
@@ -73,6 +80,8 @@
     "node-cron": "4.6.0",
     "pg": "8.23.1",
     "pino": "10.4.0",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2",
     "typescript": "5.9.3",
     "winston": "3.19.0"
   }

package/src/PeekInside.js

@@ -4,7 +4,7 @@
  * Records every request and response your app handles. During development they go to the free
  * local dashboard, which is shared by all your projects and keeps its data on this machine.
  * With an API key they are encrypted and sent to PeekInside Cloud instead.
- * Works with Express, Koa, Fastify and the native http module.
+ * Works with Express, Koa, Fastify, NestJS, Hono and the native http module.
  *
  * Exceptions are recorded too: errors that reach the framework's error handling, crashes
  * (uncaught exceptions and unhandled rejections), and errors the app reports. Each is linked to the
@@ -13,6 +13,9 @@
  * Each request also gets a timeline: the database queries, outgoing HTTP calls, console lines and
  * exceptions that happened while it was handled (see src/timeline and src/instrumentation).
  *
+ * In development, dump() shows values in the local dashboard, under the request they were dumped
+ * in (see src/dumps).
+ *
  * This class is the public API. It decides where requests go and which requests are recorded,
  * and leaves the work to the capture (src/capture), exception (src/exceptions), framework
  * (src/integrations) and transport (src/transport) classes.
@@ -26,6 +29,7 @@ import { isIgnoredPath } from './capture/ignored-paths.js';
 import { LOG_PREFIX, VERSION, settings } from './config.js';
 import { TrafficClassifier } from './deployment.js';
 import { ExceptionCapture } from './exceptions/exception-capture.js';
+import { DumpCapture } from './dumps/dump-capture.js';
 import { ProcessMonitor } from './exceptions/process-monitor.js';
 import { RequestContext } from './exceptions/request-context.js';
 import { Instrumentation } from './instrumentation/index.js';
@@ -33,8 +37,10 @@ import { isNativePromise } from './instrumentation/patch.js';
 import { TIMELINE_DEFAULTS, Timeline, TimelineSettings } from './timeline/timeline.js';
 import { ExpressAdapter } from './integrations/express.js';
 import { FastifyAdapter } from './integrations/fastify.js';
+import { HonoAdapter } from './integrations/hono.js';
 import { HttpServerAdapter } from './integrations/http-server.js';
 import { KoaAdapter } from './integrations/koa.js';
+import { NestAdapter } from './integrations/nest.js';
 import { ServerBinder } from './integrations/server-binder.js';
 import { ProjectIdentity } from './project.js';
 import { Release } from './release.js';
@@ -42,6 +48,7 @@ import { JobRunner } from './jobs/job-runner.js';
 import { LogCapture } from './logs/log-capture.js';
 import { LoopMonitor } from './runtime/loop-monitor.js';
 import { RuntimeSampler } from './runtime/sampler.js';
+import { RequestCounter } from './runtime/request-counter.js';
 import { UserInfo } from './user.js';
 import { CloudTransport } from './transport/cloud.js';
 import { LocalTransport } from './transport/local.js';
@@ -59,9 +66,10 @@ const DEFAULT_OPTIONS = {
   ...TIMELINE_DEFAULTS
 };
 
-// Tried in this order by attachTo(): Fastify and Koa apps also have use(), and anything with
-// use() is handled as middleware before falling back to a plain server.
-const ADAPTERS = [FastifyAdapter, KoaAdapter, ExpressAdapter, HttpServerAdapter];
+// Tried in this order by attachTo(): Nest apps (which pass Express's or Fastify's methods
+// through), Hono, Fastify and Koa apps also have use(), and anything with use() is handled as
+// middleware before falling back to a plain server.
+const ADAPTERS = [NestAdapter, HonoAdapter, FastifyAdapter, KoaAdapter, ExpressAdapter, HttpServerAdapter];
 
 // Marks requests already being recorded, so a request that passes through several integrations
 // (or PeekInside instances) is recorded once.
@@ -72,7 +80,7 @@ const kTracked = Symbol('peekInside.tracked');
  *
  * @class PeekInside
  * @example
- * // Express, Koa, Fastify or an http.Server
+ * // Express, Koa, Fastify, NestJS, Hono or an http.Server
  * PeekInside.attach(app);
  *
  * @example
@@ -103,8 +111,8 @@ class PeekInside {
    *   "v2.4.0". Defaults to PEEKINSIDE_RELEASE, then the commit your host deployed (Vercel, Render,
    *   Railway, Heroku and others set it), then the commit checked out in the project folder.
    * @param {boolean} [options.captureExceptions=true] - Record exceptions automatically: errors that
-   *   reach Express, Koa or Fastify error handling, uncaught exceptions and unhandled rejections.
-   *   report() works either way.
+   *   reach Express, Koa, Fastify, NestJS or Hono error handling, uncaught exceptions and unhandled
+   *   rejections. report() works either way.
    * @param {boolean} [options.sourceContext=true] - Include the source lines around the app's own
    *   stack frames in exception records
    * @param {boolean} [options.sourceMaps=true] - Map stack frames of compiled code (TypeScript
@@ -113,11 +121,12 @@ class PeekInside {
    *   queries, outgoing calls, console lines and exceptions
    * @param {boolean} [options.captureQueries=true] - pg, mysql2, MongoDB (and Mongoose), Prisma
    * @param {boolean} [options.captureOutgoing=true] - node:http/https requests and fetch
-   * @param {boolean} [options.captureLogs=true] - Log lines (the console, pino, winston): on request
-   *   timelines and the Logs page
+   * @param {boolean} [options.captureLogs=true] - Log lines (the console, pino, winston, NestJS's
+   *   Logger): on request timelines and the Logs page
    * @param {'debug'|'info'|'warn'|'error'} [options.logLevel='info'] - The lowest level the Logs
    *   page records
-   * @param {boolean} [options.captureJobs=true] - Runs of node-cron, cron and BullMQ jobs
+   * @param {boolean} [options.captureJobs=true] - Runs of node-cron, cron, BullMQ and
+   *   @nestjs/schedule jobs
    * @param {boolean} [options.queryParams=true] - Keep the (masked) values sent with queries
    * @param {number} [options.slowQueryMs=100] - Queries this slow or slower are flagged
    * @param {number} [options.nPlusOneThreshold=5] - A statement run this many times in one request
@@ -159,9 +168,12 @@ class PeekInside {
     // Whether this instance uses the event-loop monitor, and its process sampler.
     this._loopMonitor = false;
     this._sampler = null;
-    // Log lines for the Logs page, and job runs.
+    // The requests this instance serves, counted for its process samples.
+    this._requests = null;
+    // Log lines for the Logs page, job runs, and dumps (local mode only).
     this._logs = null;
     this._jobs = null;
+    this._dumps = null;
     this._servers = new ServerBinder(this, { onListening: (port) => this._onAppListening(port) });
 
     const environment = this.options.environment || settings.environment();
@@ -218,9 +230,11 @@ class PeekInside {
       }
       if (this.options.runtime !== false) {
         const transport = this._transport;
+        this._requests = new RequestCounter();
         this._sampler = new RuntimeSampler({
           intervalMs: this._cloud ? 60_000 : 10_000,
           monitor: LoopMonitor.shared,
+          requests: this._requests,
           onSample: (sample) => transport.addSample(sample)
         }).start();
       }
@@ -232,6 +246,9 @@ class PeekInside {
       if (logs) {
         this._logs = new LogCapture({ level: LogCapture.level(this.options.logLevel), sink: () => this._transport, isEnabled: () => this.isEnabled });
       }
+      if (this._local) {
+        this._dumps = new DumpCapture({ capture: this._exceptions, sink: () => this._transport, isEnabled: () => this.isEnabled });
+      }
       this._jobs = new JobRunner({
         capture: this._exceptions,
         sink: () => this._transport,
@@ -359,6 +376,48 @@ class PeekInside {
     return instance ? instance.measure(name, fn) : fn();
   }
 
+  /**
+   * Shows a value in the local dashboard instead of your terminal: on the Dumps page and under the
+   * request (or job run) it was dumped in, as a tree that opens level by level, with the line that
+   * dumped it. Returns the value, so it can wrap an expression in place.
+   *
+   * Dumps are for development: they go to the local dashboard only. With PeekInside Cloud, or when
+   * nothing is recorded, dump() just returns the value.
+   *
+   * @template T
+   * @param {T} value - Anything: objects, arrays, Maps, class instances, errors...
+   * @param {string} [label] - Shown with the dump, such as "cart before checkout"
+   * @returns {T} The same value
+   *
+   * @example
+   * const order = PeekInside.dump(await buildOrder(cart), 'order');
+   */
+  dump(value, label) {
+    if (this._dumps) this._dumps.record(value, label, PeekInside.prototype.dump);
+    return value;
+  }
+
+  /**
+   * PeekInside#dump() with the instance that tracks the current request, or else the most recently
+   * created instance that records.
+   *
+   * @template T
+   * @param {T} value
+   * @param {string} [label]
+   * @returns {T} The same value
+   */
+  static dump(value, label) {
+    try {
+      const context = RequestContext.current();
+      const capture = context && context.capture && context.capture.recording ? context.capture : ExceptionCapture.latest();
+      const owner = capture ? capture.owner : null;
+      if (owner && owner._dumps) owner._dumps.record(value, label, PeekInside.dump);
+    } catch (error) {
+      // The value comes back all the same.
+    }
+    return value;
+  }
+
   /**
    * The id of the request the calling code runs for: the id its record has in the dashboard, to
    * put in the app's own logs.
@@ -427,13 +486,14 @@ class PeekInside {
    * customer ran into. In PeekInside Cloud the user is encrypted with the rest of the request.
    * Call it once the user is known, such as in your authentication middleware.
    *
-   * @param {{ id?: string|number, email?: string, name?: string }|string|number|null} user - The
-   *   user, or just their id; null forgets it
+   * @param {{ id?: string|number, email?: string, name?: string, phone?: string|number }|string|number|null} user -
+   *   The user, or just their id; null forgets it. The phone is kept as written (phoneNumber,
+   *   phone_number and mobile work too).
    * @returns {boolean} Whether a request was running to attach it to
    *
    * @example
    * app.use((req, res, next) => {
-   *   if (req.user) PeekInside.setUser({ id: req.user.id, email: req.user.email });
+   *   if (req.user) PeekInside.setUser({ id: req.user.id, email: req.user.email, name: req.user.name, phone: req.user.phone });
    *   next();
    * });
    */
@@ -553,7 +613,9 @@ class PeekInside {
   /**
    * Attach to an application and record its traffic
    *
-   * Detects Fastify, Koa, Express-like apps (Express, Connect) and native `http.Server`s.
+   * Detects NestJS apps (and application contexts), Hono apps, Fastify, Koa, Express-like apps
+   * (Express, Connect) and native `http.Server`s. Attach a NestJS app before app.listen(), a Hono
+   * app before serve(), and a Fastify app before fastify.listen().
    *
    * @param {Object} app - Application or server instance
    * @param {Object} [options] - `maxBodySize` and `ignorePaths` to merge into the configuration
@@ -567,7 +629,7 @@ class PeekInside {
     if (Adapter) {
       this._adapter(Adapter).attach(app);
     } else {
-      console.warn(`${LOG_PREFIX} Could not detect the framework. Use expressMiddleware(), koaMiddleware(), fastifyHook() or wrapHttpServer().`);
+      console.warn(`${LOG_PREFIX} Could not detect the framework. Pass an Express, Koa, Fastify, NestJS or Hono app, or use expressMiddleware(), koaMiddleware(), fastifyHook() or wrapHttpServer().`);
     }
     return this;
   }
@@ -575,7 +637,7 @@ class PeekInside {
   /**
    * One-line setup: record every request an app handles
    *
-   * @param {Object} app - Express, Koa or Fastify app, or an http.Server
+   * @param {Object} app - Express, Koa, Fastify, NestJS or Hono app, or an http.Server
    * @param {Object} [options] - Configuration options (see constructor)
    * @returns {PeekInside} PeekInside instance
    *
@@ -683,6 +745,7 @@ class PeekInside {
 
   _track(req, res, target, integration) {
     let context = null;
+    const requests = this._requests;
     const recorder = new ExchangeRecorder(req, res, target, {
       maxBodySize: () => this.options.maxBodySize,
       onExchange: (exchange) => {
@@ -698,6 +761,19 @@ class PeekInside {
     });
     context = new RequestContext({ capture: this._exceptions, req, recorder, target, integration });
     recorder.start();
+    if (requests) {
+      // Counted off the response itself, so a request ends once whatever happens to its record.
+      requests.started();
+      let open = true;
+      const end = () => {
+        if (open) {
+          open = false;
+          requests.ended();
+        }
+      };
+      res.once('finish', end);
+      res.once('close', end);
+    }
     if (this._timeline) {
       context.timeline = new Timeline(this._timeline, recorder.perfStart);
     }

package/src/alerts/rule-matcher.js

@@ -0,0 +1,158 @@
+/**
+ * The parts of a project's alert rules that only the app's server can check: conditions on a
+ * request's path, user and response, and on an exception's or a log line's message, which reach
+ * PeekInside Cloud sealed. The matcher fetches them now and then, checks each record before it is
+ * sealed, and the transport sends which records met which rule with the batch: never what they
+ * hold. Everything else about a rule (a status, a duration, an environment) is checked by
+ * PeekInside Cloud itself.
+ */
+
+import { RequestContext } from '../exceptions/request-context.js';
+
+// Fetched again this often, the first time this long after the transport first delivered.
+const REFRESH_MS = 60_000;
+const FIRST_FETCH_MS = 1000;
+// The most of a response body checked for a "contains" condition.
+const MAX_BODY = 64 * 1024;
+const RULE_ID = /^rl[0-9a-z]{12}$/;
+
+/**
+ * @typedef {Object} SealedRule
+ * @property {string} id - The rule's id
+ * @property {'requests'|'exceptions'|'logs'} source
+ * @property {{ field: string, op: 'is'|'is-not'|'contains'|'matches', value: string }[]} conditions
+ */
+
+export class RuleMatcher {
+  /**
+   * @param {Object} options
+   * @param {() => Promise<{ rules: SealedRule[] }>} options.fetchRules - Asks PeekInside Cloud for them
+   * @param {number} [options.refreshMs]
+   */
+  constructor({ fetchRules, refreshMs = REFRESH_MS }) {
+    this.fetchRules = fetchRules;
+    this.refreshMs = refreshMs;
+    /** @type {SealedRule[]} */
+    this.rules = [];
+    this.timer = null;
+    this.first = null;
+  }
+
+  /**
+   * Fetches the rules shortly, then keeps them current. Its timers never keep the process alive:
+   * a script that ends right away never waits for them.
+   *
+   * @returns {void}
+   */
+  start() {
+    if (this.timer || this.first) return;
+    this.first = RequestContext.outside(() =>
+      setTimeout(() => {
+        void this.refresh();
+        this.timer = RequestContext.outside(() => setInterval(() => void this.refresh(), this.refreshMs));
+        if (typeof this.timer.unref === 'function') this.timer.unref();
+      }, FIRST_FETCH_MS)
+    );
+    if (typeof this.first.unref === 'function') this.first.unref();
+  }
+
+  stop() {
+    clearTimeout(this.first);
+    clearInterval(this.timer);
+    this.first = null;
+    this.timer = null;
+  }
+
+  /**
+   * @returns {Promise<void>} Never rejects: without rules, nothing is reported
+   */
+  async refresh() {
+    try {
+      const answer = await RequestContext.outside(() => this.fetchRules());
+      this.rules = Array.isArray(answer && answer.rules) ? answer.rules.filter(valid) : [];
+    } catch (error) {
+      // Kept as they were: PeekInside Cloud may be briefly unreachable.
+    }
+  }
+
+  /**
+   * The rules a record meets on its sealed fields.
+   *
+   * @param {Object} record - A RequestRecord, ExceptionRecord or LogRecord, before it is sealed
+   * @returns {{ rule: string, id: string }[]}
+   */
+  matches(record) {
+    if (!this.rules.length || !record || typeof record.id !== 'string') return [];
+    const source = sourceOf(record);
+    if (!source) return [];
+    const found = [];
+    for (const rule of this.rules) {
+      if (rule.source !== source) continue;
+      if (rule.conditions.every((condition) => meets(condition, valuesOf(record, condition.field)))) found.push({ rule: rule.id, id: record.id });
+    }
+    return found;
+  }
+}
+
+function valid(rule) {
+  return (
+    rule &&
+    RULE_ID.test(rule.id) &&
+    ['requests', 'exceptions', 'logs'].includes(rule.source) &&
+    Array.isArray(rule.conditions) &&
+    rule.conditions.length > 0 &&
+    rule.conditions.every((condition) => condition && typeof condition.field === 'string' && typeof condition.value === 'string')
+  );
+}
+
+function sourceOf(record) {
+  const name = record.constructor && record.constructor.name;
+  if (name === 'RequestRecord') return 'requests';
+  if (name === 'ExceptionRecord') return 'exceptions';
+  if (name === 'LogRecord') return 'logs';
+  return null;
+}
+
+// The values a condition looks at (a user has several: its id, email and phone).
+function valuesOf(record, field) {
+  const summary = record.summary || {};
+  switch (field) {
+    case 'path':
+      return [summary.path];
+    case 'user': {
+      const user = summary.user || {};
+      return [user.id, user.email, user.phone].filter((value) => value !== undefined && value !== null).map(String);
+    }
+    case 'response': {
+      const body = record.detail && record.detail.response ? record.detail.response.body : null;
+      const text = typeof body === 'string' ? body : body && typeof body.text === 'string' ? body.text : '';
+      return [text.slice(0, MAX_BODY)];
+    }
+    case 'name':
+      return [summary.name];
+    case 'message':
+      return [summary.message];
+    default:
+      return [];
+  }
+}
+
+// Text compares without case; "matches" takes * as anything. A condition is met by any of the values.
+function meets(condition, values) {
+  const wanted = String(condition.value).toLowerCase();
+  const pattern = condition.op === 'matches' ? new RegExp(`^${wanted.split('*').map(escape).join('.*')}$`) : null;
+  const met = values.some((value) => {
+    if (typeof value !== 'string') return false;
+    const text = value.toLowerCase();
+    if (condition.op === 'is') return text === wanted;
+    if (condition.op === 'is-not') return text !== wanted;
+    if (condition.op === 'contains') return text.includes(wanted);
+    if (condition.op === 'matches') return pattern.test(text);
+    return false;
+  });
+  return condition.op === 'is-not' ? values.length === 0 || met : met;
+}
+
+function escape(text) {
+  return text.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/capture/exchange-recorder.js

@@ -11,7 +11,7 @@ import { randomUUID } from 'crypto';
 import http from 'http';
 import { performance } from 'perf_hooks';
 import { BodyDecoder, EMPTY_BODY } from './body-decoder.js';
-import { hasBody, parseQuery } from './http-message.js';
+import { hasBody, parseQuery, stringParams } from './http-message.js';
 import { RequestBodyTap } from './request-body-tap.js';
 import { ResponseTap } from './response-tap.js';
 
@@ -41,6 +41,10 @@ const kBodySource = Symbol('peekInside.bodySource');
  * @property {Array<{ id: string, name: string, message: string }>} [exceptions] - The first of them
  * @property {Object} [stats] - Timeline counters (queries, outgoing calls, logs), added by PeekInside
  * @property {Object} [timeline] - The request's timeline, when something was recorded on it
+ * @property {string} [route] - The route pattern it matched ("/users/:id"), when the framework says
+ * @property {string} [handler] - The code that handled it ("UsersController.findOne"), when known
+ * @property {Array<{ id: string, label: string|null, type: string, preview: string }>} [dumps] - The
+ *   dumps made during it (local dashboard only)
  */
 
 /**
@@ -250,14 +254,3 @@ export class ExchangeRecorder {
     return decoder.decodeValue(parsed, headers);
   }
 }
-
-// Route parameters as strings (Express keeps them as strings; other routers may not).
-function stringParams(params) {
-  const result = {};
-  if (!params || typeof params !== 'object') return result;
-  for (const key of Object.keys(params)) {
-    const value = params[key];
-    if (value !== undefined && value !== null && typeof value !== 'object') result[key] = String(value);
-  }
-  return result;
-}

package/src/capture/http-message.js

@@ -136,3 +136,20 @@ export function hasBody(headers) {
 export function setOwn(target, key, value) {
   Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
 }
+
+/**
+ * Route parameters as strings, as records keep them: Express keeps them as strings, other routers
+ * (Fastify, Hono) may not. Values that are objects are left out.
+ *
+ * @param {*} params
+ * @returns {Object<string, string>}
+ */
+export function stringParams(params) {
+  const result = {};
+  if (!params || typeof params !== 'object') return result;
+  for (const key of Object.keys(params)) {
+    const value = params[key];
+    if (value !== undefined && value !== null && typeof value !== 'object') setOwn(result, key, String(value));
+  }
+  return result;
+}