opencons 0.1.0

package/src/drivers/record.js

@@ -0,0 +1,158 @@
+'use strict';
+
+const { getCurrentTracer, getCurrentContext, runWithContext } = require('../core/context');
+const { buildDbNodeLanguage } = require('./db-language');
+
+const MAX_QUERY_LEN = 500;
+const MAX_PARAMS = 12;
+
+/**
+ * @param {unknown} value
+ */
+function safeParams(value) {
+  if (value == null) return undefined;
+
+  if (Array.isArray(value)) {
+    return value.slice(0, MAX_PARAMS).map((item) => safeParamValue(item));
+  }
+
+  if (typeof value === 'object') {
+    const out = {};
+    const entries = Object.entries(value).slice(0, MAX_PARAMS);
+    for (const [key, item] of entries) {
+      out[key] = safeParamValue(item);
+    }
+    return out;
+  }
+
+  return safeParamValue(value);
+}
+
+/**
+ * @param {unknown} value
+ */
+function safeParamValue(value) {
+  if (value == null) return value;
+  if (typeof value === 'string') return value.length > 80 ? `${value.slice(0, 80)}…` : value;
+  if (typeof value === 'number' || typeof value === 'boolean') return value;
+  if (value instanceof Date) return value.toISOString();
+  if (Buffer.isBuffer(value)) return `[Buffer ${value.length}b]`;
+  try {
+    const text = JSON.stringify(value);
+    return text.length > 120 ? `${text.slice(0, 120)}…` : text;
+  } catch {
+    return '[unserializable]';
+  }
+}
+
+/**
+ * @param {string} query
+ */
+function truncateQuery(query) {
+  const text = String(query || '').replace(/\s+/g, ' ').trim();
+  if (text.length <= MAX_QUERY_LEN) return text;
+  return `${text.slice(0, MAX_QUERY_LEN)}…`;
+}
+
+/**
+ * @param {unknown} result
+ */
+function countRows(result) {
+  if (result == null) return undefined;
+  if (Array.isArray(result)) return result.length;
+  if (typeof result === 'object') {
+    if ('rowCount' in result && result.rowCount != null) return Number(result.rowCount);
+    if ('count' in result && result.count != null) return Number(result.count);
+    if ('length' in result && typeof result.length === 'number') return result.length;
+    if ('affectedRows' in result) return Number(result.affectedRows);
+  }
+  return undefined;
+}
+
+/**
+ * @param {object} payload
+ * @param {string} payload.driver
+ * @param {string} [payload.operation]
+ * @param {string} [payload.query]
+ * @param {unknown} [payload.params]
+ * @param {number} [payload.rows]
+ * @param {number} payload.duration_ms
+ * @param {string} [payload.collection]
+ * @param {string} [payload.error]
+ */
+function recordDbQuery(payload) {
+  const tracer = getCurrentTracer();
+  const ctx = getCurrentContext();
+
+  if (!tracer) return;
+
+  const record = () => {
+    const parentId = ctx?.scopeNodeId || tracer.getLastSequentialNodeId();
+    const operation = payload.operation || 'query';
+    const language = buildDbNodeLanguage({
+      driver: payload.driver,
+      operation,
+      query: payload.query,
+      collection: payload.collection,
+      rows: payload.rows,
+      duration_ms: payload.duration_ms,
+      error: payload.error,
+    });
+
+    tracer.addForkNode(parentId, {
+      type: 'db',
+      label: language.label,
+      summary: language.summary,
+      db_action: language.db_action,
+      db_intent: language.db_intent,
+      db_result: language.db_result,
+      query: payload.query ? truncateQuery(payload.query) : undefined,
+      params: safeParams(payload.params),
+      rows: payload.rows,
+      duration_ms: payload.duration_ms,
+      driver: payload.driver,
+      operation,
+      collection: payload.collection,
+      exit_reason: payload.error,
+    });
+  };
+
+  if (ctx) {
+    runWithContext(ctx, record);
+  } else {
+    record();
+  }
+}
+
+/**
+ * @param {() => Promise<unknown> | unknown} fn
+ * @param {object} meta
+ */
+async function traceDbCall(fn, meta) {
+  const start = performance.now();
+
+  try {
+    const result = await fn();
+    recordDbQuery({
+      ...meta,
+      rows: meta.rows ?? countRows(result),
+      duration_ms: Math.round((performance.now() - start) * 10) / 10,
+    });
+    return result;
+  } catch (err) {
+    recordDbQuery({
+      ...meta,
+      duration_ms: Math.round((performance.now() - start) * 10) / 10,
+      error: err && err.message ? err.message : String(err),
+    });
+    throw err;
+  }
+}
+
+module.exports = {
+  recordDbQuery,
+  traceDbCall,
+  truncateQuery,
+  safeParams,
+  countRows,
+};

package/src/index.js

@@ -0,0 +1,28 @@
+'use strict';
+
+/**
+ * Opencons public entry point.
+ *
+ * Import-time side effects are intentional:
+ * - Express prototype patching so handlers registered after setup are wrapped
+ * - Optional AST require hook when OPENCONS_TRANSFORM is set
+ *
+ * Require this module before express() and call opencons() as the first middleware.
+ */
+
+const { createOpencons } = require('./core');
+const { patchExpressGlobally } = require('./interceptors/express');
+const { applyToNest, createNestMiddleware } = require('./integrations/nest');
+const { label } = require('./utils/label');
+
+require('./transform/register');
+patchExpressGlobally();
+
+const opencons = createOpencons;
+
+opencons.applyToNest = applyToNest;
+opencons.createNestMiddleware = createNestMiddleware;
+opencons.label = label;
+
+module.exports = opencons;
+module.exports.default = opencons;

package/src/integrations/nest-lifecycle.js

@@ -0,0 +1,357 @@
+'use strict';
+
+const { getCurrentTracer, getCurrentContext, runWithContext } = require('../core/context');
+const { traceObservable } = require('../utils/observable');
+
+let nestPatched = false;
+
+/**
+ * @param {import('../core/tracer').TraceTracer | null | undefined} tracer
+ * @param {string} label
+ * @param {number} entered
+ * @param {boolean} [calledNext]
+ * @param {string} [exitReason]
+ * @param {'middleware' | 'controller'} [nodeType]
+ */
+function recordStep(tracer, label, entered, calledNext = true, exitReason, nodeType = 'middleware') {
+  if (!tracer) return;
+
+  const duration_ms = Math.round((performance.now() - entered) * 10) / 10;
+
+  tracer.addNode({
+    type: nodeType,
+    label,
+    duration_ms,
+    called_next: calledNext,
+    exit_reason: exitReason,
+  });
+}
+
+/**
+ * @param {import('../core/context').TraceContext | undefined} alsContext
+ * @param {import('../core/tracer').TraceTracer | null} tracer
+ * @param {string} label
+ * @param {number} entered
+ * @param {boolean} [calledNext]
+ * @param {string} [exitReason]
+ * @param {'middleware' | 'controller'} [nodeType]
+ */
+function recordStepSafe(alsContext, tracer, label, entered, calledNext, exitReason, nodeType) {
+  if (alsContext) {
+    const { runWithContext } = require('../core/context');
+    runWithContext(alsContext, () =>
+      recordStep(tracer, label, entered, calledNext, exitReason, nodeType)
+    );
+    return;
+  }
+
+  recordStep(tracer, label, entered, calledNext, exitReason, nodeType);
+}
+
+/**
+ * @param {object} interceptor
+ */
+function wrapNestInterceptor(interceptor) {
+  if (!interceptor || interceptor.__openconsWrapped) {
+    return interceptor;
+  }
+
+  if (typeof interceptor.intercept !== 'function') {
+    return interceptor;
+  }
+
+  const name = resolveNestComponentName(interceptor, 'Interceptor');
+  const original = interceptor.intercept.bind(interceptor);
+
+  interceptor.intercept = function OpenconsIntercept(context, next) {
+    const tracer = getCurrentTracer();
+    const alsContext = getCurrentContext();
+
+    if (!tracer) {
+      return original(context, next);
+    }
+
+    const entered = performance.now();
+
+    try {
+      const result = original(context, next);
+
+      return traceObservable(
+        result,
+        (exitReason) => {
+          recordStepSafe(alsContext, tracer, name, entered, true, exitReason);
+        },
+        alsContext
+      );
+    } catch (err) {
+      recordStepSafe(alsContext, tracer, name, entered, false, `error: ${err.message}`);
+      throw err;
+    }
+  };
+
+  interceptor.__openconsWrapped = true;
+  return interceptor;
+}
+
+/**
+ * @param {object} guard
+ */
+function wrapNestGuard(guard) {
+  if (!guard || guard.__openconsWrapped) {
+    return guard;
+  }
+
+  if (typeof guard.canActivate !== 'function') {
+    return guard;
+  }
+
+  const name = resolveNestComponentName(guard, 'Guard');
+  const original = guard.canActivate.bind(guard);
+
+  guard.canActivate = async function OpenconsCanActivate(context) {
+    const tracer = getCurrentTracer();
+    const alsContext = getCurrentContext();
+
+    if (!tracer) {
+      return original(context);
+    }
+
+    const entered = performance.now();
+
+    try {
+      const allowed = await original(context);
+      recordStepSafe(alsContext, tracer, name, entered, Boolean(allowed), allowed ? undefined : 'denied');
+      return allowed;
+    } catch (err) {
+      recordStepSafe(alsContext, tracer, name, entered, false, `error: ${err.message}`);
+      throw err;
+    }
+  };
+
+  guard.__openconsWrapped = true;
+  return guard;
+}
+
+/**
+ * @param {object} component
+ * @param {string} fallbackSuffix
+ */
+function resolveNestComponentName(component, fallbackSuffix) {
+  const ctor = component.constructor?.name;
+  if (ctor && ctor !== 'Object' && ctor !== 'Function') {
+    return ctor;
+  }
+  return `Anonymous${fallbackSuffix}`;
+}
+
+/**
+ * @param {import('@nestjs/common').ExecutionContext} context
+ */
+function resolveControllerLabel(context) {
+  const className = context.getClass()?.name || 'Controller';
+  const handler = context.getHandler();
+  const handlerName = handler?.name || handler?.displayName || 'handler';
+  return `${className}.${handlerName}`;
+}
+
+/**
+ * Trace controller handlers — must run as the innermost global interceptor.
+ */
+class OpenconsControllerInterceptor {
+  intercept(context, next) {
+    const tracer = getCurrentTracer();
+    const alsContext = getCurrentContext();
+
+    if (!tracer) {
+      return next.handle();
+    }
+
+    const label = resolveControllerLabel(context);
+    const entered = performance.now();
+
+    const openController = () => {
+      const node = tracer.addNode({
+        type: 'controller',
+        label,
+        duration_ms: null,
+        called_next: true,
+      });
+      if (alsContext) {
+        alsContext.scopeNodeId = node.id;
+      }
+      return node.id;
+    };
+
+    const controllerNodeId = alsContext
+      ? runWithContext(alsContext, openController)
+      : openController();
+
+    const completeController = (calledNext, exitReason) => {
+      tracer.updateNode(controllerNodeId, {
+        duration_ms: Math.round((performance.now() - entered) * 10) / 10,
+        called_next: calledNext,
+        exit_reason: exitReason,
+      });
+    };
+
+    try {
+      const result = next.handle();
+
+      return traceObservable(
+        result,
+        (exitReason) => {
+          if (alsContext) {
+            runWithContext(alsContext, () => completeController(true, exitReason));
+            return;
+          }
+          completeController(true, exitReason);
+        },
+        alsContext
+      );
+    } catch (err) {
+      if (alsContext) {
+        runWithContext(alsContext, () => completeController(false, `error: ${err.message}`));
+      } else {
+        completeController(false, `error: ${err.message}`);
+      }
+      throw err;
+    }
+  }
+}
+
+/**
+ * Patch Nest application methods so globally registered components are traced.
+ */
+function patchNestGlobally() {
+  if (nestPatched) return;
+  nestPatched = true;
+
+  try {
+    const { NestApplication } = require('@nestjs/core/nest-application');
+
+    const originalInterceptors = NestApplication.prototype.useGlobalInterceptors;
+    NestApplication.prototype.useGlobalInterceptors = function (...interceptors) {
+      return originalInterceptors.call(
+        this,
+        ...interceptors.map((item) => wrapNestInterceptor(item))
+      );
+    };
+
+    const originalGuards = NestApplication.prototype.useGlobalGuards;
+    NestApplication.prototype.useGlobalGuards = function (...guards) {
+      return originalGuards.call(this, ...guards.map((item) => wrapNestGuard(item)));
+    };
+
+    const originalPipes = NestApplication.prototype.useGlobalPipes;
+    NestApplication.prototype.useGlobalPipes = function (...pipes) {
+      return originalPipes.call(this, ...pipes.map((pipe) => wrapNestPipe(pipe)));
+    };
+  } catch {
+    // @nestjs/core not installed — Express-only mode.
+  }
+}
+
+/**
+ * Register the controller interceptor last so it wraps the route handler directly.
+ * @param {import('@nestjs/common').INestApplication} nestApp
+ */
+function attachControllerTracing(nestApp) {
+  nestApp.useGlobalInterceptors(new OpenconsControllerInterceptor());
+}
+
+/**
+ * @param {import('@nestjs/common').INestApplication} nestApp
+ */
+function deferControllerTracingUntilReady(nestApp) {
+  let attached = false;
+
+  const attach = () => {
+    if (attached) return;
+    attached = true;
+    attachControllerTracing(nestApp);
+  };
+
+  const originalListen = nestApp.listen.bind(nestApp);
+  nestApp.listen = function OpenconsListen(...args) {
+    attach();
+    return originalListen(...args);
+  };
+
+  if (typeof nestApp.init === 'function') {
+    const originalInit = nestApp.init.bind(nestApp);
+    nestApp.init = async function OpenconsInit(...args) {
+      attach();
+      return originalInit(...args);
+    };
+  }
+}
+
+/** @deprecated Use OpenconsControllerInterceptor via deferControllerTracingUntilReady */
+class OpenconsNestInterceptor {
+  intercept(context, next) {
+    return new OpenconsControllerInterceptor().intercept(context, next);
+  }
+}
+
+/**
+ * @param {object} pipe
+ */
+function wrapNestPipe(pipe) {
+  if (!pipe || pipe.__openconsWrapped) {
+    return pipe;
+  }
+
+  if (typeof pipe.transform !== 'function') {
+    return pipe;
+  }
+
+  const name = resolveNestComponentName(pipe, 'Pipe');
+  const original = pipe.transform.bind(pipe);
+
+  pipe.transform = function OpenconsTransform(value, metadata) {
+    const tracer = getCurrentTracer();
+    const alsContext = getCurrentContext();
+
+    if (!tracer) {
+      return original(value, metadata);
+    }
+
+    const entered = performance.now();
+
+    try {
+      const result = original(value, metadata);
+
+      if (result && typeof result.then === 'function') {
+        return result
+          .then((resolved) => {
+            recordStepSafe(alsContext, tracer, name, entered);
+            return resolved;
+          })
+          .catch((err) => {
+            recordStepSafe(alsContext, tracer, name, entered, false, `error: ${err.message}`);
+            throw err;
+          });
+      }
+
+      recordStepSafe(alsContext, tracer, name, entered);
+      return result;
+    } catch (err) {
+      recordStepSafe(alsContext, tracer, name, entered, false, `error: ${err.message}`);
+      throw err;
+    }
+  };
+
+  pipe.__openconsWrapped = true;
+  return pipe;
+}
+
+module.exports = {
+  patchNestGlobally,
+  wrapNestInterceptor,
+  wrapNestGuard,
+  wrapNestPipe,
+  attachControllerTracing,
+  deferControllerTracingUntilReady,
+  OpenconsControllerInterceptor,
+  OpenconsNestInterceptor,
+};

package/src/integrations/nest.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const { createOpencons } = require('../core');
+const { patchExpressApp } = require('../interceptors/express');
+const {
+  patchNestGlobally,
+  deferControllerTracingUntilReady,
+} = require('./nest-lifecycle');
+
+/**
+ * @param {import('express').Application} expressApp
+ * @param {import('express').RequestHandler} handler
+ */
+function prependMiddleware(expressApp, handler) {
+  if (typeof expressApp.lazyrouter === 'function') {
+    expressApp.lazyrouter();
+  }
+
+  const router = expressApp._router;
+
+  if (!router || !Array.isArray(router.stack)) {
+    expressApp.use(handler);
+    return;
+  }
+
+  const Layer = require('express/lib/router/layer');
+  const layer = new Layer('/', { sensitive: false, strict: false, end: false }, handler);
+  router.stack.unshift(layer);
+}
+
+/**
+ * @param {import('@nestjs/common').INestApplication} nestApp
+ * @param {Parameters<typeof createOpencons>[0]} [options]
+ * @returns {ReturnType<typeof createOpencons>}
+ */
+function applyToNest(nestApp, options) {
+  patchNestGlobally();
+
+  const middleware = createOpencons(options);
+  const httpAdapter = nestApp.getHttpAdapter();
+
+  if (!httpAdapter || typeof httpAdapter.getInstance !== 'function') {
+    const { OpenconsError } = require('../lib/errors');
+    throw new OpenconsError(
+      'Nest app must use the Express adapter (@nestjs/platform-express).',
+      'NEST_ADAPTER_REQUIRED'
+    );
+  }
+
+  const expressApp = httpAdapter.getInstance();
+  patchExpressApp(expressApp);
+  prependMiddleware(expressApp, middleware);
+
+  if (typeof httpAdapter.setOnRequestHook === 'function') {
+    const previousHook = httpAdapter.onRequestHook;
+
+    httpAdapter.setOnRequestHook((req, res, next) => {
+      middleware(req, res, () => {
+        if (previousHook) {
+          previousHook(req, res, next);
+          return;
+        }
+        next();
+      });
+    });
+  }
+
+  // Register controller tracing after the app's own global interceptors (on listen/init).
+  deferControllerTracingUntilReady(nestApp);
+
+  const { logger } = require('../lib/logger');
+  logger.info('Attached to Nest (middleware + guards + interceptors + controllers)');
+
+  return middleware;
+}
+
+/**
+ * @param {Parameters<typeof createOpencons>[0]} [options]
+ * @returns {ReturnType<typeof createOpencons>}
+ */
+function createNestMiddleware(options) {
+  return createOpencons(options);
+}
+
+module.exports = {
+  applyToNest,
+  createNestMiddleware,
+  prependMiddleware,
+};