limitforge 0.0.0-stage → 8.0.0

package/src/telemetry/prometheusExporter.js

@@ -0,0 +1,131 @@
+import {
+  METRIC_TYPE,
+  METRIC_NAMES,
+  METRIC_METADATA
+} from './telemetryEvents.js';
+import { defaultMetricsCollector } from './metricsCollector.js';
+
+export function escapeLabelValue(value) {
+  return String(value)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n');
+}
+
+export function escapeHelpString(help) {
+  return String(help)
+    .replace(/\\/g, '\\\\')
+    .replace(/\n/g, '\\n');
+}
+
+export function formatLabels(labels = {}, additionalLabels = {}) {
+  const merged = { ...labels, ...additionalLabels };
+  const entries = Object.entries(merged).filter(
+    ([, v]) => v !== undefined && v !== null
+  );
+
+  if (entries.length === 0) {
+    return '';
+  }
+
+  entries.sort(([a], [b]) => a.localeCompare(b));
+
+  const formatted = entries
+    .map(([k, v]) => `${k}="${escapeLabelValue(v)}"`)
+    .join(',');
+
+  return `{${formatted}}`;
+}
+
+export function formatPrometheusMetrics(snapshot = {}) {
+  const lines = [];
+  const { counters = {}, gauges = {}, histograms = {} } = snapshot;
+
+  // format counters
+  for (const [name, records] of Object.entries(counters)) {
+    if (!Array.isArray(records) || records.length === 0) continue;
+
+    const meta = METRIC_METADATA[name] || {
+      type: METRIC_TYPE.COUNTER,
+      help: `Counter metric ${name}`
+    };
+
+    lines.push(`# HELP ${name} ${escapeHelpString(meta.help)}`);
+    lines.push(`# TYPE ${name} ${meta.type}`);
+
+    for (const record of records) {
+      const labelStr = formatLabels(record.labels);
+      lines.push(`${name}${labelStr} ${record.value}`);
+    }
+  }
+
+  // format gauges
+  for (const [name, records] of Object.entries(gauges)) {
+    if (!Array.isArray(records) || records.length === 0) continue;
+
+    const meta = METRIC_METADATA[name] || {
+      type: METRIC_TYPE.GAUGE,
+      help: `Gauge metric ${name}`
+    };
+
+    lines.push(`# HELP ${name} ${escapeHelpString(meta.help)}`);
+    lines.push(`# TYPE ${name} ${meta.type}`);
+
+    for (const record of records) {
+      const labelStr = formatLabels(record.labels);
+      lines.push(`${name}${labelStr} ${record.value}`);
+    }
+  }
+
+  // format histograms
+  for (const [name, records] of Object.entries(histograms)) {
+    if (!Array.isArray(records) || records.length === 0) continue;
+
+    const meta = METRIC_METADATA[name] || {
+      type: METRIC_TYPE.HISTOGRAM,
+      help: `Histogram metric ${name}`
+    };
+
+    lines.push(`# HELP ${name} ${escapeHelpString(meta.help)}`);
+    lines.push(`# TYPE ${name} ${meta.type}`);
+
+    for (const record of records) {
+      const baseLabels = record.labels || {};
+
+      // buckets
+      if (Array.isArray(record.buckets)) {
+        for (const bucket of record.buckets) {
+          const bucketLabels = formatLabels(baseLabels, { le: bucket.le });
+          lines.push(`${name}_bucket${bucketLabels} ${bucket.count}`);
+        }
+      }
+
+      // inf bucket matches total count
+      const infLabels = formatLabels(baseLabels, { le: '+Inf' });
+      lines.push(`${name}_bucket${infLabels} ${record.count}`);
+
+      // sum and count
+      const sumLabels = formatLabels(baseLabels);
+      lines.push(`${name}_sum${sumLabels} ${record.sum}`);
+      lines.push(`${name}_count${sumLabels} ${record.count}`);
+    }
+  }
+
+  return lines.length > 0 ? `${lines.join('\n')}\n` : '';
+}
+
+export function createPrometheusExporter(options = {}) {
+  const collector = options.collector || options.metricsCollector || defaultMetricsCollector;
+
+  return function prometheusExporterMiddleware(req, res, next) {
+    try {
+      const snapshot = collector.getSnapshot();
+      const output = formatPrometheusMetrics(snapshot);
+
+      res.setHeader('Content-Type', 'text/plain; version=0.0.4; charset=utf-8');
+      res.status(200).end(output);
+    } catch (err) {
+      next(err);
+    }
+  };
+}

package/src/telemetry/telemetryEvents.js

@@ -0,0 +1,58 @@
+
+
+export const METRIC_TYPE = Object.freeze({
+  COUNTER: 'counter',
+  GAUGE: 'gauge',
+  HISTOGRAM: 'histogram'
+});
+
+export const METRIC_NAMES = Object.freeze({
+  REQUESTS_TOTAL: 'smartrate_requests_total',
+  STORE_ERRORS_TOTAL: 'smartrate_store_errors_total',
+  DEGRADED_REQUESTS_TOTAL: 'smartrate_degraded_requests_total',
+  CIRCUIT_BREAKER_STATE: 'smartrate_circuit_breaker_state',
+  STORE_DURATION_SECONDS: 'smartrate_store_duration_seconds'
+});
+
+export const CIRCUIT_STATE_GAUGE_VALUES = Object.freeze({
+  CLOSED: 0,
+  HALF_OPEN: 1,
+  OPEN: 2
+});
+
+export const DEFAULT_STORE_DURATION_BUCKETS = Object.freeze([
+  0.0005,
+  0.001,
+  0.0025,
+  0.005,
+  0.01,
+  0.025,
+  0.05,
+  0.1,
+  0.25,
+  0.5,
+  1.0
+]);
+
+export const METRIC_METADATA = Object.freeze({
+  [METRIC_NAMES.REQUESTS_TOTAL]: {
+    type: METRIC_TYPE.COUNTER,
+    help: 'Total number of rate limiter requests evaluated.'
+  },
+  [METRIC_NAMES.STORE_ERRORS_TOTAL]: {
+    type: METRIC_TYPE.COUNTER,
+    help: 'Total number of store or timeout errors encountered.'
+  },
+  [METRIC_NAMES.DEGRADED_REQUESTS_TOTAL]: {
+    type: METRIC_TYPE.COUNTER,
+    help: 'Total number of requests handled under degraded or fallback conditions.'
+  },
+  [METRIC_NAMES.CIRCUIT_BREAKER_STATE]: {
+    type: METRIC_TYPE.GAUGE,
+    help: 'Current state of the rate limiter circuit breaker (0=CLOSED, 1=HALF_OPEN, 2=OPEN).'
+  },
+  [METRIC_NAMES.STORE_DURATION_SECONDS]: {
+    type: METRIC_TYPE.HISTOGRAM,
+    help: 'Duration of rate limiter store operations in seconds.'
+  }
+});

package/src/utils/keyBuilder.js

@@ -0,0 +1,41 @@
+import crypto from 'node:crypto';
+
+export const MAX_IDENTIFIER_LENGTH = 256;
+
+export function buildRateLimitKey({
+  prefix = 'smartrate',
+  algorithm = 'fixed-window',
+  method = 'GET',
+  route = '/',
+  clientIdentifier = '127.0.0.1',
+  hashClientIdentifier = false
+} = {}) {
+  const cleanMethod = (method || 'GET').toUpperCase();
+  const cleanRoute = (route || '/').split('?')[0] || '/';
+  const rawId = clientIdentifier && String(clientIdentifier).trim()
+    ? String(clientIdentifier).trim()
+    : '127.0.0.1';
+
+  let cleanId;
+  if (hashClientIdentifier === true) {
+    cleanId = crypto.createHash('sha256').update(rawId).digest('hex');
+  } else if (typeof hashClientIdentifier === 'function') {
+    cleanId = String(hashClientIdentifier(rawId) || rawId);
+    if (cleanId.length > MAX_IDENTIFIER_LENGTH) {
+      const digest = crypto.createHash('sha256').update(rawId).digest('hex');
+      cleanId = `${cleanId.slice(0, MAX_IDENTIFIER_LENGTH - digest.length - 1)}:${digest}`;
+    }
+  } else if (rawId.length > MAX_IDENTIFIER_LENGTH) {
+    cleanId = crypto.createHash('sha256').update(rawId).digest('hex');
+  } else {
+    cleanId = rawId;
+  }
+
+  if (algorithm && algorithm !== 'fixed-window') {
+    return `${prefix}:${algorithm}:${cleanMethod}:${cleanRoute}:${cleanId}`;
+  }
+
+  return `${prefix}:${cleanMethod}:${cleanRoute}:${cleanId}`;
+}
+
+export default buildRateLimitKey;

package/src/utils/routeNormalizer.js

@@ -0,0 +1,49 @@
+const UUID_REGEX = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+const NUMERIC_SEGMENT_REGEX = /\/\d+(?=\/|$)/g;
+const LONG_HEX_HASH_REGEX = /\/[0-9a-fA-F]{16,}(?=\/|$)/g;
+const ULID_REGEX = /\/[0-7][0-9A-HJKMNP-TV-Z]{25}(?=\/|$)/gi;
+const CUID_REGEX = /\/c[0-9a-z]{24}(?=\/|$)/gi;
+
+export function sanitizePath(rawPath) {
+  if (!rawPath || typeof rawPath !== 'string') {
+    return '/';
+  }
+
+  const cleanPath = rawPath.split('?')[0];
+  const sanitized = cleanPath
+    .replace(UUID_REGEX, ':id')
+    .replace(ULID_REGEX, '/:id')
+    .replace(CUID_REGEX, '/:id')
+    .replace(NUMERIC_SEGMENT_REGEX, '/:id')
+    .replace(LONG_HEX_HASH_REGEX, '/:id')
+    .replace(/\/+/g, '/');
+
+  return sanitized || '/';
+}
+
+export function normalizeRoute(req, customNormalizer) {
+  if (typeof customNormalizer === 'function') {
+    try {
+      const custom = customNormalizer(req);
+      if (typeof custom === 'string' && custom.length > 0) {
+        return sanitizePath(custom);
+      }
+    } catch {
+      // ignore normalizer error and fallback
+    }
+  }
+
+  if (!req || typeof req !== 'object') {
+    return '/';
+  }
+
+  if (req.route && typeof req.route.path === 'string') {
+    const base = req.baseUrl || '';
+    const route = req.route.path;
+    const combined = `${base}${route}`.replace(/\/+/g, '/');
+    return combined || '/';
+  }
+
+  const fallbackPath = `${req.baseUrl || ''}${req.path || req.originalUrl || '/'}`;
+  return sanitizePath(fallbackPath);
+}