@senzops/apm-node 1.2.0 → 1.2.2

package/.claude/worktrees/infallible-chatelet-f3fb36/src/utils/getClientIp.ts

@@ -0,0 +1,175 @@
+/**
+ * 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;
+};

package/.claude/worktrees/infallible-chatelet-f3fb36/src/utils/ids.ts

@@ -0,0 +1,7 @@
+import { randomUUID } from 'crypto';
+
+export const generateTraceId = (): string =>
+  randomUUID().replace(/-/g, '');
+
+export const generateSpanId = (): string =>
+  randomUUID().replace(/-/g, '').slice(0, 16);

package/.claude/worktrees/infallible-chatelet-f3fb36/src/utils/internal.ts

@@ -0,0 +1 @@
+export const SENZOR_INTERNAL_HEADER = 'x-senzor-sdk-internal';

package/.claude/worktrees/infallible-chatelet-f3fb36/src/utils/sdkMeta.ts

@@ -0,0 +1,6 @@
+import pkg from '../../package.json';
+
+export const SDK_META = {
+  name: pkg.name,
+  version: pkg.version
+};

package/.claude/worktrees/infallible-chatelet-f3fb36/src/utils/traceContext.ts

@@ -0,0 +1,44 @@
+/**
+ * W3C Trace Context Implementation
+ * Standard: https://www.w3.org/TR/trace-context/
+ * Format: 00-{traceId}-{spanId}-{traceFlags}
+ */
+
+export interface TraceContext {
+  traceId: string;
+  parentSpanId: string;
+  sampled: boolean;
+}
+
+const TRACEPARENT_REGEX = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+
+export const parseTraceparent = (header?: string | string[]): TraceContext | null => {
+  if (!header) return null;
+
+  const traceparent = Array.isArray(header) ? header[0] : header;
+  if (typeof traceparent !== 'string') return null;
+
+  const match = traceparent.trim().toLowerCase().match(TRACEPARENT_REGEX);
+  if (!match) return null;
+
+  const traceId = match[1];
+  const parentSpanId = match[2];
+  const flags = match[3];
+
+  // Invalid IDs according to W3C specification
+  if (traceId === '00000000000000000000000000000000') return null;
+  if (parentSpanId === '0000000000000000') return null;
+
+  // The least significant bit of flags indicates if the trace is sampled
+  const sampled = (parseInt(flags, 16) & 0x01) === 0x01;
+
+  return { traceId, parentSpanId, sampled };
+};
+
+/**
+ * Generates a valid W3C traceparent header string for OUTGOING requests.
+ */
+export const generateTraceparent = (traceId: string, spanId: string, sampled: boolean = true): string => {
+  const flags = sampled ? '01' : '00';
+  return `00-${traceId}-${spanId}-${flags}`;
+};

package/.claude/worktrees/infallible-chatelet-f3fb36/src/wrappers/fastify.ts

@@ -0,0 +1,35 @@
+import { client } from '../core/client';
+import { SenzorOptions } from '../core/types';
+import { instrumentFastifyInstance } from '../instrumentation/fastify';
+import { getClientIp } from '../utils/getClientIp';
+
+export const senzorPlugin = (fastify: any, options: SenzorOptions, done: Function) => {
+  if (options && options.apiKey) {
+    client.init(options);
+  }
+
+  instrumentFastifyInstance(fastify, options);
+
+  fastify.addHook('onRequest', (request: any, reply: any, next: Function) => {
+    client.startTrace({
+      method: request.method,
+      path: request.raw.url || request.url,
+      ip: getClientIp(request),
+      userAgent: request.headers['user-agent'],
+      headers: request.headers // Pass headers
+    }, () => next());
+  });
+
+  fastify.addHook('onError', (request: any, reply: any, error: any, next: Function) => {
+    client.captureError(error);
+    next();
+  });
+
+  fastify.addHook('onResponse', (request: any, reply: any, next: Function) => {
+    const route = request.routeOptions?.url || request.routerPath || 'UNKNOWN';
+    client.endTrace(reply.statusCode, { route });
+    next();
+  });
+
+  done();
+};

package/.claude/worktrees/infallible-chatelet-f3fb36/src/wrappers/h3.ts

@@ -0,0 +1,59 @@
+import { client } from '../core/client';
+import { getRoute } from '../core/normalizer';
+import { invokeWithFrameworkSpan } from '../instrumentation/framework';
+import { getClientIp } from '../utils/getClientIp';
+
+type EventHandler = (event: any) => any;
+
+export const wrapH3 = (handler: EventHandler) => {
+  return (event: any) => {
+    const req = event.node.req;
+    const path = req.originalUrl || req.url || '/';
+
+    return client.startTrace({
+      method: req.method || 'GET',
+      path: path,
+      ip: getClientIp(req),
+      userAgent: req.headers['user-agent'],
+      headers: req.headers // Pass headers
+    }, async () => {
+      try {
+        const route = getRoute(event, path);
+        const response = await invokeWithFrameworkSpan(
+          handler,
+          undefined,
+          [event],
+          {
+            framework: 'h3',
+            type: 'event_handler',
+            name: `h3.event_handler ${req.method || 'GET'} ${route}`,
+            route,
+            method: req.method || 'GET',
+            request: req,
+            response: event.node.res,
+            attributes: {
+              'h3.type': 'event_handler',
+              'http.route': route
+            }
+          },
+          undefined,
+          {
+            callbackCompletesSpan: false,
+            responseEndsSpan: false
+          }
+        );
+        let status = 200;
+        if (event.node.res.statusCode) status = event.node.res.statusCode;
+        if (response && response.statusCode) status = response.statusCode;
+
+        client.endTrace(status, { route });
+        return response;
+      } catch (err: any) {
+        client.captureError(err);
+        const status = err.statusCode || err.status || 500;
+        client.endTrace(status, { route: getRoute(event, path) });
+        throw err;
+      }
+    });
+  };
+};

package/.claude/worktrees/infallible-chatelet-f3fb36/src/wrappers/next.ts

@@ -0,0 +1,131 @@
+import { client } from '../core/client';
+import { normalizePath } from '../core/normalizer';
+import { invokeWithFrameworkSpan } from '../instrumentation/framework';
+import { getClientIp } from '../utils/getClientIp';
+
+// --- App Router Wrapper ---
+export const wrapNextRoute = (handler: Function) => {
+  return async (req: Request | any, context?: any) => {
+
+    // Extract info from Web Standard Request
+    const url = req.url ? new URL(req.url) : { pathname: '/' };
+    const method = req.method || 'GET';
+
+    // Header Extraction
+    let headers: Record<string, string> = {};
+    let ua: string | undefined;
+    let ip: string | undefined;
+
+    if (typeof req.headers.get === 'function') {
+      // It's a Web Request Object
+      ua = req.headers.get('user-agent');
+      ip = req.headers.get('x-forwarded-for');
+
+      // Convert to plain object for trace context extraction
+      req.headers.forEach((value: string, key: string) => {
+        headers[key] = value;
+      });
+    } else {
+      // It's a Node Request Object (rare in App router but possible)
+      headers = req.headers;
+      ua = headers['user-agent'];
+      ip = headers['x-forwarded-for'] as string;
+    }
+
+    return client.startTrace({
+      method,
+      path: url.pathname,
+      userAgent: ua,
+      ip: ip || getClientIp(req),
+      headers: headers // Pass extracted headers
+    }, async () => {
+      try {
+        const route = normalizePath(url.pathname);
+        const response = await invokeWithFrameworkSpan(
+          handler,
+          undefined,
+          [req, context],
+          {
+            framework: 'next',
+            type: 'route_handler',
+            name: `next.app_route_handler ${method} ${route}`,
+            route,
+            method,
+            request: req,
+            attributes: {
+              'next.router': 'app',
+              'http.route': route,
+              'url.path': url.pathname
+            }
+          },
+          undefined,
+          {
+            callbackCompletesSpan: false,
+            responseEndsSpan: false
+          }
+        );
+        const status = response?.status || 200;
+
+        client.endTrace(status, { route });
+        return response;
+      } catch (err: any) {
+        client.captureError(err);
+        client.endTrace(500, { route: normalizePath(url.pathname) });
+        throw err;
+      }
+    });
+  };
+};
+
+// --- Pages Router Wrapper ---
+export const wrapNextPages = (handler: Function) => {
+  return async (req: any, res: any) => {
+    const path = req.url ? req.url.split('?')[0] : '/';
+
+    return client.startTrace({
+      method: req.method || 'GET',
+      path: path,
+      userAgent: req.headers['user-agent'],
+      ip: getClientIp(req),
+      headers: req.headers // Standard Node headers work fine
+    }, async () => {
+
+      const done = () => {
+        client.endTrace(res.statusCode || 200, { route: normalizePath(path) });
+      };
+
+      res.once('finish', done);
+      res.once('close', done);
+
+      try {
+        const route = normalizePath(path);
+        return await invokeWithFrameworkSpan(
+          handler,
+          undefined,
+          [req, res],
+          {
+            framework: 'next',
+            type: 'route_handler',
+            name: `next.pages_api_handler ${req.method || 'GET'} ${route}`,
+            route,
+            method: req.method || 'GET',
+            request: req,
+            response: res,
+            attributes: {
+              'next.router': 'pages',
+              'http.route': route
+            }
+          },
+          undefined,
+          {
+            callbackCompletesSpan: false,
+            responseEndsSpan: true
+          }
+        );
+      } catch (e: any) {
+        client.captureError(e);
+        throw e;
+      }
+    });
+  };
+};

package/.claude/worktrees/infallible-chatelet-f3fb36/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/.claude/worktrees/infallible-chatelet-f3fb36/tsup.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig([
+  {
+    entry: ['src/index.ts', 'src/register.ts'],
+    format: ['cjs', 'esm'],
+    dts: true,
+    clean: true,
+    minify: true,
+    sourcemap: true,
+    splitting: false,
+  },
+  {
+    entry: ['src/index.ts'],
+    format: ['iife'],
+    clean: false,
+    minify: true,
+    sourcemap: true,
+    splitting: false,
+  }
+]);