express-sequelize-traffic 0.1.0 → 0.2.0

package/dist/index.js

@@ -0,0 +1,844 @@
+import { fileURLToPath as __fileURLToPath } from "node:url"; const __PACKAGE_DIR__ = __fileURLToPath(new URL(".", import.meta.url));
+
+// src/models/TrafficLog.js
+import { DataTypes } from "sequelize";
+function defineTrafficLogModel(sequelize) {
+  if (!sequelize) {
+    throw new Error("A Sequelize instance is required to define TrafficLog.");
+  }
+  if (sequelize.models.TrafficLog) {
+    return sequelize.models.TrafficLog;
+  }
+  return sequelize.define(
+    "TrafficLog",
+    {
+      id: {
+        type: DataTypes.BIGINT,
+        autoIncrement: true,
+        primaryKey: true
+      },
+      userId: {
+        type: DataTypes.STRING,
+        allowNull: true
+      },
+      sessionId: {
+        type: DataTypes.STRING,
+        allowNull: true
+      },
+      method: {
+        type: DataTypes.STRING(16),
+        allowNull: false
+      },
+      route: {
+        type: DataTypes.STRING,
+        allowNull: false
+      },
+      originalUrl: {
+        type: DataTypes.STRING,
+        allowNull: false
+      },
+      statusCode: {
+        type: DataTypes.INTEGER,
+        allowNull: false
+      },
+      durationMs: {
+        type: DataTypes.INTEGER,
+        allowNull: false
+      },
+      isSlow: {
+        type: DataTypes.BOOLEAN,
+        allowNull: false,
+        defaultValue: false
+      },
+      ip: {
+        type: DataTypes.STRING,
+        allowNull: true
+      },
+      userAgent: {
+        type: DataTypes.TEXT,
+        allowNull: true
+      },
+      startedAt: {
+        type: DataTypes.DATE,
+        allowNull: false
+      },
+      endedAt: {
+        type: DataTypes.DATE,
+        allowNull: false
+      }
+    },
+    {
+      tableName: "traffic_logs",
+      indexes: [
+        { fields: ["userId"] },
+        { fields: ["sessionId"] },
+        { fields: ["route"] },
+        { fields: ["method"] },
+        { fields: ["statusCode"] },
+        { fields: ["durationMs"] },
+        { fields: ["createdAt"] }
+      ]
+    }
+  );
+}
+
+// src/utils/safeAsync.js
+async function safeAsync(task, options = {}) {
+  const { fallback = null, onError } = options;
+  try {
+    return await task();
+  } catch (error) {
+    if (typeof onError === "function") {
+      onError(error);
+    }
+    return fallback;
+  }
+}
+
+// src/utils/routeMatcher.js
+function normalizeRouteCandidate(route) {
+  if (Array.isArray(route)) {
+    return route[0] || "/";
+  }
+  if (route instanceof RegExp) {
+    return route.toString();
+  }
+  return route || null;
+}
+function resolveTrackedRoute(req) {
+  const routePath = normalizeRouteCandidate(req.route?.path);
+  if (req.baseUrl && routePath) {
+    return routePath === "/" ? req.baseUrl || "/" : `${req.baseUrl}${routePath}`;
+  }
+  return routePath || req.path || req.originalUrl || "/";
+}
+function matchesIgnoredRoute(matcher, candidate) {
+  if (!candidate) {
+    return false;
+  }
+  if (matcher instanceof RegExp) {
+    return matcher.test(candidate);
+  }
+  if (typeof matcher === "function") {
+    return Boolean(matcher(candidate));
+  }
+  if (typeof matcher === "string") {
+    return candidate === matcher || candidate.startsWith(`${matcher}?`);
+  }
+  return false;
+}
+function shouldIgnoreRoute({
+  route,
+  originalUrl,
+  ignoredRoutes = []
+}) {
+  return ignoredRoutes.some(
+    (matcher) => matchesIgnoredRoute(matcher, route) || matchesIgnoredRoute(matcher, originalUrl)
+  );
+}
+
+// src/middleware.js
+function resolveOptionalValue(getter, req, debug, label) {
+  if (typeof getter !== "function") {
+    return null;
+  }
+  try {
+    return getter(req) ?? null;
+  } catch (error) {
+    if (debug) {
+      console.error(
+        `[express-sequelize-traffic] Failed to resolve ${label}.`,
+        error
+      );
+    }
+    return null;
+  }
+}
+function createLogPayload({
+  req,
+  res,
+  startedAt,
+  endedAt,
+  slowRouteThresholdMs,
+  trackIp,
+  trackUserAgent,
+  getUserId,
+  getSessionId,
+  debug
+}) {
+  const route = resolveTrackedRoute(req);
+  const durationMs = Math.max(0, endedAt.getTime() - startedAt.getTime());
+  return {
+    userId: resolveOptionalValue(getUserId, req, debug, "userId"),
+    sessionId: resolveOptionalValue(getSessionId, req, debug, "sessionId"),
+    method: req.method,
+    route,
+    originalUrl: req.originalUrl || route,
+    statusCode: res.statusCode,
+    durationMs,
+    isSlow: durationMs >= slowRouteThresholdMs,
+    ip: trackIp ? req.ip || req.socket?.remoteAddress || null : null,
+    userAgent: trackUserAgent ? req.get("user-agent") || null : null,
+    startedAt,
+    endedAt
+  };
+}
+function createTrackingMiddleware({
+  TrafficLog,
+  getUserId,
+  getSessionId,
+  slowRouteThresholdMs = 1e3,
+  ignoredRoutes = [],
+  trackIp = false,
+  trackUserAgent = true,
+  debug = false,
+  realtimeBridge
+}) {
+  return (req, res, next) => {
+    const startedAt = /* @__PURE__ */ new Date();
+    res.once("finish", () => {
+      const endedAt = /* @__PURE__ */ new Date();
+      const route = resolveTrackedRoute(req);
+      const originalUrl = req.originalUrl || route;
+      if (shouldIgnoreRoute({ route, originalUrl, ignoredRoutes })) {
+        return;
+      }
+      void safeAsync(
+        async () => {
+          const payload = createLogPayload({
+            req,
+            res,
+            startedAt,
+            endedAt,
+            slowRouteThresholdMs,
+            trackIp,
+            trackUserAgent,
+            getUserId,
+            getSessionId,
+            debug
+          });
+          const createdLog = await TrafficLog.create(payload);
+          realtimeBridge?.emitNewRequest(createdLog.get({ plain: true }));
+        },
+        {
+          onError: (error) => {
+            if (debug) {
+              console.error(
+                "[express-sequelize-traffic] Failed to persist traffic log.",
+                error
+              );
+            }
+          }
+        }
+      );
+    });
+    next();
+  };
+}
+
+// src/services/analyticsService.js
+import { Op, fn, col, literal } from "sequelize";
+function toNumber(value, decimals = 2) {
+  const parsed = Number(value ?? 0);
+  if (!Number.isFinite(parsed)) {
+    return 0;
+  }
+  return Number(parsed.toFixed(decimals));
+}
+function normalizeLog(log) {
+  return {
+    id: log.id,
+    userId: log.userId,
+    sessionId: log.sessionId,
+    method: log.method,
+    route: log.route,
+    originalUrl: log.originalUrl,
+    statusCode: Number(log.statusCode),
+    durationMs: Number(log.durationMs),
+    isSlow: Boolean(log.isSlow),
+    ip: log.ip,
+    userAgent: log.userAgent,
+    startedAt: log.startedAt,
+    endedAt: log.endedAt,
+    createdAt: log.createdAt,
+    updatedAt: log.updatedAt
+  };
+}
+function buildTimeline(logs = []) {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const log of logs) {
+    const bucketDate = new Date(log.createdAt);
+    bucketDate.setMinutes(0, 0, 0);
+    const bucketKey = bucketDate.toISOString();
+    buckets.set(bucketKey, (buckets.get(bucketKey) || 0) + 1);
+  }
+  return [...buckets.entries()].sort(([left], [right]) => left.localeCompare(right)).slice(-24).map(([timestamp, totalRequests]) => ({
+    timestamp,
+    totalRequests
+  }));
+}
+function buildGroupKey(row) {
+  return `${row.route}::${row.method}`;
+}
+function mapGroupedCounts(rows = []) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    counts.set(buildGroupKey(row), Number(row.totalCount || 0));
+  }
+  return counts;
+}
+function createAnalyticsService(TrafficLog) {
+  return {
+    async getOverview() {
+      const [
+        totalRequests,
+        averageDurationMsRaw,
+        slowRequestCount,
+        errorRequestCount,
+        uniqueUsers,
+        topRoutesRows,
+        slowestRoutesRows,
+        statusCodeRows,
+        latestRequests,
+        timelineLogs
+      ] = await Promise.all([
+        TrafficLog.count(),
+        TrafficLog.aggregate("durationMs", "avg"),
+        TrafficLog.count({ where: { isSlow: true } }),
+        TrafficLog.count({
+          where: {
+            statusCode: { [Op.gte]: 400 }
+          }
+        }),
+        TrafficLog.count({
+          distinct: true,
+          col: "userId",
+          where: {
+            userId: { [Op.not]: null }
+          }
+        }),
+        TrafficLog.findAll({
+          attributes: [
+            "route",
+            [fn("COUNT", col("id")), "totalRequests"]
+          ],
+          where: {
+            route: { [Op.not]: null }
+          },
+          group: ["route"],
+          order: [[literal("totalRequests"), "DESC"]],
+          limit: 5,
+          raw: true
+        }),
+        TrafficLog.findAll({
+          attributes: [
+            "route",
+            "method",
+            [fn("AVG", col("durationMs")), "averageDurationMs"],
+            [fn("MAX", col("durationMs")), "maxDurationMs"],
+            [fn("COUNT", col("id")), "totalRequests"]
+          ],
+          where: {
+            route: { [Op.not]: null }
+          },
+          group: ["route", "method"],
+          order: [[literal("averageDurationMs"), "DESC"]],
+          limit: 5,
+          raw: true
+        }),
+        TrafficLog.findAll({
+          attributes: [
+            "statusCode",
+            [fn("COUNT", col("id")), "totalRequests"]
+          ],
+          group: ["statusCode"],
+          order: [["statusCode", "ASC"]],
+          raw: true
+        }),
+        TrafficLog.findAll({
+          order: [["createdAt", "DESC"]],
+          limit: 10,
+          raw: true
+        }),
+        TrafficLog.findAll({
+          attributes: ["createdAt"],
+          order: [["createdAt", "DESC"]],
+          limit: 1e3,
+          raw: true
+        })
+      ]);
+      return {
+        totalRequests,
+        averageDurationMs: toNumber(averageDurationMsRaw),
+        slowRequestCount,
+        errorRequestCount,
+        uniqueUsers,
+        topRoutes: topRoutesRows.map((row) => ({
+          route: row.route,
+          totalRequests: Number(row.totalRequests)
+        })),
+        slowestRoutes: slowestRoutesRows.map((row) => ({
+          route: row.route,
+          method: row.method,
+          totalRequests: Number(row.totalRequests),
+          averageDurationMs: toNumber(row.averageDurationMs),
+          maxDurationMs: Number(row.maxDurationMs)
+        })),
+        statusCodeSummary: statusCodeRows.map((row) => ({
+          statusCode: Number(row.statusCode),
+          totalRequests: Number(row.totalRequests)
+        })),
+        latestRequests: latestRequests.map(normalizeLog),
+        requestsTimeline: buildTimeline(timelineLogs)
+      };
+    },
+    async getLive() {
+      const logs = await TrafficLog.findAll({
+        order: [["createdAt", "DESC"]],
+        limit: 100,
+        raw: true
+      });
+      return logs.map(normalizeLog);
+    },
+    async getRoutes() {
+      const [baseRows, errorRows, slowRows] = await Promise.all([
+        TrafficLog.findAll({
+          attributes: [
+            "route",
+            "method",
+            [fn("COUNT", col("id")), "totalRequests"],
+            [fn("AVG", col("durationMs")), "averageDurationMs"],
+            [fn("MAX", col("durationMs")), "maxDurationMs"]
+          ],
+          where: {
+            route: { [Op.not]: null }
+          },
+          group: ["route", "method"],
+          order: [[literal("averageDurationMs"), "DESC"]],
+          raw: true
+        }),
+        TrafficLog.findAll({
+          attributes: [
+            "route",
+            "method",
+            [fn("COUNT", col("id")), "totalCount"]
+          ],
+          where: {
+            route: { [Op.not]: null },
+            statusCode: { [Op.gte]: 400 }
+          },
+          group: ["route", "method"],
+          raw: true
+        }),
+        TrafficLog.findAll({
+          attributes: [
+            "route",
+            "method",
+            [fn("COUNT", col("id")), "totalCount"]
+          ],
+          where: {
+            route: { [Op.not]: null },
+            isSlow: true
+          },
+          group: ["route", "method"],
+          raw: true
+        })
+      ]);
+      const errorCounts = mapGroupedCounts(errorRows);
+      const slowCounts = mapGroupedCounts(slowRows);
+      return baseRows.map((row) => {
+        const key = buildGroupKey(row);
+        return {
+          route: row.route,
+          method: row.method,
+          totalRequests: Number(row.totalRequests),
+          averageDurationMs: toNumber(row.averageDurationMs),
+          maxDurationMs: Number(row.maxDurationMs),
+          errorCount: errorCounts.get(key) || 0,
+          slowCount: slowCounts.get(key) || 0
+        };
+      });
+    },
+    async getUsers() {
+      const rows = await TrafficLog.findAll({
+        attributes: [
+          "userId",
+          [fn("COUNT", col("id")), "totalRequests"],
+          [fn("MAX", col("createdAt")), "lastSeenAt"],
+          [fn("AVG", col("durationMs")), "averageDurationMs"]
+        ],
+        where: {
+          userId: { [Op.not]: null }
+        },
+        group: ["userId"],
+        order: [[literal("totalRequests"), "DESC"]],
+        raw: true
+      });
+      return rows.map((row) => ({
+        userId: row.userId,
+        totalRequests: Number(row.totalRequests),
+        lastSeenAt: row.lastSeenAt,
+        averageDurationMs: toNumber(row.averageDurationMs)
+      }));
+    },
+    async getErrors() {
+      const rows = await TrafficLog.findAll({
+        where: {
+          statusCode: { [Op.gte]: 400 }
+        },
+        order: [["createdAt", "DESC"]],
+        limit: 100,
+        raw: true
+      });
+      return rows.map(normalizeLog);
+    }
+  };
+}
+
+// src/dashboard.js
+import fs from "node:fs";
+import path from "node:path";
+import express2 from "express";
+
+// src/routes/analyticsRoutes.js
+import express from "express";
+function sendApiError(res, message) {
+  res.status(500).json({ error: message });
+}
+function createAnalyticsRouter({ analyticsService, debug = false }) {
+  const router = express.Router();
+  const logApiError = (scope) => (error) => {
+    if (debug) {
+      console.error(`[express-sequelize-traffic] ${scope}`, error);
+    }
+  };
+  router.get("/overview", async (_req, res) => {
+    const data = await safeAsync(() => analyticsService.getOverview(), {
+      onError: logApiError("Failed to load overview analytics.")
+    });
+    if (!data) {
+      sendApiError(res, "Unable to load overview analytics.");
+      return;
+    }
+    res.json(data);
+  });
+  router.get("/live", async (_req, res) => {
+    const data = await safeAsync(() => analyticsService.getLive(), {
+      onError: logApiError("Failed to load live traffic logs.")
+    });
+    if (!data) {
+      sendApiError(res, "Unable to load live traffic logs.");
+      return;
+    }
+    res.json(data);
+  });
+  router.get("/routes", async (_req, res) => {
+    const data = await safeAsync(() => analyticsService.getRoutes(), {
+      onError: logApiError("Failed to load route analytics.")
+    });
+    if (!data) {
+      sendApiError(res, "Unable to load route analytics.");
+      return;
+    }
+    res.json(data);
+  });
+  router.get("/users", async (_req, res) => {
+    const data = await safeAsync(() => analyticsService.getUsers(), {
+      onError: logApiError("Failed to load user analytics.")
+    });
+    if (!data) {
+      sendApiError(res, "Unable to load user analytics.");
+      return;
+    }
+    res.json(data);
+  });
+  router.get("/errors", async (_req, res) => {
+    const data = await safeAsync(() => analyticsService.getErrors(), {
+      onError: logApiError("Failed to load error analytics.")
+    });
+    if (!data) {
+      sendApiError(res, "Unable to load error analytics.");
+      return;
+    }
+    res.json(data);
+  });
+  return router;
+}
+
+// src/utils/dashboardAuth.js
+function parseBasicAuthHeader(headerValue) {
+  if (!headerValue || !headerValue.startsWith("Basic ")) {
+    return null;
+  }
+  try {
+    const decoded = Buffer.from(headerValue.slice(6), "base64").toString(
+      "utf8"
+    );
+    const separatorIndex = decoded.indexOf(":");
+    if (separatorIndex === -1) {
+      return null;
+    }
+    return {
+      username: decoded.slice(0, separatorIndex),
+      password: decoded.slice(separatorIndex + 1)
+    };
+  } catch (_error) {
+    return null;
+  }
+}
+function isDashboardAuthEnabled(dashboard = {}) {
+  return Boolean(dashboard.enabled && dashboard.username && dashboard.password);
+}
+function createBasicAuthMiddleware(dashboard = {}) {
+  if (!isDashboardAuthEnabled(dashboard)) {
+    return (_req, _res, next) => next();
+  }
+  return (req, res, next) => {
+    const credentials = parseBasicAuthHeader(req.headers.authorization);
+    if (credentials?.username === dashboard.username && credentials?.password === dashboard.password) {
+      next();
+      return;
+    }
+    res.setHeader("WWW-Authenticate", 'Basic realm="Traffic Dashboard"');
+    res.status(401).json({ error: "Dashboard authentication required." });
+  };
+}
+function createSocketAuthMiddleware(dashboard = {}) {
+  return (socket, next) => {
+    if (!isDashboardAuthEnabled(dashboard)) {
+      next();
+      return;
+    }
+    const credentials = parseBasicAuthHeader(
+      socket.handshake.headers.authorization
+    );
+    if (credentials?.username === dashboard.username && credentials?.password === dashboard.password) {
+      next();
+      return;
+    }
+    next(new Error("Dashboard authentication required."));
+  };
+}
+
+// src/dashboard.js
+var dashboardBuildDirectory = path.resolve(
+  __PACKAGE_DIR__,
+  "dashboard-public"
+);
+var dashboardIndexFile = path.join(dashboardBuildDirectory, "index.html");
+function createMissingBuildPage() {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Traffic Dashboard Build Missing</title>
+    <style>
+      body {
+        margin: 0;
+        font-family: "Segoe UI", sans-serif;
+        background: linear-gradient(135deg, #0f172a, #1e293b);
+        color: #e2e8f0;
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        padding: 24px;
+      }
+
+      .panel {
+        max-width: 640px;
+        background: rgba(15, 23, 42, 0.9);
+        border: 1px solid rgba(148, 163, 184, 0.2);
+        border-radius: 24px;
+        padding: 32px;
+        box-shadow: 0 24px 60px rgba(15, 23, 42, 0.45);
+      }
+
+      h1 {
+        margin-top: 0;
+        font-size: 2rem;
+      }
+
+      code {
+        background: rgba(148, 163, 184, 0.16);
+        padding: 2px 6px;
+        border-radius: 6px;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="panel">
+      <h1>Dashboard build not found</h1>
+      <p>
+        The analytics APIs are available, but the Vite dashboard has not been built
+        into <code>dist/dashboard-public</code> yet.
+      </p>
+      <p>Run <code>npm run build:dashboard</code> in this package to generate the static dashboard assets.</p>
+    </div>
+  </body>
+</html>`;
+}
+function createDisabledDashboardRouter() {
+  const router = express2.Router();
+  router.use("/api", (_req, res) => {
+    res.status(404).json({ error: "Dashboard is disabled." });
+  });
+  router.use((_req, res) => {
+    res.status(404).send("The traffic dashboard is disabled for this tracker instance.");
+  });
+  return router;
+}
+function createDashboardRouter({
+  analyticsService,
+  dashboard = {},
+  debug = false
+}) {
+  const router = express2.Router();
+  router.use(createBasicAuthMiddleware(dashboard));
+  router.use("/api", createAnalyticsRouter({ analyticsService, debug }));
+  const hasBuiltDashboard = fs.existsSync(dashboardIndexFile);
+  if (hasBuiltDashboard) {
+    router.get("/", (req, res, next) => {
+      if (!req.originalUrl.endsWith("/")) {
+        res.redirect(302, `${req.baseUrl}/`);
+        return;
+      }
+      next();
+    });
+    router.use(
+      express2.static(dashboardBuildDirectory, {
+        index: false
+      })
+    );
+    router.get("*", (req, res, next) => {
+      if (req.path.startsWith("/api")) {
+        next();
+        return;
+      }
+      res.sendFile(dashboardIndexFile);
+    });
+    return router;
+  }
+  router.get("*", (req, res, next) => {
+    if (req.path.startsWith("/api")) {
+      next();
+      return;
+    }
+    res.status(503).send(createMissingBuildPage());
+  });
+  return router;
+}
+
+// src/realtime.js
+import { Server } from "socket.io";
+function normalizeSocketPath(dashboard = {}) {
+  const mountPath = dashboard.mountPath || "/traffic-dashboard";
+  const sanitizedMountPath = mountPath.startsWith("/") ? mountPath : `/${mountPath}`;
+  return `${sanitizedMountPath.replace(/\/$/, "")}/socket.io`;
+}
+function buildRealtimePayload(log) {
+  return {
+    userId: log.userId,
+    sessionId: log.sessionId,
+    method: log.method,
+    route: log.route,
+    originalUrl: log.originalUrl,
+    statusCode: Number(log.statusCode),
+    durationMs: Number(log.durationMs),
+    isSlow: Boolean(log.isSlow),
+    createdAt: log.createdAt
+  };
+}
+function createRealtimeBridge({ dashboard = {}, debug = false } = {}) {
+  let io = null;
+  const socketPath = normalizeSocketPath(dashboard);
+  return {
+    attachRealtime(server) {
+      if (!server) {
+        throw new Error("An HTTP server instance is required for realtime.");
+      }
+      if (io) {
+        return io;
+      }
+      io = new Server(server, {
+        path: socketPath,
+        serveClient: false
+      });
+      io.use(createSocketAuthMiddleware(dashboard));
+      if (debug) {
+        io.on("connection", (socket) => {
+          console.info(
+            `[express-sequelize-traffic] Dashboard realtime connected: ${socket.id}`
+          );
+        });
+      }
+      return io;
+    },
+    emitNewRequest(log) {
+      if (!io) {
+        return;
+      }
+      io.emit("traffic:new-request", buildRealtimePayload(log));
+    },
+    getSocketPath() {
+      return socketPath;
+    }
+  };
+}
+
+// src/index.js
+function createTrafficTracker(options = {}) {
+  const {
+    sequelize,
+    getUserId,
+    getSessionId,
+    slowRouteThresholdMs = 1e3,
+    ignoredRoutes = [],
+    trackIp = false,
+    trackUserAgent = true,
+    dashboard = {},
+    debug = false
+  } = options;
+  if (!sequelize) {
+    throw new Error(
+      "createTrafficTracker requires a Sequelize instance via options.sequelize."
+    );
+  }
+  const TrafficLog = defineTrafficLogModel(sequelize);
+  const analyticsService = createAnalyticsService(TrafficLog);
+  const realtimeBridge = createRealtimeBridge({ dashboard, debug });
+  return {
+    middleware: createTrackingMiddleware({
+      TrafficLog,
+      getUserId,
+      getSessionId,
+      slowRouteThresholdMs,
+      ignoredRoutes,
+      trackIp,
+      trackUserAgent,
+      debug,
+      realtimeBridge
+    }),
+    dashboard: dashboard.enabled ? createDashboardRouter({
+      analyticsService,
+      dashboard,
+      debug
+    }) : createDisabledDashboardRouter(),
+    attachRealtime(server) {
+      return realtimeBridge.attachRealtime(server);
+    },
+    async sync(syncOptions = {}) {
+      return TrafficLog.sync(syncOptions);
+    },
+    getModel() {
+      return TrafficLog;
+    },
+    getSocketPath() {
+      return realtimeBridge.getSocketPath();
+    }
+  };
+}
+export {
+  createTrafficTracker,
+  defineTrafficLogModel
+};