mbkauthe 4.9.0 → 5.0.0

package/lib/utils/dbQueryLogger.js

@@ -1,4 +1,5 @@
-import path from "path";
+import path from "path";
+import crypto from "crypto";
 import { AsyncLocalStorage } from "async_hooks";
 
 const isDev = process.env.env === "dev" && process.env.dbLogs === "true";
@@ -11,6 +12,12 @@ const globalQueryState = {
 };
 let autoPoolId = 0;
 
+const callsiteCaptureSetting = (process.env.dbLogsCallsite || "true").toLowerCase();
+const parsedCallsiteSampleRate = Number(process.env.dbLogsCallsiteSample || "1");
+const callsiteSampleRate = Number.isFinite(parsedCallsiteSampleRate)
+  ? Math.min(1, Math.max(0, parsedCallsiteSampleRate))
+  : 1;
+
 const safeValue = (value, depth = 0, seen = new WeakSet()) => {
   if (value == null) return value;
   if (typeof value === "string") {
@@ -59,40 +66,81 @@ const toWorkspacePath = (filePath) => {
   return rel.replace(/\\/g, "/");
 };
 
+const isIgnorableStackFrame = (line) =>
+  !line.startsWith("at ") ||
+  line.includes("/lib/utils/dbQueryLogger.js") ||
+  line.includes("\\lib\\utils\\dbQueryLogger.js") ||
+  line.includes("node:internal") ||
+  line.includes("internal/process");
+
+const parseStackFrame = (frame) => {
+  const withFunc = /^at\s+([^\s(]+)\s+\((.+):([0-9]+):([0-9]+)\)$/.exec(frame);
+  const noFunc = /^at\s+(.+):([0-9]+):([0-9]+)$/.exec(frame);
+
+  if (withFunc) {
+    return {
+      function: withFunc[1],
+      file: withFunc[2],
+      line: Number(withFunc[3]),
+      column: Number(withFunc[4]),
+    };
+  }
+
+  if (noFunc) {
+    return {
+      function: null,
+      file: noFunc[1],
+      line: Number(noFunc[2]),
+      column: Number(noFunc[3]),
+    };
+  }
+
+  return null;
+};
+
+const isNodeModulesFrame = (filePath) => /[\\/]node_modules[\\/]/i.test(filePath || "");
+
+const shouldCaptureCallsite = () => {
+  if (callsiteCaptureSetting === "false" || callsiteCaptureSetting === "0") {
+    return false;
+  }
+
+  if (callsiteSampleRate <= 0) {
+    return false;
+  }
+
+  if (callsiteSampleRate >= 1) {
+    return true;
+  }
+
+  return Math.random() < callsiteSampleRate;
+};
+
 const buildCallsite = () => {
+  if (!shouldCaptureCallsite()) {
+    return null;
+  }
+
   try {
     const stack = new Error().stack || "";
-    const lines = stack.split("\n").map((l) => l.trim());
-    const frame = lines.find(
-      (line) =>
-        line.startsWith("at ") &&
-        !line.includes("/lib/utils/dbQueryLogger.js") &&
-        !line.includes("node:internal") &&
-        !line.includes("internal/process")
-    );
-
-    if (!frame) return null;
-
-    const withFunc = /^at\s+([^\s(]+)\s+\((.+):([0-9]+):([0-9]+)\)$/.exec(frame);
-    const noFunc = /^at\s+(.+):([0-9]+):([0-9]+)$/.exec(frame);
-
-    if (withFunc) {
-      return {
-        function: withFunc[1],
-        file: toWorkspacePath(withFunc[2]),
-        line: Number(withFunc[3]),
-        column: Number(withFunc[4]),
-      };
-    }
-
-    if (noFunc) {
-      return {
-        function: null,
-        file: toWorkspacePath(noFunc[1]),
-        line: Number(noFunc[2]),
-        column: Number(noFunc[3]),
-      };
-    }
+    const frames = stack
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => !isIgnorableStackFrame(line))
+      .map(parseStackFrame)
+      .filter(Boolean);
+
+    if (!frames.length) return null;
+
+    const preferredFrame = frames.find((frame) => !isNodeModulesFrame(frame.file));
+    if (!preferredFrame) return null;
+
+    return {
+      function: preferredFrame.function,
+      file: toWorkspacePath(preferredFrame.file),
+      line: preferredFrame.line,
+      column: preferredFrame.column,
+    };
   } catch {
     return null;
   }
@@ -100,6 +148,43 @@ const buildCallsite = () => {
   return null;
 };
 
+const normalizeQueryText = (queryText) =>
+  String(queryText || "")
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+    .replace(/--.*$/gm, " ")
+    .replace(/\$[0-9]+\b/g, "?")
+    .replace(/\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/gi, "?")
+    .replace(/'(?:''|[^'])*'/g, "?")
+    .replace(/\b\d+(?:\.\d+)?\b/g, "?")
+    .replace(/\s+/g, " ")
+    .trim()
+    .toLowerCase();
+
+const buildQueryFingerprint = (queryText) => {
+  const normalizedQuery = normalizeQueryText(queryText);
+  if (!normalizedQuery) {
+    return { fingerprint: null, normalizedQuery: "" };
+  }
+
+  return {
+    normalizedQuery,
+    fingerprint: crypto
+      .createHash("sha1")
+      .update(normalizedQuery)
+      .digest("hex")
+      .slice(0, 12),
+  };
+};
+
+const isSessionStoreQuery = (normalizedQuery, queryName) => {
+  const normalizedName = String(queryName || "").toLowerCase();
+  if (normalizedName.includes("session")) {
+    return true;
+  }
+
+  return /\b(?:from|update|into|delete from)\s+"session"\b/.test(normalizedQuery || "");
+};
+
 const buildRequestContext = () => {
   const store = getRequestContext();
   const req = store?.req;
@@ -135,6 +220,59 @@ const buildReturnValue = (result) => {
   return returnValue;
 };
 
+const buildTriggerContext = ({ request, callsite, normalizedQuery, queryName }) => {
+  const routeText = request ? `${request.method || ""} ${request.url || ""}`.trim() : "";
+  const sessionStore = isSessionStoreQuery(normalizedQuery, queryName);
+
+  if (request && sessionStore) {
+    return {
+      type: "request",
+      source: "session-store",
+      label: routeText ? `Session store during ${routeText}` : "Session store during request",
+      route: routeText || null,
+    };
+  }
+
+  if (request) {
+    return {
+      type: "request",
+      source: "route",
+      label: routeText || "Request route",
+      route: routeText || null,
+    };
+  }
+
+  if (callsite) {
+    const functionName = callsite.function || "(anonymous)";
+    const location = callsite.file
+      ? `${callsite.file}:${callsite.line}:${callsite.column}`
+      : "unknown location";
+
+    return {
+      type: "code",
+      source: "callsite",
+      label: `Code trigger: ${functionName} @ ${location}`,
+      route: null,
+    };
+  }
+
+  if (sessionStore) {
+    return {
+      type: "code",
+      source: "session-store",
+      label: "Session store outside request context",
+      route: null,
+    };
+  }
+
+  return {
+    type: "code",
+    source: "unknown",
+    label: "Code trigger (unresolved)",
+    route: null,
+  };
+};
+
 const recordGlobalLog = (entry) => {
   globalQueryState.totalCount += 1;
   globalQueryState.log.push(entry);
@@ -171,12 +309,11 @@ export const getRequestContext = () => {
 };
 
 const resolveLoggerPool = (item) => {
-  if (item && typeof item === 'object') {
+  if (item && typeof item === "object") {
     if (item.pool && item.pool.query) {
       return { pool: item.pool, name: item.name || item.pool.__mbkQueryLoggerName || item.pool.name };
     }
     if (item.query) {
-      // Don't force 'default' here; let getPoolName assign a non-default auto name.
       return { pool: item, name: item.__mbkQueryLoggerName || item.name || item.options?.application_name || null };
     }
   }
@@ -188,16 +325,35 @@ const getPoolName = (pool, fallbackName) => {
   if (pool.__mbkQueryLoggerName) return pool.__mbkQueryLoggerName;
   if (pool.name) return pool.name;
   if (pool.options && pool.options.application_name) return pool.options.application_name;
-  // never return "default"; always provide an actual pool name
   autoPoolId += 1;
   return `pool-${autoPoolId}`;
 };
 
+const parseQueryArgs = (args) => {
+  let queryText = "";
+  let queryName = "";
+  let queryValues;
+
+  try {
+    if (typeof args[0] === "string") {
+      queryText = args[0];
+      queryValues = Array.isArray(args[1]) ? args[1] : undefined;
+    } else if (args[0] && typeof args[0] === "object") {
+      queryText = args[0].text || "";
+      queryName = args[0].name || "";
+      queryValues = Array.isArray(args[0].values) ? args[0].values : undefined;
+    }
+  } catch {
+    queryText = "";
+  }
+
+  return { queryText, queryName, queryValues };
+};
+
 const attachSinglePool = (pool, poolName = null) => {
   if (!pool) return;
 
   if (pool.__mbkQueryLoggerInstalled) {
-    // Allow late explicit naming to override a previous auto name.
     if (poolName && pool.__mbkQueryLoggerName !== poolName) {
       pool.__mbkQueryLoggerName = poolName;
     }
@@ -210,6 +366,7 @@ const attachSinglePool = (pool, poolName = null) => {
   let dbQueryCount = 0;
   const dbQueryLog = [];
   const originalQuery = pool.query.bind(pool);
+  const originalConnect = typeof pool.connect === "function" ? pool.connect.bind(pool) : null;
 
   const recordPoolLog = (entry) => {
     dbQueryCount += 1;
@@ -220,80 +377,328 @@ const attachSinglePool = (pool, poolName = null) => {
     recordGlobalLog(entry);
   };
 
-  pool.query = (...args) => {
-    let queryText = "";
-    let queryName = "";
-    let queryValues;
+  const recordLogEntry = ({
+    queryText,
+    queryName,
+    queryValues,
+    callsiteSnapshot,
+    success,
+    error,
+    result,
+    durationMs,
+    executionDurationMs,
+    poolWait,
+  }) => {
+    const request = buildRequestContext();
+    const returnValue = buildReturnValue(result);
+    const { fingerprint, normalizedQuery } = buildQueryFingerprint(queryText);
+    const trigger = buildTriggerContext({
+      request,
+      callsite: callsiteSnapshot,
+      normalizedQuery,
+      queryName,
+    });
+
+    recordPoolLog({
+      time: new Date().toISOString(),
+      query: queryText,
+      normalizedQuery,
+      fingerprint,
+      name: queryName || undefined,
+      values: queryValues,
+      durationMs,
+      executionDurationMs,
+      success,
+      error: error ? { message: error.message, code: error.code } : undefined,
+      returnValue,
+      request,
+      trigger,
+      pool: {
+        name: pool.__mbkQueryLoggerName,
+        total: pool.totalCount,
+        idle: pool.idleCount,
+        waiting: pool.waitingCount,
+      },
+      poolWait,
+      callsite: callsiteSnapshot,
+    });
+  };
 
-    try {
-      if (typeof args[0] === "string") {
-        queryText = args[0];
-        queryValues = Array.isArray(args[1]) ? args[1] : undefined;
-      } else if (args[0] && typeof args[0] === "object") {
-        queryText = args[0].text || "";
-        queryName = args[0].name || "";
-        queryValues = Array.isArray(args[0].values) ? args[0].values : undefined;
-      }
-    } catch {
-      queryText = "";
+  const instrumentClient = (client, acquisition = null) => {
+    if (!client || typeof client.query !== "function") {
+      return client;
     }
 
-    if (!queryText) {
-      return originalQuery(...args);
+    client.__mbkQueryLoggerAcquisition = acquisition
+      ? { ...acquisition, attributedToQuery: false }
+      : null;
+
+    if (!client.__mbkQueryLoggerOriginalQuery) {
+      client.__mbkQueryLoggerOriginalQuery = client.query.bind(client);
     }
 
-    const startTime = process.hrtime.bigint();
-    const callsiteSnapshot = buildCallsite();
+    if (!client.__mbkQueryLoggerReleaseWrapped && typeof client.release === "function") {
+      const originalRelease = client.release.bind(client);
+      client.release = (...args) => {
+        client.__mbkQueryLoggerAcquisition = null;
+        return originalRelease(...args);
+      };
+      client.__mbkQueryLoggerReleaseWrapped = true;
+    }
+
+    if (client.__mbkQueryLoggerQueryWrapped) {
+      return client;
+    }
+
+    client.query = (...args) => {
+      const { queryText, queryName, queryValues } = parseQueryArgs(args);
+      if (!queryText) {
+        return client.__mbkQueryLoggerOriginalQuery(...args);
+      }
+
+      const callsiteSnapshot = buildCallsite();
+      const executionStartTime = process.hrtime.bigint();
+      const acquisitionMeta = client.__mbkQueryLoggerAcquisition;
+      const waitMs = acquisitionMeta && acquisitionMeta.attributedToQuery
+        ? 0
+        : acquisitionMeta?.waitMs || 0;
+      const waitingBefore = acquisitionMeta?.waitingBefore || 0;
+      const waitSource = acquisitionMeta?.source || "pool.connect";
+
+      if (acquisitionMeta && !acquisitionMeta.attributedToQuery) {
+        acquisitionMeta.attributedToQuery = true;
+      }
+
+      const finalize = (success, error, result) => {
+        const executionDurationMs = Number(process.hrtime.bigint() - executionStartTime) / 1_000_000;
+
+        recordLogEntry({
+          queryText,
+          queryName,
+          queryValues,
+          callsiteSnapshot,
+          success,
+          error,
+          result,
+          durationMs: executionDurationMs + waitMs,
+          executionDurationMs,
+          poolWait: {
+            source: waitSource,
+            waitMs,
+            waitingBefore,
+            waitingAfter: pool.waitingCount,
+            hadPoolPressure: waitingBefore > 0 || waitMs > 0,
+            captured: true,
+          },
+        });
+      };
+
+      try {
+        const result = client.__mbkQueryLoggerOriginalQuery(...args);
+        if (result && typeof result.then === "function") {
+          return result
+            .then((res) => {
+              finalize(true, null, res);
+              return res;
+            })
+            .catch((err) => {
+              finalize(false, err);
+              throw err;
+            });
+        }
+
+        finalize(true, null, result);
+        return result;
+      } catch (err) {
+        finalize(false, err);
+        throw err;
+      }
+    };
+
+    client.__mbkQueryLoggerQueryWrapped = true;
+    return client;
+  };
+
+  if (originalConnect) {
+    pool.connect = (...args) => {
+      const connectStartTime = process.hrtime.bigint();
+      const waitingBefore = pool.waitingCount;
+
+      if (typeof args[0] === "function") {
+        const callback = args[0];
+        return originalConnect((err, client, done) => {
+          if (err || !client) {
+            callback(err, client, done);
+            return;
+          }
+
+          callback(
+            null,
+            instrumentClient(client, {
+              source: "pool.connect",
+              waitMs: Number(process.hrtime.bigint() - connectStartTime) / 1_000_000,
+              waitingBefore,
+            }),
+            done
+          );
+        });
+      }
+
+      return originalConnect(...args).then((client) =>
+        instrumentClient(client, {
+          source: "pool.connect",
+          waitMs: Number(process.hrtime.bigint() - connectStartTime) / 1_000_000,
+          waitingBefore,
+        })
+      );
+    };
+  }
 
-    const recordLog = (success, error, result) => {
+  const runDirectLoggedPoolQuery = (args, { queryText, queryName, queryValues }) => {
+    const callsiteSnapshot = buildCallsite();
+    const startTime = process.hrtime.bigint();
+    const waitingBefore = pool.waitingCount;
+    const finalize = (success, error, result) => {
       const durationMs = Number(process.hrtime.bigint() - startTime) / 1_000_000;
-      const request = buildRequestContext();
-      const returnValue = buildReturnValue(result);
-
-      const entry = {
-        time: new Date().toISOString(),
-        query: queryText,
-        name: queryName || undefined,
-        values: queryValues,
-        durationMs,
+
+      recordLogEntry({
+        queryText,
+        queryName,
+        queryValues,
+        callsiteSnapshot,
         success,
-        error: error ? { message: error.message, code: error.code } : undefined,
-        returnValue,
-        request,
-        pool: {
-          name: pool.__mbkQueryLoggerName,
-          total: pool.totalCount,
-          idle: pool.idleCount,
-          waiting: pool.waitingCount,
+        error,
+        result,
+        durationMs,
+        executionDurationMs: durationMs,
+        poolWait: {
+          source: "pool.query",
+          waitMs: 0,
+          waitingBefore,
+          waitingAfter: pool.waitingCount,
+          hadPoolPressure: waitingBefore > 0,
+          captured: false,
         },
-        callsite: callsiteSnapshot,
+      });
+    };
+
+    const callbackIndex = args.findIndex((arg) => typeof arg === "function");
+    if (callbackIndex >= 0) {
+      const wrappedArgs = [...args];
+      const originalCallback = wrappedArgs[callbackIndex];
+      wrappedArgs[callbackIndex] = (err, result) => {
+        finalize(!err, err, result);
+        return originalCallback(err, result);
       };
 
-      recordPoolLog(entry);
-    };
+      try {
+        return originalQuery(...wrappedArgs);
+      } catch (err) {
+        finalize(false, err, null);
+        throw err;
+      }
+    }
 
     try {
       const result = originalQuery(...args);
       if (result && typeof result.then === "function") {
         return result
           .then((res) => {
-            recordLog(true, null, res);
+            finalize(true, null, res);
             return res;
           })
           .catch((err) => {
-            recordLog(false, err);
+            finalize(false, err, null);
             throw err;
           });
       }
 
-      recordLog(true, null, result);
+      finalize(true, null, result);
       return result;
     } catch (err) {
-      recordLog(false, err);
+      finalize(false, err, null);
       throw err;
     }
   };
 
+  pool.query = (...args) => {
+    const { queryText, queryName, queryValues } = parseQueryArgs(args);
+    const usesCallback = args.some((arg) => typeof arg === "function");
+
+    if (!queryText) {
+      return originalQuery(...args);
+    }
+
+    if (usesCallback || !originalConnect) {
+      return runDirectLoggedPoolQuery(args, { queryText, queryName, queryValues });
+    }
+
+    const callsiteSnapshot = buildCallsite();
+    const connectStartTime = process.hrtime.bigint();
+    const waitingBefore = pool.waitingCount;
+
+    return originalConnect()
+      .then(async (client) => {
+        const waitMs = Number(process.hrtime.bigint() - connectStartTime) / 1_000_000;
+        const rawQuery = client.query.bind(client);
+        const release = typeof client.release === "function" ? client.release.bind(client) : null;
+        const executionStartTime = process.hrtime.bigint();
+
+        try {
+          const result = await rawQuery(...args);
+          const executionDurationMs = Number(process.hrtime.bigint() - executionStartTime) / 1_000_000;
+
+          recordLogEntry({
+            queryText,
+            queryName,
+            queryValues,
+            callsiteSnapshot,
+            success: true,
+            error: null,
+            result,
+            durationMs: executionDurationMs + waitMs,
+            executionDurationMs,
+            poolWait: {
+              source: "pool.query",
+              waitMs,
+              waitingBefore,
+              waitingAfter: pool.waitingCount,
+              hadPoolPressure: waitingBefore > 0 || waitMs > 0,
+              captured: true,
+            },
+          });
+
+          return result;
+        } catch (err) {
+          const executionDurationMs = Number(process.hrtime.bigint() - executionStartTime) / 1_000_000;
+
+          recordLogEntry({
+            queryText,
+            queryName,
+            queryValues,
+            callsiteSnapshot,
+            success: false,
+            error: err,
+            result: null,
+            durationMs: executionDurationMs + waitMs,
+            executionDurationMs,
+            poolWait: {
+              source: "pool.query",
+              waitMs,
+              waitingBefore,
+              waitingAfter: pool.waitingCount,
+              hadPoolPressure: waitingBefore > 0 || waitMs > 0,
+              captured: true,
+            },
+          });
+
+          throw err;
+        } finally {
+          release?.();
+        }
+      });
+  };
+
   pool.getQueryCount = () => dbQueryCount;
   pool.resetQueryCount = () => {
     dbQueryCount = 0;

package/lib/utils/errors.js

@@ -272,4 +272,4 @@ export default {
   getErrorByCode,
   createErrorResponse,
   logError
-};
+};

package/lib/utils/logger.js

@@ -0,0 +1,12 @@
+import dotenv from "dotenv";
+import createDebug from "debug";
+
+dotenv.config();
+createDebug.enable(process.env.DEBUG || "");
+
+export const createLogger = (namespace = "") => {
+  const suffix = namespace ? `:${namespace}` : "";
+  return createDebug(`mbkauthe${suffix}`);
+};
+
+export const logDebug = createLogger();

package/lib/utils/timingSafeToken.js

@@ -32,4 +32,4 @@ export function timingSafeTokenMatch(providedToken, expectedToken) {
 
   const matches = timingSafeEqual(providedHash, expectedHash);
   return matches && expected.length > 0;
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mbkauthe",
-  "version": "4.9.0",
+  "version": "5.0.0",
   "description": "MBKTech's reusable authentication system for Node.js applications.",
   "main": "index.js",
   "type": "module",