limitforge 0.0.0-stage → 8.0.1

package/src/resilience/circuitBreaker.js

@@ -0,0 +1,216 @@
+import { EventEmitter } from 'node:events';
+import { CircuitBreakerOpenError } from './errors.js';
+
+export const CIRCUIT_STATE = Object.freeze({
+  CLOSED: 'CLOSED',
+  OPEN: 'OPEN',
+  HALF_OPEN: 'HALF_OPEN'
+});
+
+export class CircuitBreaker extends EventEmitter {
+  constructor(options = {}) {
+    super();
+
+    const {
+      failureThreshold = 5,
+      resetTimeoutMs = 10000,
+      successThreshold = 1,
+      isFailure = () => true
+    } = options;
+
+    if (typeof failureThreshold !== 'number' || !Number.isInteger(failureThreshold) || failureThreshold <= 0) {
+      throw new RangeError(
+        `SmartRate: CircuitBreaker 'failureThreshold' must be a positive integer (received: ${failureThreshold}).`
+      );
+    }
+    if (typeof resetTimeoutMs !== 'number' || !Number.isFinite(resetTimeoutMs) || resetTimeoutMs <= 0) {
+      throw new RangeError(
+        `SmartRate: CircuitBreaker 'resetTimeoutMs' must be a positive number in milliseconds (received: ${resetTimeoutMs}).`
+      );
+    }
+    if (typeof successThreshold !== 'number' || !Number.isInteger(successThreshold) || successThreshold <= 0) {
+      throw new RangeError(
+        `SmartRate: CircuitBreaker 'successThreshold' must be a positive integer (received: ${successThreshold}).`
+      );
+    }
+    if (typeof isFailure !== 'function') {
+      throw new TypeError("SmartRate: CircuitBreaker 'isFailure' must be a function.");
+    }
+
+    this.failureThreshold = failureThreshold;
+    this.resetTimeoutMs = resetTimeoutMs;
+    this.successThreshold = successThreshold;
+    this.isFailure = isFailure;
+    this.id = (typeof options.id === 'string' && options.id.trim()) || (typeof options.name === 'string' && options.name.trim()) || null;
+
+    this.state = CIRCUIT_STATE.CLOSED;
+    this.consecutiveFailures = 0;
+    this.consecutiveSuccesses = 0;
+    this.lastFailureTime = null;
+    this.nextAttempt = 0;
+    this.probeInFlight = false;
+    this.probeGeneration = 0;
+  }
+
+  getState() {
+    if (this.state === CIRCUIT_STATE.OPEN && Date.now() >= this.nextAttempt) {
+      this._transitionTo(CIRCUIT_STATE.HALF_OPEN);
+    }
+    return this.state;
+  }
+
+  isOpen() { return this.getState() === CIRCUIT_STATE.OPEN; }
+  isClosed() { return this.getState() === CIRCUIT_STATE.CLOSED; }
+  isHalfOpen() { return this.getState() === CIRCUIT_STATE.HALF_OPEN; }
+
+  _transitionTo(nextState, context = {}) {
+    if (this.state === nextState) return;
+
+    const from = this.state;
+    this._invalidateProbe();
+    this.state = nextState;
+
+    if (nextState === CIRCUIT_STATE.CLOSED) {
+      this.consecutiveFailures = 0;
+      this.consecutiveSuccesses = 0;
+      this.probeInFlight = false;
+    } else if (nextState === CIRCUIT_STATE.OPEN) {
+      this.nextAttempt = Date.now() + this.resetTimeoutMs;
+      this.probeInFlight = false;
+    } else if (nextState === CIRCUIT_STATE.HALF_OPEN) {
+      this.consecutiveSuccesses = 0;
+      this.probeInFlight = false;
+    }
+
+    const eventPayload = {
+      from,
+      to: nextState,
+      timestamp: Date.now(),
+      ...context
+    };
+
+    this.emit('stateChange', eventPayload);
+
+    if (nextState === CIRCUIT_STATE.OPEN) {
+      this.emit('open', eventPayload);
+      this.emit('trip', eventPayload);
+    } else if (nextState === CIRCUIT_STATE.HALF_OPEN) {
+      this.emit('halfOpen', eventPayload);
+    } else if (nextState === CIRCUIT_STATE.CLOSED) {
+      this.emit('close', eventPayload);
+      this.emit('reset', eventPayload);
+    }
+  }
+
+  _invalidateProbe() {
+    this.probeGeneration += 1;
+    this.probeInFlight = false;
+  }
+
+  _ownsProbe(token) {
+    return token !== null &&
+      token === this.probeGeneration &&
+      this.probeInFlight &&
+      this.state === CIRCUIT_STATE.HALF_OPEN;
+  }
+
+  async execute(fn) {
+    if (typeof fn !== 'function') {
+      throw new TypeError("SmartRate: CircuitBreaker.execute() expects a function argument.");
+    }
+
+    const currentState = this.getState();
+    if (currentState === CIRCUIT_STATE.OPEN) {
+      const remainingMs = Math.max(0, this.nextAttempt - Date.now());
+      throw new CircuitBreakerOpenError(
+        `SmartRate: Circuit breaker is OPEN. Fast-failing without calling store (resets in ${remainingMs}ms).`,
+        remainingMs
+      );
+    }
+
+    let probeToken = null;
+    if (currentState === CIRCUIT_STATE.HALF_OPEN) {
+      if (this.probeInFlight) {
+        throw new CircuitBreakerOpenError(
+          'SmartRate: Circuit breaker is HALF_OPEN and a canary probe is already in-flight.',
+          Math.max(0, this.nextAttempt - Date.now())
+        );
+      }
+      this.probeInFlight = true;
+      probeToken = ++this.probeGeneration;
+      this.emit('probe', { timestamp: Date.now() });
+    }
+
+    try {
+      const result = await fn();
+      this._recordSuccess(probeToken);
+      return result;
+    } catch (err) {
+      if ((probeToken === null || this._ownsProbe(probeToken)) && this.isFailure(err)) {
+        this._recordFailure(err, probeToken);
+      }
+      throw err;
+    } finally {
+      if (this._ownsProbe(probeToken)) {
+        this.probeInFlight = false;
+        this.probeGeneration += 1;
+      }
+    }
+  }
+
+  _recordSuccess(probeToken = null) {
+    const isProbe = probeToken !== null;
+    if (isProbe && !this._ownsProbe(probeToken)) return;
+
+    if (this.state === CIRCUIT_STATE.HALF_OPEN) {
+      if (!isProbe) return;
+      this.consecutiveSuccesses += 1;
+      if (this.consecutiveSuccesses >= this.successThreshold) {
+        this._transitionTo(CIRCUIT_STATE.CLOSED);
+      }
+    } else if (this.state === CIRCUIT_STATE.CLOSED) {
+      this.consecutiveFailures = 0;
+    }
+  }
+
+  _recordFailure(err, probeToken = null) {
+    const isProbe = probeToken !== null;
+    if (isProbe && !this._ownsProbe(probeToken)) return;
+    if (this.state === CIRCUIT_STATE.HALF_OPEN && !isProbe) return;
+
+    this.lastFailureTime = Date.now();
+    this.consecutiveFailures += 1;
+
+    if (this.state === CIRCUIT_STATE.HALF_OPEN) {
+      this._transitionTo(CIRCUIT_STATE.OPEN, { error: err, probeFailed: true });
+    } else if (this.state === CIRCUIT_STATE.CLOSED) {
+      if (this.consecutiveFailures >= this.failureThreshold) {
+        this._transitionTo(CIRCUIT_STATE.OPEN, { error: err, consecutiveFailures: this.consecutiveFailures });
+      }
+    }
+  }
+
+  trip(error) {
+    this._invalidateProbe();
+    this._transitionTo(CIRCUIT_STATE.OPEN, { error, manual: true });
+  }
+
+  reset() {
+    this._invalidateProbe();
+    this._transitionTo(CIRCUIT_STATE.CLOSED, { manual: true });
+  }
+
+  getStats() {
+    return {
+      state: this.getState(),
+      consecutiveFailures: this.consecutiveFailures,
+      consecutiveSuccesses: this.consecutiveSuccesses,
+      failureThreshold: this.failureThreshold,
+      resetTimeoutMs: this.resetTimeoutMs,
+      successThreshold: this.successThreshold,
+      lastFailureTime: this.lastFailureTime,
+      nextAttempt: this.nextAttempt,
+      probeInFlight: this.probeInFlight
+    };
+  }
+}

package/src/resilience/errors.js

@@ -0,0 +1,29 @@
+export class StoreTimeoutError extends Error {
+  constructor(timeoutMs = 250, message) {
+    super(message || `SmartRate: Rate limit store operation timed out after ${timeoutMs}ms.`);
+    this.name = 'StoreTimeoutError';
+    this.isTimeout = true;
+    this.code = 'ERR_STORE_TIMEOUT';
+    this.timeoutMs = timeoutMs;
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, StoreTimeoutError);
+    }
+  }
+}
+
+export class CircuitBreakerOpenError extends Error {
+  constructor(message, resetTimeoutMs) {
+    super(message || 'SmartRate: Circuit breaker is OPEN. Store operations temporarily suspended.');
+    this.name = 'CircuitBreakerOpenError';
+    this.isCircuitOpen = true;
+    this.code = 'ERR_CIRCUIT_OPEN';
+    if (resetTimeoutMs !== undefined) {
+      this.resetTimeoutMs = resetTimeoutMs;
+    }
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, CircuitBreakerOpenError);
+    }
+  }
+}

package/src/resilience/timeoutGuard.js

@@ -0,0 +1,24 @@
+import { StoreTimeoutError } from './errors.js';
+
+export async function withTimeout(operation, timeoutMs) {
+  if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new RangeError(
+      `SmartRate: 'timeoutMs' must be a positive number in milliseconds (received: ${timeoutMs}).`
+    );
+  }
+
+  if (!operation || typeof operation.then !== 'function') {
+    return operation;
+  }
+
+  let timer;
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new StoreTimeoutError(timeoutMs)), timeoutMs);
+  });
+
+  try {
+    return await Promise.race([operation, timeoutPromise]);
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/scripts/fixedWindow.lua

@@ -0,0 +1,10 @@
+
+local count = redis.call("INCR", KEYS[1])
+
+if count == 1 then
+    redis.call("PEXPIRE", KEYS[1], ARGV[1])
+end
+
+local ttl = redis.call("PTTL", KEYS[1])
+
+return {count, ttl}

package/src/scripts/slidingWindow.lua

@@ -0,0 +1,26 @@
+
+local key = KEYS[1]
+local now = tonumber(ARGV[1])
+local windowMs = tonumber(ARGV[2])
+local limit = tonumber(ARGV[3])
+local member = ARGV[4]
+
+local cutoff = now - windowMs
+
+redis.call("ZREMRANGEBYSCORE", key, "-inf", cutoff)
+
+local currentCount = redis.call("ZCARD", key)
+local allowed = 0
+
+if currentCount < limit then
+    redis.call("ZADD", key, now, member)
+    currentCount = currentCount + 1
+    allowed = 1
+end
+
+local oldest = redis.call("ZRANGE", key, 0, 0, "WITHSCORES")
+local oldestScore = (oldest and #oldest >= 2) and tonumber(oldest[2]) or now
+
+redis.call("PEXPIRE", key, windowMs)
+
+return { allowed, currentCount, oldestScore }

package/src/scripts/tokenBucket.lua

@@ -0,0 +1,66 @@
+
+local key = KEYS[1]
+local now = tonumber(ARGV[1])
+local capacity = tonumber(ARGV[2])
+local refillRate = tonumber(ARGV[3])
+local refillIntervalMs = tonumber(ARGV[4]) or 1000
+local cost = tonumber(ARGV[5]) or 1
+
+if refillIntervalMs <= 0 then
+    refillIntervalMs = 1000
+end
+
+local refillPerMs = refillRate / refillIntervalMs
+
+local data = redis.call("HMGET", key, "tokens", "lastRefill")
+local rawTokens = data[1]
+local rawLastRefill = data[2]
+
+local currentTokens = capacity
+local lastRefill = now
+
+if rawTokens and rawLastRefill then
+    local prevTokens = tonumber(rawTokens)
+    local prevLastRefill = tonumber(rawLastRefill)
+
+    local elapsedMs = math.max(0, now - prevLastRefill)
+    local tokensToAdd = elapsedMs * refillPerMs
+    currentTokens = math.min(capacity, prevTokens + tokensToAdd)
+    lastRefill = now
+end
+
+local allowed = 0
+local remaining = 0
+local retryAfter = 0
+
+if currentTokens >= cost then
+    currentTokens = currentTokens - cost
+    allowed = 1
+    remaining = math.floor(currentTokens)
+    lastRefill = now
+else
+    allowed = 0
+    remaining = math.floor(currentTokens)
+    local neededTokens = cost - currentTokens
+    local waitMs = neededTokens / refillPerMs
+    retryAfter = math.max(1, math.ceil(waitMs / 1000))
+end
+
+-- update bucket state in redis
+redis.call("HSET", key, "tokens", tostring(currentTokens), "lastRefill", tostring(lastRefill))
+
+local fullTimeMs = math.ceil(capacity / refillPerMs)
+local fullTimeSec = math.ceil(fullTimeMs / 1000)
+local ttlSeconds = math.max(60, fullTimeSec * 2)
+redis.call("EXPIRE", key, ttlSeconds)
+
+-- calculate reset option c semantics
+local reset
+if allowed == 1 then
+    local timeToFullMs = math.max(0, (capacity - currentTokens) / refillPerMs)
+    reset = math.max(1, math.ceil(timeToFullMs / 1000))
+else
+    reset = retryAfter
+end
+
+return { allowed, remaining, reset, retryAfter }

package/src/stores/memoryStore.js

@@ -0,0 +1,238 @@
+export class MemoryStore {
+  constructor(options = {}) {
+    this.store = new Map();
+    this.cleanupIntervalMs = options.cleanupIntervalMs || 60_000;
+    this.cleanupInterval = null;
+    this._ensureCleanupTimer();
+  }
+
+  consume({
+    key,
+    limit,
+    windowMs,
+    algorithm = 'fixed-window',
+    capacity,
+    refillRate,
+    refillIntervalMs = 1000,
+    cost = 1,
+    now = Date.now()
+  }) {
+    if (algorithm === 'sliding-window') {
+      return this._consumeSlidingWindow({ key, limit, windowMs, now });
+    }
+
+    if (algorithm === 'token-bucket') {
+      const resolvedCapacity = capacity ?? limit;
+      const resolvedRefillRate = refillRate ?? (limit && windowMs ? (limit * refillIntervalMs) / windowMs : 1);
+      return this._consumeTokenBucket({
+        key,
+        capacity: resolvedCapacity,
+        refillRate: resolvedRefillRate,
+        refillIntervalMs,
+        cost,
+        now
+      });
+    }
+
+    return this._consumeFixedWindow({ key, limit, windowMs, now });
+  }
+
+  _consumeFixedWindow({ key, limit, windowMs, now }) {
+    const record = this.store.get(key);
+
+    if (!record || record.windowStart === undefined) {
+      this.store.set(key, { count: 1, windowStart: now, windowMs });
+      return {
+        allowed: true,
+        count: 1,
+        remaining: Math.max(0, limit - 1),
+        reset: Math.ceil(windowMs / 1000)
+      };
+    }
+
+    const elapsed = now - record.windowStart;
+    if (elapsed >= windowMs) {
+      record.count = 1;
+      record.windowStart = now;
+      record.windowMs = windowMs;
+
+      return {
+        allowed: true,
+        count: 1,
+        remaining: Math.max(0, limit - 1),
+        reset: Math.ceil(windowMs / 1000)
+      };
+    }
+
+    if (record.count < limit) {
+      record.count += 1;
+      const reset = Math.max(1, Math.ceil((record.windowStart + windowMs - now) / 1000));
+      return {
+        allowed: true,
+        count: record.count,
+        remaining: Math.max(0, limit - record.count),
+        reset
+      };
+    }
+
+    const reset = Math.max(1, Math.ceil((record.windowStart + windowMs - now) / 1000));
+    return {
+      allowed: false,
+      count: record.count,
+      remaining: 0,
+      reset,
+      retryAfter: reset
+    };
+  }
+
+  _consumeSlidingWindow({ key, limit, windowMs, now }) {
+    const cutoff = now - windowMs;
+    let record = this.store.get(key);
+
+    if (!record || !Array.isArray(record.timestamps)) {
+      record = { timestamps: [], windowMs };
+      this.store.set(key, record);
+    } else {
+      record.windowMs = windowMs;
+    }
+
+    while (record.timestamps.length > 0 && record.timestamps[0] <= cutoff) {
+      record.timestamps.shift();
+    }
+
+    const currentCount = record.timestamps.length;
+    if (currentCount < limit) {
+      record.timestamps.push(now);
+      const newCount = currentCount + 1;
+      const remaining = Math.max(0, limit - newCount);
+      const oldest = record.timestamps[0];
+      const reset = Math.max(1, Math.ceil((oldest + windowMs - now) / 1000));
+
+      return {
+        allowed: true,
+        count: newCount,
+        remaining,
+        reset
+      };
+    }
+
+    const oldest = record.timestamps[0];
+    const reset = Math.max(1, Math.ceil((oldest + windowMs - now) / 1000));
+
+    return {
+      allowed: false,
+      count: currentCount,
+      remaining: 0,
+      reset,
+      retryAfter: reset
+    };
+  }
+
+  _consumeTokenBucket({ key, capacity, refillRate, refillIntervalMs = 1000, cost = 1, now }) {
+    const refillPerMs = refillRate / refillIntervalMs;
+    let record = this.store.get(key);
+
+    if (!record || record.algorithm !== 'token-bucket') {
+      record = {
+        algorithm: 'token-bucket',
+        tokens: capacity,
+        lastRefillTimestamp: now,
+        capacity,
+        refillRate,
+        refillIntervalMs
+      };
+      this.store.set(key, record);
+    } else {
+      record.capacity = capacity;
+      record.refillRate = refillRate;
+      record.refillIntervalMs = refillIntervalMs;
+
+      const elapsed = Math.max(0, now - record.lastRefillTimestamp);
+      if (elapsed > 0) {
+        const tokensToAdd = elapsed * refillPerMs;
+        record.tokens = Math.min(record.capacity, record.tokens + tokensToAdd);
+        record.lastRefillTimestamp = now;
+      }
+    }
+
+    if (record.tokens >= cost) {
+      record.tokens -= cost;
+      const remaining = Math.max(0, Math.floor(record.tokens));
+      const timeToFullMs = Math.max(0, (record.capacity - record.tokens) / refillPerMs);
+      const reset = Math.max(1, Math.ceil(timeToFullMs / 1000));
+
+      return {
+        allowed: true,
+        count: Math.max(0, record.capacity - remaining),
+        remaining,
+        reset
+      };
+    }
+
+    const neededTokens = cost - record.tokens;
+    const waitMs = neededTokens / refillPerMs;
+    const retryAfter = Math.max(1, Math.ceil(waitMs / 1000));
+
+    return {
+      allowed: false,
+      count: record.capacity,
+      remaining: Math.max(0, Math.floor(record.tokens)),
+      reset: retryAfter,
+      retryAfter
+    };
+  }
+
+  cleanupExpiredRecords(now = Date.now()) {
+    let removed = 0;
+
+    for (const [key, record] of this.store.entries()) {
+      if (Array.isArray(record.timestamps)) {
+        const cutoff = now - record.windowMs;
+        while (record.timestamps.length > 0 && record.timestamps[0] <= cutoff) {
+          record.timestamps.shift();
+        }
+        if (record.timestamps.length === 0) {
+          this.store.delete(key);
+          removed++;
+        }
+      } else if (record.algorithm === 'token-bucket') {
+        const elapsed = now - record.lastRefillTimestamp;
+        const refillPerMs = (record.refillRate || 1) / (record.refillIntervalMs || 1000);
+        const timeToFullMs = Math.max(0, (record.capacity - record.tokens) / refillPerMs);
+        if (elapsed >= timeToFullMs + this.cleanupIntervalMs) {
+          this.store.delete(key);
+          removed++;
+        }
+      } else if (record.windowStart !== undefined) {
+        if (now - record.windowStart >= record.windowMs) {
+          this.store.delete(key);
+          removed++;
+        }
+      }
+    }
+
+    return removed;
+  }
+
+  _ensureCleanupTimer() {
+    if (!this.cleanupInterval) {
+      this.cleanupInterval = setInterval(() => {
+        this.cleanupExpiredRecords();
+      }, this.cleanupIntervalMs);
+
+      if (typeof this.cleanupInterval.unref === 'function') {
+        this.cleanupInterval.unref();
+      }
+    }
+  }
+
+  destroy() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.store.clear();
+  }
+}
+
+export default MemoryStore;