rate-limiting-persistent

Files (6)

• README.md
• SKILL.md
• persistent-limiter.ts · files/lib/rate-limit/
• install.sh
• 20251223100001_create_rate_limits.sql · supabase/migrations/
• persistent-limiter.test.ts · tests/

SKILL.md (first lines)

# Rate Limiting Persistent Skill

**Version:** 1.0.0
**Category:** Core
**Extracted from:** Production-tested in a real-world SaaS
**Production-ready:** ✅ Yes

## Description

Persistent rate limiting using PostgreSQL for atomic counters. Survives serverless cold starts and deployments with automatic in-memory fallback.

**Key Features:**
- 🗄️ **Persistent Storage**: Uses PostgreSQL for atomic rate limit tracking
- ⚡ **Serverless-Ready**: Survives Vercel/Railway cold starts
- 🛡️ **Automatic Fallback**: In-memory limiter if database unavailable
- ⚙️ **Flexible Configuration**: Per-action rate limits
- 🔒 **Thread-Safe**: Atomic PostgreSQL function prevents race conditions
- 🧹 **Auto-Cleanup**: Periodic cleanup of expired entries

## What This Skill Provides

### Core Components

1. **checkRateLimit()** - Main rate limiting function
   - Uses PostgreSQL `increment_rate_limit()` function
   - Automatic fallback to in-memory limiter
   - Returns: `{ allowed, remaining, resetAt }`

2. **PostgreSQL Function** - Atomic counter increment
   - UPSERT with ON CONFLICT
   - Automatic window reset when expired
   - Returns allowed status + remaining count

3. **In-Memory Fallback** - Resilience when DB unavailable
   - Map-based storage
   - Automatic cleanup every 5 minutes
   - Same interface as persistent limiter

## Installation

### 1. Run Installation Script

```bash
cd skills/core/rate-limiting-persistent
bash install.sh
```

### 2. Apply Supabase Migration

In your Supabase dashboard or CLI:

```bash
supabase migration new create_rate_limits
# Copy contents from supabase/migrations/20251223100001_create_rate_limits.sql
supabase db push
```

Or manually:

```sql
-- See supabase/migrations/20251223100001_create_rate_limits.sql
CREATE TABLE rate_limits (...);
CREATE FUNCTION increment_rate_limit(...);
```

### 3. Install Dependencies

Already included if you have Supabase:

```bash
npm install @supabase/supabase-js
```

## Usage

### Basic Usage

```typescript
import { checkRateLimit } from '@/lib/rate-limit/persistent-limiter'

// In your API route
export async function POST(request: Request) {
  const { userId } = await getUser()

  const rateLimit = await checkRateLimit(userId, {
    action: 'api_call',
    maxRequests: 60,
    windowSeconds: 60
  })

  if (!rateLimit.allowed) {
    return new Response('Rate limit exceeded', {
      status: 429,
      headers: {
        'X-RateLimit-Remaining': '0',
        'X-RateLimit-Reset': new Date(rateLimit.resetAt).toISOString()
      }
    })
  }

  // Process request...
  return Response.json({ success: true })
}
```

### With Rate Limit Headers

```typescript
async function handleRateLimitedRequest(userId: string) {
  const rateLimit = await checkRateLimit(userId, {
    action: 'api',
    maxRequests: 100,
    windowSeconds: 60
  })

  const headers = new Headers({
    'X-RateLimit-Limit': '100',
    'X-RateLimit-Remaining': String(rateLimit.remaining),
    'X-RateLimit-Reset': String(rateLimit.resetAt)

From JimmyBlanquet/project-forge, MIT.

More from JimmyBlanquet/project-forge