ratelimit-engine 0.0.0-stage → 1.0.0

package/src/stores/BaseStore.js

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Abstract base class for all store implementations.
+ * Any custom store must extend this class and implement all methods.
+ */
+
+import { ErrorFactory } from '../errors/ErrorFactory.js'
+
+export class BaseStore {
+  /**
+   * @param {string} type - Store type identifier (from STORE_TYPES).
+   */
+  constructor(type) {
+    if (new.target === BaseStore) {
+      throw ErrorFactory.invalidStore({ reason: 'BaseStore cannot be instantiated directly' })
+    }
+    this.type = type
+  }
+
+  /**
+   * Retrieves the entry for a key. Returns null if not found or expired.
+   *
+   * @param {string} key
+   * @returns {Promise<import('../types/index.js').StoreEntry|null>}
+   */
+  async get(_key) {
+    throw new Error('get() must be implemented by subclass')
+  }
+
+  /**
+   * Persists an entry for a key with a TTL.
+   *
+   * @param {string}                                   key
+   * @param {import('../types/index.js').StoreEntry}   entry
+   * @param {number}                                   ttlMs
+   * @returns {Promise<void>}
+   */
+  async set(_key, _entry, _ttlMs) {
+    throw new Error('set() must be implemented by subclass')
+  }
+
+  /**
+   * Atomically increments the count for a key.
+   * Creates the entry with ttlMs if it does not exist.
+   *
+   * @param {string} key
+   * @param {number} ttlMs
+   * @returns {Promise<number>} New count after increment.
+   */
+  async increment(_key, _ttlMs) {
+    throw new Error('increment() must be implemented by subclass')
+  }
+
+  /**
+   * Deletes the entry for a key.
+   *
+   * @param {string} key
+   * @returns {Promise<void>}
+   */
+  async delete(_key) {
+    throw new Error('delete() must be implemented by subclass')
+  }
+
+  /**
+   * Releases resources held by the store (connections, timers).
+   *
+   * @returns {Promise<void>}
+   */
+  async destroy() {}
+}

package/src/stores/MemoryStore.js

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview In-memory store backed by a Map.
+ * Suitable for development, testing, and single-instance deployments.
+ * Not suitable for multi-pod / distributed deployments.
+ */
+
+import { BaseStore }     from './BaseStore.js'
+import { ErrorFactory }  from '../errors/ErrorFactory.js'
+import { STORE_TYPES, MEMORY_STORE_CLEANUP_INTERVAL_MS } from '../constants/store.js'
+import { createLogger }  from '../logger/LoggerFactory.js'
+
+const logger = createLogger('MemoryStore')
+
+export class MemoryStore extends BaseStore {
+  constructor() {
+    super(STORE_TYPES.MEMORY)
+    /** @type {Map<string, import('../types/index.js').StoreEntry>} */
+    this._store = new Map()
+    this._cleanupTimer = setInterval(
+      () => this._evictExpired(),
+      MEMORY_STORE_CLEANUP_INTERVAL_MS,
+    )
+    // Allow Node.js to exit even if this timer is active
+    this._cleanupTimer.unref?.()
+  }
+
+  /**
+   * @param {string} key
+   * @returns {Promise<import('../types/index.js').StoreEntry|null>}
+   */
+  async get(key) {
+    try {
+      const entry = this._store.get(key)
+      if (!entry) {
+        return null
+      }
+      if (Date.now() > entry.expiresAt) {
+        this._store.delete(key)
+        return null
+      }
+      return entry
+    } catch (cause) {
+      throw ErrorFactory.storeOperationFailed('read', cause, { key })
+    }
+  }
+
+  /**
+   * @param {string}                                  key
+   * @param {import('../types/index.js').StoreEntry}  entry
+   * @param {number}                                  ttlMs
+   * @returns {Promise<void>}
+   */
+  async set(key, entry, ttlMs) {
+    try {
+      this._store.set(key, {
+        expiresAt: Date.now() + ttlMs,
+        ...entry,
+      })
+    } catch (cause) {
+      throw ErrorFactory.storeOperationFailed('write', cause, { key })
+    }
+  }
+
+  /**
+   * Atomically increments the count for a key.
+   * If no entry exists, initialises count to 1 with the given TTL.
+   *
+   * @param {string} key
+   * @param {number} ttlMs
+   * @returns {Promise<number>}
+   */
+  async increment(key, ttlMs) {
+    try {
+      const now   = Date.now()
+      const entry = this._store.get(key)
+
+      if (!entry || now > entry.expiresAt) {
+        const fresh = { count: 1, windowStart: now, expiresAt: now + ttlMs, meta: {} }
+        this._store.set(key, fresh)
+        return 1
+      }
+
+      entry.count += 1
+      return entry.count
+    } catch (cause) {
+      throw ErrorFactory.storeOperationFailed('write', cause, { key })
+    }
+  }
+
+  /**
+   * @param {string} key
+   * @returns {Promise<void>}
+   */
+  async delete(key) {
+    try {
+      this._store.delete(key)
+    } catch (cause) {
+      throw ErrorFactory.storeOperationFailed('write', cause, { key })
+    }
+  }
+
+  /**
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    clearInterval(this._cleanupTimer)
+    this._store.clear()
+    logger.info('MemoryStore destroyed')
+  }
+
+  /**
+   * Removes entries whose TTL has elapsed.
+   */
+  _evictExpired() {
+    const now     = Date.now()
+    let   evicted = 0
+
+    for (const [key, entry] of this._store) {
+      if (now > entry.expiresAt) {
+        this._store.delete(key)
+        evicted++
+      }
+    }
+
+    if (evicted > 0) {
+      logger.debug('Evicted expired entries', { evicted })
+    }
+  }
+}

package/src/stores/RedisStore.js

@@ -0,0 +1,168 @@
+/**
+ * @fileoverview Redis-backed store using atomic Lua scripts.
+ * Requires ioredis (peer dependency).
+ * Safe for distributed / multi-pod deployments.
+ */
+
+import { BaseStore }    from './BaseStore.js'
+import { ErrorFactory } from '../errors/ErrorFactory.js'
+import { STORE_TYPES }  from '../constants/store.js'
+import { createLogger } from '../logger/LoggerFactory.js'
+
+const logger = createLogger('RedisStore')
+
+/**
+ * Atomically increments a counter key, setting TTL on first write.
+ * Returns: [newCount, ttlMs]
+ */
+const LUA_INCREMENT_WITH_TTL = `
+local current = redis.call('GET', KEYS[1])
+if current == false then
+  redis.call('SET', KEYS[1], 1, 'PX', ARGV[1])
+  return {1, tonumber(ARGV[1])}
+end
+local newVal = redis.call('INCR', KEYS[1])
+local pttl   = redis.call('PTTL', KEYS[1])
+return {newVal, pttl}
+`
+
+/**
+ * Atomically gets a JSON-encoded entry. Returns nil if absent/expired.
+ */
+const LUA_GET_ENTRY = `
+local val = redis.call('GET', KEYS[1])
+if val == false then return nil end
+return val
+`
+
+/**
+ * Atomically sets a JSON-encoded entry with a TTL in milliseconds.
+ */
+const LUA_SET_ENTRY = `
+redis.call('SET', KEYS[1], ARGV[1], 'PX', ARGV[2])
+return 1
+`
+
+export class RedisStore extends BaseStore {
+  /**
+   * @param {Object} options
+   * @param {Object} options.client   - ioredis client instance.
+   * @param {string} [options.prefix] - Key prefix. Default: 'rle:'.
+   */
+  constructor({ client, prefix = 'rle:' }) {
+    super(STORE_TYPES.REDIS)
+
+    if (!client) {
+      throw ErrorFactory.missingField('client', { store: 'RedisStore' })
+    }
+
+    this._client = client
+    this._prefix = prefix
+    this._defineScripts()
+    logger.info('RedisStore initialised', { prefix })
+  }
+
+  /**
+   * @param {string} key
+   * @returns {Promise<import('../types/index.js').StoreEntry|null>}
+   */
+  async get(key) {
+    try {
+      const raw = await this._client.get(this._prefixed(key))
+      if (!raw) {
+        return null
+      }
+      const entry = JSON.parse(raw)
+      if (Date.now() > entry.expiresAt) {
+        return null
+      }
+      return entry
+    } catch (cause) {
+      throw ErrorFactory.storeOperationFailed('read', cause, { key })
+    }
+  }
+
+  /**
+   * @param {string}                                  key
+   * @param {import('../types/index.js').StoreEntry}  entry
+   * @param {number}                                  ttlMs
+   * @returns {Promise<void>}
+   */
+  async set(key, entry, ttlMs) {
+    try {
+      await this._client.call(
+        'EVALSHA', this._scripts.setEntry,
+        1,
+        this._prefixed(key),
+        JSON.stringify({ ...entry, expiresAt: Date.now() + ttlMs }),
+        String(ttlMs),
+      )
+    } catch (cause) {
+      throw ErrorFactory.storeOperationFailed('write', cause, { key })
+    }
+  }
+
+  /**
+   * @param {string} key
+   * @param {number} ttlMs
+   * @returns {Promise<number>}
+   */
+  async increment(key, ttlMs) {
+    try {
+      const result = await this._client.call(
+        'EVALSHA', this._scripts.incrementWithTtl,
+        1,
+        this._prefixed(key),
+        String(ttlMs),
+      )
+      return result[0]
+    } catch (cause) {
+      throw ErrorFactory.storeOperationFailed('write', cause, { key })
+    }
+  }
+
+  /**
+   * @param {string} key
+   * @returns {Promise<void>}
+   */
+  async delete(key) {
+    try {
+      await this._client.del(this._prefixed(key))
+    } catch (cause) {
+      throw ErrorFactory.storeOperationFailed('write', cause, { key })
+    }
+  }
+
+  /**
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    await this._client.quit()
+    logger.info('RedisStore connection closed')
+  }
+
+  /**
+   * Loads Lua scripts into Redis and caches their SHAs.
+   */
+  _defineScripts() {
+    const load = (script) => this._client.script('LOAD', script)
+
+    this._scripts = {}
+
+    Promise.all([
+      load(LUA_INCREMENT_WITH_TTL).then((sha) => { this._scripts.incrementWithTtl = sha }),
+      load(LUA_GET_ENTRY).then((sha)          => { this._scripts.getEntry         = sha }),
+      load(LUA_SET_ENTRY).then((sha)          => { this._scripts.setEntry         = sha }),
+    ]).catch((cause) => {
+      logger.error('Failed to load Lua scripts', { error: cause.message })
+    })
+  }
+
+  /**
+   * @param {string} key
+   * @returns {string}
+   */
+  _prefixed(key) {
+    return `${this._prefix}${key}`
+  }
+}

package/src/types/index.js

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Central JSDoc type contracts for ratelimit-engine.
+ * All layers depend on these types — never on concrete implementations.
+ */
+
+/**
+ * Result returned by every algorithm check.
+ *
+ * @typedef {Object} RateLimitResult
+ * @property {boolean} allowed      - Whether the request is permitted.
+ * @property {number}  limit        - Maximum requests allowed in the window.
+ * @property {number}  remaining    - Requests remaining in the current window.
+ * @property {Date}    resetAt      - When the current window resets.
+ * @property {number}  [retryAfter] - Seconds until the client may retry (only when allowed=false).
+ */
+
+/**
+ * Raw entry persisted in a store for a given key.
+ *
+ * @typedef {Object} StoreEntry
+ * @property {number} count     - Request count in the current window.
+ * @property {number} windowStart - Window start timestamp (ms since epoch).
+ * @property {number} expiresAt - Absolute expiry timestamp (ms since epoch).
+ * @property {Object} [meta]    - Algorithm-specific extra fields (e.g. tokens, lastLeak).
+ */
+
+/**
+ * Request context passed through the engine and resolvers.
+ *
+ * @typedef {Object} RequestContext
+ * @property {string}  ip              - Client IP address.
+ * @property {string}  [userId]        - Authenticated user ID, if available.
+ * @property {string}  [apiKey]        - API key from request headers, if present.
+ * @property {string}  method          - HTTP method (GET, POST, …).
+ * @property {string}  path            - Request path.
+ * @property {Object}  headers         - Raw request headers.
+ * @property {Object}  [rawRequest]    - Original framework request object.
+ */
+
+/**
+ * Core engine configuration passed to createLimiter().
+ *
+ * @typedef {Object} LimiterConfig
+ * @property {import('../algorithms/BaseAlgorithm.js').BaseAlgorithm} algorithm - Algorithm instance.
+ * @property {import('../stores/BaseStore.js').BaseStore}             store     - Store instance.
+ * @property {KeyResolverFn}   keyBy      - Function that derives the rate limit key from context.
+ * @property {boolean}         [failOpen]  - Allow requests when store is unavailable. Default: true.
+ * @property {OnBlockedHook}   [onBlocked] - Called when a request is blocked.
+ * @property {OnAllowedHook}   [onAllowed] - Called when a request is allowed.
+ * @property {import('../logger/Logger.js').Logger} [logger] - Custom logger instance.
+ */
+
+/**
+ * Function that derives a rate limit key string from a request context.
+ *
+ * @typedef {function(RequestContext): (string|Promise<string>)} KeyResolverFn
+ */
+
+/**
+ * Hook called when a request is blocked by the rate limiter.
+ *
+ * @typedef {function(RequestContext, RateLimitResult): void} OnBlockedHook
+ */
+
+/**
+ * Hook called when a request is allowed through.
+ *
+ * @typedef {function(RequestContext, RateLimitResult): void} OnAllowedHook
+ */
+
+/**
+ * Logger interface — implement this to plug in Winston, Pino, etc.
+ *
+ * @typedef {Object} LoggerInterface
+ * @property {function(string, Object=): void} debug
+ * @property {function(string, Object=): void} info
+ * @property {function(string, Object=): void} warn
+ * @property {function(string, Object=): void} error
+ */