webspresso 0.0.104 → 0.0.106

package/core/rate-limit/index.js

@@ -0,0 +1,22 @@
+/**
+ * Webspresso Core Zero-Dependency Rate Limiter Engine
+ * @module core/rate-limit
+ */
+
+'use strict';
+
+const { RateLimiter, createRateLimiter, rateLimit } = require('./limiter');
+const { MemoryRateLimitStore } = require('./stores/memory');
+const { RedisRateLimitStore } = require('./stores/redis');
+const { parseWindow, extractClientIp, formatResetSeconds } = require('./utils');
+
+module.exports = {
+  RateLimiter,
+  createRateLimiter,
+  rateLimit,
+  MemoryRateLimitStore,
+  RedisRateLimitStore,
+  parseWindow,
+  extractClientIp,
+  formatResetSeconds,
+};

package/core/rate-limit/limiter.js

@@ -0,0 +1,219 @@
+/**
+ * Webspresso Core Rate Limiter Engine
+ * Zero-dependency, framework-agnostic rate limiting middleware for Express and Hono.
+ * Implements RFC 6585 and IETF Draft standard RateLimit headers.
+ * @module core/rate-limit/limiter
+ */
+
+'use strict';
+
+const { parseWindow, extractClientIp, formatResetSeconds } = require('./utils');
+const { MemoryRateLimitStore } = require('./stores/memory');
+const { TooManyRequestsError } = require('../errors');
+
+class RateLimiter {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.limit=60] - Maximum requests allowed in the time window
+   * @param {number} [options.max=60] - Alias for options.limit
+   * @param {string|number} [options.window='1m'] - Time window in ms or string ('1m', '10s', etc.)
+   * @param {string|number} [options.windowMs] - Alias for options.window
+   * @param {Object} [options.store] - Store instance (MemoryRateLimitStore or RedisRateLimitStore)
+   * @param {Function} [options.keyGenerator] - Custom key generator (req) => string
+   * @param {Function} [options.skip] - Predicate function (req) => boolean
+   * @param {boolean} [options.standardHeaders=true] - Send RateLimit-* headers
+   * @param {boolean} [options.legacyHeaders=false] - Send X-RateLimit-* headers
+   * @param {boolean} [options.skipFailedRequests=false] - Don't count failed requests (status >= 400)
+   * @param {boolean} [options.skipSuccessfulRequests=false] - Don't count successful requests (status < 400)
+   * @param {number} [options.statusCode=429] - Status code on limit exceeded
+   * @param {string|Object} [options.message] - Response body on limit exceeded
+   * @param {Function} [options.handler] - Custom handler when limit exceeded
+   */
+  constructor(options = {}) {
+    this.limit = options.limit || options.max || 60;
+    this.windowMs = parseWindow(options.windowMs || options.window || 60000);
+    this.store = options.store || new MemoryRateLimitStore();
+    this.keyGenerator = typeof options.keyGenerator === 'function' ? options.keyGenerator : extractClientIp;
+    this.skip = typeof options.skip === 'function' ? options.skip : (() => false);
+    this.standardHeaders = options.standardHeaders !== false;
+    this.legacyHeaders = Boolean(options.legacyHeaders);
+    this.skipFailedRequests = Boolean(options.skipFailedRequests);
+    this.skipSuccessfulRequests = Boolean(options.skipSuccessfulRequests);
+    this.statusCode = options.statusCode || 429;
+    this.message = options.message || {
+      error: 'Too Many Requests',
+      message: 'Too many requests, please try again later.',
+      statusCode: this.statusCode,
+    };
+    this.handler = typeof options.handler === 'function' ? options.handler : null;
+
+    // Bind middleware
+    this.middleware = this.middleware.bind(this);
+  }
+
+  /**
+   * Set standard and legacy RateLimit headers on response
+   * @private
+   */
+  _setHeaders(setter, limit, remaining, resetSeconds, resetDate, isExceeded) {
+    if (this.standardHeaders) {
+      setter('ratelimit-limit', String(limit));
+      setter('ratelimit-remaining', String(remaining));
+      setter('ratelimit-reset', String(resetSeconds));
+      setter('ratelimit-policy', `${limit};w=${Math.ceil(this.windowMs / 1000)}`);
+    }
+
+    if (this.legacyHeaders) {
+      setter('x-ratelimit-limit', String(limit));
+      setter('x-ratelimit-remaining', String(remaining));
+      setter('x-ratelimit-reset', String(Math.ceil(resetDate.getTime() / 1000)));
+    }
+
+    if (isExceeded) {
+      setter('retry-after', String(Math.max(1, resetSeconds)));
+    }
+  }
+
+  /**
+   * Universal Middleware Handler
+   * Works on Express (req, res, next) and Hono (c, next)
+   */
+  async middleware(reqOrC, resOrNext, maybeNext) {
+    // 1. Detect Hono vs Express signature
+    const isHono = typeof reqOrC.header === 'function' && typeof reqOrC.text === 'function' && typeof resOrNext === 'function';
+
+    if (isHono) {
+      const c = reqOrC;
+      const next = resOrNext;
+
+      const reqMock = {
+        ip: c.req.header('cf-connecting-ip') || c.req.header('x-forwarded-for') || '127.0.0.1',
+        headers: c.req.header(),
+        path: c.req.path,
+        method: c.req.method,
+      };
+
+      if (this.skip(reqMock)) {
+        return next();
+      }
+
+      const key = String(this.keyGenerator(reqMock) || '127.0.0.1');
+      const { totalHits, resetTime } = await this.store.increment(key, this.windowMs);
+      const remaining = Math.max(0, this.limit - totalHits);
+      const resetSeconds = formatResetSeconds(resetTime);
+      const isExceeded = totalHits > this.limit;
+
+      this._setHeaders(
+        (headerName, headerVal) => c.header(headerName, headerVal),
+        this.limit,
+        remaining,
+        resetSeconds,
+        resetTime,
+        isExceeded
+      );
+
+      if (isExceeded) {
+        if (this.handler) {
+          return this.handler(c, {
+            totalHits,
+            remaining,
+            resetTime,
+            limit: this.limit,
+          });
+        }
+        return c.json(typeof this.message === 'object' ? this.message : { message: this.message }, this.statusCode);
+      }
+
+      return next();
+    }
+
+    // 2. Standard Express signature: (req, res, next)
+    const req = reqOrC;
+    const res = resOrNext;
+    const next = maybeNext || (() => {});
+
+    if (this.skip(req)) {
+      return next();
+    }
+
+    const key = String(this.keyGenerator(req) || '127.0.0.1');
+    const { totalHits, resetTime } = await this.store.increment(key, this.windowMs);
+    const remaining = Math.max(0, this.limit - totalHits);
+    const resetSeconds = formatResetSeconds(resetTime);
+    const isExceeded = totalHits > this.limit;
+
+    // Attach info to request
+    req.rateLimit = {
+      limit: this.limit,
+      current: totalHits,
+      remaining,
+      resetTime,
+    };
+
+    if (res && typeof res.setHeader === 'function') {
+      this._setHeaders(
+        (name, val) => res.setHeader(name, val),
+        this.limit,
+        remaining,
+        resetSeconds,
+        resetTime,
+        isExceeded
+      );
+    }
+
+    // Handle skip on success / failure
+    if (res && typeof res.on === 'function' && (this.skipFailedRequests || this.skipSuccessfulRequests)) {
+      res.on('finish', () => {
+        const isFailed = res.statusCode >= 400;
+        if (isFailed && this.skipFailedRequests) {
+          this.store.decrement(key).catch(() => {});
+        } else if (!isFailed && this.skipSuccessfulRequests) {
+          this.store.decrement(key).catch(() => {});
+        }
+      });
+    }
+
+    if (isExceeded) {
+      if (this.handler) {
+        return this.handler(req, res, next, {
+          totalHits,
+          remaining,
+          resetTime,
+          limit: this.limit,
+        });
+      }
+
+      if (res && typeof res.status === 'function') {
+        if (typeof this.message === 'object') {
+          return res.status(this.statusCode).json(this.message);
+        }
+        return res.status(this.statusCode).send(String(this.message));
+      }
+
+      const err = new TooManyRequestsError(
+        typeof this.message === 'string' ? this.message : this.message.message || 'Too Many Requests'
+      );
+      return next(err);
+    }
+
+    return next();
+  }
+}
+
+/**
+ * Factory helper for creating rate limiter middleware
+ * @param {Object} [options]
+ * @returns {import('express').RequestHandler & { limiter: RateLimiter }}
+ */
+function createRateLimiter(options = {}) {
+  const limiter = new RateLimiter(options);
+  const mw = (req, res, next) => limiter.middleware(req, res, next);
+  mw.limiter = limiter;
+  return mw;
+}
+
+module.exports = {
+  RateLimiter,
+  createRateLimiter,
+  rateLimit: createRateLimiter,
+};

package/core/rate-limit/stores/memory.js

@@ -0,0 +1,129 @@
+/**
+ * Webspresso In-Memory Rate Limit Store
+ * Sliding window algorithm with automatic cleanup and memory bound safety.
+ * @module core/rate-limit/stores/memory
+ */
+
+'use strict';
+
+class MemoryRateLimitStore {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.cleanupIntervalMs=30000] - Interval to sweep expired keys
+   */
+  constructor(options = {}) {
+    /** @type {Map<string, number[]>} Map of key -> timestamps */
+    this.hits = new Map();
+    this.cleanupIntervalMs = options.cleanupIntervalMs || 30000;
+
+    // Periodic sweep to prevent memory growth
+    this._cleanupTimer = setInterval(() => {
+      this.sweep();
+    }, this.cleanupIntervalMs);
+
+    if (this._cleanupTimer.unref) {
+      this._cleanupTimer.unref();
+    }
+  }
+
+  /**
+   * Increment request count for a given key within windowMs
+   * @param {string} key
+   * @param {number} windowMs
+   * @returns {Promise<{ totalHits: number, resetTime: Date }>}
+   */
+  async increment(key, windowMs) {
+    const now = Date.now();
+    const threshold = now - windowMs;
+
+    let timestamps = this.hits.get(key);
+    if (!timestamps) {
+      timestamps = [];
+      this.hits.set(key, timestamps);
+    }
+
+    // Filter out expired timestamps
+    let validIndex = 0;
+    while (validIndex < timestamps.length && timestamps[validIndex] <= threshold) {
+      validIndex++;
+    }
+    if (validIndex > 0) {
+      timestamps.splice(0, validIndex);
+    }
+
+    timestamps.push(now);
+
+    const oldest = timestamps[0];
+    const resetTime = new Date(oldest + windowMs);
+
+    return {
+      totalHits: timestamps.length,
+      resetTime,
+    };
+  }
+
+  /**
+   * Decrement request count (e.g. when request is skipped or failed)
+   * @param {string} key
+   * @returns {Promise<void>}
+   */
+  async decrement(key) {
+    const timestamps = this.hits.get(key);
+    if (timestamps && timestamps.length > 0) {
+      timestamps.pop();
+      if (timestamps.length === 0) {
+        this.hits.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Reset hits for a single key
+   * @param {string} key
+   * @returns {Promise<void>}
+   */
+  async resetKey(key) {
+    this.hits.delete(key);
+  }
+
+  /**
+   * Reset all stored keys
+   * @returns {Promise<void>}
+   */
+  async resetAll() {
+    this.hits.clear();
+  }
+
+  /**
+   * Sweep stale keys that have no recent hits
+   */
+  sweep() {
+    const now = Date.now();
+    for (const [key, timestamps] of this.hits.entries()) {
+      if (timestamps.length === 0) {
+        this.hits.delete(key);
+      } else {
+        const latest = timestamps[timestamps.length - 1];
+        // If the newest hit is older than 1 hour, safely purge
+        if (now - latest > 3600000) {
+          this.hits.delete(key);
+        }
+      }
+    }
+  }
+
+  /**
+   * Destroy store and stop background cleanup timer
+   */
+  destroy() {
+    if (this._cleanupTimer) {
+      clearInterval(this._cleanupTimer);
+      this._cleanupTimer = null;
+    }
+    this.hits.clear();
+  }
+}
+
+module.exports = {
+  MemoryRateLimitStore,
+};

package/core/rate-limit/stores/redis.js

@@ -0,0 +1,151 @@
+/**
+ * Webspresso Redis Rate Limit Store
+ * Distributed sliding window rate limiter backed by Redis.
+ * Supports official redis, ioredis, or Webspresso MiniRedisClient.
+ * @module core/rate-limit/stores/redis
+ */
+
+'use strict';
+
+class RedisRateLimitStore {
+  /**
+   * @param {Object} options
+   * @param {Object} options.client - Redis client instance
+   * @param {string} [options.prefix='rl:'] - Key prefix
+   * @param {boolean} [options.passOnStoreError=true] - Fail-open on Redis connection errors
+   */
+  constructor(options = {}) {
+    if (!options.client) {
+      throw new Error('[RedisRateLimitStore] Requires an initialized redis client');
+    }
+    this.client = options.client;
+    this.prefix = options.prefix || 'rl:';
+    this.passOnStoreError = options.passOnStoreError !== false;
+  }
+
+  _getKey(key) {
+    return `${this.prefix}${key}`;
+  }
+
+  /**
+   * Increment request count for key within windowMs
+   * @param {string} key
+   * @param {number} windowMs
+   * @returns {Promise<{ totalHits: number, resetTime: Date }>}
+   */
+  async increment(key, windowMs) {
+    const redisKey = this._getKey(key);
+    const now = Date.now();
+    const threshold = now - windowMs;
+    const member = `${now}-${Math.random().toString(36).slice(2, 8)}`;
+
+    try {
+      // 1. If client supports multi() with sorted sets (ioredis / node-redis)
+      if (typeof this.client.multi === 'function') {
+        const multi = this.client.multi();
+        multi.zremrangebyscore(redisKey, 0, threshold);
+        multi.zadd(redisKey, now, member);
+        multi.zcard(redisKey);
+        multi.pexpire(redisKey, windowMs + 1000);
+
+        const execRes = await multi.exec();
+        // Handle ioredis tuple [err, res] vs node-redis single value
+        const zcardRes = execRes[2];
+        const count = Array.isArray(zcardRes) ? zcardRes[1] : zcardRes;
+
+        return {
+          totalHits: Number(count) || 1,
+          resetTime: new Date(now + windowMs),
+        };
+      }
+
+      // 2. Fallback using individual commands or INCR + PEXPIRE
+      if (typeof this.client.zremrangebyscore === 'function' && typeof this.client.zadd === 'function') {
+        await this.client.zremrangebyscore(redisKey, 0, threshold);
+        await this.client.zadd(redisKey, now, member);
+        const count = await this.client.zcard(redisKey);
+        if (typeof this.client.pexpire === 'function') {
+          await this.client.pexpire(redisKey, windowMs + 1000);
+        }
+        return {
+          totalHits: Number(count) || 1,
+          resetTime: new Date(now + windowMs),
+        };
+      }
+
+      // 3. Fallback using key per time bucket
+      const bucket = Math.floor(now / windowMs);
+      const bucketKey = `${redisKey}:${bucket}`;
+      let count = 1;
+      if (typeof this.client.incr === 'function') {
+        count = await this.client.incr(bucketKey);
+        if (count === 1 && typeof this.client.pexpire === 'function') {
+          await this.client.pexpire(bucketKey, windowMs + 1000);
+        }
+      }
+
+      return {
+        totalHits: Number(count) || 1,
+        resetTime: new Date((bucket + 1) * windowMs),
+      };
+    } catch (err) {
+      if (this.passOnStoreError) {
+        // Fail-open: allow request to proceed if Redis is down
+        return {
+          totalHits: 1,
+          resetTime: new Date(now + windowMs),
+        };
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Decrement request count
+   * @param {string} key
+   * @returns {Promise<void>}
+   */
+  async decrement(key) {
+    const redisKey = this._getKey(key);
+    try {
+      if (typeof this.client.zpopmax === 'function') {
+        await this.client.zpopmax(redisKey, 1);
+      } else if (typeof this.client.decr === 'function') {
+        await this.client.decr(redisKey);
+      }
+    } catch (_) {}
+  }
+
+  /**
+   * Reset hits for a single key
+   * @param {string} key
+   * @returns {Promise<void>}
+   */
+  async resetKey(key) {
+    const redisKey = this._getKey(key);
+    try {
+      if (typeof this.client.del === 'function') {
+        await this.client.del(redisKey);
+      }
+    } catch (_) {}
+  }
+
+  /**
+   * Reset all keys matching prefix
+   * @returns {Promise<void>}
+   */
+  async resetAll() {
+    try {
+      if (typeof this.client.keys === 'function' && typeof this.client.del === 'function') {
+        const keys = await this.client.keys(`${this.prefix}*`);
+        if (keys && keys.length > 0) {
+          await this.client.del(...keys);
+        }
+      }
+    } catch (_) {}
+  }
+}
+
+module.exports = {
+  RedisRateLimitStore,
+};

package/core/rate-limit/utils.js

@@ -0,0 +1,112 @@
+/**
+ * Webspresso Core Rate Limit Utilities
+ * @module core/rate-limit/utils
+ */
+
+'use strict';
+
+/**
+ * Parse window duration string or number into milliseconds
+ * Supports: 500, '500ms', '10s', '1m', '15m', '1h', '1d'
+ * @param {string|number} window
+ * @returns {number} duration in milliseconds
+ */
+function parseWindow(window) {
+  if (typeof window === 'number' && !Number.isNaN(window) && window > 0) {
+    return Math.floor(window);
+  }
+
+  if (typeof window === 'string') {
+    const trimmed = window.trim().toLowerCase();
+    const match = trimmed.match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)?$/);
+    if (match) {
+      const val = parseFloat(match[1]);
+      const unit = match[2] || 'ms';
+
+      switch (unit) {
+        case 'ms': return Math.floor(val);
+        case 's': return Math.floor(val * 1000);
+        case 'm': return Math.floor(val * 60 * 1000);
+        case 'h': return Math.floor(val * 60 * 60 * 1000);
+        case 'd': return Math.floor(val * 24 * 60 * 60 * 1000);
+        default: return Math.floor(val);
+      }
+    }
+  }
+
+  // Fallback default: 60,000ms (1 minute)
+  return 60000;
+}
+
+/**
+ * Extract client IP address from incoming request with reverse proxy support
+ * @param {Object} req
+ * @returns {string} client IP
+ */
+function extractClientIp(req) {
+  if (!req) return '127.0.0.1';
+
+  // 1. Direct req.ip (populated by Express if trust proxy is enabled)
+  if (req.ip && typeof req.ip === 'string') {
+    return req.ip;
+  }
+
+  const headers = req.headers || (req.header ? {
+    'cf-connecting-ip': req.header('cf-connecting-ip'),
+    'x-forwarded-for': req.header('x-forwarded-for'),
+    'x-real-ip': req.header('x-real-ip'),
+    'fastly-client-ip': req.header('fastly-client-ip'),
+  } : {});
+
+  // 2. Cloudflare Connecting IP
+  const cfIp = headers['cf-connecting-ip'];
+  if (cfIp && typeof cfIp === 'string') {
+    return cfIp.trim();
+  }
+
+  // 3. Fastly / Akamai / True-Client-IP
+  const fastlyIp = headers['fastly-client-ip'] || headers['true-client-ip'];
+  if (fastlyIp && typeof fastlyIp === 'string') {
+    return fastlyIp.trim();
+  }
+
+  // 4. Standard X-Forwarded-For (take the first client IP in chain)
+  const forwardedFor = headers['x-forwarded-for'];
+  if (forwardedFor && typeof forwardedFor === 'string') {
+    const parts = forwardedFor.split(',');
+    if (parts.length > 0 && parts[0].trim()) {
+      return parts[0].trim();
+    }
+  }
+
+  // 5. X-Real-IP
+  const realIp = headers['x-real-ip'];
+  if (realIp && typeof realIp === 'string') {
+    return realIp.trim();
+  }
+
+  // 6. Socket remote address
+  const socketIp = req.socket?.remoteAddress || req.connection?.remoteAddress;
+  if (socketIp && typeof socketIp === 'string') {
+    return socketIp.replace(/^::ffff:/, ''); // Normalize IPv4-mapped IPv6
+  }
+
+  return '127.0.0.1';
+}
+
+/**
+ * Format reset time as seconds remaining from current timestamp
+ * @param {Date|number} resetTime
+ * @returns {number} seconds until reset
+ */
+function formatResetSeconds(resetTime) {
+  const targetTime = resetTime instanceof Date ? resetTime.getTime() : Number(resetTime);
+  const diffMs = targetTime - Date.now();
+  return Math.max(0, Math.ceil(diffMs / 1000));
+}
+
+module.exports = {
+  parseWindow,
+  extractClientIp,
+  formatResetSeconds,
+};