logquill 0.2.0 → 0.3.0

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { createHash } from 'crypto';
 import { gzipSync } from 'zlib';
 import { mkdirSync, openSync, writeSync, fstatSync, closeSync, existsSync, unlinkSync, renameSync } from 'fs';
 import { dirname } from 'path';
@@ -58,6 +59,17 @@ var JSONFormatter = class {
   }
 };
 
+// src/core/plugin.ts
+var FunctionPlugin = class {
+  func;
+  constructor(func) {
+    this.func = func;
+  }
+  beforeLog(record) {
+    return this.func(record);
+  }
+};
+
 // src/plugins/context-plugin.ts
 var ContextPlugin = class {
   context;
@@ -87,19 +99,409 @@ var RedactPlugin = class {
   }
 };
 
+// src/plugins/pii-redact-plugin.ts
+var DEFAULT_PII_PATTERNS = {
+  email: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+  ssn: /\b\d{3}-\d{2}-\d{4}\b/g,
+  creditCard: /\b(?:\d[ -]?){13,16}\b/g,
+  phone: /\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g
+};
+var MAX_DEPTH = 50;
+var PIIRedactPlugin = class {
+  patterns;
+  replacement;
+  constructor(options = {}) {
+    this.patterns = options.patterns ?? DEFAULT_PII_PATTERNS;
+    this.replacement = options.replacement ?? "***";
+  }
+  beforeLog(record) {
+    return { ...record, meta: this.redactValue(record.meta, /* @__PURE__ */ new Set(), 0) };
+  }
+  redactValue(value, seen, depth) {
+    if (depth > MAX_DEPTH) {
+      return value;
+    }
+    if (typeof value === "string") {
+      return this.redactText(value);
+    }
+    if (Array.isArray(value)) {
+      if (seen.has(value)) {
+        return value;
+      }
+      const nextSeen = new Set(seen).add(value);
+      return value.map((entry) => this.redactValue(entry, nextSeen, depth + 1));
+    }
+    if (value !== null && typeof value === "object") {
+      if (seen.has(value)) {
+        return value;
+      }
+      const nextSeen = new Set(seen).add(value);
+      const result = {};
+      for (const [key, entryValue] of Object.entries(value)) {
+        result[key] = this.redactValue(entryValue, nextSeen, depth + 1);
+      }
+      return result;
+    }
+    return value;
+  }
+  redactText(text) {
+    let redacted = text;
+    for (const pattern of Object.values(this.patterns)) {
+      const global = pattern.global ? pattern : new RegExp(pattern.source, `${pattern.flags}g`);
+      redacted = redacted.replace(global, this.replacement);
+    }
+    return redacted;
+  }
+};
+
 // src/plugins/sampling-plugin.ts
 var SamplingPlugin = class {
   rate;
+  traceKey;
+  elevateAt;
+  transports;
+  maxBufferedRecords;
+  maxTraces;
   rng;
+  buffer = /* @__PURE__ */ new Map();
+  bufferedCount = 0;
+  elevated = /* @__PURE__ */ new Set();
   constructor(rate, options = {}) {
     if (rate < 0 || rate > 1) {
       throw new Error(`rate must be between 0 and 1, got ${String(rate)}`);
     }
     this.rate = rate;
     this.rng = options.rng ?? Math.random;
+    this.traceKey = options.traceKey ?? "traceId";
+    this.elevateAt = parseLevel(options.elevateAt ?? 40 /* ERROR */);
+    this.transports = options.transports;
+    this.maxBufferedRecords = options.maxBufferedRecords ?? 1e3;
+    this.maxTraces = options.maxTraces ?? 200;
   }
   beforeLog(record) {
-    return this.rng() < this.rate ? record : null;
+    const transports = this.transports;
+    if (transports === void 0) {
+      return this.rng() < this.rate ? record : null;
+    }
+    const traceId = record.meta[this.traceKey];
+    if (traceId !== void 0 && this.elevated.has(traceId)) {
+      return record;
+    }
+    const keep = this.rng() < this.rate;
+    const reachedElevateLevel = parseLevel(record.level) >= this.elevateAt;
+    if (traceId !== void 0 && reachedElevateLevel) {
+      this.elevate(traceId, transports);
+      return record;
+    }
+    if (keep) {
+      return record;
+    }
+    if (traceId !== void 0) {
+      this.bufferRecord(traceId, record);
+    }
+    return null;
+  }
+  elevate(traceId, transports) {
+    this.elevated.add(traceId);
+    const buffered = this.buffer.get(traceId) ?? [];
+    this.buffer.delete(traceId);
+    this.bufferedCount -= buffered.length;
+    for (const bufferedRecord of buffered) {
+      for (const transport of transports) {
+        transport.write(transport.format(bufferedRecord), bufferedRecord);
+      }
+    }
+  }
+  bufferRecord(traceId, record) {
+    let records = this.buffer.get(traceId);
+    if (records) {
+      this.buffer.delete(traceId);
+      this.buffer.set(traceId, records);
+    } else {
+      if (this.buffer.size >= this.maxTraces) {
+        this.evictOldestTrace();
+      }
+      records = [];
+      this.buffer.set(traceId, records);
+    }
+    records.push(record);
+    this.bufferedCount += 1;
+    while (this.bufferedCount > this.maxBufferedRecords && this.buffer.size > 0) {
+      this.evictOldestTrace();
+    }
+  }
+  evictOldestTrace() {
+    const oldest = this.buffer.entries().next();
+    if (oldest.done) {
+      return;
+    }
+    const [oldestKey, oldestRecords] = oldest.value;
+    this.buffer.delete(oldestKey);
+    this.bufferedCount -= oldestRecords.length;
+  }
+};
+var GENESIS_HASH = "0".repeat(64);
+function canonicalStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => canonicalStringify(entry)).join(",")}]`;
+  }
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${canonicalStringify(entryValue)}`).join(",")}}`;
+  }
+  if (value === void 0) {
+    return "null";
+  }
+  return JSON.stringify(value);
+}
+function computeHash(record, prevHash) {
+  const restMeta = Object.fromEntries(Object.entries(record.meta).filter(([key]) => key !== "hash" && key !== "prevHash"));
+  const payload = canonicalStringify({
+    timestamp: record.timestamp,
+    level: record.level,
+    logger: record.logger,
+    message: record.message,
+    meta: restMeta
+  });
+  return createHash("sha256").update(`${prevHash}${payload}`).digest("hex");
+}
+var TamperEvidentPlugin = class {
+  genesisHash;
+  lastHash;
+  constructor(options = {}) {
+    this.genesisHash = options.genesisHash ?? GENESIS_HASH;
+    this.lastHash = this.genesisHash;
+  }
+  beforeLog(record) {
+    const prevHash = this.lastHash;
+    const digest = computeHash(record, prevHash);
+    const next = { ...record, meta: { ...record.meta, prevHash, hash: digest } };
+    this.lastHash = digest;
+    return next;
+  }
+  /**
+   * Returns `true` iff every record's hash matches its content plus the
+   * previous record's hash, in the given order. Returns `false` at the
+   * first break in the chain (an edited, removed, or reordered record).
+   */
+  static verifyChain(records, options = {}) {
+    let prevHash = options.genesisHash ?? GENESIS_HASH;
+    for (const record of records) {
+      const storedHash = record.meta.hash;
+      const storedPrevHash = record.meta.prevHash;
+      if (typeof storedHash !== "string" || storedPrevHash !== prevHash) {
+        return false;
+      }
+      if (computeHash(record, prevHash) !== storedHash) {
+        return false;
+      }
+      prevHash = storedHash;
+    }
+    return true;
+  }
+};
+
+// src/plugins/alerting-plugin.ts
+function defaultDedupeKey(record) {
+  return `${record.level}:${record.logger}:${record.message}`;
+}
+var AlertingPlugin = class {
+  threshold;
+  dedupeWindowMs;
+  maxTrackedKeys;
+  dedupeKeyFn;
+  windows = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.threshold = parseLevel(options.threshold ?? 40 /* ERROR */);
+    this.dedupeWindowMs = options.dedupeWindowMs ?? 3e5;
+    this.dedupeKeyFn = options.dedupeKey ?? defaultDedupeKey;
+    this.maxTrackedKeys = options.maxTrackedKeys ?? 500;
+  }
+  afterLog(record) {
+    if (parseLevel(record.level) < this.threshold) {
+      return;
+    }
+    const key = this.dedupeKeyFn(record);
+    const existing = this.windows.get(key);
+    if (existing) {
+      existing.count += 1;
+      return;
+    }
+    if (this.windows.size >= this.maxTrackedKeys) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      this.flush(key);
+    }, this.dedupeWindowMs);
+    timer.unref();
+    this.windows.set(key, { record, count: 1, timer });
+    this.safeSend(record, 1);
+  }
+  flush(key) {
+    const window = this.windows.get(key);
+    this.windows.delete(key);
+    if (!window || window.count <= 1) {
+      return;
+    }
+    this.safeSend(window.record, window.count);
+  }
+  safeSend(record, occurrences) {
+    Promise.resolve().then(() => this.sendAlert(record, occurrences)).catch((error) => {
+      try {
+        this.onError?.(error, record);
+      } catch {
+      }
+    });
+  }
+  /** Cancel any pending dedupe-window timers. Call on logger shutdown. */
+  close() {
+    const windows = [...this.windows.values()];
+    this.windows.clear();
+    for (const window of windows) {
+      clearTimeout(window.timer);
+    }
+  }
+};
+
+// src/plugins/slack-alert-plugin.ts
+async function fetchSlackSender(webhookUrl, body) {
+  const response = await fetch(webhookUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body
+  });
+  if (!response.ok) {
+    throw new Error(
+      `SlackAlertPlugin: webhook returned HTTP ${String(response.status)} \u2014 check the webhook URL is still valid in Slack's app config`
+    );
+  }
+}
+function formatMessage(record, occurrences) {
+  const suffix = occurrences > 1 ? ` (x${String(occurrences)})` : "";
+  return `[${record.level}] ${record.logger}: ${record.message}${suffix}`;
+}
+var SlackAlertPlugin = class extends AlertingPlugin {
+  webhookUrl;
+  sender;
+  constructor(webhookUrl, options = {}) {
+    super(options);
+    this.webhookUrl = webhookUrl;
+    this.sender = options.sender ?? fetchSlackSender;
+  }
+  async sendAlert(record, occurrences) {
+    const body = JSON.stringify({ text: formatMessage(record, occurrences) });
+    await this.sender(this.webhookUrl, body);
+  }
+};
+
+// src/plugins/pagerduty-alert-plugin.ts
+var ENDPOINT = "https://events.pagerduty.com/v2/enqueue";
+var SEVERITY = { ERROR: "error", FATAL: "critical" };
+async function fetchPagerDutySender(body) {
+  const response = await fetch(ENDPOINT, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body
+  });
+  if (!response.ok) {
+    throw new Error(
+      `PagerDutyAlertPlugin: Events API returned HTTP ${String(response.status)} \u2014 check the routing key is a valid Events API v2 integration key`
+    );
+  }
+}
+var PagerDutyAlertPlugin = class extends AlertingPlugin {
+  routingKey;
+  sender;
+  constructor(routingKey, options = {}) {
+    super(options);
+    this.routingKey = routingKey;
+    this.sender = options.sender ?? fetchPagerDutySender;
+  }
+  async sendAlert(record, occurrences) {
+    let summary = `${record.logger}: ${record.message}`;
+    if (occurrences > 1) {
+      summary += ` (x${String(occurrences)})`;
+    }
+    const body = JSON.stringify({
+      routing_key: this.routingKey,
+      event_action: "trigger",
+      payload: {
+        summary,
+        severity: SEVERITY[record.level] ?? "error",
+        source: record.logger,
+        timestamp: record.timestamp,
+        custom_details: { occurrences, ...record.meta }
+      }
+    });
+    await this.sender(body);
+  }
+};
+
+// src/plugins/email-alert-plugin.ts
+var EmailAlertPlugin = class extends AlertingPlugin {
+  smtpHost;
+  smtpPort;
+  fromAddr;
+  toAddrs;
+  username;
+  password;
+  useTls;
+  injectedSender;
+  transporter;
+  constructor(options) {
+    super(options);
+    this.smtpHost = options.smtpHost;
+    this.smtpPort = options.smtpPort;
+    this.fromAddr = options.fromAddr;
+    this.toAddrs = options.toAddrs;
+    this.username = options.username;
+    this.password = options.password;
+    this.useTls = options.useTls ?? true;
+    this.injectedSender = options.sender;
+  }
+  async sendAlert(record, occurrences) {
+    let subject = `[${record.level}] ${record.logger}`;
+    if (occurrences > 1) {
+      subject += ` (x${String(occurrences)})`;
+    }
+    const text = [
+      record.message,
+      "",
+      `occurrences: ${String(occurrences)}`,
+      `timestamp: ${record.timestamp}`,
+      `meta: ${JSON.stringify(record.meta)}`
+    ].join("\n");
+    const message = { from: this.fromAddr, to: this.toAddrs, subject, text };
+    if (this.injectedSender) {
+      await this.injectedSender(message);
+      return;
+    }
+    const transporter = this.transporter ?? await this.importTransporter();
+    await transporter.sendMail({ from: message.from, to: message.to.join(", "), subject: message.subject, text: message.text });
+  }
+  async importTransporter() {
+    let createTransport;
+    try {
+      const moduleName = "nodemailer";
+      const mod = await import(moduleName);
+      const resolved = mod.default?.createTransport ?? mod.createTransport;
+      if (!resolved) {
+        throw new Error("no createTransport export found");
+      }
+      createTransport = resolved;
+    } catch {
+      throw new Error(
+        "EmailAlertPlugin: install `nodemailer` to use this plugin without providing a `sender` \u2014 `npm install nodemailer`"
+      );
+    }
+    this.transporter = createTransport({
+      host: this.smtpHost,
+      port: this.smtpPort,
+      secure: false,
+      requireTLS: this.useTls,
+      auth: this.username && this.password ? { user: this.username, pass: this.password } : void 0
+    });
+    return this.transporter;
   }
 };
 
@@ -1318,7 +1720,10 @@ var Logger = class _Logger {
     this.name = name;
     this.currentLevel = parseLevel(options.level ?? 20 /* INFO */);
     this.transports = options.transports ? [...options.transports] : [];
-    this.plugins = options.plugins ? [...options.plugins] : [];
+    this.plugins = [];
+    for (const plugin of options.plugins ?? []) {
+      this.use(plugin);
+    }
     this.baseMeta = options.meta ? { ...options.meta } : {};
   }
   get level() {
@@ -1327,9 +1732,14 @@ var Logger = class _Logger {
   setLevel(level) {
     this.currentLevel = parseLevel(level);
   }
-  /** Register a plugin. Returns `this` so calls can be chained. */
+  /**
+   * Register a plugin, or a plain `beforeLog`-style function. A function is
+   * wrapped internally as an anonymous `Plugin` (`FunctionPlugin`) — the
+   * same middleware ergonomics as Express/Koa, without needing to read the
+   * `Plugin` interface first. Returns `this` so calls can be chained.
+   */
   use(plugin) {
-    this.plugins.push(plugin);
+    this.plugins.push(typeof plugin === "function" ? new FunctionPlugin(plugin) : plugin);
     return this;
   }
   /** Close every attached transport. Call on shutdown to flush buffered writes. */
@@ -1409,8 +1819,8 @@ var Logger = class _Logger {
 };
 
 // src/index.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 
-export { AppInsightsTransport, BaseQueueTransport, BaseSQLTransport, BatchingTransport, CloudLoggingTransport, CloudWatchTransport, CollectingTransport, ConsoleTransport, ContextPlugin, DEFAULT_REDACTED_KEYS, DatadogTransport, DynamoDBTransport, ElasticsearchTransport, FileTransport, HTTPTransport, JSONFormatter, KafkaTransport, Level, Logger, MongoDBTransport, MySQLTransport, NewRelicTransport, PostgresTransport, PubSubTransport, RabbitMQTransport, RedactPlugin, RedisTransport, SQLiteTransport, SQSTransport, SamplingPlugin, Transport, VERSION, createRecord, levelName, parseLevel, utcTimestamp };
+export { AlertingPlugin, AppInsightsTransport, BaseQueueTransport, BaseSQLTransport, BatchingTransport, CloudLoggingTransport, CloudWatchTransport, CollectingTransport, ConsoleTransport, ContextPlugin, DEFAULT_PII_PATTERNS, DEFAULT_REDACTED_KEYS, DatadogTransport, DynamoDBTransport, ElasticsearchTransport, EmailAlertPlugin, FileTransport, FunctionPlugin, GENESIS_HASH, HTTPTransport, JSONFormatter, KafkaTransport, Level, Logger, MongoDBTransport, MySQLTransport, NewRelicTransport, PIIRedactPlugin, PagerDutyAlertPlugin, PostgresTransport, PubSubTransport, RabbitMQTransport, RedactPlugin, RedisTransport, SQLiteTransport, SQSTransport, SamplingPlugin, SlackAlertPlugin, TamperEvidentPlugin, Transport, VERSION, createRecord, levelName, parseLevel, utcTimestamp };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map