Package com.google.gerrit.server.quota

Interface QuotaEnforcer

public interface QuotaEnforcer

Allows plugins to enforce different types of quota.

Enforcing quotas can be helpful in many scenarios. For example:

• Reducing the number of QPS a user can send to Gerrit on the REST API
• Limiting the size of a repository (project)
• Limiting the number of changes in a repository
• Limiting the number of actions that have the potential for spam, abuse or flooding if not limited

This endpoint gives plugins the capability to enforce any of these limits. The server will ask all plugins that registered this endpoint and collect all results. In case requestTokens(String, QuotaRequestContext, long) was called and one or more plugins returned an erroneous result, the server will call refill(String, QuotaRequestContext, long) on all plugins with the same parameters. Plugins that deducted tokens in the requestTokens(String, QuotaRequestContext, long) call can refill them so that users don't get charged any quota for failed requests.

Not all implementations will need to deduct quota on requestTokens(String, QuotaRequestContext, long)}. Implementations that work on top of instance-attributes, such as the number of projects per instance can choose not to keep any state and always check how many existing projects there are and if adding the inquired number would exceed the limit. In this case, requestTokens(String, QuotaRequestContext, long) and dryRun(String, QuotaRequestContext, long) share the same implementation and refill(String, QuotaRequestContext, long) is a no-op.

Method Summary

Modifier and Type	Method	Description
QuotaResponse	availableTokens(String quotaGroup, QuotaRequestContext ctx)	Returns available tokens that can be later requested.
QuotaResponse	dryRun(String quotaGroup, QuotaRequestContext ctx, long numTokens)	Checks if there is at least numTokens quota to fulfil the request.
void	refill(String quotaGroup, QuotaRequestContext ctx, long numTokens)	A previously requested and deducted quota has to be refilled (if possible) because the request failed other quota checks.
QuotaResponse	requestTokens(String quotaGroup, QuotaRequestContext ctx, long numTokens)	Checks if there is at least numTokens quota to fulfil the request.

Method Detail

requestTokens

QuotaResponse requestTokens(String quotaGroup,
                            QuotaRequestContext ctx,
                            long numTokens)

Checks if there is at least numTokens quota to fulfil the request. Bucket-based implementations can deduct the inquired number of tokens from the bucket.

dryRun

QuotaResponse dryRun(String quotaGroup,
                     QuotaRequestContext ctx,
                     long numTokens)

Checks if there is at least numTokens quota to fulfil the request. This is a pre-flight request, implementations should not deduct tokens from a bucket, yet.

availableTokens

QuotaResponse availableTokens(String quotaGroup,
                              QuotaRequestContext ctx)

Returns available tokens that can be later requested.

This is used as a pre-flight check for the exceptional case when the requested number of tokens is not known in advance. Implementation should not deduct tokens from a bucket. It should be followed by a call to requestTokens(String, QuotaRequestContext, long) with the number of tokens that were eventually used. It is in QuotaBackend callers discretion to ensure that QuotaBackend.WithResource.requestTokens(String, long) is called.

refill

void refill(String quotaGroup,
            QuotaRequestContext ctx,
            long numTokens)

A previously requested and deducted quota has to be refilled (if possible) because the request failed other quota checks. Implementations can choose to leave this a no-op in case they are the first line of defence (e.g. always deduct HTTP quota even if the request failed for other quota issues so that the user gets throttled).

Will not be called if the requestTokens(String, QuotaRequestContext, long) call returned QuotaResponse.Status.NO_OP.