@dotdo/postgres 0.1.0

package/src/middleware/rate-limit.ts

@@ -0,0 +1,840 @@
+/**
+ * Rate Limiting Middleware for Cloudflare Workers
+ * Task: postgres-k06 - Add rate limiting middleware to Worker entry points
+ *
+ * Implements sliding window rate limiting using DO storage or KV.
+ * Supports rate limiting by IP, user, or custom key.
+ */
+import type { MiddlewareHandler } from 'hono'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Generic storage backend interface for rate limit data.
+ *
+ * @typeParam T - The type of data stored (defaults to RateLimitWindow for backwards compatibility)
+ */
+export interface GenericRateLimitStorage<T = RateLimitWindow> {
+  /**
+   * Get the stored data for a key
+   */
+  get(key: string): Promise<T | null>
+
+  /**
+   * Store data for a key
+   */
+  set(key: string, data: T, ttlMs: number): Promise<void>
+}
+
+/**
+ * Storage backend interface for rate limit data.
+ * This is the default storage interface for sliding window rate limiting.
+ */
+export interface RateLimitStorage extends GenericRateLimitStorage<RateLimitWindow> {}
+
+/**
+ * Sliding window data structure
+ */
+export interface RateLimitWindow {
+  /** Request counts per sub-window */
+  counts: number[]
+  /** Timestamp of the start of the current window (ms) */
+  windowStart: number
+  /** Total requests in the current window */
+  total: number
+}
+
+/**
+ * Rate limit key extraction modes
+ */
+export type RateLimitKeyMode = 'ip' | 'user' | 'custom'
+
+/**
+ * Rate limit options
+ */
+export interface RateLimitOptions {
+  /**
+   * Maximum number of requests allowed in the window
+   * @default 60
+   */
+  requests?: number
+
+  /**
+   * Window duration in milliseconds
+   * @default 60000 (1 minute)
+   */
+  windowMs?: number
+
+  /**
+   * Number of sub-windows for sliding window algorithm
+   * More sub-windows = more accuracy but more storage
+   * @default 10
+   */
+  subWindows?: number
+
+  /**
+   * Key extraction mode
+   * - 'ip': Rate limit by client IP address
+   * - 'user': Rate limit by user ID from request context
+   * - 'custom': Use custom key extractor function
+   * @default 'ip'
+   */
+  keyMode?: RateLimitKeyMode
+
+  /**
+   * Custom key extractor function
+   * Required when keyMode is 'custom'
+   */
+  keyExtractor?: (c: HonoContext) => string | null
+
+  /**
+   * Key prefix for storage
+   * @default 'ratelimit:'
+   */
+  keyPrefix?: string
+
+  /**
+   * Header to extract IP from (e.g., 'CF-Connecting-IP', 'X-Forwarded-For')
+   * @default 'CF-Connecting-IP'
+   */
+  ipHeader?: string
+
+  /**
+   * Header or context key for user ID
+   * @default 'X-User-ID'
+   */
+  userHeader?: string
+
+  /**
+   * Whether to skip rate limiting for certain requests
+   */
+  skip?: (c: HonoContext) => boolean | Promise<boolean>
+
+  /**
+   * Custom response handler when rate limit is exceeded
+   */
+  onRateLimited?: (c: HonoContext, info: RateLimitInfo) => Response | Promise<Response>
+
+  /**
+   * Storage backend (DO storage or KV)
+   * If not provided, will use in-memory storage (not recommended for production)
+   */
+  storage?: RateLimitStorage
+}
+
+/**
+ * Rate limit status information
+ */
+export interface RateLimitInfo {
+  /** Total requests allowed in window */
+  limit: number
+  /** Remaining requests in current window */
+  remaining: number
+  /** Time in seconds until the rate limit resets */
+  resetAfterSeconds: number
+  /** Whether the request was rate limited */
+  limited: boolean
+}
+
+/**
+ * Hono context interface (minimal)
+ */
+interface HonoContext {
+  req: {
+    header(name: string): string | undefined
+    raw: Request
+  }
+  header(name: string, value: string): void
+  json(data: unknown, status?: number): Response
+  set(key: string, value: unknown): void
+  get(key: string): unknown
+}
+
+// ============================================================================
+// Storage Implementations
+// ============================================================================
+
+/**
+ * Generic in-memory storage for rate limiting (for testing/development only).
+ *
+ * @typeParam T - The type of data stored
+ */
+export class GenericInMemoryStorage<T> implements GenericRateLimitStorage<T> {
+  private store = new Map<string, { data: T; expiresAt: number }>()
+
+  async get(key: string): Promise<T | null> {
+    const entry = this.store.get(key)
+    if (!entry) return null
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key)
+      return null
+    }
+    return entry.data
+  }
+
+  async set(key: string, data: T, ttlMs: number): Promise<void> {
+    this.store.set(key, {
+      data,
+      expiresAt: Date.now() + ttlMs,
+    })
+  }
+
+  /** Clear all entries (for testing) */
+  clear(): void {
+    this.store.clear()
+  }
+}
+
+/**
+ * In-memory storage for rate limiting (for testing/development only).
+ * Alias for GenericInMemoryStorage<RateLimitWindow> for backwards compatibility.
+ */
+export class InMemoryRateLimitStorage extends GenericInMemoryStorage<RateLimitWindow> implements RateLimitStorage {}
+
+/**
+ * In-memory storage for token bucket rate limiting (for testing/development only).
+ */
+export class InMemoryTokenBucketStorage extends GenericInMemoryStorage<TokenBucket> implements TokenBucketStorage {}
+
+/**
+ * Generic Durable Object storage adapter for rate limiting.
+ *
+ * @typeParam T - The type of data stored
+ */
+export class GenericDOStorage<T> implements GenericRateLimitStorage<T> {
+  constructor(private storage: DurableObjectStorage) {}
+
+  async get(key: string): Promise<T | null> {
+    const data = await this.storage.get<T>(key)
+    return data ?? null
+  }
+
+  async set(key: string, data: T, _ttlMs: number): Promise<void> {
+    // Use alarm for TTL cleanup
+    await this.storage.put(key, data)
+    // Schedule cleanup - DO storage doesn't have native TTL
+    // The sliding window algorithm handles stale data naturally
+  }
+}
+
+/**
+ * Durable Object storage adapter for rate limiting.
+ * Alias for GenericDOStorage<RateLimitWindow> for backwards compatibility.
+ */
+export class DurableObjectRateLimitStorage extends GenericDOStorage<RateLimitWindow> implements RateLimitStorage {}
+
+/**
+ * Durable Object storage adapter for token bucket rate limiting.
+ */
+export class DurableObjectTokenBucketStorage extends GenericDOStorage<TokenBucket> implements TokenBucketStorage {}
+
+/**
+ * Generic KV storage adapter for rate limiting.
+ *
+ * @typeParam T - The type of data stored
+ */
+export class GenericKVStorage<T> implements GenericRateLimitStorage<T> {
+  constructor(private kv: KVNamespace) {}
+
+  async get(key: string): Promise<T | null> {
+    const data = await this.kv.get<T>(key, 'json')
+    return data ?? null
+  }
+
+  async set(key: string, data: T, ttlMs: number): Promise<void> {
+    // KV TTL is in seconds, minimum 60 seconds
+    const ttlSeconds = Math.max(60, Math.ceil(ttlMs / 1000))
+    await this.kv.put(key, JSON.stringify(data), { expirationTtl: ttlSeconds })
+  }
+}
+
+/**
+ * KV storage adapter for rate limiting.
+ * Alias for GenericKVStorage<RateLimitWindow> for backwards compatibility.
+ */
+export class KVRateLimitStorage extends GenericKVStorage<RateLimitWindow> implements RateLimitStorage {}
+
+/**
+ * KV storage adapter for token bucket rate limiting.
+ */
+export class KVTokenBucketStorage extends GenericKVStorage<TokenBucket> implements TokenBucketStorage {}
+
+// ============================================================================
+// Sliding Window Algorithm
+// ============================================================================
+
+/**
+ * Sliding window rate limiter implementation
+ *
+ * Uses a sliding window log algorithm with sub-windows for efficiency:
+ * - Divides the main window into N sub-windows
+ * - Each sub-window tracks request counts
+ * - Calculates weighted sum based on current position in window
+ * - More accurate than fixed window, more efficient than per-request logging
+ */
+export class SlidingWindowRateLimiter {
+  private requests: number
+  private windowMs: number
+  private subWindows: number
+  private subWindowMs: number
+  private storage: RateLimitStorage
+
+  constructor(options: Required<Pick<RateLimitOptions, 'requests' | 'windowMs' | 'subWindows' | 'storage'>>) {
+    this.requests = options.requests
+    this.windowMs = options.windowMs
+    this.subWindows = options.subWindows
+    this.subWindowMs = options.windowMs / options.subWindows
+    this.storage = options.storage
+  }
+
+  /**
+   * Check if a request should be rate limited
+   */
+  async check(key: string): Promise<RateLimitInfo> {
+    const now = Date.now()
+    const currentWindow = await this.storage.get(key)
+
+    // Initialize or rotate window
+    let window = this.rotateWindow(currentWindow, now)
+
+    // Calculate weighted request count using sliding window
+    const weightedCount = this.calculateWeightedCount(window, now)
+
+    // Check if rate limited - we need to check if adding this request would exceed
+    // The current count + 1 (this request) must not exceed the limit
+    const limited = weightedCount + 1 > this.requests
+
+    if (!limited) {
+      // Increment current sub-window
+      const currentSubWindowIndex = this.getCurrentSubWindowIndex(window, now)
+      window.counts[currentSubWindowIndex]!++
+      window.total++
+
+      // Save updated window
+      await this.storage.set(key, window, this.windowMs * 2)
+    }
+
+    // Calculate time until reset
+    const windowEnd = window.windowStart + this.windowMs
+    const resetAfterSeconds = Math.max(0, Math.ceil((windowEnd - now) / 1000))
+
+    // Remaining is: limit - (current weighted count + this request if allowed)
+    const currentCount = limited ? Math.ceil(weightedCount) : Math.ceil(weightedCount) + 1
+
+    return {
+      limit: this.requests,
+      remaining: Math.max(0, this.requests - currentCount),
+      resetAfterSeconds,
+      limited,
+    }
+  }
+
+  /**
+   * Rotate window if needed (handles time progression)
+   */
+  private rotateWindow(existing: RateLimitWindow | null, now: number): RateLimitWindow {
+    if (!existing) {
+      // Create new window
+      return {
+        counts: new Array(this.subWindows).fill(0),
+        windowStart: now - (now % this.subWindowMs),
+        total: 0,
+      }
+    }
+
+    const windowAge = now - existing.windowStart
+    const subWindowsElapsed = Math.floor(windowAge / this.subWindowMs)
+
+    if (subWindowsElapsed >= this.subWindows) {
+      // Entire window has elapsed, start fresh
+      return {
+        counts: new Array(this.subWindows).fill(0),
+        windowStart: now - (now % this.subWindowMs),
+        total: 0,
+      }
+    }
+
+    if (subWindowsElapsed > 0) {
+      // Rotate: shift out old sub-windows, add new ones
+      const newCounts = new Array(this.subWindows).fill(0)
+      for (let i = 0; i < this.subWindows - subWindowsElapsed; i++) {
+        newCounts[i] = existing.counts[i + subWindowsElapsed]
+      }
+
+      return {
+        counts: newCounts,
+        windowStart: existing.windowStart + subWindowsElapsed * this.subWindowMs,
+        total: newCounts.reduce((a, b) => a + b, 0),
+      }
+    }
+
+    return existing
+  }
+
+  /**
+   * Calculate weighted request count using sliding window
+   *
+   * For a proper sliding window, we count all requests in all sub-windows.
+   * The sliding window effect is achieved through the rotation logic which
+   * removes old sub-windows as time passes.
+   */
+  private calculateWeightedCount(window: RateLimitWindow, _now: number): number {
+    // Simply sum all requests in all sub-windows
+    // The rotation logic already handles removing expired sub-windows
+    return window.total
+  }
+
+  /**
+   * Get the current sub-window index
+   */
+  private getCurrentSubWindowIndex(window: RateLimitWindow, now: number): number {
+    const elapsed = now - window.windowStart
+    return Math.min(this.subWindows - 1, Math.floor(elapsed / this.subWindowMs))
+  }
+}
+
+// ============================================================================
+// Middleware Factory
+// ============================================================================
+
+/** Default rate limit options */
+const DEFAULT_OPTIONS: Required<Omit<RateLimitOptions, 'keyExtractor' | 'skip' | 'onRateLimited' | 'storage'>> = {
+  requests: 60,
+  windowMs: 60000,
+  subWindows: 10,
+  keyMode: 'ip',
+  keyPrefix: 'ratelimit:',
+  ipHeader: 'CF-Connecting-IP',
+  userHeader: 'X-User-ID',
+}
+
+/**
+ * Extract client IP from request
+ */
+function extractIP(c: HonoContext, header: string): string {
+  const ip = c.req.header(header) ?? c.req.header('X-Forwarded-For')?.split(',')[0]?.trim() ?? 'unknown'
+  return ip
+}
+
+/**
+ * Extract user ID from request
+ */
+function extractUser(c: HonoContext, header: string): string | null {
+  return c.req.header(header) ?? null
+}
+
+/**
+ * Create default rate limited response
+ */
+function createRateLimitedResponse(c: HonoContext, info: RateLimitInfo): Response {
+  return c.json(
+    {
+      error: true,
+      code: 'RATE_LIMITED',
+      message: 'Too many requests. Please try again later.',
+      retryAfter: info.resetAfterSeconds,
+    },
+    429
+  )
+}
+
+/**
+ * Create rate limiting middleware for Hono
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono'
+ * import { rateLimit, KVRateLimitStorage } from '@dotdo/postgres/middleware'
+ *
+ * const app = new Hono<{ Bindings: { RATE_LIMIT_KV: KVNamespace } }>()
+ *
+ * // Rate limit by IP: 100 requests per minute
+ * app.use('*', rateLimit({
+ *   requests: 100,
+ *   windowMs: 60000,
+ *   storage: new KVRateLimitStorage(env.RATE_LIMIT_KV),
+ * }))
+ *
+ * // Rate limit by user: 1000 requests per minute
+ * app.use('/api/*', rateLimit({
+ *   requests: 1000,
+ *   windowMs: 60000,
+ *   keyMode: 'user',
+ *   userHeader: 'Authorization',
+ * }))
+ * ```
+ */
+export function rateLimit(options: RateLimitOptions = {}): MiddlewareHandler {
+  const opts = {
+    ...DEFAULT_OPTIONS,
+    ...options,
+  }
+
+  // Use in-memory storage if none provided (not recommended for production)
+  const storage = opts.storage ?? new InMemoryRateLimitStorage()
+
+  const limiter = new SlidingWindowRateLimiter({
+    requests: opts.requests,
+    windowMs: opts.windowMs,
+    subWindows: opts.subWindows,
+    storage,
+  })
+
+  return async (c, next) => {
+    // Check if should skip rate limiting
+    if (options.skip) {
+      const shouldSkip = await options.skip(c as HonoContext)
+      if (shouldSkip) {
+        return next()
+      }
+    }
+
+    // Extract rate limit key
+    let key: string | null = null
+    switch (opts.keyMode) {
+      case 'ip':
+        key = extractIP(c as HonoContext, opts.ipHeader)
+        break
+      case 'user':
+        key = extractUser(c as HonoContext, opts.userHeader)
+        break
+      case 'custom':
+        if (options.keyExtractor) {
+          key = options.keyExtractor(c as HonoContext)
+        }
+        break
+    }
+
+    // If no key could be extracted, skip rate limiting
+    if (!key) {
+      return next()
+    }
+
+    // Add prefix to key
+    const fullKey = `${opts.keyPrefix}${key}`
+
+    // Check rate limit
+    const info = await limiter.check(fullKey)
+
+    // Set rate limit headers
+    c.header('X-RateLimit-Limit', String(info.limit))
+    c.header('X-RateLimit-Remaining', String(info.remaining))
+    c.header('X-RateLimit-Reset', String(info.resetAfterSeconds))
+
+    // Store rate limit info in context for downstream use
+    c.set('rateLimitInfo', info)
+
+    if (info.limited) {
+      // Set Retry-After header (required for 429 responses)
+      c.header('Retry-After', String(info.resetAfterSeconds))
+
+      // Return rate limited response
+      if (options.onRateLimited) {
+        return options.onRateLimited(c as HonoContext, info)
+      }
+      return createRateLimitedResponse(c as HonoContext, info)
+    }
+
+    return next()
+  }
+}
+
+/**
+ * Create rate limit middleware with Durable Object storage
+ */
+export function rateLimitWithDO(
+  storage: DurableObjectStorage,
+  options: Omit<RateLimitOptions, 'storage'> = {}
+): MiddlewareHandler {
+  return rateLimit({
+    ...options,
+    storage: new DurableObjectRateLimitStorage(storage),
+  })
+}
+
+/**
+ * Create rate limit middleware with KV storage
+ */
+export function rateLimitWithKV(
+  kv: KVNamespace,
+  options: Omit<RateLimitOptions, 'storage'> = {}
+): MiddlewareHandler {
+  return rateLimit({
+    ...options,
+    storage: new KVRateLimitStorage(kv),
+  })
+}
+
+// ============================================================================
+// Token Bucket Algorithm (Alternative)
+// ============================================================================
+
+/**
+ * Token bucket data structure
+ */
+export interface TokenBucket {
+  /** Current number of tokens */
+  tokens: number
+  /** Last refill timestamp (ms) */
+  lastRefill: number
+}
+
+/**
+ * Token bucket options
+ */
+export interface TokenBucketOptions {
+  /**
+   * Maximum tokens in the bucket (burst capacity)
+   * @default 10
+   */
+  bucketSize?: number
+
+  /**
+   * Tokens added per second (refill rate)
+   * @default 1
+   */
+  tokensPerSecond?: number
+
+  /**
+   * Tokens consumed per request
+   * @default 1
+   */
+  tokensPerRequest?: number
+
+  /**
+   * Key extraction mode
+   * @default 'ip'
+   */
+  keyMode?: RateLimitKeyMode
+
+  /**
+   * Custom key extractor
+   */
+  keyExtractor?: (c: HonoContext) => string | null
+
+  /**
+   * Key prefix for storage
+   * @default 'tokenbucket:'
+   */
+  keyPrefix?: string
+
+  /**
+   * Header to extract IP from
+   * @default 'CF-Connecting-IP'
+   */
+  ipHeader?: string
+
+  /**
+   * Header for user ID
+   * @default 'X-User-ID'
+   */
+  userHeader?: string
+
+  /**
+   * Skip function
+   */
+  skip?: (c: HonoContext) => boolean | Promise<boolean>
+
+  /**
+   * Custom response handler
+   */
+  onRateLimited?: (c: HonoContext, info: TokenBucketInfo) => Response | Promise<Response>
+
+  /**
+   * Storage backend for token bucket data.
+   * Use TokenBucketStorage implementations (InMemoryTokenBucketStorage, DurableObjectTokenBucketStorage, KVTokenBucketStorage)
+   * for type-safe storage, or GenericRateLimitStorage<TokenBucket> for custom implementations.
+   */
+  storage?: TokenBucketStorage
+}
+
+/**
+ * Token bucket status information
+ */
+export interface TokenBucketInfo {
+  /** Maximum tokens (bucket size) */
+  bucketSize: number
+  /** Current available tokens */
+  tokens: number
+  /** Tokens consumed per request */
+  tokensPerRequest: number
+  /** Seconds until bucket is full */
+  refillsInSeconds: number
+  /** Whether the request was rate limited */
+  limited: boolean
+}
+
+/**
+ * Token bucket storage type
+ */
+export type TokenBucketStorage = GenericRateLimitStorage<TokenBucket>
+
+/**
+ * Token bucket rate limiter implementation
+ *
+ * Classic token bucket algorithm:
+ * - Bucket starts full with N tokens
+ * - Each request consumes tokens
+ * - Tokens are added at a constant rate
+ * - Allows bursts up to bucket size
+ */
+export class TokenBucketRateLimiter {
+  private bucketSize: number
+  private tokensPerSecond: number
+  private tokensPerRequest: number
+  private storage: TokenBucketStorage
+
+  constructor(options: Required<Pick<TokenBucketOptions, 'bucketSize' | 'tokensPerSecond' | 'tokensPerRequest'>> & { storage: TokenBucketStorage }) {
+    this.bucketSize = options.bucketSize
+    this.tokensPerSecond = options.tokensPerSecond
+    this.tokensPerRequest = options.tokensPerRequest
+    this.storage = options.storage
+  }
+
+  /**
+   * Check if a request should be rate limited
+   */
+  async check(key: string): Promise<TokenBucketInfo> {
+    const now = Date.now()
+    const existing = await this.storage.get(key)
+
+    let bucket: TokenBucket
+    if (existing) {
+      // Refill tokens based on time elapsed
+      const elapsed = (now - existing.lastRefill) / 1000
+      const refilled = elapsed * this.tokensPerSecond
+      bucket = {
+        tokens: Math.min(this.bucketSize, existing.tokens + refilled),
+        lastRefill: now,
+      }
+    } else {
+      // New bucket starts full
+      bucket = {
+        tokens: this.bucketSize,
+        lastRefill: now,
+      }
+    }
+
+    const limited = bucket.tokens < this.tokensPerRequest
+
+    if (!limited) {
+      // Consume tokens
+      bucket.tokens -= this.tokensPerRequest
+      await this.storage.set(key, bucket, 3600000) // 1 hour TTL
+    }
+
+    // Calculate time until bucket is full
+    const tokensNeeded = this.bucketSize - bucket.tokens
+    const refillsInSeconds = Math.ceil(tokensNeeded / this.tokensPerSecond)
+
+    return {
+      bucketSize: this.bucketSize,
+      tokens: Math.floor(bucket.tokens),
+      tokensPerRequest: this.tokensPerRequest,
+      refillsInSeconds,
+      limited,
+    }
+  }
+}
+
+/** Default token bucket options */
+const DEFAULT_TOKEN_BUCKET_OPTIONS: Required<Omit<TokenBucketOptions, 'keyExtractor' | 'skip' | 'onRateLimited' | 'storage'>> = {
+  bucketSize: 10,
+  tokensPerSecond: 1,
+  tokensPerRequest: 1,
+  keyMode: 'ip',
+  keyPrefix: 'tokenbucket:',
+  ipHeader: 'CF-Connecting-IP',
+  userHeader: 'X-User-ID',
+}
+
+/**
+ * Create token bucket rate limiting middleware
+ *
+ * @example
+ * ```typescript
+ * import { tokenBucket, KVRateLimitStorage } from '@dotdo/postgres/middleware'
+ *
+ * // Allow bursts of 10 requests, refill at 1/second
+ * app.use('*', tokenBucket({
+ *   bucketSize: 10,
+ *   tokensPerSecond: 1,
+ *   storage: new KVRateLimitStorage(env.RATE_LIMIT_KV),
+ * }))
+ * ```
+ */
+export function tokenBucket(options: TokenBucketOptions = {}): MiddlewareHandler {
+  const opts = {
+    ...DEFAULT_TOKEN_BUCKET_OPTIONS,
+    ...options,
+  }
+
+  // Use provided token bucket storage or default in-memory storage
+  const storage: TokenBucketStorage = opts.storage ?? new InMemoryTokenBucketStorage()
+
+  const limiter = new TokenBucketRateLimiter({
+    bucketSize: opts.bucketSize,
+    tokensPerSecond: opts.tokensPerSecond,
+    tokensPerRequest: opts.tokensPerRequest,
+    storage,
+  })
+
+  return async (c, next) => {
+    if (options.skip) {
+      const shouldSkip = await options.skip(c as HonoContext)
+      if (shouldSkip) {
+        return next()
+      }
+    }
+
+    let key: string | null = null
+    switch (opts.keyMode) {
+      case 'ip':
+        key = extractIP(c as HonoContext, opts.ipHeader)
+        break
+      case 'user':
+        key = extractUser(c as HonoContext, opts.userHeader)
+        break
+      case 'custom':
+        if (options.keyExtractor) {
+          key = options.keyExtractor(c as HonoContext)
+        }
+        break
+    }
+
+    if (!key) {
+      return next()
+    }
+
+    const fullKey = `${opts.keyPrefix}${key}`
+    const info = await limiter.check(fullKey)
+
+    c.header('X-RateLimit-Limit', String(info.bucketSize))
+    c.header('X-RateLimit-Remaining', String(info.tokens))
+    c.header('X-RateLimit-Reset', String(info.refillsInSeconds))
+
+    c.set('tokenBucketInfo', info)
+
+    if (info.limited) {
+      c.header('Retry-After', String(Math.ceil(info.tokensPerRequest / opts.tokensPerSecond)))
+
+      if (options.onRateLimited) {
+        return options.onRateLimited(c as HonoContext, info)
+      }
+
+      return c.json(
+        {
+          error: true,
+          code: 'RATE_LIMITED',
+          message: 'Too many requests. Please try again later.',
+          retryAfter: Math.ceil(info.tokensPerRequest / opts.tokensPerSecond),
+        },
+        429
+      )
+    }
+
+    return next()
+  }
+}