peekinside 0.0.0-stage → 1.2.1

package/src/exceptions/stack-parser.js

@@ -0,0 +1,179 @@
+/**
+ * Reads V8 stack traces, the `error.stack` strings of Node.js, into frames.
+ *
+ * Every form V8 prints is understood:
+ *
+ *   at createOrder (/app/src/orders.js:12:9)          named function
+ *   at /app/src/orders.js:12:9                         anonymous function
+ *   at async createOrder (/app/src/orders.js:12:9)     async continuation
+ *   at new Order (/app/src/order.js:3:11)              constructor
+ *   at Layer.handle [as handle_request] (...)          method called under another name
+ *   at file:///app/src/orders.mjs:12:9                 ES module (file URL)
+ *   at Module._compile (node:internal/modules/...)     Node.js internals
+ *   at JSON.parse (<anonymous>)                        built-in, no source
+ *   at Array.forEach (native)                          built-in (older V8)
+ *   at async Promise.all (index 0)                     Promise combinator
+ *   at eval (eval at run (/app/src/x.js:3:5), <anonymous>:1:7)   code run by eval()
+ *
+ * Parsing is purely textual: nothing here touches the file system.
+ */
+
+import { fileURLToPath } from 'url';
+
+// Frames are indented: a line of the message that happens to start with "at " is not a frame.
+const FRAME_LINE = /^\s+at (.+)$/;
+// "file:line:column" or "file:line". The file part is matched lazily, so the line and column are
+// the last two numbers even when the path itself contains colons (C:\..., node:internal/...).
+const LOCATION = /^(.*?):(\d+)(?::(\d+))?$/;
+const PROMISE_INDEX = /^index \d+$/;
+// The header holds the error's name and message; frames start after it.
+const MAX_HEADER_SEARCH = 1024;
+
+/**
+ * @typedef {Object} ParsedFrame
+ * @property {string|null} function - Such as "createOrder" or "Layer.handle [as handle_request]";
+ *   null for anonymous functions
+ * @property {string|null} file - Path, "node:..." for internals, null when there is no source
+ * @property {number|null} line
+ * @property {number|null} column
+ * @property {boolean} native - A built-in without source ("native", "<anonymous>")
+ * @property {boolean} async - An "at async" frame
+ */
+
+/**
+ * Turns stack strings and their lines into frames.
+ */
+export class StackParser {
+  /**
+   * Parses a stack trace, top (throwing) frame first.
+   *
+   * @param {string} stack - error.stack
+   * @param {Object} [options]
+   * @param {string} [options.message] - The error's message. Frames are read after it, so a
+   *   message that quotes another stack trace isn't mistaken for frames.
+   * @param {number} [options.limit=100] - Most frames returned
+   * @returns {ParsedFrame[]}
+   */
+  static parse(stack, { message = '', limit = 100 } = {}) {
+    if (typeof stack !== 'string' || stack === '') return [];
+
+    let text = stack;
+    if (typeof message === 'string' && message !== '') {
+      const at = stack.indexOf(message);
+      if (at !== -1 && at <= MAX_HEADER_SEARCH) text = stack.slice(at + message.length);
+    }
+
+    const frames = [];
+    for (const line of text.split('\n')) {
+      if (frames.length >= limit) break;
+      const match = FRAME_LINE.exec(line);
+      if (match) frames.push(StackParser.parseFrame(match[1]));
+    }
+    return frames;
+  }
+
+  /**
+   * Parses what follows "at " on one frame line.
+   *
+   * @param {string} body - Such as "async createOrder (/app/src/orders.js:12:9)"
+   * @returns {ParsedFrame}
+   */
+  static parseFrame(body) {
+    let rest = String(body).trim();
+    let isAsync = false;
+    if (rest.startsWith('async ')) {
+      isAsync = true;
+      rest = rest.slice(6).trimStart();
+    }
+
+    let fn = null;
+    let location = rest;
+    // "name (location)": the location is the last parenthesized group, which may itself contain
+    // parentheses (eval frames, folder names such as "My App (old)").
+    if (rest.endsWith(')')) {
+      const open = matchingOpen(rest, rest.length - 1);
+      if (open > 0 && rest[open - 1] === ' ') {
+        fn = rest.slice(0, open - 1).trim() || null;
+        location = rest.slice(open + 1, -1);
+      }
+    }
+
+    return { function: fn, ...StackParser.parseLocation(location), async: isAsync };
+  }
+
+  /**
+   * Parses a frame's location.
+   *
+   * @param {string} location - Such as "/app/src/orders.js:12:9", "native" or "eval at ..."
+   * @returns {{ file: string|null, line: number|null, column: number|null, native: boolean }}
+   */
+  static parseLocation(location) {
+    const text = String(location).trim();
+    if (text === 'native' || text === '<anonymous>' || text === 'unknown location' || PROMISE_INDEX.test(text)) {
+      return { file: null, line: null, column: null, native: true };
+    }
+
+    // Code run by eval() or new Function() has no file of its own: the place that called eval()
+    // is what tells people where it came from.
+    if (text.startsWith('eval at ')) {
+      const origin = evalOrigin(text);
+      return origin ? { ...StackParser.parseLocation(origin), native: false } : { file: null, line: null, column: null, native: false };
+    }
+
+    const match = LOCATION.exec(text);
+    if (match) {
+      const line = Number(match[2]);
+      const column = match[3] === undefined ? null : Number(match[3]);
+      // Generated code without a name ("<anonymous>:3:9") has positions but no file.
+      if (match[1] === '<anonymous>') return { file: null, line, column, native: true };
+      return { file: toPath(match[1]), line, column, native: false };
+    }
+    return { file: text ? toPath(text) : null, line: null, column: null, native: false };
+  }
+}
+
+// The index of the "(" that the ")" at `close` closes, or -1.
+function matchingOpen(text, close) {
+  let depth = 0;
+  for (let i = close; i >= 0; i--) {
+    const ch = text[i];
+    if (ch === ')') depth++;
+    else if (ch === '(' && --depth === 0) return i;
+  }
+  return -1;
+}
+
+// The index of the ")" that closes the "(" at `open`, or -1.
+function matchingClose(text, open) {
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '(') depth++;
+    else if (ch === ')' && --depth === 0) return i;
+  }
+  return -1;
+}
+
+// "eval at run (/app/x.js:3:5), <anonymous>:1:7" -> "/app/x.js:3:5". Nested evals
+// ("eval at a (eval at b (/app/x.js:1:2), <anonymous>:3:4), ...") lead to the outermost caller.
+function evalOrigin(text) {
+  let current = text;
+  for (let depth = 0; depth < 10 && current.startsWith('eval at '); depth++) {
+    const open = current.indexOf('(');
+    if (open === -1) return null;
+    const close = matchingClose(current, open);
+    if (close === -1) return null;
+    current = current.slice(open + 1, close).trim();
+  }
+  return current.startsWith('eval at ') ? null : current;
+}
+
+// ES modules report file URLs; everything else keeps its form ("node:fs", "webpack://...").
+function toPath(file) {
+  if (!file.startsWith('file://')) return file;
+  try {
+    return fileURLToPath(file);
+  } catch (error) {
+    return file;
+  }
+}

package/src/hub/brand/peekinside-span-core-mark-dark.svg

@@ -0,0 +1,7 @@
+<svg preserveAspectRatio="none" overflow="visible" style="display: block;" width="48" height="48" viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g id="Stacked mark / 48">
+<path id="Parent request span" d="M3.75 9.75H30.75C33.1369 9.75 35.4261 10.6982 37.114 12.386C38.8018 14.0739 39.75 16.3631 39.75 18.75V29.25C39.75 31.6369 38.8018 33.9261 37.114 35.614C35.4261 37.3018 33.1369 38.25 30.75 38.25H44.25" stroke="#EEF0EC" stroke-width="5" stroke-linecap="square" stroke-linejoin="round"/>
+<path id="Child execution span" d="M10.5 17.25H28.5C29.6935 17.25 30.8381 17.7241 31.682 18.568C32.5259 19.4119 33 20.5565 33 21.75V26.25C33 27.4435 32.5259 28.5881 31.682 29.432C30.8381 30.2759 29.6935 30.75 28.5 30.75H21.75" stroke="#EEF0EC" stroke-width="4" stroke-linecap="square" stroke-linejoin="round"/>
+<path id="Measured core" d="M17.25 24H27" stroke="#46C5AF" stroke-width="4" stroke-linecap="square" stroke-linejoin="round"/>
+</g>
+</svg>

package/src/hub/brand/peekinside-span-core-mark-light.svg

@@ -0,0 +1,7 @@
+<svg preserveAspectRatio="none" overflow="visible" style="display: block;" width="88" height="88" viewBox="0 0 88 88" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g id="Light mode glyph">
+<path id="Parent request span" d="M6.875 17.875H56.375C60.7511 17.875 64.9479 19.6134 68.0423 22.7077C71.1366 25.8021 72.875 29.9989 72.875 34.375V53.625C72.875 58.0011 71.1366 62.1979 68.0423 65.2923C64.9479 68.3866 60.7511 70.125 56.375 70.125H81.125" stroke="#121A10" stroke-width="5" stroke-linecap="square" stroke-linejoin="round"/>
+<path id="Child execution span" d="M19.25 31.625H52.25C54.438 31.625 56.5365 32.4942 58.0836 34.0414C59.6308 35.5885 60.5 37.687 60.5 39.875V48.125C60.5 50.313 59.6308 52.4115 58.0836 53.9586C56.5365 55.5058 54.438 56.375 52.25 56.375H39.875" stroke="#121A10" stroke-width="4" stroke-linecap="square" stroke-linejoin="round"/>
+<path id="Measured core" d="M31.625 44H49.5" stroke="#18B69B" stroke-width="4" stroke-linecap="square" stroke-linejoin="round"/>
+</g>
+</svg>

package/src/hub/client.js

@@ -0,0 +1,184 @@
+/**
+ * Talking to the local hub from apps and the CLI: health checks, starting it in the background
+ * and sending JSON. Connects to 127.0.0.1 directly, so "localhost" resolving to IPv6 first
+ * never matters.
+ */
+
+import { spawn } from 'child_process';
+import fs from 'fs';
+import http from 'http';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { HUB_APP_ID, VERSION, settings } from '../config.js';
+
+const HUB_ENTRY = fileURLToPath(new URL('./entry.js', import.meta.url));
+
+/**
+ * A failed hub request.
+ *
+ * `code` tells failures apart: a Node network code such as ECONNREFUSED (nothing listens),
+ * HUB_ERROR (the hub answered with an error) or NOT_HUB (another program answered).
+ */
+export class HubError extends Error {
+  /**
+   * @param {string} message
+   * @param {Object} [details]
+   * @param {number} [details.status=0] - HTTP status, when there was an answer
+   * @param {string} [details.code=''] - Failure code
+   */
+  constructor(message, { status = 0, code = '' } = {}) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/**
+ * Client of the hub on one port.
+ */
+export class HubClient {
+  /**
+   * @param {number} [port] - Hub port (default: PEEKINSIDE_HUB_PORT or 7335)
+   * @param {Object} [options]
+   * @param {boolean} [options.keepAlive=false] - Reuse connections, for apps that send batches
+   *   all day long. Call close() when done.
+   */
+  constructor(port = settings.hubPort(), { keepAlive = false } = {}) {
+    this.port = port;
+    // Batches are sent one at a time, so two sockets are plenty.
+    this.agent = keepAlive ? new http.Agent({ keepAlive: true, maxSockets: 2 }) : undefined;
+  }
+
+  /**
+   * Address of the hub's dashboard, as shown to people.
+   *
+   * @type {string}
+   */
+  get url() {
+    return settings.hubUrl(this.port);
+  }
+
+  /**
+   * Sends a JSON request to the hub.
+   *
+   * @param {string} method
+   * @param {string} pathname
+   * @param {Object} [options]
+   * @param {*} [options.body] - Sent as JSON
+   * @param {number} [options.timeout=5000] - Milliseconds without activity before giving up
+   * @returns {Promise<Object>} Parsed response body; rejects with HubError for non-2xx answers,
+   *   answers that are not JSON (code NOT_HUB) and network errors
+   */
+  request(method, pathname, { body, timeout = 5000 } = {}) {
+    return new Promise((resolve, reject) => {
+      const payload = body === undefined ? null : JSON.stringify(body);
+      // The hub accepts ingest only with this header, which browsers can't send cross-site
+      // without a preflight the hub never answers.
+      const headers = { 'x-peekinside-sdk': VERSION || 'dev', accept: 'application/json' };
+      if (payload !== null) {
+        headers['content-type'] = 'application/json';
+        headers['content-length'] = Buffer.byteLength(payload);
+      }
+
+      const req = http.request({ host: '127.0.0.1', port: this.port, method, path: pathname, headers, agent: this.agent, timeout }, (res) => {
+        const chunks = [];
+        res.on('data', (chunk) => chunks.push(chunk));
+        res.on('end', () => {
+          const text = Buffer.concat(chunks).toString('utf8');
+          let parsed = null;
+          try {
+            parsed = JSON.parse(text);
+          } catch (error) {
+            parsed = null;
+          }
+          if (res.statusCode >= 200 && res.statusCode < 300 && parsed) return resolve(parsed);
+          const message = (parsed && parsed.error) || `HTTP ${res.statusCode}`;
+          reject(new HubError(message, { status: res.statusCode, code: parsed ? 'HUB_ERROR' : 'NOT_HUB' }));
+        });
+        res.on('error', (error) => reject(new HubError(error.message, { code: error.code })));
+      });
+      req.on('timeout', () => req.destroy(Object.assign(new Error('Timed out'), { code: 'ETIMEDOUT' })));
+      req.on('error', (error) => reject(new HubError(error.message, { code: error.code })));
+      req.end(payload === null ? undefined : payload);
+    });
+  }
+
+  /**
+   * Checks whether the hub runs.
+   *
+   * @param {number} [timeout=2000]
+   * @returns {Promise<Object|null>} The hub's status, or null when nothing listens on the port.
+   *   Rejects with code NOT_HUB when another program uses the port.
+   */
+  async status(timeout = 2000) {
+    try {
+      const status = await this.request('GET', '/api/status', { timeout });
+      if (status.app !== HUB_APP_ID) throw new HubError('Another program uses this port', { code: 'NOT_HUB' });
+      return status;
+    } catch (error) {
+      if (error.code === 'ECONNREFUSED') return null;
+      if (error.code === 'HUB_ERROR' || error.code === 'NOT_HUB') {
+        throw new HubError(`Port ${this.port} is used by another program`, { code: 'NOT_HUB' });
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Starts the hub as a background process that outlives this one. Its output goes to hub.log
+   * in the data folder.
+   *
+   * @returns {void}
+   */
+  spawn() {
+    const dir = settings.dataDir();
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const log = fs.openSync(path.join(dir, 'hub.log'), 'a', 0o600);
+
+    // NODE_OPTIONS may hold loaders or --inspect flags meant for the app, not for the hub.
+    const env = { ...process.env, PEEKINSIDE_HUB_PORT: String(this.port) };
+    delete env.NODE_OPTIONS;
+
+    try {
+      const child = spawn(process.execPath, [HUB_ENTRY], {
+        detached: true,
+        stdio: ['ignore', log, log],
+        env,
+        windowsHide: true
+      });
+      child.on('error', () => {});
+      child.unref();
+    } finally {
+      fs.closeSync(log);
+    }
+  }
+
+  /**
+   * Waits until the hub answers.
+   *
+   * @param {number} [timeout=5000] - Milliseconds to wait
+   * @returns {Promise<Object|null>} The hub's status, or null when it did not answer in time.
+   *   Rejects with code NOT_HUB when another program uses the port.
+   */
+  async waitUntilReady(timeout = 5000) {
+    const deadline = Date.now() + timeout;
+    for (;;) {
+      const status = await this.status().catch((error) => {
+        if (error.code === 'NOT_HUB') throw error;
+        return null;
+      });
+      if (status) return status;
+      if (Date.now() > deadline) return null;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+
+  /**
+   * Closes kept-alive connections.
+   *
+   * @returns {void}
+   */
+  close() {
+    if (this.agent) this.agent.destroy();
+  }
+}

package/src/hub/entry.js

@@ -0,0 +1,4 @@
+// Entry point of the background hub process started by HubClient#spawn().
+import { HubProcess } from './process.js';
+
+new HubProcess().run();

package/src/hub/exception-state.js

@@ -0,0 +1,97 @@
+/**
+ * What the dashboard remembers about a project's issues: which exception fingerprints were marked
+ * resolved, and when. Stored in the project's folder as exception-state.json.
+ *
+ * Several dashboards (tabs) may edit it at once, so every save names the version it started from;
+ * a save based on an older version is refused, and the dashboard merges and tries again.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const FINGERPRINT = /^[0-9a-f]{16}$/;
+export const MAX_RESOLVED = 5000;
+
+/**
+ * @typedef {Object} ExceptionStateValue
+ * @property {Object<string, number>} resolved - Fingerprint -> when it was marked resolved (ms)
+ */
+
+/**
+ * The exception state file of one project.
+ */
+export class ExceptionState {
+  /**
+   * @param {string} dir - The project's folder
+   */
+  constructor(dir) {
+    this.file = path.join(dir, 'exception-state.json');
+    this._current = null;
+  }
+
+  /**
+   * Checks a state sent by a dashboard.
+   *
+   * @param {*} value
+   * @returns {ExceptionStateValue|null} The state with only known fields, or null when it is
+   *   malformed or holds more than 5000 fingerprints
+   */
+  static validate(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+    const resolved = value.resolved;
+    if (!resolved || typeof resolved !== 'object' || Array.isArray(resolved)) return null;
+    const keys = Object.keys(resolved);
+    if (keys.length > MAX_RESOLVED) return null;
+
+    const clean = {};
+    for (const key of keys) {
+      const at = resolved[key];
+      if (!FINGERPRINT.test(key) || !Number.isFinite(at) || at < 0) return null;
+      clean[key] = at;
+    }
+    return { resolved: clean };
+  }
+
+  /**
+   * The saved state; version 0 and nothing resolved when it was never saved.
+   *
+   * @returns {{ state: ExceptionStateValue, version: number }}
+   */
+  read() {
+    if (!this._current) {
+      this._current = { state: { resolved: {} }, version: 0 };
+      try {
+        const saved = JSON.parse(fs.readFileSync(this.file, 'utf8'));
+        const state = ExceptionState.validate(saved && saved.state);
+        if (state && Number.isInteger(saved.version) && saved.version > 0) {
+          this._current = { state, version: saved.version };
+        }
+      } catch (error) {
+        // Missing or unreadable: start from scratch rather than fail the dashboard.
+      }
+    }
+    return this._current;
+  }
+
+  /**
+   * Saves a new state if `version` is the current one.
+   *
+   * @param {ExceptionStateValue} state - Validated state
+   * @param {number} version - The version the dashboard read
+   * @returns {{ saved: boolean, state: ExceptionStateValue, version: number }} The new version when
+   *   saved; otherwise the current state and version, for the dashboard to merge with
+   */
+  write(state, version) {
+    const current = this.read();
+    if (version !== current.version) {
+      return { saved: false, ...current };
+    }
+    const next = { state, version: current.version + 1 };
+    // Written to a temporary file first, so a crash never leaves half a file.
+    const temp = `${this.file}.${process.pid}.tmp`;
+    fs.writeFileSync(temp, `${JSON.stringify(next)}\n`, { mode: 0o600 });
+    fs.renameSync(temp, this.file);
+    this._current = next;
+    return { saved: true, ...next };
+  }
+}