peekinside 0.0.0-stage → 1.2.0

package/src/integrations/framework-adapter.js

@@ -0,0 +1,53 @@
+/**
+ * Base class of the framework integrations.
+ *
+ * An adapter recognizes one kind of app and plugs PeekInside into it. Every adapter hands each
+ * request to the same PeekInside#_intercept(), which also runs the rest of the request inside its
+ * context, so recording works the same everywhere; adapters only differ in where they hook in,
+ * how they see the framework's errors and how they find the app's HTTP server.
+ */
+
+/**
+ * Plugs PeekInside into one kind of app.
+ *
+ * Subclasses set `framework`, and implement matches() and attach().
+ */
+export class FrameworkAdapter {
+  /**
+   * Framework name shown next to the app in the local dashboard.
+   *
+   * @type {string}
+   */
+  static framework = 'node';
+
+  /**
+   * Whether `app` is the kind of app this adapter handles. Detection is duck-typed, so PeekInside
+   * never has to import (or depend on) the frameworks themselves.
+   *
+   * @param {*} app
+   * @returns {boolean}
+   */
+  static matches(app) {
+    return false;
+  }
+
+  /**
+   * @param {{ _intercept: Function, options: Object }} peekInside - The PeekInside instance that
+   *   records exchanges
+   * @param {import('./server-binder.js').ServerBinder} servers - Tracks the app's HTTP servers
+   */
+  constructor(peekInside, servers) {
+    this.peekInside = peekInside;
+    this.servers = servers;
+  }
+
+  /**
+   * Starts recording every request the app handles.
+   *
+   * @param {Object} app - An app this adapter matches
+   * @returns {void}
+   */
+  attach(app) {
+    throw new Error(`${this.constructor.name} does not implement attach()`);
+  }
+}

package/src/integrations/http-server.js

@@ -0,0 +1,32 @@
+/**
+ * Integration for native http (and https) servers.
+ */
+
+import net from 'net';
+import { FrameworkAdapter } from './framework-adapter.js';
+
+/**
+ * Records every request a server emits, before the app's own request listeners run.
+ */
+export class HttpServerAdapter extends FrameworkAdapter {
+  static framework = 'http';
+
+  /**
+   * @param {*} target
+   * @returns {boolean} Whether `target` is a server, or behaves like one
+   */
+  static matches(target) {
+    return target instanceof net.Server ||
+      (Boolean(target) && typeof target.on === 'function' && typeof target.emit === 'function' && typeof target.listen === 'function');
+  }
+
+  /**
+   * Records the server's requests and learns its port once it listens.
+   *
+   * @param {import('http').Server} server
+   * @returns {void}
+   */
+  attach(server) {
+    this.servers.bind(server, { interceptRequests: true });
+  }
+}

package/src/integrations/koa.js

@@ -0,0 +1,72 @@
+/**
+ * Koa integration.
+ */
+
+import { ExchangeRecorder } from '../capture/exchange-recorder.js';
+import { RequestContext } from '../exceptions/request-context.js';
+import { FrameworkAdapter } from './framework-adapter.js';
+
+/**
+ * Records requests through a Koa middleware, and the errors that propagate out of the middleware
+ * after it.
+ *
+ * Errors are seen by catching around `await next()` and rethrowing them unchanged, so Koa still
+ * answers them and still emits 'error' (which logs them when the app has no listener). No 'error'
+ * listener is added: Koa only logs errors itself while the app has none.
+ */
+export class KoaAdapter extends FrameworkAdapter {
+  static framework = 'koa';
+
+  /**
+   * @param {*} app
+   * @returns {boolean} Whether `app` looks like a Koa application
+   */
+  static matches(app) {
+    return Boolean(app) && typeof app.use === 'function' && typeof app.callback === 'function' && Array.isArray(app.middleware);
+  }
+
+  /**
+   * Koa middleware that records each exchange from the underlying Node request and response.
+   * Body parsers for Koa keep the parsed body on ctx.request, not on the Node request, so the
+   * recorder is told where to look in case a parser read the body first.
+   *
+   * Errors are recorded as unhandled: Koa's default handler answers them, unless middleware
+   * registered before this one catches them, so attach PeekInside before your own error handler.
+   *
+   * @returns {Function} Koa middleware `(ctx, next)`
+   */
+  middleware() {
+    return (ctx, next) => {
+      ExchangeRecorder.setBodySource(ctx.req, () => ctx.request.body);
+      return this.peekInside._intercept(ctx.req, ctx.res, () => KoaAdapter._next(ctx, next), 'koa');
+    };
+  }
+
+  /**
+   * Adds the middleware and watches app.listen() for the app's server.
+   *
+   * @param {Object} app - Koa application
+   * @returns {void}
+   */
+  attach(app) {
+    app.use(this.middleware());
+    this.servers.patchListen(app);
+  }
+
+  // Runs the downstream middleware and records what it throws, then rethrows it unchanged.
+  static async _next(ctx, next) {
+    try {
+      await next();
+    } catch (error) {
+      try {
+        const context = RequestContext.of(ctx.req);
+        if (context && context.capture) {
+          context.capture.frameworkError(context, error, { mechanism: 'koa', handled: false });
+        }
+      } catch (failure) {
+        // Recording must never change the error the app sees.
+      }
+      throw error;
+    }
+  }
+}

package/src/integrations/server-binder.js

@@ -0,0 +1,120 @@
+/**
+ * Finds the app's HTTP servers, to learn the port the app listens on (the local dashboard shows
+ * it, and registers the app as soon as it is known) and, for plain http servers, to see every
+ * request.
+ *
+ * Servers are found three ways: passed directly (http.Server, Fastify), returned by a patched
+ * app.listen() (Express, Koa), or discovered from the socket of a request the app handled, which
+ * catches servers created with http.createServer(app).
+ */
+
+/**
+ * Binds each of the app's servers once.
+ */
+export class ServerBinder {
+  /**
+   * @param {{ _intercept: Function }} peekInside - Records exchanges, for servers whose requests
+   *   are intercepted here
+   * @param {Object} options
+   * @param {(port: number) => void} options.onListening - Called once, with the first port the
+   *   app listens on
+   */
+  constructor(peekInside, { onListening }) {
+    this.peekInside = peekInside;
+    this._onListening = onListening;
+    this._bound = new WeakSet();
+
+    /**
+     * Port the app listens on, once known
+     * @type {number|null}
+     */
+    this.appPort = null;
+  }
+
+  /**
+   * Wraps app.listen() so the server it creates is bound as soon as it exists.
+   *
+   * @param {Object} app - Express or Koa app
+   * @returns {void}
+   */
+  patchListen(app) {
+    if (typeof app.listen !== 'function') {
+      return;
+    }
+    const binder = this;
+    const originalListen = app.listen;
+
+    app.listen = function (...args) {
+      const server = originalListen.apply(this, args);
+      if (server && typeof server.emit === 'function') {
+        binder.bind(server);
+      }
+      return server;
+    };
+  }
+
+  /**
+   * Binds the server a request arrived on, if it isn't bound yet.
+   *
+   * @param {import('http').IncomingMessage} req
+   * @returns {void}
+   */
+  discover(req) {
+    const socket = req.socket;
+    const server = socket && (socket.server || socket._server);
+    if (server && !this._bound.has(server)) {
+      this.bind(server);
+    }
+  }
+
+  /**
+   * Watches a server for its port. A server is bound only once: binding it again changes nothing.
+   *
+   * @param {import('http').Server} server
+   * @param {Object} [options]
+   * @param {boolean} [options.interceptRequests=false] - Also record every request the server
+   *   emits, for plain http servers where no middleware runs
+   * @returns {void}
+   */
+  bind(server, { interceptRequests = false } = {}) {
+    if (!server || typeof server.emit !== 'function' || this._bound.has(server)) {
+      return;
+    }
+    this._bound.add(server);
+
+    if (interceptRequests) {
+      // Wrapping emit() runs PeekInside before every 'request' listener, including the app's, and
+      // runs the listeners inside the request's context. An error a listener throws escapes
+      // through here unchanged.
+      const peekInside = this.peekInside;
+      const originalEmit = server.emit;
+      server.emit = function (event, req, res) {
+        if (event === 'request' && req && res) {
+          const args = arguments;
+          return peekInside._intercept(req, res, () => originalEmit.apply(this, args), 'http');
+        }
+        return originalEmit.apply(this, arguments);
+      };
+    }
+
+    if (typeof server.once === 'function') {
+      const onListening = () => this._noteListening(server);
+      if (server.listening) {
+        onListening();
+      } else {
+        server.once('listening', onListening);
+      }
+    }
+  }
+
+  // The first port seen is the app's port; servers on pipes or sockets have no port.
+  _noteListening(server) {
+    const address = typeof server.address === 'function' ? server.address() : null;
+    const port = address && typeof address === 'object' ? address.port : null;
+    if (port === null || this.appPort !== null) {
+      return;
+    }
+    this.appPort = port;
+    this._onListening(port);
+  }
+}

package/src/jobs/job-context.js

@@ -0,0 +1,40 @@
+/**
+ * A job run's context: what a request's context is to a request, for a background job. Code the
+ * job runs (queries, outgoing calls, log lines, exceptions) finds the run through it and links
+ * to it, with the same AsyncLocalStorage the requests use.
+ */
+
+import { randomUUID } from 'crypto';
+import { RequestContext } from '../exceptions/request-context.js';
+
+const NO_TARGET = Object.freeze({ url: '', pathname: '', search: '' });
+
+/**
+ * One job run.
+ */
+export class JobContext extends RequestContext {
+  /**
+   * @param {Object} fields
+   * @param {import('../exceptions/exception-capture.js').ExceptionCapture} fields.capture
+   * @param {string} fields.name - The job's name
+   */
+  constructor({ capture, name }) {
+    super({ capture, req: null, recorder: null, target: NO_TARGET, integration: 'job' });
+    /**
+     * The id of the run's record
+     * @type {string}
+     */
+    this.jobRunId = randomUUID();
+    this.jobName = name;
+  }
+
+  /** A job has no request to show with its exceptions. */
+  snapshot() {
+    return null;
+  }
+
+  /** @returns {null} */
+  requestLine() {
+    return null;
+  }
+}

package/src/jobs/job-run-record.js

@@ -0,0 +1,104 @@
+/**
+ * One run of a background job (a scheduled task, a queue worker's job, or code wrapped in
+ * PeekInside.job()), as the Jobs page lists it (see the data contract).
+ *
+ * Readable in PeekInside Cloud, like a request's method and status: the job's name, its queue and
+ * schedule, when it ran, for how long, how it ended, its attempt and counters. Sealed: the error it
+ * failed with, the user, the job's data and its timeline.
+ */
+
+/**
+ * A recorded job run.
+ */
+export class JobRunRecord {
+  /**
+   * @param {Object} fields
+   * @param {string} fields.id - UUID
+   * @param {number} fields.occurredAt - When the run started (ms since the epoch)
+   * @param {string} fields.environment
+   * @param {string|null} [fields.release=null]
+   * @param {string} fields.name - Such as "send-invoices"
+   * @param {string|null} [fields.queue=null] - The queue it came from (BullMQ)
+   * @param {string|null} [fields.schedule=null] - Its cron expression, when it runs on one
+   * @param {string|null} [fields.timezone=null] - The schedule's time zone
+   * @param {'cron'|'queue'|'manual'} fields.trigger
+   * @param {'ok'|'failed'} fields.status
+   * @param {number|null} fields.duration - ms
+   * @param {number} [fields.attempt=1]
+   * @param {number} [fields.exceptionCount=0]
+   * @param {Object} [fields.stats] - Timeline counters, as requests have them
+   * @param {Object} fields.summary - `{ error: { name, message } | null, user }` (sealed in Cloud)
+   * @param {Object} fields.detail - `{ data, timeline, exceptions }` (sealed in Cloud)
+   */
+  constructor({ id, occurredAt, environment, release = null, name, queue = null, schedule = null, timezone = null, trigger, status, duration, attempt = 1, exceptionCount = 0, stats, summary, detail }) {
+    this.id = id;
+    this.occurredAt = occurredAt;
+    this.environment = environment;
+    this.release = release;
+    this.name = name;
+    this.queue = queue;
+    this.schedule = schedule;
+    this.timezone = timezone;
+    this.trigger = trigger;
+    this.status = status;
+    this.duration = duration;
+    this.attempt = attempt;
+    this.exceptionCount = exceptionCount;
+    if (stats) this.stats = stats;
+    this.summary = summary;
+    this.detail = detail;
+  }
+
+  /**
+   * The plain form, as the local hub stores it.
+   *
+   * @returns {Object}
+   */
+  toJSON() {
+    return { ...this };
+  }
+
+  /**
+   * The sealed form, for PeekInside Cloud.
+   *
+   * @param {import('../crypto.js').Sealer} sealer
+   * @returns {Promise<Object>}
+   */
+  async seal(sealer) {
+    const { summary, detail, ...meta } = this.toJSON();
+    return {
+      ...meta,
+      summary: await sealer.seal(JSON.stringify(summary), JobRunRecord.summaryAad(this.id)),
+      detail: await sealer.seal(JSON.stringify(detail), JobRunRecord.detailAad(this.id))
+    };
+  }
+
+  /**
+   * @param {import('../crypto.js').SyncSealer} sealer
+   * @returns {Object}
+   */
+  sealSync(sealer) {
+    const { summary, detail, ...meta } = this.toJSON();
+    return {
+      ...meta,
+      summary: sealer.seal(JSON.stringify(summary), JobRunRecord.summaryAad(this.id)),
+      detail: sealer.seal(JSON.stringify(detail), JobRunRecord.detailAad(this.id))
+    };
+  }
+
+  /**
+   * @param {string} id
+   * @returns {string}
+   */
+  static summaryAad(id) {
+    return `job:summary:${id}`;
+  }
+
+  /**
+   * @param {string} id
+   * @returns {string}
+   */
+  static detailAad(id) {
+    return `job:detail:${id}`;
+  }
+}

package/src/jobs/job-runner.js

@@ -0,0 +1,173 @@
+/**
+ * Runs a background job as a recorded job run: its own context (so its queries, calls, log lines
+ * and exceptions link to it), a timeline, and a record of how it went (see JobRunRecord). The
+ * job's function runs exactly as it would without PeekInside: same arguments, same result, same
+ * error thrown.
+ */
+
+import { performance } from 'perf_hooks';
+import { ExceptionCapture } from '../exceptions/exception-capture.js';
+import { truncate, truncateBytes } from '../exceptions/limits.js';
+import { SafeJson } from '../exceptions/safe-json.js';
+import { isNativePromise } from '../instrumentation/patch.js';
+import { Timeline } from '../timeline/timeline.js';
+import { JobContext } from './job-context.js';
+import { JobRunRecord } from './job-run-record.js';
+
+const MAX_NAME = 128;
+const MAX_SCHEDULE = 128;
+const MAX_DATA = 8 * 1024;
+const MAX_ERROR_MESSAGE = 1000;
+
+/**
+ * @typedef {Object} JobOptions
+ * @property {string} [schedule] - Its cron expression, when it runs on one (monitors it)
+ * @property {string} [timezone] - The schedule's time zone
+ * @property {string} [queue] - The queue it came from
+ * @property {number} [attempt=1]
+ * @property {*} [data] - The job's input, shown with the run (first 8 KB)
+ * @property {'cron'|'queue'|'manual'} [trigger]
+ */
+
+/**
+ * Runs jobs for one PeekInside instance.
+ */
+export class JobRunner {
+  /**
+   * Runs `fn` as a job run of the instance tracking the code running now, else the most recently
+   * created instance that records. Without one, just runs `fn`.
+   *
+   * @param {string} name
+   * @param {Function} fn
+   * @param {JobOptions} [options]
+   * @returns {*} What fn returns
+   */
+  static run(name, fn, options = {}) {
+    const capture = ExceptionCapture.latest();
+    const owner = capture ? capture.owner : null;
+    const runner = owner && owner._jobs;
+    return runner ? runner.run(name, fn, options) : fn();
+  }
+
+  /**
+   * @param {Object} options
+   * @param {import('../exceptions/exception-capture.js').ExceptionCapture} options.capture
+   * @param {() => Object|null} options.sink - The instance's transport
+   * @param {() => import('../timeline/timeline.js').TimelineSettings|null} options.timeline
+   * @param {() => boolean} options.isEnabled
+   */
+  constructor({ capture, sink, timeline, isEnabled }) {
+    this.capture = capture;
+    this._sink = sink;
+    this._timeline = timeline;
+    this._isEnabled = isEnabled;
+  }
+
+  /**
+   * @param {string} name
+   * @param {Function} fn
+   * @param {JobOptions} [options]
+   * @returns {*} What fn returns (for an async fn, a promise of the same outcome)
+   */
+  run(name, fn, options = {}) {
+    if (typeof fn !== 'function') throw new TypeError('PeekInside.job() needs a function to run');
+    const sink = this._sink();
+    if (!sink || sink.disabled || !this._isEnabled()) return fn();
+
+    const context = new JobContext({ capture: this.capture, name: jobName(name) });
+    const settings = this._timeline();
+    if (settings) context.timeline = new Timeline(settings);
+    const run = { context, options: options || {}, occurredAt: Date.now(), started: performance.now() };
+
+    let result;
+    try {
+      result = context.run(fn);
+    } catch (error) {
+      this._finish(run, error, true);
+      throw error;
+    }
+    if (isNativePromise(result) || (result && typeof result.then === 'function')) {
+      return Promise.resolve(result).then(
+        (value) => {
+          this._finish(run, null, false);
+          return value;
+        },
+        (error) => {
+          this._finish(run, error, true);
+          throw error;
+        }
+      );
+    }
+    this._finish(run, null, false);
+    return result;
+  }
+
+  // Records the run; never throws into the job.
+  _finish({ context, options, occurredAt, started }, error, failed) {
+    try {
+      if (failed) this.capture.jobError(context, error);
+      const sink = this._sink();
+      if (!sink || sink.disabled) return;
+      const closed = context.timeline ? context.timeline.close() : null;
+      const schedule = typeof options.schedule === 'string' && options.schedule.trim() ? truncate(options.schedule.trim(), MAX_SCHEDULE) : null;
+      const queue = typeof options.queue === 'string' && options.queue ? truncate(options.queue, MAX_NAME) : null;
+      const record = new JobRunRecord({
+        id: context.jobRunId,
+        occurredAt,
+        environment: sink.environment,
+        release: sink.release || null,
+        name: context.jobName,
+        queue,
+        schedule,
+        timezone: typeof options.timezone === 'string' && options.timezone ? truncate(options.timezone, 64) : null,
+        trigger: ['cron', 'queue', 'manual'].includes(options.trigger) ? options.trigger : schedule ? 'cron' : queue ? 'queue' : 'manual',
+        status: failed ? 'failed' : 'ok',
+        duration: Math.round((performance.now() - started) * 100) / 100,
+        attempt: Number.isInteger(options.attempt) && options.attempt > 0 ? options.attempt : 1,
+        exceptionCount: context.exceptionCount,
+        stats: closed ? closed.stats : undefined,
+        summary: { error: failed ? describe(error) : null, ...(context.user ? { user: context.user } : {}) },
+        detail: {
+          data: preview(options.data),
+          exceptions: context.links.slice(),
+          ...(closed && closed.timeline ? { timeline: closed.timeline } : {})
+        }
+      });
+      context.release();
+      sink.enqueueRecord(record);
+    } catch (failure) {
+      // The job's own outcome is unaffected.
+    }
+  }
+}
+
+function jobName(name) {
+  const text = typeof name === 'string' ? name.trim() : '';
+  return truncate(text || 'job', MAX_NAME);
+}
+
+function describe(error) {
+  if (error instanceof Error || (error && typeof error === 'object' && typeof error.message === 'string')) {
+    let name = 'Error';
+    try {
+      name = String(error.name || (error.constructor && error.constructor.name) || 'Error');
+    } catch (failure) {
+      name = 'Error';
+    }
+    return { name: truncate(name, 200), message: truncate(String(error.message), MAX_ERROR_MESSAGE) };
+  }
+  return { name: 'ThrownValue', message: truncate(String(error), MAX_ERROR_MESSAGE) };
+}
+
+// The job's input as JSON-safe data, or a preview of its JSON past 8 KB.
+function preview(data) {
+  if (data === undefined) return null;
+  const { json, truncated } = SafeJson.stringify(data, MAX_DATA + 1);
+  if (json === undefined) return null;
+  if (truncated || Buffer.byteLength(json) > MAX_DATA) return { truncated: true, preview: truncateBytes(json, 2048) };
+  try {
+    return JSON.parse(json);
+  } catch (error) {
+    return null;
+  }
+}