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

Request → Check User Plan → Apply Limits
                │
    ┌───────────┼───────────┐
    │           │           │
    ▼           ▼           ▼
┌───────┐  ┌───────┐  ┌───────────┐
│ GUEST │  │  PRO  │  │   ULTRA   │
│50/15m │  │500/1h │  │2000/1h   │
│IP-based│ │User-based│ │User-based │
└───────┘  └───────┘  └───────────┘

Guest Rate Limiting

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

TypeScript

import { RateLimiterRedis } from "rate-limiter-flexible";

// Redis-based rate limiter
const rateLimiterRedis = new RateLimiterRedis({
	storeClient: redis, // Redis connection
	keyPrefix: "arcane_guest", // Key prefix for guest users
	points: 50, // 50 requests
	duration: 900, // per 15 minutes (900 seconds)
});

export async function rateLimitGuest(request: Request, user: TUserDoc) {
	let ip = "UNKNOWN";

	if (isDevEnv) {
		ip = request.ip ?? ip;
	} else {
		// Production: Get real IP from proxy
		ip = request.header("x-forwarded-for")?.split(",")[0] ?? ip;
	}

	// Only apply to guest users
	if (user.userPlan === "GUEST") {
		try {
			await rateLimiterRedis.consume(ip, 1); // Consume 1 point
		} catch (error) {
			// Check if limit exceeded
			if (
				error &&
				error._remainingPoints !== undefined &&
				error._remainingPoints === 0
			) {
				logger.info({ ip }, "ERROR/RATE_LIMITER");
				throw new ClientError(429, ErrorType.RATE_LIMIT_EXCEEDED);
			}
		}
	}
}

TypeScript

export const checkUsageLimits = async (user: TUserDoc, usage: TUsageConfig) => {
	const planLimits = {
		GUEST: { queriesPerDay: 100, queriesPerMonth: 500 },
		FREE: { queriesPerDay: 500, queriesPerMonth: 5000 },
		PRO: { queriesPerDay: 2000, queriesPerMonth: 20000 },
		ULTRA: { queriesPerDay: 5000, queriesPerMonth: 50000 },
	};

	const limits = planLimits[user.userPlan] || planLimits.FREE;

	// Check daily limit
	const dailyUsage = await getDailyUsage(user.uid);
	if (dailyUsage + usage.queries > limits.queriesPerDay) {
		throw new ClientError(
			429,
			ErrorType.DAILY_LIMIT_EXCEEDED,
			Severity.WARNING,
			{
				limit: limits.queriesPerDay,
				used: dailyUsage,
				requested: usage.queries,
			},
		);
	}

	// Check monthly limit
	const monthlyUsage = await getMonthlyUsage(user.uid);
	if (monthlyUsage + usage.queries > limits.queriesPerMonth) {
		throw new ClientError(
			429,
			ErrorType.MONTHLY_LIMIT_EXCEEDED,
			Severity.WARNING,
			{
				limit: limits.queriesPerMonth,
				used: monthlyUsage,
				requested: usage.queries,
			},
		);
	}

	// Record usage
	await recordUsage(user.uid, usage);
};

Plan	Daily Queries	Monthly Queries	Concurrent Requests
GUEST	100	500	1
FREE	500	5,000	2
PRO	2,000	20,000	5
ULTRA	5,000	50,000	10

TypeScript

export const recordUsage = async (userId: string, usage: TUsageConfig) => {
	const today = new Date().toISOString().split("T")[0]; // YYYY-MM-DD
	const month = today.substring(0, 7); // YYYY-MM

	const dailyKey = `usage:daily:${userId}:${today}`;
	const monthlyKey = `usage:monthly:${userId}:${month}`;

	// Increment counters in Redis
	await Promise.all([
		redis.incrby(dailyKey, usage.queries),
		redis.incrby(monthlyKey, usage.queries),
		redis.expire(dailyKey, 86400 * 2), // 2 days TTL
		redis.expire(monthlyKey, 86400 * 33), // 33 days TTL
	]);

	// Save detailed usage to Firestore
	await db.collection("usage").add({
		userId,
		timestamp: Timestamp.now(),
		queries: usage.queries,
		tokens: usage.tokens,
		model: usage.model,
		date: today,
	});
};

TypeScript

type TUsageConfig = {
	queries: number; // Cost in query units
	tokens: {
		input: number; // Prompt tokens
		output: number; // Completion tokens
		cached: number; // Cached prompt tokens
		reasoning: number; // Reasoning/thinking tokens
	};
	model: TLLMModels; // Which model was used
};

TypeScript

const checkTokenLimits = async (user: TUserDoc, tokens: number) => {
	const tokenLimits = {
		GUEST: 100_000, // 100k tokens/day
		FREE: 500_000, // 500k tokens/day
		PRO: 2_000_000, // 2M tokens/day
		ULTRA: 5_000_000, // 5M tokens/day
	};

	const limit = tokenLimits[user.userPlan];
	const used = await getDailyTokenUsage(user.uid);

	if (used + tokens > limit) {
		throw new ClientError(
			429,
			ErrorType.TOKEN_LIMIT_EXCEEDED,
			Severity.WARNING,
			{
				limit,
				used,
				requested: tokens,
			},
		);
	}
};

TypeScript

export const checkAiToolLimits = async (user: TUserDoc, toolName: string) => {
	const toolLimits = {
		image_generation: {
			FREE: 10, // 10 images/day
			PRO: 50, // 50 images/day
			ULTRA: 100, // 100 images/day
		},
		deep_research: {
			FREE: 3, // 3 research sessions/day
			PRO: 10, // 10 research sessions/day
			ULTRA: 30, // 30 research sessions/day
		},
		data_analysis: {
			FREE: 5, // 5 analyses/day
			PRO: 20, // 20 analyses/day
			ULTRA: 50, // 50 analyses/day
		},
	};

	const limit = toolLimits[toolName]?.[user.userPlan];
	if (!limit) return; // No limit for this tool

	const key = `ai_tool_usage:${user.uid}:${toolName}:${today}`;
	const used = parseInt((await redis.get(key)) || "0");

	if (used >= limit) {
		throw new ClientError(
			429,
			ErrorType.AI_TOOL_LIMIT_EXCEEDED,
			Severity.WARNING,
			{
				tool: toolName,
				limit,
				used,
			},
		);
	}

	await redis.incr(key);
	await redis.expire(key, 86400); // 24 hours
};

TypeScript

export const usageLimitsMiddleware = async ({
	input,
}: {
	input: z.infer<typeof usageLimitSchema>;
}) => {
	const { user }: TAuthenticatedRequestContext = requestContext.get();

	// Check guest rate limit
	if (user.userPlan === "GUEST") {
		await rateLimitGuest(request, user);
	}

	// Check if user has exceeded plan limits
	// (Actual check happens post-request based on usage)

	return {};
};

TypeScript

// Allow short bursts for better UX
const rateLimiterWithBurst = new RateLimiterRedis({
	storeClient: redis,
	keyPrefix: "arcane_burst",
	points: 10, // 10 burst requests
	duration: 1, // per 1 second
});

// Then fall back to standard limiter
const rateLimiterStandard = new RateLimiterRedis({
	storeClient: redis,
	keyPrefix: "arcane_standard",
	points: 50, // 50 requests
	duration: 900, // per 15 minutes
});

Plain text

# Rate limiting
arcane_guest:{ip}                    → Points remaining
arcane_burst:{userId}                  → Burst points
arcane_standard:{userId}               → Standard points

# Usage tracking
usage:daily:{userId}:{YYYY-MM-DD}      → Daily query count
usage:monthly:{userId}:{YYYY-MM}       → Monthly query count
usage:tokens:daily:{userId}:{date}     → Daily token count

# AI tool limits
ai_tool_usage:{userId}:{toolName}:{date} → Tool usage count

TypeScript

// Rate limit exceeded
{
    "error": {
        "type": "RATE_LIMIT_EXCEEDED",
        "message": "Too many requests. Please slow down.",
        "details": {
            "limit": 50,
            "window": "15 minutes",
            "retry_after": 847  // seconds
        }
    }
}

// Plan limit exceeded
{
    "error": {
        "type": "DAILY_LIMIT_EXCEEDED",
        "message": "Daily query limit exceeded",
        "details": {
            "plan": "FREE",
            "daily_limit": 500,
            "used": 500,
            "upgrade_url": "/upgrade"
        }
    }
}

09-RateLimiting

Rate Limiting Architecture

Overview

Architecture

Guest Rate Limiting

09-RateLimiting

Rate Limiting Architecture

Overview

Architecture

Guest Rate Limiting

Plan-Based Usage Limits

Usage Tracking

Token-Based Limits

AI Tools Usage Limits

Middleware Integration

Burst Handling

Redis Key Structure

Error Responses

Summary