Inkdown
Start writing

Merlin Backend

12 files·0 subfolders

Shared Workspace

Merlin Backend
01-Orchestration.md

09-RateLimiting

Shared from "Merlin Backend" on Inkdown

Rate Limiting Architecture

Overview

The rate limiting system prevents abuse and ensures fair resource allocation across users. It uses Redis-based sliding window counters with plan-based limits.


Architecture

Plain text

Guest Rate Limiting

File: src/server/middlewares/rateLimiter/rateLimiter.ts

02-DeepResearch.md
03-Search.md
04-Scraping.md
05-Streaming.md
06-MultiProviderLLM.md
07-MemoryAndContext.md
08-ErrorHandling.md
09-RateLimiting.md
10-TaskQueue.md
11-SecurityAndAuth.md
Orchestration-2nd-draft
TypeScript

How It Works:

  1. Identify guest users (userPlan === "GUEST")
  2. Extract IP address (dev vs production handling)
  3. Consume 1 point from Redis counter
  4. If points exhausted (0 remaining), throw 429 error
  5. Redis key: arcane_guest:{ip}
  6. Auto-expires after 15 minutes (sliding window)

Plan-Based Usage Limits

File: src/server/middlewares/usageLimits/usageLimits.ts

TypeScript

Plan Limits:

PlanDaily QueriesMonthly QueriesConcurrent Requests
GUEST1005001
FREE5005,0002
PRO2,00020,0005
ULTRA5,00050,00010

Usage Tracking

File: src/server/middlewares/usageLimits/functions/saveDailyUsage.ts

TypeScript

Usage Schema:

TypeScript

Token-Based Limits

Some operations count tokens instead of queries:

TypeScript

AI Tools Usage Limits

File: src/server/middlewares/aiToolsUsageLimits/aiToolsUsageLimits.ts

Special limits for expensive AI features:

TypeScript

Middleware Integration

File: src/server/middlewares/usageLimits/usageLimits.ts

TypeScript

Applied in routing:

TypeScript

Burst Handling

TypeScript

Redis Key Structure

Plain text

Error Responses

TypeScript

Summary

The rate limiting system:

  1. Guest Limiting: IP-based, 50 req/15min via Redis
  2. Plan Tiers: Daily/monthly query limits per plan
  3. Token Tracking: Separate token limits for large operations
  4. AI Tool Limits: Per-tool daily limits (images, research, etc.)
  5. Sliding Window: Redis TTL for automatic reset
  6. Burst Handling: Short-term higher limits for UX
  7. Middleware Integration: Applied to all endpoints
  8. Clear Errors: Retry-after hints, upgrade CTAs

Key Principle: Protect resources while providing clear upgrade paths. Never silently fail - always tell users their limits.