peekinside 0.0.0-stage → 1.2.1

package/src/capture/ignored-paths.js

@@ -0,0 +1,49 @@
+/**
+ * Which request paths are never recorded: browser and dev-server noise, plus the app's own
+ * `ignorePaths` rules.
+ */
+
+/**
+ * Prefixes of browser and dev-server noise that is never worth recording.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export const DEFAULT_SKIP_PATHS = Object.freeze(['/.well-known/', '/favicon.ico', '/__webpack_hmr', '/sockjs-node/', '/_next/static/', '/static/']);
+
+/**
+ * Whether a path must not be recorded.
+ *
+ * The rules are passed on every call rather than kept, because apps may change their
+ * `ignorePaths` option after PeekInside starts (attachTo() merges new options in).
+ *
+ * @param {string} pathname - Request path, without the query string
+ * @param {string|RegExp|Function|Array<string|RegExp|Function>} rules - String prefixes, regular
+ *   expressions, or predicates receiving the pathname. Empty strings match nothing, and a
+ *   predicate that throws counts as no match.
+ * @returns {boolean}
+ */
+export function isIgnoredPath(pathname, rules) {
+  if (DEFAULT_SKIP_PATHS.some(prefix => pathname.startsWith(prefix))) {
+    return true;
+  }
+
+  const list = Array.isArray(rules) ? rules : [rules];
+  return list.some(rule => {
+    if (typeof rule === 'string') {
+      return rule !== '' && pathname.startsWith(rule);
+    }
+    if (rule instanceof RegExp) {
+      // A global or sticky expression would otherwise resume from where its last match ended.
+      rule.lastIndex = 0;
+      return rule.test(pathname);
+    }
+    if (typeof rule === 'function') {
+      try {
+        return Boolean(rule(pathname));
+      } catch (error) {
+        return false;
+      }
+    }
+    return false;
+  });
+}

package/src/capture/request-body-tap.js

@@ -0,0 +1,40 @@
+/**
+ * Captures a request body as the app reads it.
+ *
+ * Reading stays the app's business: adding a 'data' listener would switch the stream into
+ * flowing mode, so data could flow before the app's body parser is ready for it. Wrapping
+ * emit() instead shows PeekInside every chunk the app receives, whichever middleware reads it
+ * and whenever, so middleware order does not matter.
+ */
+
+import { BodyCapture } from './body-capture.js';
+
+/**
+ * Observes the 'data' events of one request.
+ */
+export class RequestBodyTap {
+  /**
+   * Starts observing `req`.
+   *
+   * @param {import('http').IncomingMessage} req
+   * @param {number} limit - Most bytes kept
+   */
+  constructor(req, limit) {
+    /**
+     * Bytes the app has read so far
+     * @type {BodyCapture}
+     */
+    this.body = new BodyCapture(limit);
+
+    if (typeof req.emit === 'function') {
+      const body = this.body;
+      const originalEmit = req.emit;
+      req.emit = function (event, chunk) {
+        if (event === 'data') {
+          body.push(chunk);
+        }
+        return originalEmit.apply(this, arguments);
+      };
+    }
+  }
+}

package/src/capture/response-tap.js

@@ -0,0 +1,83 @@
+/**
+ * Captures a response as the app sends it: the body passed to write() and end(), and the headers
+ * passed directly to writeHead(), which res.getHeaders() does not report.
+ */
+
+import { BodyCapture } from './body-capture.js';
+import { mergeHeaders, normalizeHeaders } from './http-message.js';
+
+/**
+ * Wraps the write methods of one response.
+ *
+ * The originals are always called with the same arguments and their results returned, so the
+ * response behaves exactly as without PeekInside.
+ */
+export class ResponseTap {
+  /**
+   * Starts observing `res`.
+   *
+   * @param {import('http').ServerResponse} res
+   * @param {number} limit - Most body bytes kept
+   */
+  constructor(res, limit) {
+    /**
+     * Bytes the app has written so far
+     * @type {BodyCapture}
+     */
+    this.body = new BodyCapture(limit);
+    this._res = res;
+    this._explicitHeaders = null;
+
+    this._tapBody(res);
+    this._tapWriteHead(res);
+  }
+
+  /**
+   * Response headers: those set with setHeader(), plus those passed to writeHead().
+   *
+   * @returns {Object<string, string|string[]|number>} Lowercase names
+   */
+  headers() {
+    const res = this._res;
+    const current = typeof res.getHeaders === 'function' ? res.getHeaders() : {};
+    return mergeHeaders(current, this._explicitHeaders);
+  }
+
+  // Writes after end(), including a second end(), send nothing, so they are not part of the body.
+  _tapBody(res) {
+    const body = this.body;
+    const originalWrite = res.write;
+    const originalEnd = res.end;
+
+    res.write = function (chunk, encoding) {
+      if (!res.writableEnded) {
+        body.push(chunk, encoding);
+      }
+      return originalWrite.apply(this, arguments);
+    };
+
+    res.end = function (chunk, encoding) {
+      if (!res.writableEnded) {
+        body.push(chunk, encoding);
+      }
+      return originalEnd.apply(this, arguments);
+    };
+  }
+
+  // writeHead(status, [reason], [headers]): headers may be an object or a flat or nested array.
+  _tapWriteHead(res) {
+    const tap = this;
+    const originalWriteHead = res.writeHead;
+    if (typeof originalWriteHead !== 'function') {
+      return;
+    }
+
+    res.writeHead = function (statusCode, reason, headers) {
+      const provided = reason !== null && typeof reason === 'object' ? reason : headers;
+      if (provided) {
+        tap._explicitHeaders = mergeHeaders(tap._explicitHeaders, normalizeHeaders(provided));
+      }
+      return originalWriteHead.apply(this, arguments);
+    };
+  }
+}

package/src/cli.js

@@ -0,0 +1,254 @@
+/**
+ * The `peekinside` command, which manages the free local dashboard:
+ *
+ *   npx peekinside            Start it in the background (if needed) and print its address
+ *   npx peekinside open       Same, then open it in the browser
+ *   npx peekinside status     Show whether it runs and which projects it holds
+ *   npx peekinside stop       Stop it (data stays on disk)
+ *   npx peekinside run        Run it in this terminal, with its log
+ *   npx peekinside test       Send a test error, to check that a project is set up
+ */
+
+import { spawn } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { LOG_PREFIX, VERSION, settings } from './config.js';
+import { HubClient } from './hub/client.js';
+import { HubProcess } from './hub/process.js';
+
+/**
+ * Runs one command against the hub on the configured port.
+ */
+export class Cli {
+  /**
+   * Targets the hub on PEEKINSIDE_HUB_PORT (default 7335).
+   */
+  constructor() {
+    this.port = settings.hubPort();
+    this.url = settings.hubUrl(this.port);
+    this.hub = new HubClient(this.port);
+  }
+
+  /**
+   * Runs a command. Unknown commands print the help and exit with status 1, as do failures.
+   *
+   * @param {string[]} args - Command-line arguments, without node and the script
+   * @returns {void}
+   */
+  run(args) {
+    const command = args[0] || 'start';
+    const commands = {
+      start: () => this.start(false),
+      open: () => this.start(true),
+      status: () => this.status(),
+      stop: () => this.stop(),
+      run: () => new HubProcess().run(),
+      test: () => this.test(),
+      help: () => this.help(),
+      '--help': () => this.help(),
+      '-h': () => this.help(),
+      '--version': () => console.log(VERSION),
+      '-v': () => console.log(VERSION)
+    };
+
+    if (!commands[command]) {
+      console.error(`Unknown command: ${command}\n`);
+      this.help();
+      process.exit(1);
+    }
+    Promise.resolve(commands[command]()).catch((error) => {
+      console.error(error.message);
+      process.exit(1);
+    });
+  }
+
+  /**
+   * Starts the hub in the background unless it already runs, and prints its address.
+   *
+   * @param {boolean} openBrowser - Also open the dashboard in the default browser
+   * @returns {Promise<void>}
+   * @throws {Error} When the hub did not start in time
+   */
+  async start(openBrowser) {
+    let running = await this.hub.status();
+    if (!running) {
+      this.hub.spawn();
+      running = await this.hub.waitUntilReady(8000);
+      if (!running) {
+        throw new Error(`The local dashboard did not start. See ${settings.dataDir()}/hub.log`);
+      }
+    }
+    console.log(`PeekInside Local is running: ${this.url}`);
+    if (openBrowser) this._openInBrowser(this.url);
+  }
+
+  /**
+   * Prints whether the hub runs, and its projects.
+   *
+   * @returns {Promise<void>}
+   */
+  async status() {
+    const running = await this.hub.status();
+    if (!running) {
+      console.log(`PeekInside Local is not running. Start it with: npx peekinside`);
+      console.log(`Data folder: ${settings.dataDir()}`);
+      return;
+    }
+    const { projects } = await this.hub.request('GET', '/api/projects');
+    console.log(`PeekInside Local ${running.version} is running: ${this.url} (pid ${running.pid})`);
+    console.log(`Data folder: ${running.dataDir}\n`);
+    if (!projects.length) {
+      console.log('No projects yet. Attach PeekInside to an app and start it.');
+      return;
+    }
+    for (const project of projects) {
+      const state = project.online
+        ? `running${project.instances[0] && project.instances[0].port ? ` on :${project.instances[0].port}` : ''}`
+        : 'stopped';
+      const exceptions = Number.isInteger(project.exceptionCount) ? `${String(project.exceptionCount).padStart(5)} exceptions   ` : '';
+      console.log(`  ${project.online ? '●' : '○'} ${project.name.padEnd(28)} ${String(project.requestCount).padStart(6)} requests ${exceptions}  ${state}`);
+      console.log(`    ${project.root}`);
+    }
+  }
+
+  /**
+   * Stops the hub and waits up to five seconds for it to exit.
+   *
+   * @returns {Promise<void>}
+   * @throws {Error} When it is still running after that
+   */
+  async stop() {
+    const running = await this.hub.status();
+    if (!running) {
+      console.log('PeekInside Local is not running.');
+      return;
+    }
+    process.kill(running.pid, 'SIGTERM');
+    for (let i = 0; i < 50; i++) {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      if (!(await this.hub.status().catch(() => null))) {
+        console.log('PeekInside Local stopped. Your data stays in ' + running.dataDir);
+        return;
+      }
+    }
+    throw new Error(`PeekInside Local (pid ${running.pid}) did not stop.`);
+  }
+
+  /**
+   * Sends a test error the way the app would, run from the project's folder: to PeekInside Cloud
+   * when PEEKINSIDE_API_KEY is set (in the environment, or in the project's .env), otherwise to the
+   * local dashboard, which is started if needed. Exits with status 1 when it didn't arrive.
+   *
+   * @returns {Promise<void>}
+   * @throws {Error} When the error could not be delivered
+   */
+  async test() {
+    loadProjectEnv(process.cwd());
+    const { default: PeekInside } = await import('./PeekInside.js');
+    const cloud = Boolean(settings.apiKey());
+    if (!cloud) await this.start(false);
+
+    // Only report(): no automatic capture of this command's own errors, no instrumentation.
+    const peekInside = new PeekInside({ local: true, captureExceptions: false, timeline: false, projectRoot: process.cwd() });
+    const transport = peekInside._transport;
+    if (!transport) throw new Error('PeekInside could not set up a destination for the test error.');
+    if (peekInside._local) {
+      // This command prints where the error went; the app's "Requests from ..." line would only confuse.
+      peekInside._local.announced = true;
+      peekInside._local.start();
+    }
+
+    const id = peekInside.report(new PeekInsideTestError(), {
+      request: { method: 'GET', url: '/peekinside/test', headers: { host: 'localhost', 'user-agent': `peekinside-cli/${VERSION}` } },
+      tags: { test: 'true' },
+      extra: { sentBy: 'npx peekinside test', node: process.version, release: peekInside.release },
+      handled: true
+    });
+    if (!id) throw new Error('PeekInside is paused or not recording, so no test error was sent.');
+
+    const deadline = Date.now() + 15_000;
+    while ((transport.queue.length || transport.inflight) && !transport.disabled && Date.now() < deadline) {
+      await transport.flush();
+      if (transport.queue.length) await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    const delivered = !transport.disabled && !transport.queue.length && !transport.inflight;
+    peekInside.stop();
+    if (!delivered) {
+      throw new Error(cloud
+        ? 'The test error did not reach PeekInside Cloud. Check PEEKINSIDE_API_KEY and your connection.'
+        : `The test error did not reach the local dashboard. See ${settings.dataDir()}/hub.log`);
+    }
+
+    const where = cloud
+      ? `PeekInside Cloud (${transport.environment}). Open your project's Exceptions page: ${settings.siteUrl()}/projects`
+      : `PeekInside Local: ${this.url}/p/${peekInside._local.project.id}/exceptions`;
+    console.log(`${LOG_PREFIX} Sent a test error to ${where}`);
+    if (peekInside.release) console.log(`${LOG_PREFIX} Release: ${peekInside.release}`);
+  }
+
+  /**
+   * Prints the usage.
+   *
+   * @returns {void}
+   */
+  help() {
+    console.log(`PeekInside ${VERSION}: the free local dashboard for all your Node.js projects
+
+Usage: npx peekinside [command]
+
+  start     Start the dashboard in the background and print its address (default)
+  open      Start it and open it in your browser
+  status    Show whether it is running and list your projects
+  stop      Stop it; your data stays in ${settings.dataDir()}
+  run       Run it in this terminal
+  test      Send a test error from this project, to check it's set up
+
+Apps that use PeekInside start the dashboard automatically.
+Settings: PEEKINSIDE_HUB_PORT (default 7335), PEEKINSIDE_HOME (default ~/.peekinside)`);
+  }
+
+  // Opening a browser is a convenience: when it fails, the address is printed instead.
+  _openInBrowser(target) {
+    const [cmd, args] = process.platform === 'darwin'
+      ? ['open', [target]]
+      : process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', target]]
+        : ['xdg-open', [target]];
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => console.log(`Open ${target} in your browser.`));
+    child.unref();
+  }
+}
+
+/**
+ * The error `npx peekinside test` sends: a stand-in for a real one, with a name of its own so it
+ * groups into one issue however often it is sent.
+ */
+class PeekInsideTestError extends Error {
+  constructor() {
+    super('This is a test error sent by `npx peekinside test`: errors from this project reach PeekInside.');
+    this.name = 'PeekInsideTestError';
+  }
+}
+
+// PEEKINSIDE_* settings from the project's .env files, for the variables the environment doesn't
+// set already: apps usually load PEEKINSIDE_API_KEY from .env, and so does this command. Nothing
+// else in those files is read into the environment.
+function loadProjectEnv(dir) {
+  for (const name of ['.env.local', '.env']) {
+    let text;
+    try {
+      text = fs.readFileSync(path.join(dir, name), 'utf8');
+    } catch (error) {
+      continue;
+    }
+    for (const line of text.split(/\r?\n/)) {
+      const match = /^\s*(?:export\s+)?(PEEKINSIDE_[A-Z_]+)\s*=\s*(.*?)\s*$/.exec(line);
+      if (!match || process.env[match[1]] !== undefined) continue;
+      let value = match[2];
+      const quoted = /^(['"])(.*)\1$/.exec(value);
+      value = quoted ? quoted[2] : value.replace(/\s+#.*$/, '');
+      process.env[match[1]] = value;
+    }
+  }
+}

package/src/config.js

@@ -0,0 +1,183 @@
+/**
+ * Settings shared by the SDK, the local hub and the CLI: product constants, and the environment
+ * variables that decide where requests go.
+ *
+ * Environment variables are read each time a setting is used, never cached, so a process (or a
+ * test) can change them at runtime.
+ *
+ *   PEEKINSIDE_URL           Base URL of the PeekInside site: cloud ingest and the dashboard interface
+ *                            (default https://peekinside.dev). Change it when developing the dashboard.
+ *   PEEKINSIDE_HOME          Folder for local data (default ~/.peekinside)
+ *   PEEKINSIDE_HUB_PORT      Port of the local dashboard (default 7335)
+ *   PEEKINSIDE_MAX_REQUESTS  Requests the local dashboard keeps per project (default 1000)
+ *   PEEKINSIDE_MAX_EXCEPTIONS  Exceptions the local dashboard keeps per project (default 500)
+ *   PEEKINSIDE_API_KEY       PeekInside Cloud API key; turns on cloud mode
+ *   PEEKINSIDE_ENV           Environment label (falls back to NODE_ENV)
+ *   PEEKINSIDE_PROJECT       Project name in the local dashboard
+ *   PEEKINSIDE_LOCAL         1 or 0 to force the local dashboard on or off
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+export const PRODUCT_NAME = 'PeekInside';
+export const LOG_PREFIX = '[peekinside]';
+export const DEFAULT_SITE_URL = 'https://peekinside.dev';
+// "PEEK" on a phone keypad
+export const DEFAULT_HUB_PORT = 7335;
+// Bumped only for breaking changes to the hub's HTTP API; the dashboard interface is versioned with it.
+export const HUB_API_VERSION = 1;
+export const HUB_APP_ID = 'peekinside-hub';
+
+export const VERSION = readPackageVersion();
+
+const TRUE_FLAGS = ['1', 'true', 'yes', 'on'];
+const FALSE_FLAGS = ['0', 'false', 'no', 'off'];
+
+/**
+ * Reads PeekInside's settings from environment variables.
+ *
+ * Every method reads the variables again, so changes made after startup apply.
+ */
+export class Settings {
+  /**
+   * @param {Object<string, string>} [env] - Variables to read. By default process.env, looked up on
+   *   every read.
+   */
+  constructor(env = null) {
+    this._env = env;
+  }
+
+  /**
+   * The variables settings are read from.
+   *
+   * @type {Object<string, string>}
+   */
+  get env() {
+    return this._env || process.env;
+  }
+
+  /**
+   * Origin of the PeekInside site, which hosts cloud ingest and the dashboard interface.
+   * An invalid PEEKINSIDE_URL is reported and ignored, so a typo can't send data elsewhere.
+   *
+   * @returns {string} Origin such as "https://peekinside.dev"
+   */
+  siteUrl() {
+    const value = this.env.PEEKINSIDE_URL;
+    if (!value) return DEFAULT_SITE_URL;
+    try {
+      const url = new URL(value);
+      if (url.protocol === 'https:' || url.protocol === 'http:') return url.origin;
+    } catch (error) {
+      // Fall through to the default.
+    }
+    console.warn(`${LOG_PREFIX} Ignoring PEEKINSIDE_URL: "${value}" is not an http(s) URL`);
+    return DEFAULT_SITE_URL;
+  }
+
+  /**
+   * Folder of the local dashboard's data.
+   *
+   * @returns {string} Absolute path
+   */
+  dataDir() {
+    return path.resolve(this.env.PEEKINSIDE_HOME || path.join(os.homedir(), '.peekinside'));
+  }
+
+  /**
+   * Port of the local dashboard; invalid values fall back to the default.
+   *
+   * @returns {number}
+   */
+  hubPort() {
+    const port = Number(this.env.PEEKINSIDE_HUB_PORT);
+    return Number.isInteger(port) && port > 0 && port < 65536 ? port : DEFAULT_HUB_PORT;
+  }
+
+  /**
+   * Address of the local dashboard, as shown to people.
+   *
+   * @param {number} [port] - Hub port (default: hubPort())
+   * @returns {string}
+   */
+  hubUrl(port = this.hubPort()) {
+    return `http://localhost:${port}`;
+  }
+
+  /**
+   * Requests the local dashboard keeps per project.
+   *
+   * @returns {number|undefined} The configured number, or undefined for the store's default
+   */
+  maxRequests() {
+    return Number(this.env.PEEKINSIDE_MAX_REQUESTS) || undefined;
+  }
+
+  /**
+   * Exceptions the local dashboard keeps per project.
+   *
+   * @returns {number|undefined} The configured number, or undefined for the store's default
+   */
+  maxExceptions() {
+    return Number(this.env.PEEKINSIDE_MAX_EXCEPTIONS) || undefined;
+  }
+
+  /**
+   * @returns {string|undefined} PeekInside Cloud API key
+   */
+  apiKey() {
+    return this.env.PEEKINSIDE_API_KEY;
+  }
+
+  /**
+   * @returns {string|undefined} Environment label: PEEKINSIDE_ENV, then NODE_ENV
+   */
+  environment() {
+    return this.env.PEEKINSIDE_ENV || this.env.NODE_ENV;
+  }
+
+  /**
+   * @returns {string|undefined} Project name chosen for the local dashboard
+   */
+  projectName() {
+    return this.env.PEEKINSIDE_PROJECT;
+  }
+
+  /**
+   * Whether the free local dashboard is on when the app doesn't decide. It is for development,
+   * so it is off in production, in tests and in CI, unless PEEKINSIDE_LOCAL says otherwise.
+   *
+   * @returns {boolean}
+   */
+  localMode() {
+    const flag = String(this.env.PEEKINSIDE_LOCAL || '').trim().toLowerCase();
+    if (TRUE_FLAGS.includes(flag)) return true;
+    if (FALSE_FLAGS.includes(flag)) return false;
+
+    const ci = String(this.env.CI || '').toLowerCase();
+    const inCi = ci !== '' && ci !== '0' && ci !== 'false';
+    return this.env.NODE_ENV !== 'production' && this.env.NODE_ENV !== 'test' && !inCi;
+  }
+
+  /**
+   * @returns {boolean} Whether NODE_ENV is "production"
+   */
+  isProduction() {
+    return this.env.NODE_ENV === 'production';
+  }
+}
+
+/** Settings read from process.env, shared by every module. */
+export const settings = new Settings();
+
+function readPackageVersion() {
+  try {
+    const file = fileURLToPath(new URL('../package.json', import.meta.url));
+    return JSON.parse(fs.readFileSync(file, 'utf8')).version || '';
+  } catch (error) {
+    return '';
+  }
+}