Plan-Aware Rate Limiter

Build an Express middleware that enforces per-request limits based on asynchronously resolved client plans. Plans are determined at request time and control how many calls are allowed before returning a 429 response with a plan-aware payload.

Capabilities

Dynamic per-plan limits

• Requests with header X-Plan: pro may perform 6 actions within a 60s window, while requests without that header default to 2. The third basic request in the window returns HTTP 429, but a pro request is still accepted until the seventh call triggers 429. @test

Async key per user and route

• The limiter derives its counter key from an asynchronous lookup that combines the X-User header and the request path. Requests from the same user on two different paths should not share a counter; each path allows its own quota before 429. @test

Customized block response

• When a request exceeds its plan quota, the middleware responds with HTTP 429 and a JSON body containing { plan, reason, retryAfterSeconds }. The plan value reflects the resolved plan name, and retryAfterSeconds reflects the remaining window rounded up. @test

Fallback when plan lookup fails

• If the plan lookup rejects or returns no result, the middleware applies a fallback plan that allows 1 request per 60s window and sets a response header X-Limit-Source: fallback on all responses. @test

Implementation

@generates

API

import type { Request, RequestHandler } from "express";

export interface PlanInfo {
  name: string;
  windowMs: number;
  limit: number;
  blockMessage?: string;
}

export interface PlanLimiterOptions {
  fetchPlan: (req: Request) => Promise<PlanInfo | null>;
  defaultPlan: PlanInfo;
}

export function createPlanAwareLimiter(options: PlanLimiterOptions): RequestHandler;

Dependencies { .dependencies }

express-rate-limit { .dependency }

Express middleware that enforces request quotas with support for asynchronous option resolvers. @satisfied-by

express { .dependency }

HTTP framework providing request/response types and middleware composition. @satisfied-by