rate-limiting-persistent

Files (25)

• POSTGRESQL_SETUP.md
• PROGRESS.md
• README.md
• SKILL.md
• VALIDATION.md
• basic-usage.ts · examples/
• custom-provider.ts · examples/
• in-memory-only.ts · examples/
• nextjs-integration.ts · examples/
• supabase-setup.ts · examples/
• manifest.yaml
• create_rate_limits.sql · migrations/
• package-lock.json
• package.json
• fallback.ts · src/
• index.ts · src/
• middleware.ts · src/
• persistent-limiter.ts · src/
• pre-configured.ts · src/
• rate-limiter.ts · src/
• types.ts · src/
• index.test.ts · tests/
• persistent-limiter.test.ts · tests/
• tsconfig.json
• vitest.config.ts

SKILL.md (first lines)

# Rate Limiting Persistent

Database-backed rate limiting system for Next.js API routes with atomic PostgreSQL functions, in-memory fallback, and serverless-friendly design.

## When to Use

Use this skill when building Next.js APIs that need:
- Persistent rate limiting across serverless cold starts
- Per-user or per-action rate limiting
- Atomic counter increments (no race conditions)
- Automatic fallback when database is unavailable
- Standard HTTP rate limit headers (X-RateLimit-*)
- Protection against abuse and DoS

**Don't use this skill if:**
- You need distributed rate limiting across multiple data centers (use Redis/Upstash instead)
- Your app isn't using PostgreSQL/Supabase
- You only need in-memory rate limiting (single instance)

## Stack

- Next.js 14+ (App Router Route Handlers)
- PostgreSQL 12+ (or Supabase)
- TypeScript (strict mode)
- @supabase/supabase-js (peer dependency)

## Quick Start

### 1. Install Skill

```bash
npm install -D @project-forge/rate-limiting-persistent
npm install @supabase/supabase-js
```

### 2. Run Database Migration

```sql
-- See migrations/create_rate_limits.sql
CREATE TABLE rate_limits (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    key TEXT NOT NULL UNIQUE,
    count INTEGER NOT NULL DEFAULT 1,
    window_start TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    window_end TIMESTAMPTZ NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE FUNCTION increment_rate_limit(...)
-- Full migration in migrations/ folder
```

### 3. Create Configuration

```typescript
// lib/config.ts
export const rateLimitConfig = {
  supabaseUrl: process.env.NEXT_PUBLIC_SUPABASE_URL!,
  supabaseAnonKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
}
```

### 4. Use in API Routes

```typescript
// app/api/generate/route.ts
import { checkRateLimit } from '@project-forge/rate-limiting-persistent'
import { apiError } from '@project-forge/error-handling-api'
import { rateLimitConfig } from '@/lib/config'

export async function POST(request: NextRequest) {
  const userId = await getUserId(request)

  const result = await checkRateLimit(rateLimitConfig, userId, {
    action: 'ai_generation',
    maxRequests: 10,
    windowSeconds: 60,
  })

  if (!result.allowed) {
    return NextResponse.json(
      { error: 'Rate limit exceeded' },
      {
        status: 429,
        headers: {
          'Retry-After': Math.ceil((result.resetAt - Date.now()) / 1000).toString()
        }
      }
    )
  }

  // Process request
  const data = await generateContent()
  return NextResponse.json({ data })
}
```

### 5. Use Middleware Helper

```typescript
import { withRateLimit } from '@project-forge/rate-limiting-persistent/middleware'

export async function POST(request: NextRequest) {
  const userId = await getUserId(request)

  const rateLimitResponse = await withRateLimit(config, userId, {
    action: 'api_call',
    maxRequests: 60,
    windowSeconds: 60,
  })

  if (rateLimitResponse) {
    return rateLimitResponse // 429 with proper headers
  }

  // Continue processing
}
```

From JimmyBlanquet/project-forge, MIT.

More from JimmyBlanquet/project-forge