peekinside 0.0.0-stage → 1.2.1

package/src/exceptions/limits.js

@@ -0,0 +1,95 @@
+/**
+ * Size limits of exception records, from the data contract shared with PeekInside Cloud, and the
+ * helpers that apply them.
+ *
+ * Exceptions carry text the app doesn't control (messages built from user input, stack traces of
+ * deep recursion, whatever was passed to report()), so every field is bounded before it is queued:
+ * one exception can never take more than a few hundred kilobytes, however large the error.
+ */
+
+export const LIMITS = Object.freeze({
+  name: 200,
+  message: 2000,
+  // Preview of a thrown value that isn't an Error
+  valuePreview: 500,
+  code: 64,
+  // Bytes of error.stack
+  stack: 32 * 1024,
+  frames: 100,
+  causeDepth: 5,
+  aggregateErrors: 10,
+  // Bytes of each cause's stack
+  causeStack: 8 * 1024,
+  causeFrames: 20,
+  // In-app frames that get source lines, and the lines on each side of the frame's line
+  contextFrames: 5,
+  contextLines: 5,
+  contextLineLength: 240,
+  tags: 32,
+  tagKey: 64,
+  tagValue: 256,
+  // Bytes of `extra` once serialized, and of the preview kept when it is larger
+  extra: 16 * 1024,
+  extraPreview: 2048,
+  // Bytes of the request body kept with an exception
+  requestBody: 8 * 1024,
+  // Exceptions listed in a request record, and the length of their messages there
+  requestLinks: 10,
+  linkMessage: 500
+});
+
+/**
+ * Cuts a string to at most `max` characters without splitting a surrogate pair.
+ *
+ * @param {string} text
+ * @param {number} max
+ * @returns {string}
+ */
+export function truncate(text, max) {
+  if (typeof text !== 'string' || text.length <= max) return text;
+  let end = max;
+  // A high surrogate at the cut would leave half a character behind.
+  const code = text.charCodeAt(end - 1);
+  if (code >= 0xd800 && code <= 0xdbff) end--;
+  return text.slice(0, end);
+}
+
+/**
+ * Cuts a stack trace to at most `maxBytes` bytes of UTF-8, keeping its start and its end: the
+ * message comes first and the frames last, and a huge message (an error that quotes a whole
+ * response body) must not push the frames out.
+ *
+ * @param {string} stack
+ * @param {number} maxBytes
+ * @returns {string}
+ */
+export function truncateStack(stack, maxBytes) {
+  if (typeof stack !== 'string' || stack.length * 3 <= maxBytes || Buffer.byteLength(stack) <= maxBytes) return stack;
+  const marker = '\n    [...]\n';
+  const half = Math.floor((maxBytes - marker.length) / 2);
+  const head = truncateBytes(stack, half);
+  const tail = Buffer.from(stack, 'utf8');
+  let start = tail.length - half;
+  // Forward over continuation bytes (10xxxxxx) to the start of a character.
+  while (start < tail.length && (tail[start] & 0xc0) === 0x80) start++;
+  return `${head}${marker}${tail.subarray(start).toString('utf8')}`;
+}
+
+/**
+ * Cuts a string to at most `maxBytes` bytes of UTF-8, at a character boundary.
+ *
+ * @param {string} text
+ * @param {number} maxBytes
+ * @returns {string}
+ */
+export function truncateBytes(text, maxBytes) {
+  if (typeof text !== 'string') return text;
+  // Most strings are ASCII-sized: no need to encode them.
+  if (text.length * 3 <= maxBytes) return text;
+  const buffer = Buffer.from(text, 'utf8');
+  if (buffer.length <= maxBytes) return text;
+  let end = maxBytes;
+  // Back up over continuation bytes (10xxxxxx) to the start of the cut character.
+  while (end > 0 && (buffer[end] & 0xc0) === 0x80) end--;
+  return buffer.subarray(0, end).toString('utf8');
+}

package/src/exceptions/process-monitor.js

@@ -0,0 +1,192 @@
+/**
+ * Records crashes: uncaught exceptions, and unhandled promise rejections.
+ *
+ * Observing must not change what Node.js does with them:
+ *
+ * - 'uncaughtExceptionMonitor' sees an uncaught exception (and a rejection that Node.js raises as
+ *   one, origin "unhandledRejection") before the process exits, without handling it: the error is
+ *   still printed the same way and the process still exits with code 1. The process exits as soon
+ *   as the listener returns, so the record is built and delivered synchronously.
+ * - No 'unhandledRejection' listener is added by default: having one is what tells Node.js that
+ *   the app handles rejections itself, and the process would no longer crash. Only when the app
+ *   adds its own listener (the decision is then already made) does PeekInside add one too, to
+ *   record the rejections the app now keeps running after. It is removed with the app's last one.
+ *
+ * One monitor serves every PeekInside instance in the process: a crash goes to the instance that
+ * tracks the request it happened in, otherwise to the most recently created recording instance.
+ */
+
+import { ExceptionCapture } from './exception-capture.js';
+import { RequestContext } from './request-context.js';
+
+// What Node.js raises for a rejection whose reason isn't an error: the reason only survives as
+// text in the message.
+const UNHANDLED_REJECTION_MESSAGE = /The promise rejected with the reason "([\s\S]*)"\.$/;
+
+// In --unhandled-rejections=strict mode one rejection reaches both the monitor and the
+// 'unhandledRejection' listeners, right after each other: the second sighting is skipped.
+const SAME_EVENT_MS = 100;
+
+let installed = false;
+let observingRejections = false;
+let lastSeen = null;
+
+/**
+ * The process-level hooks, installed once per process while an instance records exceptions
+ * automatically.
+ */
+export class ProcessMonitor {
+  /**
+   * Installs the hooks when some PeekInside instance records exceptions automatically, and removes
+   * them when none does anymore.
+   *
+   * @returns {void}
+   */
+  static update() {
+    try {
+      if (ExceptionCapture.anyAutomatic()) install();
+      else uninstall();
+    } catch (error) {
+      // Monitoring must never break the host application.
+    }
+  }
+
+  /**
+   * Whether an uncaught exception now ends the process: neither an 'uncaughtException' listener
+   * nor a capture callback (domains, the REPL) takes it.
+   *
+   * @returns {boolean}
+   */
+  static isFatal() {
+    const captured = typeof process.hasUncaughtExceptionCaptureCallback === 'function' && process.hasUncaughtExceptionCaptureCallback();
+    return !captured && process.listenerCount('uncaughtException') === 0;
+  }
+
+  /**
+   * Whether PeekInside observes unhandled rejections with its own listener right now (only while
+   * the app has one).
+   *
+   * @type {boolean}
+   */
+  static get observingRejections() {
+    return observingRejections;
+  }
+}
+
+function install() {
+  if (installed) return;
+  installed = true;
+  process.on('uncaughtExceptionMonitor', onUncaught);
+  process.on('newListener', onNewListener);
+  process.on('removeListener', onRemoveListener);
+  if (process.listenerCount('unhandledRejection') > 0) observeRejections();
+}
+
+function uninstall() {
+  if (!installed) return;
+  installed = false;
+  process.removeListener('uncaughtExceptionMonitor', onUncaught);
+  process.removeListener('newListener', onNewListener);
+  process.removeListener('removeListener', onRemoveListener);
+  stopObservingRejections();
+}
+
+function observeRejections() {
+  if (observingRejections) return;
+  observingRejections = true;
+  process.on('unhandledRejection', onRejection);
+}
+
+function stopObservingRejections() {
+  if (!observingRejections) return;
+  observingRejections = false;
+  process.removeListener('unhandledRejection', onRejection);
+}
+
+// The app adds an 'unhandledRejection' listener: it now keeps running after rejections. Ours is
+// added in front of it, so a listener that exits the process can't cut the recording short.
+function onNewListener(event, listener) {
+  if (event !== 'unhandledRejection' || listener === onRejection) return;
+  try {
+    observeRejections();
+  } catch (error) {
+    // Ignore: recording rejections is optional.
+  }
+}
+
+// The app's last listener is gone: ours must go too, or rejections would no longer crash.
+function onRemoveListener(event, listener) {
+  if (event !== 'unhandledRejection') return;
+  if (listener === onRejection) {
+    observingRejections = false; // removed by the app (removeAllListeners)
+    return;
+  }
+  try {
+    if (observingRejections && process.listeners('unhandledRejection').every((item) => item === onRejection)) {
+      stopObservingRejections();
+    }
+  } catch (error) {
+    // Ignore.
+  }
+}
+
+function onUncaught(error, origin) {
+  try {
+    const value = unwrapRejection(error, origin);
+    if (alreadyRecorded(value)) return;
+    const escaped = RequestContext.escaped();
+    const context = escaped || RequestContext.current();
+    const capture = captureFor(context);
+    if (!capture) return;
+    const mechanism = origin === 'unhandledRejection'
+      ? 'unhandledRejection'
+      : escaped && escaped.integration === 'http' ? 'http' : 'uncaught';
+    capture.processError(value, {
+      mechanism,
+      fatal: ProcessMonitor.isFatal(),
+      handled: false,
+      context
+    });
+  } catch (failure) {
+    // Never interfere with the crash itself.
+  }
+}
+
+function onRejection(reason) {
+  try {
+    if (alreadyRecorded(reason)) return;
+    const context = RequestContext.current();
+    const capture = captureFor(context);
+    if (!capture) return;
+    capture.processError(reason, { mechanism: 'unhandledRejection', fatal: false, handled: true, context });
+  } catch (failure) {
+    // Ignore.
+  }
+}
+
+// The instance tracking the request, when it records exceptions; otherwise the newest one that does.
+function captureFor(context) {
+  const own = context && context.capture;
+  if (own && own.automatic && own.recording) return own;
+  return ExceptionCapture.latest({ automatic: true });
+}
+
+function alreadyRecorded(value) {
+  const now = Date.now();
+  if (lastSeen && Object.is(lastSeen.value, value) && now - lastSeen.at < SAME_EVENT_MS) return true;
+  lastSeen = { value, at: now };
+  return false;
+}
+
+// Node.js wraps a non-error rejection reason (`Promise.reject('timeout')`) in an error of its own
+// whose stack is only Node.js internals. The reason itself says more.
+function unwrapRejection(error, origin) {
+  if (origin !== 'unhandledRejection' || error === null || typeof error !== 'object') return error;
+  try {
+    if (error.code !== 'ERR_UNHANDLED_REJECTION') return error;
+    const match = UNHANDLED_REJECTION_MESSAGE.exec(String(error.message));
+    return match ? match[1] : error;
+  } catch (failure) {
+    return error;
+  }
+}

package/src/exceptions/rate-limiter.js

@@ -0,0 +1,50 @@
+/**
+ * Bounds how many exceptions are recorded per second.
+ *
+ * An app in trouble can throw thousands of errors a second (a failing database behind every
+ * request, a loop that keeps throwing). Each record reads the stack and maybe source files, and
+ * waits in memory until it is sent, so a storm must not turn into a memory or CPU problem of its
+ * own: past the limit, exceptions are dropped until the bucket refills.
+ */
+
+/**
+ * Token bucket: `burst` tokens to start with, refilled at `rate` tokens per second.
+ */
+export class TokenBucket {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.rate=50] - Tokens added per second
+   * @param {number} [options.burst=100] - Most tokens held
+   * @param {() => number} [options.now] - Clock in ms (for tests)
+   */
+  constructor({ rate = 50, burst = 100, now = Date.now } = {}) {
+    this.rate = rate;
+    this.burst = burst;
+    this._now = now;
+    this._tokens = burst;
+    this._updatedAt = now();
+    /**
+     * Exceptions dropped because the bucket was empty
+     * @type {number}
+     */
+    this.dropped = 0;
+  }
+
+  /**
+   * Takes one token.
+   *
+   * @returns {boolean} False when none is left (the caller drops the exception)
+   */
+  take() {
+    const now = this._now();
+    const elapsed = Math.max(0, now - this._updatedAt) / 1000;
+    this._tokens = Math.min(this.burst, this._tokens + elapsed * this.rate);
+    this._updatedAt = now;
+    if (this._tokens < 1) {
+      this.dropped++;
+      return false;
+    }
+    this._tokens -= 1;
+    return true;
+  }
+}

package/src/exceptions/request-context.js

@@ -0,0 +1,337 @@
+/**
+ * Which request a piece of code runs for, so an exception can be linked to it.
+ *
+ * Each tracked request runs the rest of its handling inside an AsyncLocalStorage context (the
+ * integrations wrap next(), done() or the server's emit()), and the context follows timers,
+ * promises and the request's own events. One place loses it: an exception thrown synchronously
+ * out of the handler unwinds the context before the process-level hooks see it. For that case the
+ * request an exception last escaped from is remembered until the current job ends; the uncaught
+ * exception hook, which runs right after the throw, picks it up.
+ *
+ * The escape is noticed in a `finally` block, never by catching and rethrowing: a rethrown error
+ * would make Node.js print the rethrowing line instead of the app's line when the process crashes.
+ *
+ * The context also keeps the request's exception bookkeeping: which errors were already recorded
+ * (each error object is recorded once per request), the records whose outcome is still open (see
+ * ExceptionCapture), and the count and links that go into the request's record.
+ */
+
+import { AsyncLocalStorage } from 'async_hooks';
+import { BodyDecoder } from '../capture/body-decoder.js';
+import { parseQuery, splitUrl } from '../capture/http-message.js';
+import { LIMITS } from './limits.js';
+
+const storage = new AsyncLocalStorage();
+const kContext = Symbol('peekInside.context');
+// The request an exception last escaped from, until the current job ends.
+let escaped = null;
+
+/**
+ * One request, as exception capture sees it.
+ */
+export class RequestContext {
+  /**
+   * The context of the code running now.
+   *
+   * @returns {RequestContext|null}
+   */
+  static current() {
+    return storage.getStore() || null;
+  }
+
+  /**
+   * Runs `fn` outside any request, along with everything asynchronous it starts: PeekInside's own
+   * work (posting batches to the hub or the cloud, starting the hub) runs from inside requests at
+   * times, and must never show up on a request's timeline.
+   *
+   * @param {Function} fn
+   * @returns {*} What fn returns
+   */
+  static outside(fn) {
+    return storage.exit(fn);
+  }
+
+  /**
+   * The context of a request object.
+   *
+   * @param {import('http').IncomingMessage} req
+   * @returns {RequestContext|null}
+   */
+  static of(req) {
+    if (!req || (typeof req !== 'object' && typeof req !== 'function')) return null;
+    return req[kContext] || null;
+  }
+
+  /**
+   * The request an exception escaped from synchronously during the current job, if one did: the
+   * request of the exception the uncaught exception hook is looking at.
+   *
+   * @returns {RequestContext|null}
+   */
+  static escaped() {
+    return escaped;
+  }
+
+  /**
+   * @param {Object} fields
+   * @param {import('./exception-capture.js').ExceptionCapture|null} fields.capture - Records the
+   *   request's exceptions (the PeekInside instance tracking it)
+   * @param {import('http').IncomingMessage} fields.req
+   * @param {import('../capture/exchange-recorder.js').ExchangeRecorder|null} [fields.recorder] -
+   *   Records the request itself; null when it isn't recorded
+   * @param {{ url: string, pathname: string, search: string }} fields.target - The request target
+   * @param {boolean} [fields.blocked=false] - The request reached a server in local mode: neither
+   *   it nor its exceptions are recorded
+   * @param {string} [fields.integration='custom'] - Where tracking started: "express", "koa",
+   *   "fastify", "http" (a server's emit()) or "custom" (intercept())
+   */
+  constructor({ capture, req, recorder = null, target, blocked = false, integration = 'custom' }) {
+    this.capture = capture;
+    this.recorder = recorder;
+    this.blocked = blocked;
+    this.integration = integration;
+    /**
+     * Id of the request's record, or null when it isn't recorded
+     * @type {string|null}
+     */
+    this.requestId = recorder ? recorder.id : null;
+    this.method = String((req && req.method) || '');
+    this.url = target.url;
+    this.path = target.pathname;
+    this.search = target.search;
+
+    /** Exceptions recorded during the request, for its record. */
+    this.exceptionCount = 0;
+    this.links = [];
+    // Error (or thrown value) -> its record, so each is recorded once per request.
+    this.seen = new Map();
+    // Records whose outcome is still open: handled unless the error reaches the final handler.
+    this.pending = new Map();
+    // Set once the request's record is built.
+    this.finished = false;
+    /**
+     * The request's timeline (see src/timeline), when the instance records one
+     * @type {import('../timeline/timeline.js').Timeline|null}
+     */
+    this.timeline = null;
+    /**
+     * Who the request is for, once the app said so (PeekInside.setUser())
+     * @type {import('../user.js').User|null}
+     */
+    this.user = null;
+
+    this._req = req;
+    // What remains for exceptions after the request finished (see release()).
+    this._after = null;
+
+    if (req && typeof req === 'object') {
+      Object.defineProperty(req, kContext, { value: this, configurable: true, writable: true });
+    }
+  }
+
+  /**
+   * Runs `fn` inside this context. When an exception escapes it, this request is remembered as the
+   * one it escaped from (see RequestContext.escaped()); the exception itself passes through
+   * untouched.
+   *
+   * @param {Function} fn
+   * @returns {*} What `fn` returns
+   */
+  run(fn) {
+    // Code is running again, so an earlier escape was caught by someone: it is not the one a crash
+    // hook may see next.
+    escaped = null;
+    let returned = false;
+    try {
+      const result = storage.run(this, fn);
+      returned = true;
+      return result;
+    } finally {
+      if (!returned) noteEscape(this);
+    }
+  }
+
+  /**
+   * Makes an emitter's listeners run inside this context. The request's and response's events
+   * ('data', 'end', 'finish'...) come from the socket, outside any request, so listeners the app
+   * adds to them would otherwise lose the request.
+   *
+   * @param {import('events').EventEmitter} emitter
+   * @returns {void}
+   */
+  bind(emitter) {
+    if (!emitter || typeof emitter.emit !== 'function') return;
+    const context = this;
+    const originalEmit = emitter.emit;
+    emitter.emit = function () {
+      return context.run(() => originalEmit.apply(this, arguments));
+    };
+  }
+
+  /**
+   * For the exception list: the request's method and path.
+   *
+   * @returns {{ method: string, path: string }}
+   */
+  requestLine() {
+    return { method: this.method, path: this.path };
+  }
+
+  /**
+   * The request as an exception's detail shows it. After the response, the body is no longer
+   * kept (the request's own record has it).
+   *
+   * @returns {Object} A RequestSnapshot
+   */
+  snapshot() {
+    if (this.recorder && !this.recorder.recorded) {
+      return { id: this.requestId, ...this.recorder.snapshot(LIMITS.requestBody) };
+    }
+    const after = this._after || RequestSnapshot.partsOf(this._req);
+    return {
+      id: this.requestId,
+      method: this.method,
+      url: this.url,
+      headers: { ...after.headers },
+      query: parseQuery(this.search),
+      params: { ...after.params },
+      body: '',
+      bodyTruncated: false,
+      ip: after.ip,
+      userAgent: after.userAgent
+    };
+  }
+
+  /**
+   * Counts a recorded exception for the request's record.
+   *
+   * @param {import('./exception-record.js').ExceptionRecord} record
+   * @returns {void}
+   */
+  noteRecorded(record) {
+    this.exceptionCount++;
+    if (this.links.length < LIMITS.requestLinks) this.links.push(record.link());
+  }
+
+  /**
+   * Completes the exchange being turned into the request's record: its exceptions (settling the
+   * ones still open) and its timeline. Then lets go of the request (see release()).
+   *
+   * @param {import('../capture/exchange-recorder.js').Exchange} exchange - Changed in place
+   * @returns {void}
+   */
+  complete(exchange) {
+    if (this.capture) this.capture.finish(this, exchange);
+    this.completeTimeline(exchange);
+    if (this.user) exchange.user = this.user;
+    this.release();
+  }
+
+  /**
+   * Closes the request's timeline and adds its counters (and its spans, if any) to the exchange.
+   *
+   * @param {import('../capture/exchange-recorder.js').Exchange} exchange - Changed in place
+   * @returns {void}
+   */
+  completeTimeline(exchange) {
+    if (!this.timeline) return;
+    try {
+      const { stats, timeline } = this.timeline.close();
+      exchange.stats = stats;
+      if (timeline) exchange.timeline = timeline;
+    } catch (error) {
+      // The request is still recorded, without its timeline.
+    }
+  }
+
+  /**
+   * Lets go of the request and response objects once the request's record is built: code that
+   * keeps running for the request (a timer, a pool created during it) may hold the context for
+   * long, and must not hold the request's bodies (or its timeline) with it.
+   *
+   * @returns {void}
+   */
+  release() {
+    this.finished = true;
+    this._after = RequestSnapshot.partsOf(this._req);
+    this._req = null;
+    this.recorder = null;
+    this.timeline = null;
+  }
+}
+
+/**
+ * Snapshots of requests that are not tracked, for report(error, { request }).
+ */
+export class RequestSnapshot {
+  /**
+   * @param {import('http').IncomingMessage} req
+   * @returns {Object} A RequestSnapshot without an id; the body is what a body parser left on
+   *   req.body, if anything
+   */
+  static fromRequest(req) {
+    const url = String(req.originalUrl || req.url || '/');
+    const { search } = splitUrl(url);
+    const parts = RequestSnapshot.partsOf(req);
+    let body = '';
+    let bodyTruncated = false;
+    try {
+      if (req.body !== undefined) {
+        const content = new BodyDecoder(LIMITS.requestBody).decodeValue(req.body, parts.headers);
+        if (content.encoding === 'utf8') {
+          body = content.text;
+          bodyTruncated = content.truncated;
+        }
+      }
+    } catch (error) {
+      body = '';
+    }
+    return {
+      id: null,
+      method: String(req.method || ''),
+      url,
+      headers: { ...parts.headers },
+      query: parseQuery(search),
+      params: { ...parts.params },
+      body,
+      bodyTruncated,
+      ip: parts.ip,
+      userAgent: parts.userAgent
+    };
+  }
+
+  /**
+   * The small parts of a request that a snapshot keeps.
+   *
+   * @param {import('http').IncomingMessage|null} req
+   * @returns {{ headers: Object, params: Object, ip: string, userAgent: string }}
+   */
+  static partsOf(req) {
+    if (!req) return { headers: {}, params: {}, ip: '', userAgent: '' };
+    const headers = req.headers && typeof req.headers === 'object' ? req.headers : {};
+    const params = {};
+    if (req.params && typeof req.params === 'object') {
+      for (const key of Object.keys(req.params)) {
+        const value = req.params[key];
+        if (value !== undefined && value !== null && typeof value !== 'object') params[key] = String(value);
+      }
+    }
+    return {
+      headers,
+      params,
+      ip: String(req.ip || (req.socket && req.socket.remoteAddress) || ''),
+      userAgent: String(headers['user-agent'] || '')
+    };
+  }
+}
+
+// The innermost context wins: the exception escaped from it first. Once the job ends, the
+// exception was either caught by someone else or has been handled by the uncaught exception
+// hook, so the note is cleared.
+function noteEscape(context) {
+  if (escaped) return;
+  escaped = context;
+  queueMicrotask(() => {
+    escaped = null;
+  });
+}