@fabbahiense/pulsar-pino-transport 0.2.1 → 0.4.0

package/dist/middleware.cjs

@@ -0,0 +1,387 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/middleware.ts
+var middleware_exports = {};
+__export(middleware_exports, {
+  pulsarRequestLogger: () => pulsarRequestLogger
+});
+module.exports = __toCommonJS(middleware_exports);
+
+// ../shared/src/redact.ts
+var DEFAULT_REDACT_KEYS = [
+  "password",
+  "passwd",
+  "password_hash",
+  "secret",
+  "client_secret",
+  "token",
+  "access_token",
+  "refresh_token",
+  "id_token",
+  "session_id",
+  "api_key",
+  "x-api-key",
+  "x-auth-token",
+  "authorization",
+  "proxy-authorization",
+  "cookie",
+  "set-cookie"
+];
+function normalizeKey(key) {
+  return String(key).toLowerCase().replace(/[-_]/g, "");
+}
+function redactKeyList(extra = []) {
+  return [...new Set([...DEFAULT_REDACT_KEYS, ...extra].map(normalizeKey))];
+}
+function isRedactedKey(key, redactKeys) {
+  return redactKeys.includes(normalizeKey(key));
+}
+
+// ../shared/src/trace.ts
+var import_node_async_hooks = require("async_hooks");
+var import_node_crypto = require("crypto");
+var TRACEPARENT_HEADER = "traceparent";
+var TRACESTATE_HEADER = "tracestate";
+var TRACE_ID_HEADER = "x-trace-id";
+var MAX_TRACESTATE_CHARS = 512;
+var ZERO_TRACE_ID = "0".repeat(32);
+var ZERO_SPAN_ID = "0".repeat(16);
+var TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(-.*)?$/;
+var TRACE_ID_RE = /^[0-9a-f]{32}$/;
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+function newTraceId() {
+  for (; ; ) {
+    const id = (0, import_node_crypto.randomBytes)(16).toString("hex");
+    if (id !== ZERO_TRACE_ID) return id;
+  }
+}
+function newSpanId() {
+  for (; ; ) {
+    const id = (0, import_node_crypto.randomBytes)(8).toString("hex");
+    if (id !== ZERO_SPAN_ID) return id;
+  }
+}
+function sha256Hex(value) {
+  return (0, import_node_crypto.createHash)("sha256").update(value, "utf8").digest("hex");
+}
+function toW3CTraceId(traceId) {
+  const lower = traceId.toLowerCase();
+  if (TRACE_ID_RE.test(lower) && lower !== ZERO_TRACE_ID) return lower;
+  if (UUID_RE.test(lower)) {
+    const hex = lower.replace(/-/g, "");
+    if (hex !== ZERO_TRACE_ID) return hex;
+  }
+  return sha256Hex(traceId).slice(0, 32);
+}
+function parseTraceparent(value) {
+  if (typeof value !== "string") return null;
+  const header = value.trim();
+  const match = TRACEPARENT_RE.exec(header);
+  if (!match) return null;
+  const [, version, traceId, parentId, flagsHex, rest] = match;
+  if (version === "ff") return null;
+  if (version === "00" && rest !== void 0) return null;
+  if (traceId === ZERO_TRACE_ID || parentId === ZERO_SPAN_ID) return null;
+  const flags = parseInt(flagsHex, 16);
+  return { version, traceId, parentId, flags, sampled: (flags & 1) === 1 };
+}
+var STORE_KEY = /* @__PURE__ */ Symbol.for("@fabbahiense/pulsar.trace-context.v1");
+function sharedStore() {
+  const g = globalThis;
+  let store = g[STORE_KEY];
+  if (!store) {
+    store = new import_node_async_hooks.AsyncLocalStorage();
+    g[STORE_KEY] = store;
+  }
+  return store;
+}
+var traceStore = sharedStore();
+function text(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function completeContext(init) {
+  const ctx = {
+    traceId: text(init?.traceId) ?? newTraceId(),
+    spanId: text(init?.spanId) ?? newSpanId(),
+    sampled: init?.sampled !== false
+  };
+  const parentSpanId = text(init?.parentSpanId);
+  if (parentSpanId) ctx.parentSpanId = parentSpanId;
+  const traceState = text(init?.traceState);
+  if (traceState) ctx.traceState = traceState;
+  const method = text(init?.method);
+  if (method) ctx.method = method;
+  const url = text(init?.url);
+  if (url) ctx.url = url;
+  return ctx;
+}
+function childContext(parent) {
+  if (!parent || !text(parent.traceId)) return completeContext(null);
+  const local = parent;
+  return completeContext({
+    traceId: parent.traceId,
+    parentSpanId: parent.spanId,
+    sampled: parent.sampled,
+    traceState: parent.traceState,
+    method: local.method,
+    url: local.url
+  });
+}
+function read(carrier, name) {
+  let value;
+  if (typeof carrier.get === "function") {
+    value = carrier.get(name);
+  } else {
+    const record = carrier;
+    value = record[name];
+    if (value === void 0) {
+      for (const key of Object.keys(record)) {
+        if (key.toLowerCase() === name) {
+          value = record[key];
+          break;
+        }
+      }
+    }
+  }
+  if (Array.isArray(value)) value = value.find((v) => typeof v === "string");
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function readTraceState(carrier) {
+  let raw;
+  if (typeof carrier.get === "function") {
+    raw = carrier.get(TRACESTATE_HEADER);
+  } else {
+    const record = carrier;
+    raw = record[TRACESTATE_HEADER];
+    if (raw === void 0) {
+      const key = Object.keys(record).find((k) => k.toLowerCase() === TRACESTATE_HEADER);
+      raw = key === void 0 ? void 0 : record[key];
+    }
+  }
+  const joined = Array.isArray(raw) ? raw.filter((v) => typeof v === "string").join(",") : raw;
+  if (typeof joined !== "string") return void 0;
+  const value = joined.trim();
+  return value.length > 0 && value.length <= MAX_TRACESTATE_CHARS ? value : void 0;
+}
+function extractTrace(carrier) {
+  if (typeof carrier !== "object" || carrier === null) return null;
+  try {
+    const source = carrier;
+    const legacy = read(source, TRACE_ID_HEADER);
+    const parent = parseTraceparent(read(source, TRACEPARENT_HEADER));
+    if (legacy !== void 0) {
+      if (parent && parent.traceId === toW3CTraceId(legacy)) {
+        return withTraceState({ traceId: legacy, spanId: parent.parentId, sampled: parent.sampled }, source);
+      }
+      return { traceId: legacy, sampled: true };
+    }
+    if (parent) return withTraceState({ traceId: parent.traceId, spanId: parent.parentId, sampled: parent.sampled }, source);
+    return null;
+  } catch {
+    return null;
+  }
+}
+function withTraceState(trace, carrier) {
+  const traceState = readTraceState(carrier);
+  if (traceState) trace.traceState = traceState;
+  return trace;
+}
+
+// src/middleware.ts
+var DEFAULT_SKIP_URLS = ["/health", "/metrics", "/favicon.ico"];
+var DEFAULT_MAX_BODY = 5e4;
+function pulsarRequestLogger(options) {
+  const logger = options.logger;
+  if (!logger) throw new Error("pulsarRequestLogger: options.logger is required");
+  const skipUrls = options.skipUrls ?? DEFAULT_SKIP_URLS;
+  const redactKeys = redactKeyList(options.redactKeys ?? []);
+  const maxBodySize = options.maxBodySize ?? DEFAULT_MAX_BODY;
+  const getUserId = options.getUserId ?? ((req) => req.user?.id);
+  const getLevel = options.getLevel ?? defaultLevel;
+  return function pulsarMw(req, res, next) {
+    const url = req.originalUrl || req.url;
+    const ctx = requestContext(req, url);
+    if (skipUrls.some((s) => url.includes(s))) return traceStore.run(ctx, next);
+    const startedAt = Date.now();
+    const capture = new BodyCapture(maxBodySize);
+    const originalWrite = res.write.bind(res);
+    const originalEnd = res.end.bind(res);
+    res.write = function(chunk, ...rest) {
+      capture.add(chunk, rest[0]);
+      return originalWrite(chunk, ...rest);
+    };
+    res.end = function(chunk, ...rest) {
+      capture.add(chunk, rest[0]);
+      return originalEnd(chunk, ...rest);
+    };
+    res.on("finish", () => traceStore.run(ctx, () => {
+      try {
+        const responseTime = Date.now() - startedAt;
+        const status = res.statusCode;
+        const level = getLevel(req, res);
+        const responseBody = readBuffer(capture, maxBodySize, getResponseContentType(res), redactKeys);
+        const payload = {
+          // Top level: becomes columns and filters
+          req: { method: req.method, url, id: req.id },
+          res: { statusCode: status },
+          responseTime,
+          // A request id set later (pino-http registered after this middleware) still wins, as it always has.
+          traceId: req.id || ctx.traceId,
+          // The request's span-end entry.
+          spanId: ctx.spanId,
+          ...ctx.parentSpanId ? { parentSpanId: ctx.parentSpanId } : {},
+          spanKind: "server",
+          // metadata: the sections of the side panel
+          metadata: trimUndefined({
+            requestBody: redactDeep(req.body, redactKeys),
+            responseBody,
+            requestHeaders: redactHeaders(req.headers, redactKeys),
+            responseHeaders: redactHeaders(res.getHeaders ? res.getHeaders() : {}, redactKeys),
+            query: isPopulatedObject(req.query) ? req.query : void 0,
+            params: isPopulatedObject(req.params) ? req.params : void 0,
+            userId: getUserId(req)
+          })
+        };
+        const msg = `${req.method} ${url} ${status}`;
+        logger[level](payload, msg);
+      } catch (err) {
+        if (typeof console !== "undefined") console.error("[pulsarRequestLogger] failed:", err);
+      }
+    }));
+    traceStore.run(ctx, next);
+  };
+}
+function requestContext(req, url) {
+  let parent = extractTrace(req.headers);
+  const id = req.id;
+  if (id !== void 0 && id !== null && id !== "") {
+    const traceId = String(id);
+    if (!parent || parent.traceId !== traceId) parent = { traceId, sampled: parent?.sampled ?? true };
+  }
+  const ctx = childContext(parent);
+  ctx.method = req.method;
+  ctx.url = url;
+  return ctx;
+}
+function defaultLevel(_req, res) {
+  if (res.statusCode >= 500) return "error";
+  if (res.statusCode >= 400) return "warn";
+  return "info";
+}
+function toBuffer(chunk, encoding) {
+  if (Buffer.isBuffer(chunk)) return chunk;
+  if (chunk instanceof Uint8Array) return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+  if (typeof chunk === "string") {
+    return typeof encoding === "string" && Buffer.isEncoding(encoding) ? Buffer.from(chunk, encoding) : Buffer.from(chunk);
+  }
+  try {
+    return Buffer.from(JSON.stringify(chunk));
+  } catch {
+    return Buffer.alloc(0);
+  }
+}
+var BodyCapture = class {
+  constructor(max) {
+    this.max = max;
+  }
+  max;
+  chunks = [];
+  kept = 0;
+  total = 0;
+  add(chunk, encoding) {
+    if (!chunk || typeof chunk === "function") return;
+    try {
+      const buf = toBuffer(chunk, encoding);
+      this.total += buf.length;
+      const room = this.max + 1 - this.kept;
+      if (room <= 0) return;
+      const part = Buffer.from(buf.length > room ? buf.subarray(0, room) : buf);
+      this.chunks.push(part);
+      this.kept += part.length;
+    } catch {
+    }
+  }
+  bytes() {
+    return Buffer.concat(this.chunks);
+  }
+};
+function readBuffer(capture, max, contentType, redactKeys) {
+  if (capture.total === 0) return void 0;
+  const buf = capture.bytes();
+  if (capture.total > max) {
+    return `[TRUNCATED ${capture.total}B > ${max}B] ${buf.subarray(0, max).toString("utf8")}\u2026`;
+  }
+  const raw = buf.toString("utf8");
+  const ct = contentType.toLowerCase();
+  if (ct.includes("application/json")) {
+    try {
+      return redactDeep(JSON.parse(raw), redactKeys);
+    } catch {
+      return raw;
+    }
+  }
+  return raw;
+}
+function getResponseContentType(res) {
+  if (!res.getHeaders) return "";
+  const headers = res.getHeaders();
+  const v = headers["content-type"] ?? headers["Content-Type"];
+  if (typeof v === "string") return v;
+  if (Array.isArray(v)) return v.join(", ");
+  return "";
+}
+function redactHeaders(headers, redactKeys) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (v === void 0 || v === null) continue;
+    out[k] = isRedactedKey(k, redactKeys) ? "[REDACTED]" : Array.isArray(v) ? v.join(", ") : String(v);
+  }
+  return out;
+}
+function redactDeep(value, redactKeys, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value === null || value === void 0) return value;
+  if (typeof value !== "object") return value;
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) return value.map((v) => redactDeep(v, redactKeys, seen));
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = isRedactedKey(k, redactKeys) ? "[REDACTED]" : redactDeep(v, redactKeys, seen);
+    }
+    return out;
+  } finally {
+    seen.delete(value);
+  }
+}
+function trimUndefined(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== void 0) out[k] = v;
+  }
+  return out;
+}
+function isPopulatedObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v) && Object.keys(v).length > 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  pulsarRequestLogger
+});

package/dist/middleware.d.cts

@@ -0,0 +1,70 @@
+/**
+ * Express middleware that logs every request to Pulsar with its full payload:
+ * one log per request, with method, URL, status, duration, headers, bodies,
+ * query and params (redacted and size-capped). Each request runs in its own
+ * span, continuing an inbound `x-trace-id` or W3C `traceparent`; with
+ * `pulsarMixin()` on the logger, every record logged during the request
+ * carries the span's ids.
+ *
+ * @example
+ * ```ts
+ * import pino from 'pino'
+ * import { pulsarMixin } from '@fabbahiense/pulsar-pino-transport'
+ * import { pulsarRequestLogger } from '@fabbahiense/pulsar-pino-transport/middleware'
+ *
+ * const logger = pino({
+ *   mixin: pulsarMixin(),
+ *   transport: {
+ *     target: '@fabbahiense/pulsar-pino-transport',
+ *     options: { url: process.env.PULSAR_URL, apiKey: process.env.PULSAR_API_KEY },
+ *   },
+ * })
+ *
+ * const app = express()
+ * app.use(express.json())
+ * app.use(pulsarRequestLogger({ logger }))
+ * ```
+ */
+interface PinoLikeLogger {
+    info: (obj: unknown, msg?: string) => void;
+    warn: (obj: unknown, msg?: string) => void;
+    error: (obj: unknown, msg?: string) => void;
+}
+interface PulsarRequestLoggerOptions {
+    /** Your pino logger (with the Pulsar transport configured). */
+    logger: PinoLikeLogger;
+    /** URL substrings that must NOT produce a log. Default: /health, /metrics, /favicon.ico */
+    skipUrls?: string[];
+    /** Extra keys to redact in headers and bodies, on top of the defaults (passwords, tokens, secrets, API keys, cookies, auth headers). Matching ignores case, `-` and `_`, so `apiKey` also matches `api_key` and `api-key`. */
+    redactKeys?: string[];
+    /** Max bytes kept per request/response body; bigger bodies are truncated. Default: 50000 (50 KB) */
+    maxBodySize?: number;
+    /** Extracts the user id from the request, sent as `metadata.userId`. */
+    getUserId?: (req: ExpressLikeRequest) => string | undefined;
+    /** Overrides the level (default: 5xx=error, 4xx=warn, otherwise info). */
+    getLevel?: (req: ExpressLikeRequest, res: ExpressLikeResponse) => 'info' | 'warn' | 'error';
+}
+interface ExpressLikeRequest {
+    method: string;
+    url: string;
+    originalUrl?: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    query?: Record<string, unknown>;
+    params?: Record<string, unknown>;
+    id?: string;
+    user?: {
+        id?: string;
+    };
+    [key: string]: unknown;
+}
+interface ExpressLikeResponse {
+    statusCode: number;
+    write: (...args: unknown[]) => boolean;
+    end: (...args: unknown[]) => unknown;
+    getHeaders?: () => Record<string, string | string[] | number | undefined>;
+    on: (event: string, handler: () => void) => void;
+}
+declare function pulsarRequestLogger(options: PulsarRequestLoggerOptions): (req: ExpressLikeRequest, res: ExpressLikeResponse, next: () => void) => void;
+
+export { type ExpressLikeRequest, type ExpressLikeResponse, type PinoLikeLogger, type PulsarRequestLoggerOptions, pulsarRequestLogger };

package/dist/middleware.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Express middleware that logs every request to Pulsar with its full payload:
+ * one log per request, with method, URL, status, duration, headers, bodies,
+ * query and params (redacted and size-capped). Each request runs in its own
+ * span, continuing an inbound `x-trace-id` or W3C `traceparent`; with
+ * `pulsarMixin()` on the logger, every record logged during the request
+ * carries the span's ids.
+ *
+ * @example
+ * ```ts
+ * import pino from 'pino'
+ * import { pulsarMixin } from '@fabbahiense/pulsar-pino-transport'
+ * import { pulsarRequestLogger } from '@fabbahiense/pulsar-pino-transport/middleware'
+ *
+ * const logger = pino({
+ *   mixin: pulsarMixin(),
+ *   transport: {
+ *     target: '@fabbahiense/pulsar-pino-transport',
+ *     options: { url: process.env.PULSAR_URL, apiKey: process.env.PULSAR_API_KEY },
+ *   },
+ * })
+ *
+ * const app = express()
+ * app.use(express.json())
+ * app.use(pulsarRequestLogger({ logger }))
+ * ```
+ */
+interface PinoLikeLogger {
+    info: (obj: unknown, msg?: string) => void;
+    warn: (obj: unknown, msg?: string) => void;
+    error: (obj: unknown, msg?: string) => void;
+}
+interface PulsarRequestLoggerOptions {
+    /** Your pino logger (with the Pulsar transport configured). */
+    logger: PinoLikeLogger;
+    /** URL substrings that must NOT produce a log. Default: /health, /metrics, /favicon.ico */
+    skipUrls?: string[];
+    /** Extra keys to redact in headers and bodies, on top of the defaults (passwords, tokens, secrets, API keys, cookies, auth headers). Matching ignores case, `-` and `_`, so `apiKey` also matches `api_key` and `api-key`. */
+    redactKeys?: string[];
+    /** Max bytes kept per request/response body; bigger bodies are truncated. Default: 50000 (50 KB) */
+    maxBodySize?: number;
+    /** Extracts the user id from the request, sent as `metadata.userId`. */
+    getUserId?: (req: ExpressLikeRequest) => string | undefined;
+    /** Overrides the level (default: 5xx=error, 4xx=warn, otherwise info). */
+    getLevel?: (req: ExpressLikeRequest, res: ExpressLikeResponse) => 'info' | 'warn' | 'error';
+}
+interface ExpressLikeRequest {
+    method: string;
+    url: string;
+    originalUrl?: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    query?: Record<string, unknown>;
+    params?: Record<string, unknown>;
+    id?: string;
+    user?: {
+        id?: string;
+    };
+    [key: string]: unknown;
+}
+interface ExpressLikeResponse {
+    statusCode: number;
+    write: (...args: unknown[]) => boolean;
+    end: (...args: unknown[]) => unknown;
+    getHeaders?: () => Record<string, string | string[] | number | undefined>;
+    on: (event: string, handler: () => void) => void;
+}
+declare function pulsarRequestLogger(options: PulsarRequestLoggerOptions): (req: ExpressLikeRequest, res: ExpressLikeResponse, next: () => void) => void;
+
+export { type ExpressLikeRequest, type ExpressLikeResponse, type PinoLikeLogger, type PulsarRequestLoggerOptions, pulsarRequestLogger };