@senzops/apm-node 1.2.5 → 1.2.7

package/src/utils/getClientIp.ts

@@ -1,175 +1,190 @@
-/**
- * getClientIp.ts
- *
- * Robust, proxy-aware client IP extraction.
- *
- * Priority order (mirrors Umami + industry best practice):
- *   1. ENV-configured custom header  (CLIENT_IP_HEADER)
- *   2. CF-Connecting-IP              (Cloudflare — single trusted IP)
- *   3. True-Client-IP                (Cloudflare Enterprise / Akamai)
- *   4. X-Real-IP                     (Nginx realip module)
- *   5. Forwarded                     (RFC 7239 — "for=" field)
- *   6. X-Forwarded-For               (De-facto standard — leftmost public IP)
- *   7. req.socket.remoteAddress      (Direct connection fallback)
- *
- * Security note: headers 2-6 can be spoofed by clients when your server is
- * directly internet-facing. If that is a concern, restrict extraction to the
- * header your trusted reverse-proxy injects (CLIENT_IP_HEADER or X-Real-IP).
- */
-
-import { isIP } from "net";
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Strip IPv4-mapped IPv6 prefix (::ffff:1.2.3.4 → 1.2.3.4) */
-const stripIPv6Mapped = (ip: string): string =>
-  ip.startsWith("::ffff:") ? ip.slice(7) : ip;
-
-/** Strip optional port from an IPv4 address (1.2.3.4:5678 → 1.2.3.4). */
-const stripIPv4Port = (ip: string): string => {
-  const lastColon = ip.lastIndexOf(":");
-  if (lastColon === -1) return ip;
-  const maybeIP = ip.slice(0, lastColon);
-  return isIP(maybeIP) === 4 ? maybeIP : ip;
-};
-
-/** Strip brackets + optional port from an IPv6 address ([::1]:5678 → ::1). */
-const stripIPv6Brackets = (ip: string): string => {
-  const match = ip.match(/^\[([^\]]+)\](?::\d+)?$/);
-  return match ? match[1] : ip;
-};
-
-/** Normalise raw IP string into a clean, routable address (or null). */
-export const normaliseIP = (raw: string | undefined | null): string | null => {
-  if (!raw) return null;
-  let ip = raw.trim();
-  if (!ip) return null;
-
-  ip = stripIPv6Brackets(ip);
-  ip = stripIPv4Port(ip);
-  ip = stripIPv6Mapped(ip);
-
-  return isIP(ip) !== 0 ? ip : null;
-};
-
-/**
- * Returns true for IPs that will never produce a geo result:
- * loopback, link-local, private ranges, and unspecified addresses.
- */
-export const isPrivateOrLoopback = (ip: string): boolean => {
-  // IPv4 private / loopback / link-local
-  if (
-    ip === "127.0.0.1" ||
-    ip.startsWith("10.") ||
-    ip.startsWith("192.168.") ||
-    ip.startsWith("169.254.") || // link-local
-    /^172\.(1[6-9]|2\d|3[01])\./.test(ip) // 172.16–31
-  )
-    return true;
-
-  // IPv6 loopback / unspecified / link-local / unique-local
-  if (
-    ip === "::1" ||
-    ip === "::" ||
-    ip.toLowerCase().startsWith("fe80:") || // link-local
-    ip.toLowerCase().startsWith("fc") || // unique-local
-    ip.toLowerCase().startsWith("fd") // unique-local
-  )
-    return true;
-
-  return false;
-};
-
-// ---------------------------------------------------------------------------
-// RFC 7239 "Forwarded" header parser
-//   e.g.  Forwarded: for=192.0.2.60;proto=http, for="[2001:db8::cafe]"
-// ---------------------------------------------------------------------------
-const parseForwardedHeader = (header: string): string | null => {
-  const parts = header.split(",");
-  for (const part of parts) {
-    const forMatch = part.match(/for=["[]?([^\]",;>\s]+)/i);
-    if (forMatch) {
-      const ip = normaliseIP(forMatch[1]);
-      if (ip && !isPrivateOrLoopback(ip)) return ip;
-    }
-  }
-  return null;
-};
-
-// ---------------------------------------------------------------------------
-// X-Forwarded-For parser — pick the leftmost *public* IP
-//   e.g.  X-Forwarded-For: client, proxy1, proxy2
-// ---------------------------------------------------------------------------
-const parseXForwardedFor = (header: string): string | null => {
-  const ips = header.split(",").map((s) => s.trim());
-  for (const raw of ips) {
-    const ip = normaliseIP(raw);
-    if (ip && !isPrivateOrLoopback(ip)) return ip;
-  }
-  // If every hop is private (intranet-only setup) fall back to first valid IP
-  for (const raw of ips) {
-    const ip = normaliseIP(raw);
-    if (ip) return ip;
-  }
-  return null;
-};
-
-// ---------------------------------------------------------------------------
-// Main export
-// ---------------------------------------------------------------------------
-
-/**
- * Extract the best-available client IP from a request.
- *
- * Returns `null` if no valid IP can be determined.
- */
-export const getClientIp = (req: any): string | null => {
-  const h = req.headers;
-
-  // 2. Cloudflare single-IP header (most reliable when behind CF)
-  {
-    const ip = normaliseIP(h["cf-connecting-ip"] as string);
-    if (ip) return ip;
-  }
-
-  // 3. Cloudflare Enterprise / Akamai
-  {
-    const ip = normaliseIP(h["true-client-ip"] as string);
-    if (ip) return ip;
-  }
-
-  // 4. Nginx realip module (single, already-trusted IP)
-  {
-    const ip = normaliseIP(h["x-real-ip"] as string);
-    if (ip) return ip;
-  }
-
-  // 5. RFC 7239 Forwarded header
-  {
-    const fwd = h["forwarded"] as string;
-    if (fwd) {
-      const ip = parseForwardedHeader(fwd);
-      if (ip) return ip;
-    }
-  }
-
-  // 6. De-facto standard XFF
-  {
-    const xff = h["x-forwarded-for"] as string;
-    if (xff) {
-      const ip = parseXForwardedFor(xff);
-      if (ip) return ip;
-    }
-  }
-
-  // 7. Direct TCP connection (local dev / no proxy)
-  {
-    const raw = req.socket?.remoteAddress;
-    const ip = normaliseIP(raw);
-    if (ip) return ip;
-  }
-
-  return null;
-};
+/**
+ * getClientIp.ts
+ *
+ * Robust, proxy-aware client IP extraction.
+ *
+ * Priority order (mirrors Umami + industry best practice):
+ *   1. ENV-configured custom header  (CLIENT_IP_HEADER)
+ *   2. CF-Connecting-IP              (Cloudflare — single trusted IP)
+ *   3. True-Client-IP                (Cloudflare Enterprise / Akamai)
+ *   4. X-Real-IP                     (Nginx realip module)
+ *   5. Forwarded                     (RFC 7239 — "for=" field)
+ *   6. X-Forwarded-For               (De-facto standard — leftmost public IP)
+ *   7. req.socket.remoteAddress      (Direct connection fallback)
+ *
+ * Security note: headers 2-6 can be spoofed by clients when your server is
+ * directly internet-facing. If that is a concern, restrict extraction to the
+ * header your trusted reverse-proxy injects (CLIENT_IP_HEADER or X-Real-IP).
+ */
+
+// ---------------------------------------------------------------------------
+// Inline IP validation (replaces Node's net.isIP to support edge runtimes)
+// ---------------------------------------------------------------------------
+
+const IPV4_PATTERN = /^(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)$/;
+const IPV6_PATTERN = /^(?:[a-fA-F0-9]{1,4}:){7}[a-fA-F0-9]{1,4}$|^::(?:[a-fA-F0-9]{1,4}:){0,5}[a-fA-F0-9]{1,4}$|^[a-fA-F0-9]{1,4}::(?:[a-fA-F0-9]{1,4}:){0,4}[a-fA-F0-9]{1,4}$|^(?:[a-fA-F0-9]{1,4}:){1,2}:(?:[a-fA-F0-9]{1,4}:){0,3}[a-fA-F0-9]{1,4}$|^(?:[a-fA-F0-9]{1,4}:){1,3}:(?:[a-fA-F0-9]{1,4}:){0,2}[a-fA-F0-9]{1,4}$|^(?:[a-fA-F0-9]{1,4}:){1,4}:(?:[a-fA-F0-9]{1,4}:)?[a-fA-F0-9]{1,4}$|^(?:[a-fA-F0-9]{1,4}:){1,5}:[a-fA-F0-9]{1,4}$|^(?:[a-fA-F0-9]{1,4}:){1,6}:$|^::$|^::1$|^fe80:.*$/i;
+
+/**
+ * Returns 4 for IPv4, 6 for IPv6, 0 for invalid.
+ * Drop-in replacement for Node's net.isIP().
+ */
+const isIP = (ip: string): number => {
+  if (IPV4_PATTERN.test(ip)) return 4;
+  if (IPV6_PATTERN.test(ip)) return 6;
+  return 0;
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Strip IPv4-mapped IPv6 prefix (::ffff:1.2.3.4 -> 1.2.3.4) */
+const stripIPv6Mapped = (ip: string): string =>
+  ip.startsWith("::ffff:") ? ip.slice(7) : ip;
+
+/** Strip optional port from an IPv4 address (1.2.3.4:5678 -> 1.2.3.4). */
+const stripIPv4Port = (ip: string): string => {
+  const lastColon = ip.lastIndexOf(":");
+  if (lastColon === -1) return ip;
+  const maybeIP = ip.slice(0, lastColon);
+  return isIP(maybeIP) === 4 ? maybeIP : ip;
+};
+
+/** Strip brackets + optional port from an IPv6 address ([::1]:5678 -> ::1). */
+const stripIPv6Brackets = (ip: string): string => {
+  const match = ip.match(/^\[([^\]]+)\](?::\d+)?$/);
+  return match ? match[1] : ip;
+};
+
+/** Normalise raw IP string into a clean, routable address (or null). */
+export const normaliseIP = (raw: string | undefined | null): string | null => {
+  if (!raw) return null;
+  let ip = raw.trim();
+  if (!ip) return null;
+
+  ip = stripIPv6Brackets(ip);
+  ip = stripIPv4Port(ip);
+  ip = stripIPv6Mapped(ip);
+
+  return isIP(ip) !== 0 ? ip : null;
+};
+
+/**
+ * Returns true for IPs that will never produce a geo result:
+ * loopback, link-local, private ranges, and unspecified addresses.
+ */
+export const isPrivateOrLoopback = (ip: string): boolean => {
+  // IPv4 private / loopback / link-local
+  if (
+    ip === "127.0.0.1" ||
+    ip.startsWith("10.") ||
+    ip.startsWith("192.168.") ||
+    ip.startsWith("169.254.") || // link-local
+    /^172\.(1[6-9]|2\d|3[01])\./.test(ip) // 172.16-31
+  )
+    return true;
+
+  // IPv6 loopback / unspecified / link-local / unique-local
+  if (
+    ip === "::1" ||
+    ip === "::" ||
+    ip.toLowerCase().startsWith("fe80:") || // link-local
+    ip.toLowerCase().startsWith("fc") || // unique-local
+    ip.toLowerCase().startsWith("fd") // unique-local
+  )
+    return true;
+
+  return false;
+};
+
+// ---------------------------------------------------------------------------
+// RFC 7239 "Forwarded" header parser
+//   e.g.  Forwarded: for=192.0.2.60;proto=http, for="[2001:db8::cafe]"
+// ---------------------------------------------------------------------------
+const parseForwardedHeader = (header: string): string | null => {
+  const parts = header.split(",");
+  for (const part of parts) {
+    const forMatch = part.match(/for=["[]?([^\]",;>\s]+)/i);
+    if (forMatch) {
+      const ip = normaliseIP(forMatch[1]);
+      if (ip && !isPrivateOrLoopback(ip)) return ip;
+    }
+  }
+  return null;
+};
+
+// ---------------------------------------------------------------------------
+// X-Forwarded-For parser — pick the leftmost *public* IP
+//   e.g.  X-Forwarded-For: client, proxy1, proxy2
+// ---------------------------------------------------------------------------
+const parseXForwardedFor = (header: string): string | null => {
+  const ips = header.split(",").map((s) => s.trim());
+  for (const raw of ips) {
+    const ip = normaliseIP(raw);
+    if (ip && !isPrivateOrLoopback(ip)) return ip;
+  }
+  // If every hop is private (intranet-only setup) fall back to first valid IP
+  for (const raw of ips) {
+    const ip = normaliseIP(raw);
+    if (ip) return ip;
+  }
+  return null;
+};
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the best-available client IP from a request.
+ *
+ * Returns `null` if no valid IP can be determined.
+ */
+export const getClientIp = (req: any): string | null => {
+  const h = req.headers;
+
+  // 2. Cloudflare single-IP header (most reliable when behind CF)
+  {
+    const ip = normaliseIP(h["cf-connecting-ip"] as string);
+    if (ip) return ip;
+  }
+
+  // 3. Cloudflare Enterprise / Akamai
+  {
+    const ip = normaliseIP(h["true-client-ip"] as string);
+    if (ip) return ip;
+  }
+
+  // 4. Nginx realip module (single, already-trusted IP)
+  {
+    const ip = normaliseIP(h["x-real-ip"] as string);
+    if (ip) return ip;
+  }
+
+  // 5. RFC 7239 Forwarded header
+  {
+    const fwd = h["forwarded"] as string;
+    if (fwd) {
+      const ip = parseForwardedHeader(fwd);
+      if (ip) return ip;
+    }
+  }
+
+  // 6. De-facto standard XFF
+  {
+    const xff = h["x-forwarded-for"] as string;
+    if (xff) {
+      const ip = parseXForwardedFor(xff);
+      if (ip) return ip;
+    }
+  }
+
+  // 7. Direct TCP connection (local dev / no proxy)
+  {
+    const raw = req.socket?.remoteAddress;
+    const ip = normaliseIP(raw);
+    if (ip) return ip;
+  }
+
+  return null;
+};

package/src/utils/ids.ts

@@ -1,7 +1,24 @@
-import { randomUUID } from 'crypto';
+const getRandomUUID = (): string => {
+  if (typeof globalThis !== 'undefined' && globalThis.crypto && typeof globalThis.crypto.randomUUID === 'function') {
+    return globalThis.crypto.randomUUID();
+  }
+
+  try {
+    if (typeof require !== 'undefined') {
+      const { randomUUID } = require('node:crypto');
+      if (randomUUID) return randomUUID();
+    }
+  } catch {}
+
+  // Fallback: RFC4122 v4 UUID via Math.random (last resort)
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+  });
+};
 
 export const generateTraceId = (): string =>
-  randomUUID().replace(/-/g, '');
+  getRandomUUID().replace(/-/g, '');
 
 export const generateSpanId = (): string =>
-  randomUUID().replace(/-/g, '').slice(0, 16);
+  getRandomUUID().replace(/-/g, '').slice(0, 16);

package/src/wrappers/nitro.ts

@@ -0,0 +1,60 @@
+import { client } from '../core/client';
+import { getRoute, normalizePath } from '../core/normalizer';
+import { getClientIp } from '../utils/getClientIp';
+
+export interface NitroApp {
+  h3App: {
+    handler: (event: any) => Promise<any>;
+    stack: any[];
+  };
+  hooks: any;
+  [key: string]: any;
+}
+
+export const nitroPlugin = (nitroApp: NitroApp) => {
+  if (!nitroApp.h3App || !nitroApp.h3App.handler) return;
+
+  const originalHandler = nitroApp.h3App.handler;
+
+  nitroApp.h3App.handler = async (event: any) => {
+    const req = event.node?.req || event.req;
+    const path = req?.originalUrl || req?.url || (event.path as string) || '/';
+    const method = req?.method || (event.method as string) || 'GET';
+
+    const headers = req?.headers || {};
+
+    return client.startTrace({
+      method,
+      path,
+      route: normalizePath(path),
+      ip: getClientIp({ headers, socket: req?.socket }),
+      userAgent: headers['user-agent'],
+      headers
+    }, async () => {
+      let status = 200;
+      try {
+        const response = await originalHandler(event);
+
+        if (event.node?.res?.statusCode) status = event.node.res.statusCode;
+        if (response?.status) status = response.status;
+
+        client.endTrace(status, { route: getRoute(event, path) });
+        return response;
+      } catch (err: any) {
+        status = err.statusCode || err.status || 500;
+        client.captureError(err);
+        client.endTrace(status, { route: getRoute(event, path) });
+        throw err;
+      } finally {
+        const cfCtx = event.context?.cloudflare?.context || event.context?.cf || event.context;
+        const waitUntil = cfCtx?.waitUntil || event.waitUntil;
+
+        if (waitUntil && typeof waitUntil === 'function') {
+          waitUntil(client.flush());
+        } else {
+          client.flush().catch(() => {});
+        }
+      }
+    });
+  };
+};

package/src/wrappers/worker.ts

@@ -0,0 +1,45 @@
+import { client } from '../core/client';
+import { normalizePath } from '../core/normalizer';
+import { getClientIp } from '../utils/getClientIp';
+
+type WorkerHandler = (request: Request, env: any, ctx: any) => Promise<Response>;
+
+export const wrapWorker = (handler: WorkerHandler) => {
+  return async (request: Request, env: any, ctx: any) => {
+    const url = new URL(request.url);
+    const path = url.pathname;
+    const method = request.method || 'GET';
+
+    const headers: Record<string, string> = {};
+    request.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+
+    return client.startTrace({
+      method,
+      path,
+      route: normalizePath(path),
+      ip: getClientIp({ headers }),
+      userAgent: headers['user-agent'],
+      headers
+    }, async () => {
+      let status = 500;
+      try {
+        const response = await handler(request, env, ctx);
+        status = response.status;
+        return response;
+      } catch (err: any) {
+        client.captureError(err);
+        throw err;
+      } finally {
+        client.endTrace(status, { route: normalizePath(path) });
+
+        if (ctx && typeof ctx.waitUntil === 'function') {
+          ctx.waitUntil(client.flush());
+        } else {
+          await client.flush();
+        }
+      }
+    });
+  };
+};

package/tsup.config.ts

@@ -1,5 +1,11 @@
 import { defineConfig } from 'tsup';
 
+const NODE_BUILTINS = [
+  'http', 'https', 'url', 'net', 'module', 'crypto', 'async_hooks',
+  'node:http', 'node:https', 'node:url', 'node:net', 'node:module',
+  'node:crypto', 'node:async_hooks'
+];
+
 export default defineConfig([
   {
     entry: ['src/index.ts', 'src/register.ts'],
@@ -9,6 +15,8 @@ export default defineConfig([
     minify: true,
     sourcemap: true,
     splitting: false,
+    external: NODE_BUILTINS,
+    noExternal: [],
   },
   {
     entry: ['src/index.ts'],
@@ -17,5 +25,6 @@ export default defineConfig([
     minify: true,
     sourcemap: true,
     splitting: false,
+    external: NODE_BUILTINS,
   }
 ]);