§User Quotas

NOTE: this is a commercial feature of Lightbend Reactive Platform that is available for production use only for Lightbend subscribers. To find out more, contact Lightbend.

To use the User Quotas feature you must install Lightbend Reactive Platform.


User Quotas is a module that lets you control the service level that you provide to your users. User Quotas lets you set service quotas for your users and automatically restrict access when usage exceeds the quota.

Here are some scenarios where quotas are useful:

  • On your website, to stop users downloading or viewing too many pages on your site. Heavy usage might indicate the a user is a bot that is scraping your site. By setting limits on usage you can decrease the load that heavy users put on your website.
  • For your developer API. Most APIs enforce rate limits to make sure that no user consumes too many resources. To get access to higher limits a developer might need to validate their identity or pay a fee.
  • For a microservice within your organization. It is common to agree on usage limits when providing an internal service. By agreeing on limits, you can provision and allocate resources fairly, and you can also ensure other internal users get clear feedback when they exceed agreed usage.
  • To limit how much data users upload in a period of time, to prevent your service being overloaded.
  • To slow down login attempts or other sensitive actions.

User Quotas can run in several different configurations:

  • You can run it standalone in a single Play instance, so it tracks usage within a single instance.
  • You can link together several Play instances into a cluster so that they track usage across the cluster.
  • You can also link Play instances into a cluster that has a mix of Akka instances.

In the future it is planned to allow Play instances to act a clients of an Akka cluster, even if they’re not members of the cluster itself.

§Main concepts

User Quotas assigns each user a quota.

A user is a string identifier that can be used to track the user. For example, a user could be a username, an IP address or an account number.

A quota describes how much usage a user can have. Quotas can be either zero (no usage allowed), unlimited (any amount of usage allowed) or rate limited (controlled usage allowed).

A rate limited quota is enforced by a token bucket. Each user’s token bucket holds a certain number of tokens. When the user consumes a resource, some tokens are deducted. The token bucket balance can go down to zero, at which point the user is blocked. Periodically a token bucket is refilled. For example, a token bucket might hold 100 tokens and be refilled every 5 minutes. This means a user can use at most 100 tokens every 5 minutes.

All user quotas are tracked by a judge. The judge handles petitions for tokens and either grants or denies the petition. When a petition is granted the judge will deduct tokens from the user’s token bucket.

§Tour of the User Quotas API

User Quotas provides an API that you can use in your Play application. The main classes you’ll use are set out below.

Quota API

The most common object you’ll use in your Play application is the QuotaAction. A QuotaAction is used to make Play actions with usage limits. You use it like a normal Action, except it consumes tokens on each request and blocks users when they run out of tokens.

A similar object is the QuotaFilter. This is a Play filter that you can apply to your entire Play application. It will automatically consume tokens for every request in your application. Using a QuotaFilter is a convenient way to add quotas to your entire Play application.

Both QuotaAction and QuotaFilter use an internal object called a RequestJudger to do the work of checking a request. The RequestJudger factors out the common behavior of both classes: getting the User from a request, petitioning the Judge, allowing or denying the request, formatting the result. A UserExtractor provides the logic for determining the account for a request. A CorrelationIdExtractor provides an optional correlation identifier that can be extracted from the request or generated internally. A ResultFormatter handles the details of formatting requests, such as setting headers or HTTP status codes appropriately.

The Judge stores all the users’ token buckets. When a request comes in, the RequestJudger asks the Judge to deduct tokens from the appropriate User. The Judge will accept or deny the petition, depending on whether the User has any tokens available. To work out the Quota for a User, the Judge queries a UserQuotas object. The UserQuotas object returns a Quota to the Judge giving the Quota for the User.

§System requirements

User Quotas comes with the Lightbend Reactive Platform, version 2. It requires Play 2.5.x, Akka 2.4.x, and Java 1.8. You can use User Quotas with either Java or Scala.