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.
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.
User Quotas provides an API that you can use in your Play application. The main classes you’ll use are set out below.
The most common object you’ll use in your Play application is the
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.
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.
Judge stores all the users’ token buckets. When a request comes in, the
RequestJudger asks the
Judge to deduct tokens from the appropriate
Judge will accept or deny the petition, depending on whether the
User has any tokens available. To work out the
Quota for a
Judge queries a
UserQuotas object. The
UserQuotas object returns a
Quota to the
Judge giving the
Quota for the
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.