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 a max number of requests.
  • A mode as described in the Limitus documentation. Either interval or continuous. Defaults to interval.
  • 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'].
• default is a bucket name 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 to true.
• includeHeaders specifies whether rate limit headers should be included in the response.
• limitus is a Limitus instance to use for this rate limiting. Defaults to new Limitus().
• exclude is a function, called with the request object that returns true if the provided request should be omitted from limiting.
• onPass is a function called with the request object with a successful request is made which is not rate limited.
• onLimit is a function called with the request object, rule name that failed, and extra data that rule returns when a request is made which does get rate limited. You may return yaral.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 are onRequest, onPreAuth, onPostAuth

You can also configure options on a per-route basis in config.plugins.yaral:

• buckets specifies the bucket name or array of of the rate limit buckets to use in addition to the configured default rules. Buckets are matched first to last.
• enabled is a boolean which allows you to override a true enabled global configuration. This can be used to exclude routes from global rate limits. Defaults to true.
• exclude functions similarly to the exclude 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