Rate Limiter

interface RateRule {
  client_id: string;       // IP, user_id, or api_key
  endpoint: string;        // '/api/search' or '*' for global
  limit: number;           // max requests allowed
  window_sec: number;      // window duration in seconds
  tier: 'free' | 'pro' | 'enterprise';
  created_at: Date;
  updated_at: Date;
}

interface RateCheckResult {
  allowed: boolean;
  current_count: number;
  limit: number;
  remaining: number;
  reset_at: number;        // unix timestamp when window resets
  retry_after?: number;    // seconds to wait if rejected
}

class RateLimiterService {
  /**
   * Check and increment counter for a request.
   * @returns RateCheckResult — caller decides whether to allow/reject
   */
  async isAllowed(clientId: string, endpoint: string): Promise<RateCheckResult>

  /**
   * Load rule for client+endpoint. Falls back to tier default, then global default.
   * Cached in-memory for 60 seconds.
   */
  async getRuleFor(clientId: string, endpoint: string): Promise<RateRule>

  /**
   * Force-refresh the rules cache for a client (e.g. after tier upgrade).
   */
  async invalidateRulesCache(clientId: string): Promise<void>
}

// --- Data Types ---

interface RateRule {
  clientId: string;
  endpoint: string;        // '*' = wildcard (global rule)
  limit: number;
  windowSec: number;
  tier: 'free' | 'pro' | 'enterprise';
}

interface RateCheckResult {
  allowed: boolean;
  currentCount: number;
  limit: number;
  remaining: number;
  resetAt: number;         // unix timestamp
  retryAfter?: number;     // only set when allowed = false
}

// --- Service ---

class RateLimiterService {
  private rulesCache: Map<string, { rule: RateRule; expiresAt: number }>;
  private readonly CACHE_TTL_MS = 60_000;

  constructor(
    private readonly redis: RedisClient,
    private readonly rulesDb: RulesRepository,
  ) {}

  async isAllowed(clientId: string, endpoint: string): Promise<RateCheckResult> {
    const rule = await this.getRuleFor(clientId, endpoint);
    const windowBucket = Math.floor(Date.now() / 1000 / rule.windowSec);
    const key = `rate:${clientId}:${endpoint}:${windowBucket}`;

    try {
      const count = await this.redis.eval(
        LUA_INCR_SCRIPT,
        [key],
        [String(rule.windowSec * 2)]   // TTL = 2 windows
      ) as number;

      const allowed = count <= rule.limit;
      const resetAt = (windowBucket + 1) * rule.windowSec;

      return {
        allowed,
        currentCount: count,
        limit: rule.limit,
        remaining: Math.max(0, rule.limit - count),
        resetAt,
        retryAfter: allowed ? undefined : resetAt - Math.floor(Date.now() / 1000),
      };
    } catch (err) {
      // Fail open on Redis error
      logger.error('RateLimiter Redis error', { err });
      metrics.increment('rate_limiter.redis.error');
      return { allowed: true, currentCount: 0, limit: rule.limit, remaining: rule.limit, resetAt: 0 };
    }
  }

  private async getRuleFor(clientId: string, endpoint: string): Promise<RateRule> {
    const cacheKey = `${clientId}:${endpoint}`;
    const cached = this.rulesCache.get(cacheKey);
    if (cached && cached.expiresAt > Date.now()) return cached.rule;

    // Lookup priority: exact match → wildcard endpoint → tier default
    const rule =
      await this.rulesDb.findOne({ clientId, endpoint }) ??
      await this.rulesDb.findOne({ clientId, endpoint: '*' }) ??
      DEFAULT_RULES['free'];

    this.rulesCache.set(cacheKey, { rule, expiresAt: Date.now() + this.CACHE_TTL_MS });
    return rule;
  }
}

// --- Lua Script (atomic INCR + EXPIRE) ---

const LUA_INCR_SCRIPT = `
local count = redis.call('INCR', KEYS[1])
if count == 1 then
  redis.call('EXPIRE', KEYS[1], ARGV[1])
end
return count
`;

// --- Repository ---

interface RulesRepository {
  findOne(query: { clientId: string; endpoint: string }): Promise<RateRule | null>;
  upsert(rule: RateRule): Promise<void>;
  deleteById(id: string): Promise<void>;
}