feat(rate-limiter): token bucket algorithm

[icecrasher321]

Summary

Improve system to use token bucket algo that prevents exploitation of boundary bursts and smoothens traffic better.

Type of Change

• Other: Improvement

Testing

Testing Manually

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
docs	Skipped			Dec 9, 2025 10:50pm

[greptile-apps]

Greptile Overview

Greptile Summary

Replaces the fixed-window rate limiter with a token bucket algorithm to prevent exploitation of boundary bursts and smooth traffic better.

Key Changes:

• Introduced RateLimitStorageAdapter interface with Redis and PostgreSQL implementations for token bucket state management
• Each bucket tracks tokens (current available), lastRefillAt, and refills at refillRate per refillIntervalMs
• Burst capacity is 2x the sustained rate (e.g., 10 req/min → 20 max burst tokens)
• Database migration drops old user_rate_limits table and creates new rate_limit_bucket table
• Fails closed on storage errors (denies requests rather than allowing them)
• Updated API documentation to explain token bucket behavior with maxBurst field

Previous feedback addressed:

• Fixed logic issue in db-token-bucket.ts (simplified to tokens >= 0)
• Changed deprecated HMSET to HSET in Redis Lua script

Confidence Score: 4/5

• This PR is safe to merge after verifying the migration path for existing rate limit data.
• Well-designed token bucket implementation with clean abstractions, comprehensive tests, and proper documentation. Previous review feedback has been addressed. Score of 4 (not 5) due to the destructive migration that resets all existing rate limit state.
• Pay attention to packages/db/migrations/0119_far_lethal_legion.sql - the migration drops the old rate limit table, which will reset all users' rate limit counters upon deployment.

Important Files Changed

File Analysis

Filename	Score	Overview
apps/sim/lib/core/rate-limiter/rate-limiter.ts	5/5	Complete refactor from fixed-window to token bucket algorithm. Clean abstraction using storage adapters with proper error handling (fail closed on storage errors).
apps/sim/lib/core/rate-limiter/types.ts	5/5	Config updated to use TokenBucketConfig with maxTokens (2x multiplier for burst), refillRate, and refillIntervalMs parameters.
apps/sim/lib/core/rate-limiter/storage/db-token-bucket.ts	4/5	PostgreSQL token bucket implementation using atomic INSERT...ON CONFLICT DO UPDATE. Complex SQL for token refill calculations executed in single query.
apps/sim/lib/core/rate-limiter/storage/redis-token-bucket.ts	5/5	Redis token bucket using Lua scripts for atomic token consume/status operations. Uses HSET (fixed from deprecated HMSET).
apps/sim/lib/core/rate-limiter/rate-limiter.test.ts	5/5	Comprehensive tests for token bucket rate limiter covering all trigger types, subscription plans, storage errors, and bucket reset functionality.
packages/db/migrations/0119_far_lethal_legion.sql	4/5	Creates new rate_limit_bucket table and drops old user_rate_limits table. Destructive migration - existing rate limit state will be reset.

Sequence Diagram

sequenceDiagram
    participant Client
    participant RateLimiter
    participant StorageFactory
    participant Redis/DB
    
    Client->>RateLimiter: checkRateLimitWithSubscription()
    RateLimiter->>RateLimiter: getBucketConfig(plan, counterType)
    RateLimiter->>StorageFactory: createStorageAdapter()
    StorageFactory-->>RateLimiter: Redis or DB adapter
    
    RateLimiter->>Redis/DB: consumeTokens(key, 1, config)
    
    Note over Redis/DB: Atomic operation:<br/>1. Calculate elapsed time<br/>2. Refill tokens (capped at maxTokens)<br/>3. Consume if tokens >= requested<br/>4. Return new state
    
    Redis/DB-->>RateLimiter: ConsumeResult {allowed, tokensRemaining, resetAt}
    
    alt Allowed
        RateLimiter-->>Client: {allowed: true, remaining, resetAt}
    else Rate Limited
        RateLimiter-->>Client: {allowed: false, remaining: 0, retryAfterMs}
    end

Loading

[greptile-apps]

_{19 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[icecrasher321]

@greptile

[greptile-apps]

_{19 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}