Throttling
Throttles limit how often a client may call your API. They run after authentication and
permissions, and a throttled request gets 429 Too Many Requests with a Retry-After header:
{ "detail": "Request was throttled. Expected available in 37 seconds." }Throttle state is kept in Ghuri’s cache, so it works on every runtime without extra infrastructure: KV on Cloudflare, memory on a single Node process.
Configuring
Section titled “Configuring”import { AnonRateThrottle, UserRateThrottle } from '@ghuri/rest'
REST_FRAMEWORK: { DEFAULT_THROTTLE_CLASSES: [AnonRateThrottle, UserRateThrottle], DEFAULT_THROTTLE_RATES: { anon: '60/hour', user: '2000/day', uploads: '20/hour', },}Rates are <number>/<period> where the period is second, minute, hour or day (only the
first letter matters, so '10/s' works too). A multiplier is allowed: '10/5m' is ten requests
per five minutes. A scope used by a throttle must have an entry in DEFAULT_THROTTLE_RATES
(null disables it), or the request fails with ImproperlyConfigured.
Per view:
export class SearchView extends APIView { throttleClasses = [UserRateThrottle]}Built-in classes
Section titled “Built-in classes”| Class | Identifies clients by | Scope |
|---|---|---|
AnonRateThrottle |
IP address, only for anonymous requests | anon |
UserRateThrottle |
User primary key; IP for anonymous requests | user |
ScopedRateThrottle |
User or IP, per view scope | the view’s throttleScope |
Scoped throttles
Section titled “Scoped throttles”Give expensive endpoints their own budget:
export class UploadView extends APIView { throttleClasses = [ScopedRateThrottle] throttleScope = 'uploads'}Every view with the same throttleScope shares one counter per client. Views without a
throttleScope are not throttled by ScopedRateThrottle. A viewset can set a scope for one
action only: @action({ detail: true, methods: ['post'], throttleScope: 'uploads' }).
Client IP addresses
Section titled “Client IP addresses”Anonymous clients are identified by IP address (getIdent()), and only sources a client cannot
forge are trusted by default:
- On Cloudflare (Workers, and
wrangler dev), theCF-Connecting-IPheader. Cloudflare sets it and overwrites any value the client sent. - On Node, the socket address.
serve()from@ghuri/core/noderecords it, and so does plain@hono/node-server(c.env.incoming). A custom server can callsetRemoteAddr(request, addr)beforeapp.fetch(). X-Forwarded-For(andX-Real-IP) are ignored, because any client can send them.
Behind a reverse proxy (nginx, a load balancer, Cloudflare in front of a Node server), the socket
address is the proxy’s, so all clients would share one bucket. Tell Ghuri how many proxies to
trust so it reads the right entry from X-Forwarded-For:
REST_FRAMEWORK: { NUM_PROXIES: 1, // e.g. one nginx or load balancer in front of the app}With NUM_PROXIES: n the client is the address n entries from the end of X-Forwarded-For
(DRF’s rule); 0 ignores the header. Set it to exactly the number of proxies that append to the
header: a larger value lets clients pick their own identity again.
The address without proxies is core’s getRemoteAddr(c) (Django’s REMOTE_ADDR), which you can
also use in your own views, for example for login lockouts or audit logs. To read it from
somewhere else, override getRemoteAddr(request) in a throttle subclass.
Accuracy on Workers
Section titled “Accuracy on Workers”The KV cache is eventually consistent across Cloudflare locations, and a single counter can be updated by many isolates at once. Expect limits to be approximate: a client might get a few more requests than the rate allows during bursts. That is fine for fair-use limits.
If you need exact limits, use Cloudflare’s own rate limiting in front of the Worker, or write a throttle backed by a Durable Object or by your database. For a login endpoint, prefer Cloudflare’s rate limiting rules; they act before your Worker is billed.
Custom throttles
Section titled “Custom throttles”Subclass SimpleRateThrottle and implement getCacheKey(); return null to skip throttling a
request.
import { SimpleRateThrottle, type APIRequest } from '@ghuri/rest'
export class ApiKeyRateThrottle extends SimpleRateThrottle { scope = 'apikey'
getCacheKey(request: APIRequest) { const key = request.header('X-Api-Key') return key ? `throttle_${this.scope}_${key}` : null }}Or set rate = '5/minute' on the subclass instead of a scope. For a completely different
algorithm, extend BaseThrottle and implement allowRequest(request, view) (may be async) and
wait().
Throttle counters use the cache alias in THROTTLE_CACHE (default 'default'). Point it at a
separate alias to keep them apart from application data:
REST_FRAMEWORK: { THROTTLE_CACHE: 'throttle' } // an alias defined in CACHES