Skip to content

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.

src/settings.ts
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]
}
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

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' }).

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), the CF-Connecting-IP header. Cloudflare sets it and overwrites any value the client sent.
  • On Node, the socket address. serve() from @ghuri/core/node records it, and so does plain @hono/node-server (c.env.incoming). A custom server can call setRemoteAddr(request, addr) before app.fetch().
  • X-Forwarded-For (and X-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.

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.

Subclass SimpleRateThrottle and implement getCacheKey(); return null to skip throttling a request.

src/api/throttles.ts
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