opencons 0.1.0

package/src/interceptors/express.js

@@ -0,0 +1,270 @@
+'use strict';
+
+const { getCurrentTracer } = require('../core/context');
+
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'all'];
+
+let globalPatchApplied = false;
+
+/**
+ * Patch Express Application and Router prototypes so every handler
+ * registered after Opencons initialises is automatically wrapped.
+ */
+function patchExpressGlobally() {
+  if (globalPatchApplied) return;
+  globalPatchApplied = true;
+
+  const express = require('express');
+
+  patchLayer(express.application);
+  patchRouterPrototype(express.Router.prototype);
+}
+
+/**
+ * @deprecated Use patchExpressGlobally — kept for explicit per-app attachment.
+ * @param {import('express').Application} app
+ */
+function patchExpressApp(app) {
+  patchExpressGlobally();
+  patchLayer(app);
+}
+
+/**
+ * @param {import('express').Application | import('express').Router} target
+ */
+function patchLayer(target) {
+  if (target.__openconsLayerPatched) return;
+  target.__openconsLayerPatched = true;
+
+  const originalUse = target.use;
+  target.use = function patchedUse(...args) {
+    const wrapped = wrapHandlers(args);
+
+    for (const fn of wrapped) {
+      if (fn && fn.__openconsEntry) {
+        patchLayer(this);
+      }
+    }
+
+    return originalUse.apply(this, wrapped);
+  };
+
+  for (const method of HTTP_METHODS) {
+    if (typeof target[method] !== 'function') continue;
+
+    const original = target[method];
+    target[method] = function patchedMethod(...args) {
+      const wrapped = wrapHandlers(args);
+      return original.apply(this, wrapped);
+    };
+  }
+}
+
+/**
+ * @param {Function} Router
+ */
+function patchRouterPrototype(Router) {
+  if (Router.__openconsPatched) return;
+  Router.__openconsPatched = true;
+
+  const originalUse = Router.use;
+  Router.use = function patchedRouterUse(...args) {
+    const wrapped = wrapHandlers(args);
+    return originalUse.apply(this, wrapped);
+  };
+
+  for (const method of HTTP_METHODS) {
+    if (typeof Router[method] !== 'function') continue;
+
+    const original = Router[method];
+    Router[method] = function patchedRouterMethod(...args) {
+      const wrapped = wrapHandlers(args);
+      return original.apply(this, wrapped);
+    };
+  }
+}
+
+/**
+ * @param {unknown[]} args
+ * @returns {unknown[]}
+ */
+function wrapHandlers(args) {
+  const result = [...args];
+  const startIndex = typeof result[0] === 'string' || result[0] instanceof RegExp ? 1 : 0;
+
+  for (let i = startIndex; i < result.length; i += 1) {
+    const handler = result[i];
+
+    if (typeof handler === 'function') {
+      result[i] = wrapHandler(handler);
+    } else if (Array.isArray(handler)) {
+      result[i] = handler.map((fn) =>
+        typeof fn === 'function' ? wrapHandler(fn) : fn
+      );
+    }
+  }
+
+  return result;
+}
+
+/**
+ * @param {Function} handler
+ * @returns {Function}
+ */
+function wrapHandler(handler) {
+  if (handler.__openconsWrapped) return handler;
+
+  const name = resolveHandlerName(handler);
+
+  function wrapped(req, res, next) {
+    const tracer = getCurrentTracer();
+
+    if (!tracer) {
+      return handler(req, res, next);
+    }
+
+    const entered = performance.now();
+    let calledNext = false;
+    let exitReason = null;
+    let exited = false;
+
+    const wrappedNext = (...nextArgs) => {
+      calledNext = true;
+
+      if (!exited) {
+        exited = true;
+        recordMiddlewareExit();
+      }
+
+      return next(...nextArgs);
+    };
+
+    const recordMiddlewareExit = () => {
+      const duration_ms = Math.round((performance.now() - entered) * 10) / 10;
+
+      tracer.addNode({
+        type: 'middleware',
+        label: name,
+        duration_ms,
+        called_next: calledNext,
+        exit_reason: exitReason || undefined,
+      });
+    };
+
+    const originalStatus = res.status.bind(res);
+    res.status = function patchedStatus(code) {
+      if (!calledNext && !exited) {
+        exitReason = `res.status(${code})`;
+      }
+      return originalStatus(code);
+    };
+
+    const originalJson = res.json.bind(res);
+    res.json = function patchedJson(body) {
+      if (!calledNext && !exited) {
+        exitReason = 'res.json(...)';
+      }
+      return originalJson(body);
+    };
+
+    const originalSend = res.send.bind(res);
+    res.send = function patchedSend(body) {
+      if (!calledNext && !exited) {
+        exitReason = 'res.send(...)';
+      }
+      return originalSend(body);
+    };
+
+    const originalEnd = res.end.bind(res);
+    res.end = function patchedEnd(...endArgs) {
+      if (!calledNext && !exited) {
+        exitReason = 'res.end(...)';
+        exited = true;
+        recordMiddlewareExit();
+      }
+      return originalEnd(...endArgs);
+    };
+
+    try {
+      const result = handler(req, res, wrappedNext);
+
+      if (result && typeof result.then === 'function') {
+        result
+          .catch((err) => {
+            if (!exited) {
+              exitReason = `error: ${err.message}`;
+              exited = true;
+              recordMiddlewareExit();
+            }
+            if (!calledNext) next(err);
+          })
+          .finally(() => {
+            if (!exited) {
+              exited = true;
+              recordMiddlewareExit();
+            }
+          });
+      } else if (!exited && !res.headersSent && !calledNext) {
+        // Synchronous handler that did not call next or send a response yet.
+        // Defer exit recording until response is sent or next is called.
+      }
+
+      return result;
+    } catch (err) {
+      if (!exited) {
+        exitReason = `error: ${err.message}`;
+        exited = true;
+        recordMiddlewareExit();
+      }
+      throw err;
+    }
+  }
+
+  wrapped.__openconsWrapped = true;
+  wrapped.__openconsName = name;
+
+  return wrapped;
+}
+
+/**
+ * @param {Function} handler
+ */
+function resolveHandlerName(handler) {
+  if (handler.__openconsName) return handler.__openconsName;
+
+  const ctor = handler.constructor?.name;
+  let method = handler.name;
+
+  if (method && method.startsWith('bound ')) {
+    method = method.slice('bound '.length);
+  }
+
+  if (ctor && ctor !== 'Function' && ctor !== 'Object') {
+    if (method && method !== 'constructor' && method !== 'anonymous') {
+      if (method === 'use' || method === 'handle' || method === 'handleRequest') {
+        return ctor;
+      }
+      return `${ctor}.${method}`;
+    }
+    return ctor;
+  }
+
+  if (method && method !== 'anonymous') {
+    return method;
+  }
+
+  const str = Function.prototype.toString.call(handler);
+  const match =
+    str.match(/^async\s+function\s+(\w+)/) ||
+    str.match(/^function\s+(\w+)/) ||
+    str.match(/(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?(?:function|\()/);
+  if (match) return match[1];
+
+  return 'anonymous';
+}
+
+module.exports = {
+  patchExpressGlobally,
+  patchExpressApp,
+  wrapHandler,
+};

package/src/interceptors/require-hook.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const Module = require('module');
+const { transformSource } = require('../transform/ast');
+const sourceCache = require('../store/source-cache');
+
+const OPENCONS_PKG = path.normalize(path.join(__dirname, '..', '..'));
+
+/** @type {boolean} */
+let hookInstalled = false;
+
+/** @type {((filename: string) => boolean) | null} */
+let shouldTransformFile = null;
+
+/**
+ * @param {object} options
+ * @param {string[]} [options.exclude]
+ * @param {string} [options.projectRoot]
+ */
+function installRequireHook(options = {}) {
+  if (hookInstalled) return;
+  hookInstalled = true;
+
+  const projectRoot = options.projectRoot || process.cwd();
+  sourceCache.setProjectRoot(projectRoot);
+
+  shouldTransformFile = createFilter(projectRoot, options.exclude || []);
+
+  const originalJsHandler = Module._extensions['.js'];
+
+  Module._extensions['.js'] = function OpenconsJsExtension(module, filename) {
+    if (!shouldTransformFile(filename)) {
+      return originalJsHandler(module, filename);
+    }
+
+    let source;
+
+    try {
+      source = fs.readFileSync(filename, 'utf8');
+    } catch (err) {
+      return originalJsHandler(module, filename);
+    }
+
+    sourceCache.storeOriginal(filename);
+
+    const result = transformSource(source, filename, { projectRoot });
+
+    if (result.skipped) {
+      sourceCache.store(filename, source, null);
+      return module._compile(source, filename);
+    }
+
+    sourceCache.store(filename, source, result.map);
+
+    return module._compile(result.code, filename);
+  };
+
+  const { logger } = require('../lib/logger');
+  logger.info('Source transform hook installed (CommonJS .js)');
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string[]} excludePatterns
+ */
+function createFilter(projectRoot, excludePatterns) {
+  const normalizedRoot = path.normalize(projectRoot);
+
+  return function filter(filename) {
+    const normalized = path.normalize(filename);
+
+    if (normalized.includes(`${path.sep}node_modules${path.sep}`)) {
+      return false;
+    }
+
+    if (normalized.startsWith(OPENCONS_PKG)) {
+      return false;
+    }
+
+    if (!normalized.startsWith(normalizedRoot)) {
+      return false;
+    }
+
+    if (!normalized.endsWith('.js')) {
+      return false;
+    }
+
+    const relative = path.relative(normalizedRoot, normalized);
+
+    return !excludePatterns.some((pattern) => matchGlob(relative, pattern));
+  };
+}
+
+/**
+ * @param {string} value
+ * @param {string} pattern
+ */
+function matchGlob(value, pattern) {
+  const regex = new RegExp(
+    `^${pattern.replace(/\*/g, '.*').replace(/\//g, '[\\\\/]').replace(/\\/g, '\\\\')}$`
+  );
+  return regex.test(value);
+}
+
+module.exports = {
+  installRequireHook,
+};

package/src/lib/config.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const { ConfigurationError } = require('./errors');
+
+/** @typedef {import('../core/tracer').TraceGraph} TraceGraph */
+
+/**
+ * @typedef {Object} OpenconsOptions
+ * @property {number} port
+ * @property {boolean | undefined} enabled
+ * @property {boolean} enableWidget
+ * @property {string[]} exclude
+ * @property {boolean} captureBody
+ * @property {boolean} captureResponse
+ * @property {number} maxTraces
+ * @property {Record<'mongoose' | 'drizzle' | 'pg' | 'prisma' | 'mysql2', boolean>} drivers
+ * @property {{ enabled: boolean, projectRoot: string | undefined, exclude: string[] }} transform
+ * @property {number} [widgetPort]
+ */
+
+const DEFAULT_OPTIONS = {
+  port: 7331,
+  enabled: undefined,
+  enableWidget: true,
+  exclude: [],
+  captureBody: false,
+  captureResponse: false,
+  maxTraces: 100,
+  drivers: {
+    mongoose: true,
+    drizzle: true,
+    pg: true,
+    prisma: true,
+    mysql2: true,
+  },
+  transform: {
+    enabled: false,
+    projectRoot: undefined,
+    exclude: [],
+  },
+};
+
+/**
+ * @param {unknown} value
+ * @param {string} field
+ * @returns {number}
+ */
+function requirePositiveInt(value, field) {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+    throw new ConfigurationError(`${field} must be a positive integer`);
+  }
+  return value;
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} field
+ * @returns {string[]}
+ */
+function requireStringArray(value, field) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+    throw new ConfigurationError(`${field} must be an array of strings`);
+  }
+  return value;
+}
+
+/**
+ * Merge user options with defaults and validate types.
+ *
+ * @param {Partial<OpenconsOptions>} [userOptions]
+ * @returns {OpenconsOptions}
+ */
+function resolveOptions(userOptions = {}) {
+  const options = {
+    ...DEFAULT_OPTIONS,
+    ...userOptions,
+    drivers: {
+      ...DEFAULT_OPTIONS.drivers,
+      ...(userOptions.drivers || {}),
+    },
+    transform: {
+      ...DEFAULT_OPTIONS.transform,
+      ...(userOptions.transform || {}),
+    },
+  };
+
+  options.port = requirePositiveInt(options.port, 'port');
+  options.maxTraces = requirePositiveInt(options.maxTraces, 'maxTraces');
+  options.exclude = requireStringArray(options.exclude, 'exclude');
+  options.transform.exclude = requireStringArray(options.transform.exclude, 'transform.exclude');
+
+  if (typeof options.enableWidget !== 'boolean') {
+    throw new ConfigurationError('enableWidget must be a boolean');
+  }
+
+  if (typeof options.captureBody !== 'boolean') {
+    throw new ConfigurationError('captureBody must be a boolean');
+  }
+
+  if (typeof options.captureResponse !== 'boolean') {
+    throw new ConfigurationError('captureResponse must be a boolean');
+  }
+
+  if (options.enabled !== undefined && typeof options.enabled !== 'boolean') {
+    throw new ConfigurationError('enabled must be a boolean when provided');
+  }
+
+  for (const [driver, enabled] of Object.entries(options.drivers)) {
+    if (typeof enabled !== 'boolean') {
+      throw new ConfigurationError(`drivers.${driver} must be a boolean`);
+    }
+  }
+
+  if (typeof options.transform.enabled !== 'boolean') {
+    throw new ConfigurationError('transform.enabled must be a boolean');
+  }
+
+  if (
+    options.transform.projectRoot !== undefined &&
+    typeof options.transform.projectRoot !== 'string'
+  ) {
+    throw new ConfigurationError('transform.projectRoot must be a string when provided');
+  }
+
+  return options;
+}
+
+/**
+ * @returns {boolean}
+ */
+function isProductionDisabled(options) {
+  return process.env.NODE_ENV === 'production' && options.enabled !== true;
+}
+
+module.exports = {
+  DEFAULT_OPTIONS,
+  resolveOptions,
+  isProductionDisabled,
+};

package/src/lib/errors.js

@@ -0,0 +1,54 @@
+'use strict';
+
+class OpenconsError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} [code]
+   */
+  constructor(message, code = 'OPENCONS_ERROR') {
+    super(message);
+    this.name = 'OpenconsError';
+    this.code = code;
+  }
+}
+
+class ConfigurationError extends OpenconsError {
+  /**
+   * @param {string} message
+   */
+  constructor(message) {
+    super(message, 'CONFIGURATION_ERROR');
+    this.name = 'ConfigurationError';
+  }
+}
+
+class WidgetServerError extends OpenconsError {
+  /**
+   * @param {string} message
+   * @param {NodeJS.ErrnoException | null} [cause]
+   */
+  constructor(message, cause = null) {
+    super(message, 'WIDGET_SERVER_ERROR');
+    this.name = 'WidgetServerError';
+    if (cause) {
+      this.cause = cause;
+    }
+  }
+}
+
+class WebSocketError extends OpenconsError {
+  /**
+   * @param {string} message
+   */
+  constructor(message) {
+    super(message, 'WEBSOCKET_ERROR');
+    this.name = 'WebSocketError';
+  }
+}
+
+module.exports = {
+  OpenconsError,
+  ConfigurationError,
+  WidgetServerError,
+  WebSocketError,
+};

package/src/lib/http-response.js

@@ -0,0 +1,37 @@
+'use strict';
+
+/**
+ * @param {import('http').ServerResponse} res
+ * @param {number} status
+ * @param {string} body
+ * @param {string} [contentType]
+ */
+function sendText(res, status, body, contentType = 'text/plain; charset=utf-8') {
+  res.writeHead(status, { 'Content-Type': contentType });
+  res.end(body);
+}
+
+/**
+ * @param {import('http').ServerResponse} res
+ * @param {number} status
+ * @param {{ error: string, code?: string }} payload
+ */
+function sendJsonError(res, status, payload) {
+  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(JSON.stringify(payload));
+}
+
+/**
+ * @param {import('http').ServerResponse} res
+ * @param {unknown} payload
+ */
+function sendJson(res, payload) {
+  res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(JSON.stringify(payload));
+}
+
+module.exports = {
+  sendText,
+  sendJsonError,
+  sendJson,
+};

package/src/lib/logger.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/** @typedef {'debug' | 'info' | 'warn' | 'error'} LogLevel */
+
+const LEVELS = /** @type {const} */ ({ debug: 0, info: 1, warn: 2, error: 3 });
+
+/** @type {LogLevel} */
+const logLevel = process.env.OPENCONS_LOG_LEVEL || process.env.ROUTEGRAPHER_LOG_LEVEL;
+let minLevel = logLevel === 'debug' ? 'debug' : 'info';
+
+const PREFIX = '[Opencons]';
+
+/**
+ * @param {LogLevel} level
+ * @param {string} message
+ * @param {unknown} [detail]
+ */
+function write(level, message, detail) {
+  if (LEVELS[level] < LEVELS[minLevel]) return;
+
+  const line = `${PREFIX} ${message}`;
+  const sink =
+    level === 'error' ? console.error : level === 'warn' ? console.warn : console.log;
+
+  if (detail !== undefined) {
+    sink(line, detail);
+    return;
+  }
+
+  sink(line);
+}
+
+const logger = {
+  /**
+   * @param {LogLevel} level
+   */
+  setLevel(level) {
+    if (level in LEVELS) {
+      minLevel = level;
+    }
+  },
+
+  /** @returns {LogLevel} */
+  getLevel() {
+    return minLevel;
+  },
+
+  /** @param {string} message @param {unknown} [detail] */
+  debug(message, detail) {
+    write('debug', message, detail);
+  },
+
+  /** @param {string} message @param {unknown} [detail] */
+  info(message, detail) {
+    write('info', message, detail);
+  },
+
+  /** @param {string} message @param {unknown} [detail] */
+  warn(message, detail) {
+    write('warn', message, detail);
+  },
+
+  /** @param {string} message @param {unknown} [detail] */
+  error(message, detail) {
+    write('error', message, detail);
+  },
+};
+
+module.exports = { logger };

package/src/lib/serialize.js

@@ -0,0 +1,22 @@
+'use strict';
+
+/**
+ * Deep-clone a value for trace snapshots. Falls back to a placeholder when
+ * JSON serialization fails (circular refs, BigInt, etc.).
+ *
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function safeClone(value) {
+  if (value === undefined || value === null) return value;
+
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return '[unserializable]';
+  }
+}
+
+module.exports = {
+  safeClone,
+};