Add type-safe, transactional rate limiting to Convex applications with configurable sharding and fair queuing for scalable API protection.
npm install @convex-dev/rate-limiterThis component provides application-level rate limiting.
See below for more details on usage.
What is rate limiting?
Rate limiting is the technique of controlling how often actions can be performed, typically on a server. There are a host of options for achieving this, most of which operate at the network layer.
What is application-layer rate limiting?
Application-layer rate limiting happens in your app's code where you are handling authentication, authorization, and other business logic. It allows you to define nuanced rules, and enforce policies more fairly. It is not the first line of defense for a sophisticated DDOS attack (which thankfully are extremely rare), but will serve most real-world use cases.
What differentiates this approach?
Type-safe usage: you won't accidentally misspell a rate limit name.
Configurable for fixed window or token bucket algorithms.
Efficient storage and compute: storage is not proportional to requests.
Configurable sharding for scalability.
Transactional evaluation: all rate limit changes will roll back if your mutation fails.
Fairness guarantees via credit "reservation": save yourself from exponential backoff.
Opt-in "rollover" or "burst" allowance via a configurable capacity.
Fails closed, not open: avoid cascading failure when traffic overwhelms your rate limits.
See the associated [Stack post](https://stack.convex.dev/rate-limiting) for more details and background.
The Rate Limiter component provides type-safe rate limiting for Convex functions through simple decorators or middleware. You can define limits per user, IP, or custom keys with configurable time windows and request counts.
Rate Limiter offers transactional rate limiting that integrates with Convex's database transactions. It supports fair queuing to prevent legitimate users from being blocked by abusive traffic while maintaining consistent enforcement across all application instances.
The component includes configurable sharding to distribute rate limit counters across multiple database partitions. This prevents bottlenecks on high-traffic endpoints while maintaining accurate limit enforcement.
Yes, the Rate Limiter component is fully transactional and integrates with Convex's database transaction system. Rate limit checks and updates happen atomically within the same transaction as your business logic, ensuring consistency.
The Rate Limiter component distributes rate limit counters across configurable database shards to prevent write contention on high-traffic endpoints. You can configure the number of shards based on your traffic patterns while maintaining accurate limit enforcement.
Yes, the Rate Limiter component supports custom rate limiting keys and logic. You can implement per-user, per-IP, or custom composite keys with different limits based on user roles, subscription tiers, or any application-specific criteria.
The Rate Limiter component throws a ConvexError when limits are exceeded, which you can catch and handle appropriately. It provides fair queuing by default, ensuring legitimate requests are processed in order while blocking excessive traffic.