Yaral
Yaral is Yet Another RAte Limit plugin for Hapi. But, unlike others, it does several nice things!
- Integrates with you server's Catbox cache
- Allows you to limit with custom attributes, not just the user's IP.
- Allows you to limit certain responses, add limiting globally, and adjust the limiting endpoint-by-endpoint
Concepts
- The entire server can be limited under one rule, and additionally routes can provide their own limiting rules that are appended to the global rule.
- Each rule has a list of status codes that it can limit. This allows you to, for example, limit invalid response codes at a lower rate than successful response codes. Responses "bubble up" to the first rule that can handle them. If no rules handle that code, it will not be limited.
- Limit rules are specified using a maximum number of requests per unit time, similar to the way the Twitter API works.
Configuration
The following options are available when you register Yaral:
buckets
is an array of interval/mode config for Limitus intervals. Each item should have:- An identifying
name
- An
interval
that allows amax
number of requests. - A
mode
as described in the Limitus documentation. Eitherinterval
orcontinuous
. Defaults tointerval
. - An
id
function that takes a Hapi request object and returns a string, number or object that identifies the requester. - A list of
codes
that specify response codes that count towards this bucket's limit. Responses not in this range will not be limited. Defaults to['2xx', '3xx']
. Tip: to limit all responses, use['xxx']
.
- An identifying
default
is a bucketname
or array of names of the bucket applied to all routes. Defaults to[]
. Buckets are matched first to last.cache
is the cache name (as configured in the Hapi server) used to store rate limiting data. Defaults to the server's default cache.enabled
is a boolean whether to enable rate limiting. Useful to disable limiting in tests and development. Default totrue
.includeHeaders
specifies whether rate limit headers should be included in the response.limitus
is a Limitus instance to use for this rate limiting. Defaults tonew Limitus()
.exclude
is a function, called with therequest
object that returns true if the provided request should be omitted from limiting.onPass
is a function called with therequest
object with a successful request is made which is not rate limited.onLimit
is a function called with therequest
object,rule
name that failed, and extradata
that rule returns when a request is made which does get rate limited. You may returnyaral.cancel
from this method to cause the specific request not to be rate limited.event
is a string identifying when the initial checks will happen, valid valus areonRequest
,onPreAuth
,onPostAuth
You can also configure options on a per-route basis in config.plugins.yaral
:
buckets
specifies the bucketname
or array of of the rate limit buckets to use in addition to the configureddefault
rules. Buckets are matched first to last.enabled
is a boolean which allows you to override a trueenabled
global configuration. This can be used to exclude routes from global rate limits. Defaults totrue
.exclude
functions similarly to theexclude
above. If both a route-level and a global exclude passed, the request will be excluded if either return true.
Alternately, for routes, you can specify a single string or array as a shorthand for buckets.
Changelog
- 4.0.0 - Change hapi namespace to @hapi/hapi