TypeScript icon, indicating that this package has built-in type declarations

4.0.1 • Public • Published


Build Status

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


  • 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.


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.


  • 4.0.0 - Change hapi namespace to @hapi/hapi



Package Sidebar


npm i yaral

Weekly Downloads






Unpacked Size

35.8 kB

Total Files


Last publish


  • connor.peet
  • mcph