limitforge 0.0.0-stage → 8.0.1

package/src/stores/redisStore.js

@@ -0,0 +1,213 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const FIXED_WINDOW_LUA = fs.readFileSync(path.join(__dirname, '../scripts/fixedWindow.lua'), 'utf-8');
+const SLIDING_WINDOW_LUA = fs.readFileSync(path.join(__dirname, '../scripts/slidingWindow.lua'), 'utf-8');
+const TOKEN_BUCKET_LUA = fs.readFileSync(path.join(__dirname, '../scripts/tokenBucket.lua'), 'utf-8');
+
+export class RedisStore {
+  constructor(options) {
+    if (!options || typeof options !== 'object') {
+      throw new TypeError('SmartRate: RedisStore options must be an object.');
+    }
+
+    if (!options.client || typeof options.client !== 'object') {
+      throw new TypeError(
+        'SmartRate: RedisStore requires a pre-connected Redis client instance (options.client). ' +
+        'Please create and connect a Redis client in your application and inject it here.'
+      );
+    }
+
+    if (typeof options.client.eval !== 'function' && typeof options.client.sendCommand !== 'function') {
+      throw new TypeError('SmartRate: Injected Redis client does not appear to be a valid Redis client instance.');
+    }
+
+    this.client = options.client;
+    this.script = FIXED_WINDOW_LUA;
+    this.fixedScript = FIXED_WINDOW_LUA;
+    this.slidingScript = SLIDING_WINDOW_LUA;
+    this.tokenBucketScript = TOKEN_BUCKET_LUA;
+  }
+
+  async _evalFixedScript(key, windowMs) {
+    if (typeof this.client.eval === 'function') {
+      return this.client.eval(this.fixedScript, {
+        keys: [key],
+        arguments: [String(windowMs)]
+      });
+    }
+
+    return this.client.sendCommand(['EVAL', this.fixedScript, '1', key, String(windowMs)]);
+  }
+
+  async _evalSlidingScript(key, now, windowMs, limit, member) {
+    if (typeof this.client.eval === 'function') {
+      return this.client.eval(this.slidingScript, {
+        keys: [key],
+        arguments: [String(now), String(windowMs), String(limit), member]
+      });
+    }
+
+    return this.client.sendCommand([
+      'EVAL',
+      this.slidingScript,
+      '1',
+      key,
+      String(now),
+      String(windowMs),
+      String(limit),
+      member
+    ]);
+  }
+
+  async _evalTokenBucketScript(key, now, capacity, refillRate, refillIntervalMs = 1000, cost = 1) {
+    if (typeof this.client.eval === 'function') {
+      return this.client.eval(this.tokenBucketScript, {
+        keys: [key],
+        arguments: [String(now), String(capacity), String(refillRate), String(refillIntervalMs), String(cost)]
+      });
+    }
+
+    return this.client.sendCommand([
+      'EVAL',
+      this.tokenBucketScript,
+      '1',
+      key,
+      String(now),
+      String(capacity),
+      String(refillRate),
+      String(refillIntervalMs),
+      String(cost)
+    ]);
+  }
+
+  async consume({
+    key,
+    limit,
+    windowMs,
+    algorithm = 'fixed-window',
+    capacity,
+    refillRate,
+    refillIntervalMs = 1000,
+    cost = 1,
+    now = Date.now()
+  }) {
+    if (typeof key !== 'string' || key.trim().length === 0) {
+      throw new TypeError("SmartRate: RedisStore 'key' must be a non-empty string.");
+    }
+
+    if (algorithm === 'token-bucket') {
+      const resolvedCapacity = capacity ?? limit;
+      if (typeof resolvedCapacity !== 'number' || !Number.isInteger(resolvedCapacity) || resolvedCapacity <= 0) {
+        throw new RangeError(`SmartRate: RedisStore 'capacity' must be a positive integer (received: ${resolvedCapacity}).`);
+      }
+
+      const resolvedRefillRate = refillRate ?? (limit && windowMs ? limit / (windowMs / 1000) : undefined);
+      if (typeof resolvedRefillRate !== 'number' || !Number.isFinite(resolvedRefillRate) || resolvedRefillRate <= 0) {
+        throw new RangeError(`SmartRate: RedisStore 'refillRate' must be a positive number (received: ${resolvedRefillRate}).`);
+      }
+
+      if (typeof refillIntervalMs !== 'number' || !Number.isFinite(refillIntervalMs) || refillIntervalMs <= 0) {
+        throw new RangeError(`SmartRate: RedisStore 'refillIntervalMs' must be a positive number (received: ${refillIntervalMs}).`);
+      }
+
+      return this._consumeTokenBucket({
+        key,
+        capacity: resolvedCapacity,
+        refillRate: resolvedRefillRate,
+        refillIntervalMs,
+        cost,
+        now
+      });
+    }
+
+    if (typeof limit !== 'number' || !Number.isInteger(limit) || limit <= 0) {
+      throw new RangeError(`SmartRate: RedisStore 'limit' must be a positive integer (received: ${limit}).`);
+    }
+
+    if (typeof windowMs !== 'number' || !Number.isFinite(windowMs) || windowMs <= 0) {
+      throw new RangeError(`SmartRate: RedisStore 'windowMs' must be a positive number in milliseconds (received: ${windowMs}).`);
+    }
+
+    if (algorithm === 'sliding-window') {
+      return this._consumeSlidingWindow({ key, limit, windowMs, now });
+    }
+
+    return this._consumeFixedWindow({ key, limit, windowMs });
+  }
+
+  async _consumeTokenBucket({ key, capacity, refillRate, refillIntervalMs = 1000, cost = 1, now }) {
+    const rawResult = await this._evalTokenBucketScript(key, now, capacity, refillRate, refillIntervalMs, cost);
+    const [rawAllowed, rawRemaining, rawReset, rawRetryAfter] = Array.isArray(rawResult)
+      ? rawResult
+      : [1, capacity - cost, 1, 0];
+
+    const allowed = Number(rawAllowed) === 1;
+    const remaining = Number(rawRemaining);
+    const reset = Number(rawReset);
+    const retryAfter = Number(rawRetryAfter);
+
+    return {
+      allowed,
+      count: Math.max(0, capacity - remaining),
+      remaining,
+      reset,
+      ...(allowed ? {} : { retryAfter })
+    };
+  }
+
+  async _consumeFixedWindow({ key, limit, windowMs }) {
+    const rawResult = await this._evalFixedScript(key, windowMs);
+    const [rawCount, rawTtlMs] = Array.isArray(rawResult) ? rawResult : [1, windowMs];
+
+    const count = Number(rawCount);
+    const ttlMs = Number(rawTtlMs);
+
+    if (ttlMs === -1) {
+      throw new Error(`SmartRate: Key '${key}' exists in Redis without an expiration TTL.`);
+    }
+
+    const resetSeconds = Math.max(1, Math.ceil((ttlMs > 0 ? ttlMs : windowMs) / 1000));
+    const allowed = count <= limit;
+    const remaining = Math.max(0, limit - count);
+
+    return {
+      allowed,
+      count,
+      remaining,
+      reset: resetSeconds,
+      ...(allowed ? {} : { retryAfter: resetSeconds })
+    };
+  }
+
+  async _consumeSlidingWindow({ key, limit, windowMs, now }) {
+    const uniqueId = crypto.randomUUID ? crypto.randomUUID() : Math.random().toString(36).slice(2, 10);
+    const member = `${now}:${uniqueId}`;
+
+    const rawResult = await this._evalSlidingScript(key, now, windowMs, limit, member);
+    const [rawAllowed, rawCount, rawOldestScore] = Array.isArray(rawResult) ? rawResult : [1, 1, now];
+
+    const allowed = Number(rawAllowed) === 1;
+    const count = Number(rawCount);
+    const oldestScore = Number(rawOldestScore);
+    const remaining = Math.max(0, limit - count);
+
+    const resetMs = (oldestScore + windowMs) - now;
+    const resetSeconds = Math.max(1, Math.ceil(resetMs / 1000));
+
+    return {
+      allowed,
+      count,
+      remaining,
+      reset: resetSeconds,
+      ...(allowed ? {} : { retryAfter: resetSeconds })
+    };
+  }
+}
+
+export default RedisStore;

package/src/stores/resilientStore.js

@@ -0,0 +1,121 @@
+import { EventEmitter } from 'node:events';
+import { MemoryStore } from './memoryStore.js';
+import { CircuitBreaker } from '../resilience/circuitBreaker.js';
+import { withTimeout } from '../resilience/timeoutGuard.js';
+
+export class ResilientStore extends EventEmitter {
+  constructor(options = {}) {
+    super();
+
+    if (!options || typeof options !== 'object') {
+      throw new TypeError('SmartRate: ResilientStore options must be an object.');
+    }
+
+    const {
+      primaryStore,
+      fallbackStore,
+      circuitBreaker,
+      timeoutMs = 250,
+      failureThreshold = 5,
+      resetTimeoutMs = 10000
+    } = options;
+
+    if (!primaryStore || typeof primaryStore.consume !== 'function') {
+      throw new TypeError("SmartRate: ResilientStore requires a 'primaryStore' implementing a consume() method.");
+    }
+    this.primaryStore = primaryStore;
+
+    if (fallbackStore !== undefined) {
+      if (!fallbackStore || typeof fallbackStore.consume !== 'function') {
+        throw new TypeError("SmartRate: ResilientStore 'fallbackStore' must implement a consume() method.");
+      }
+      this.fallbackStore = fallbackStore;
+    } else {
+      this.fallbackStore = new MemoryStore();
+    }
+
+    if (timeoutMs !== undefined && (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+      throw new RangeError(
+        `SmartRate: ResilientStore 'timeoutMs' must be a positive number in milliseconds (received: ${timeoutMs}).`
+      );
+    }
+    this.timeoutMs = timeoutMs;
+
+    if (circuitBreaker instanceof CircuitBreaker) {
+      this.circuitBreaker = circuitBreaker;
+    } else if (typeof circuitBreaker === 'object' && circuitBreaker !== null) {
+      this.circuitBreaker = new CircuitBreaker(circuitBreaker);
+    } else if (circuitBreaker === false) {
+      this.circuitBreaker = null;
+    } else {
+      this.circuitBreaker = new CircuitBreaker({ failureThreshold, resetTimeoutMs });
+    }
+
+    if (this.circuitBreaker) {
+      this.circuitBreaker.on('stateChange', (evt) => this.emit('stateChange', evt));
+      this.circuitBreaker.on('trip', (evt) => this.emit('circuitOpen', evt));
+      this.circuitBreaker.on('close', (evt) => this.emit('circuitClose', evt));
+      this.circuitBreaker.on('probe', (evt) => this.emit('probe', evt));
+    }
+  }
+
+  async consume(params) {
+    const runPrimary = () =>
+      this.timeoutMs
+        ? withTimeout(this.primaryStore.consume(params), this.timeoutMs)
+        : this.primaryStore.consume(params);
+
+    let primaryError = null;
+    try {
+      const result = this.circuitBreaker
+        ? await this.circuitBreaker.execute(runPrimary)
+        : await runPrimary();
+
+      this.emit('primarySuccess', { key: params.key });
+      return {
+        ...result,
+        degraded: false,
+        fallbackUsed: false,
+        store: 'primary'
+      };
+    } catch (err) {
+      primaryError = err;
+    }
+
+    this.emit('fallback', {
+      key: params.key,
+      error: primaryError,
+      circuitState: this.circuitBreaker ? this.circuitBreaker.getState() : 'NONE'
+    });
+
+    const fallbackResult = await this.fallbackStore.consume(params);
+    return {
+      ...fallbackResult,
+      degraded: true,
+      fallbackUsed: true,
+      store: 'fallback',
+      primaryError
+    };
+  }
+
+  cleanupExpiredRecords(now) {
+    let cleaned = 0;
+    if (typeof this.primaryStore.cleanupExpiredRecords === 'function') {
+      cleaned += this.primaryStore.cleanupExpiredRecords(now) || 0;
+    }
+    if (typeof this.fallbackStore.cleanupExpiredRecords === 'function') {
+      cleaned += this.fallbackStore.cleanupExpiredRecords(now) || 0;
+    }
+    return cleaned;
+  }
+
+  getStats() {
+    return {
+      circuitBreaker: this.circuitBreaker ? this.circuitBreaker.getStats() : null,
+      timeoutMs: this.timeoutMs,
+      hasFallbackStore: Boolean(this.fallbackStore)
+    };
+  }
+}
+
+export default ResilientStore;

package/src/telemetry/metricsCollector.js

@@ -0,0 +1,212 @@
+import {
+  METRIC_TYPE,
+  METRIC_NAMES,
+  CIRCUIT_STATE_GAUGE_VALUES,
+  DEFAULT_STORE_DURATION_BUCKETS
+} from './telemetryEvents.js';
+
+function serializeLabelKey(labels = {}) {
+  if (!labels || typeof labels !== 'object') return '';
+  const entries = Object.entries(labels).filter(([k, v]) => v !== undefined && v !== null);
+  if (entries.length === 0) return '';
+  entries.sort(([a], [b]) => a.localeCompare(b));
+  return entries.map(([k, v]) => `${k}="${String(v)}"`).join(',');
+}
+
+export class MetricsCollector {
+  constructor(options = {}) {
+    this.storeDurationBuckets = options.storeDurationBuckets || DEFAULT_STORE_DURATION_BUCKETS;
+    this.maxSeries = typeof options.maxSeries === 'number' && options.maxSeries > 0 ? options.maxSeries : 1000;
+
+    this.counters = new Map();
+    this.gauges = new Map();
+    this.histograms = new Map();
+
+    // Default gauge for circuit breaker state (0 = CLOSED)
+    this.setGauge(METRIC_NAMES.CIRCUIT_BREAKER_STATE, CIRCUIT_STATE_GAUGE_VALUES.CLOSED);
+  }
+
+  incrementCounter(name, labels = {}, value = 1) {
+    try {
+      if (!name || typeof name !== 'string') return;
+      if (typeof value !== 'number' || value <= 0) return;
+
+      if (!this.counters.has(name)) {
+        this.counters.set(name, new Map());
+      }
+
+      const metricMap = this.counters.get(name);
+      let targetLabels = labels;
+      let labelKey = serializeLabelKey(targetLabels);
+
+      if (!metricMap.has(labelKey)) {
+        if (metricMap.size >= this.maxSeries) {
+          if (labels && labels.normalized_route) {
+            targetLabels = { ...labels, normalized_route: '_overflow' };
+            labelKey = serializeLabelKey(targetLabels);
+            if (!metricMap.has(labelKey) && metricMap.size >= this.maxSeries) {
+              return;
+            }
+          } else {
+            return;
+          }
+        }
+      }
+
+      const current = metricMap.get(labelKey) || { value: 0, labels: { ...targetLabels } };
+      current.value += value;
+      metricMap.set(labelKey, current);
+    } catch {
+      // safe telemetry boundary
+    }
+  }
+
+  setGauge(name, value, labels = {}) {
+    try {
+      if (!name || typeof name !== 'string') return;
+      if (typeof value !== 'number' || !Number.isFinite(value)) return;
+
+      if (!this.gauges.has(name)) {
+        this.gauges.set(name, new Map());
+      }
+
+      const metricMap = this.gauges.get(name);
+      let targetLabels = labels;
+      let labelKey = serializeLabelKey(targetLabels);
+
+      if (!metricMap.has(labelKey) && metricMap.size >= this.maxSeries) {
+        return;
+      }
+
+      metricMap.set(labelKey, {
+        value,
+        labels: { ...targetLabels }
+      });
+    } catch {
+      // safe telemetry boundary
+    }
+  }
+
+  observeHistogram(name, durationSeconds, labels = {}, customBuckets = this.storeDurationBuckets) {
+    try {
+      if (!name || typeof name !== 'string') return;
+      if (typeof durationSeconds !== 'number' || !Number.isFinite(durationSeconds) || durationSeconds < 0) return;
+
+      if (!this.histograms.has(name)) {
+        this.histograms.set(name, new Map());
+      }
+
+      const metricMap = this.histograms.get(name);
+      let targetLabels = labels;
+      let labelKey = serializeLabelKey(targetLabels);
+
+      if (!metricMap.has(labelKey) && metricMap.size >= this.maxSeries) {
+        return;
+      }
+
+      let record = metricMap.get(labelKey);
+      if (!record) {
+        const sortedBounds = [...customBuckets].sort((a, b) => a - b);
+        record = {
+          labels: { ...targetLabels },
+          buckets: sortedBounds.map((le) => ({ le, count: 0 })),
+          sum: 0,
+          count: 0
+        };
+        metricMap.set(labelKey, record);
+      }
+
+      record.sum += durationSeconds;
+      record.count += 1;
+
+      for (const bucket of record.buckets) {
+        if (durationSeconds <= bucket.le) {
+          bucket.count += 1;
+        }
+      }
+    } catch {
+      // safe telemetry boundary
+    }
+  }
+
+  recordRequest({ outcome, algorithm, method, normalized_route, store }) {
+    this.incrementCounter(METRIC_NAMES.REQUESTS_TOTAL, {
+      outcome: outcome || 'unknown',
+      algorithm: algorithm || 'unknown',
+      method: (method || 'GET').toUpperCase(),
+      normalized_route: normalized_route || '/',
+      store: store || 'unknown'
+    });
+  }
+
+  recordStoreError({ store, error_type }) {
+    this.incrementCounter(METRIC_NAMES.STORE_ERRORS_TOTAL, {
+      store: store || 'unknown',
+      error_type: error_type || 'store_error'
+    });
+  }
+
+  recordDegradedRequest({ reason }) {
+    this.incrementCounter(METRIC_NAMES.DEGRADED_REQUESTS_TOTAL, {
+      reason: reason || 'fallback'
+    });
+  }
+
+  recordCircuitBreakerState(state, labels = {}) {
+    const numericValue =
+      CIRCUIT_STATE_GAUGE_VALUES[state] !== undefined
+        ? CIRCUIT_STATE_GAUGE_VALUES[state]
+        : CIRCUIT_STATE_GAUGE_VALUES.CLOSED;
+
+    this.setGauge(METRIC_NAMES.CIRCUIT_BREAKER_STATE, numericValue, labels);
+  }
+
+  recordStoreDuration(durationSeconds, labels = {}) {
+    this.observeHistogram(METRIC_NAMES.STORE_DURATION_SECONDS, durationSeconds, labels);
+  }
+
+  getSnapshot() {
+    const snapshot = {
+      counters: {},
+      gauges: {},
+      histograms: {}
+    };
+
+    for (const [name, metricMap] of this.counters.entries()) {
+      snapshot.counters[name] = [];
+      for (const record of metricMap.values()) {
+        snapshot.counters[name].push({ ...record, labels: { ...record.labels } });
+      }
+    }
+
+    for (const [name, metricMap] of this.gauges.entries()) {
+      snapshot.gauges[name] = [];
+      for (const record of metricMap.values()) {
+        snapshot.gauges[name].push({ ...record, labels: { ...record.labels } });
+      }
+    }
+
+    for (const [name, metricMap] of this.histograms.entries()) {
+      snapshot.histograms[name] = [];
+      for (const record of metricMap.values()) {
+        snapshot.histograms[name].push({
+          labels: { ...record.labels },
+          buckets: record.buckets.map((b) => ({ ...b })),
+          sum: record.sum,
+          count: record.count
+        });
+      }
+    }
+
+    return snapshot;
+  }
+
+  reset() {
+    this.counters.clear();
+    this.gauges.clear();
+    this.histograms.clear();
+    this.setGauge(METRIC_NAMES.CIRCUIT_BREAKER_STATE, CIRCUIT_STATE_GAUGE_VALUES.CLOSED);
+  }
+}
+
+export const defaultMetricsCollector = new MetricsCollector();

package/src/telemetry/openTelemetryBridge.js

@@ -0,0 +1,133 @@
+export class OpenTelemetryBridge {
+  constructor(options = {}) {
+    this.tracer = options.tracer || null;
+    this.getSpan = options.getSpan || null;
+  }
+
+  startSpan(name = 'smartrate.consume', options = {}) {
+    if (this.tracer && typeof this.tracer.startSpan === 'function') {
+      try {
+        return this.tracer.startSpan(name, options);
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+
+  resolveSpan(req) {
+    if (typeof this.getSpan === 'function') {
+      try {
+        const span = this.getSpan(req);
+        if (span && typeof span.setAttribute === 'function') {
+          return span;
+        }
+      } catch {
+        return null;
+      }
+    }
+
+    if (req && req.span && typeof req.span.setAttribute === 'function') {
+      return req.span;
+    }
+    if (req && req.telemetrySpan && typeof req.telemetrySpan.setAttribute === 'function') {
+      return req.telemetrySpan;
+    }
+    if (req && req._smartRateSpan && typeof req._smartRateSpan.setAttribute === 'function') {
+      return req._smartRateSpan;
+    }
+
+    try {
+      const api = globalThis[Symbol.for('opentelemetry.js.api.1')];
+      if (api && api.trace && typeof api.trace.getActiveSpan === 'function') {
+        const activeSpan = api.trace.getActiveSpan();
+        if (activeSpan && typeof activeSpan.setAttribute === 'function') {
+          return activeSpan;
+        }
+      }
+    } catch {
+      // safe boundary
+    }
+
+    return null;
+  }
+
+  recordEvaluation({ req, result, algorithm, normalizedRoute, store }) {
+    try {
+      const span = this.resolveSpan(req);
+      if (!span || typeof span.setAttribute !== 'function') return;
+
+      const isAllowed = Boolean(result.allowed);
+      const remainingVal = typeof result.remaining === 'number' ? result.remaining : 0;
+      const resetVal = typeof result.reset === 'number' ? result.reset : 0;
+      const algoStr = algorithm || 'fixed-window';
+      const routeStr = normalizedRoute || '/';
+      const storeStr = store || 'unknown';
+
+      span.setAttribute('smartrate.outcome', isAllowed ? 'allowed' : 'blocked');
+      span.setAttribute('smartrate.algorithm', algoStr);
+      span.setAttribute('smartrate.route', routeStr);
+      span.setAttribute('smartrate.store', storeStr);
+
+      if (typeof result.remaining === 'number') {
+        span.setAttribute('smartrate.remaining', result.remaining);
+      }
+      if (typeof result.reset === 'number') {
+        span.setAttribute('smartrate.reset', result.reset);
+      }
+      if (result.degraded) {
+        span.setAttribute('smartrate.degraded', true);
+      }
+
+      span.setAttribute('ratelimit.allowed', isAllowed);
+      span.setAttribute('ratelimit.remaining', remainingVal);
+      span.setAttribute('ratelimit.reset', resetVal);
+      span.setAttribute('ratelimit.algorithm', algoStr);
+      span.setAttribute('ratelimit.store', storeStr);
+      span.setAttribute('ratelimit.degraded', Boolean(result.degraded));
+
+      if (result.circuitState) {
+        span.setAttribute('ratelimit.circuit_state', result.circuitState);
+      }
+
+      if (!isAllowed) {
+        if (typeof span.addEvent === 'function') {
+          span.addEvent('smartrate.rate_limit_exceeded', {
+            'smartrate.retry_after': result.retryAfter || 0,
+            'smartrate.route': routeStr,
+            'ratelimit.retry_after': result.retryAfter || 0
+          });
+        }
+      }
+    } catch {
+      // safe boundary
+    }
+  }
+
+  recordStoreError({ req, storeError, store }) {
+    try {
+      const span = this.resolveSpan(req);
+      if (!span) return;
+
+      if (typeof span.recordException === 'function' && storeError instanceof Error) {
+        span.recordException(storeError);
+      }
+
+      if (typeof span.setAttribute === 'function') {
+        span.setAttribute('smartrate.store_error', true);
+        span.setAttribute('smartrate.store', store || 'unknown');
+        span.setAttribute('ratelimit.store_error', true);
+        span.setAttribute('ratelimit.store', store || 'unknown');
+      }
+
+      if (typeof span.addEvent === 'function') {
+        span.addEvent('smartrate.store_error', {
+          'error.name': storeError?.name || 'Error',
+          'error.message': storeError?.message || 'Store operation failed'
+        });
+      }
+    } catch {
+      // safe boundary
+    }
+  }
+}