All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.gerrit.server.quota.QuotaEnforcer Maven / Gradle / Ivy

There is a newer version: 3.10.1
Show newest version
// Copyright (C) 2018 The Android Open Source Project
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.gerrit.server.quota;

import com.google.gerrit.extensions.annotations.ExtensionPoint;

/**
 * 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 {@link * #requestTokens(String, QuotaRequestContext, long)} was called and one or more plugins returned an * erroneous result, the server will call {@link #refill(String, QuotaRequestContext, long)} on all * plugins with the same parameters. Plugins that deducted tokens in the {@link * #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 {@link #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, {@link #requestTokens(String, QuotaRequestContext, long)} and {@link #dryRun(String, * QuotaRequestContext, long)} share the same implementation and {@link #refill(String, * QuotaRequestContext, long)} is a no-op. */ @ExtensionPoint public interface QuotaEnforcer { /** * Checks if there is at least {@code numTokens} quota to fulfil the request. Bucket-based * implementations can deduct the inquired number of tokens from the bucket. */ QuotaResponse requestTokens(String quotaGroup, QuotaRequestContext ctx, long numTokens); /** * Checks if there is at least {@code numTokens} quota to fulfil the request. This is a pre-flight * request, implementations should not deduct tokens from a bucket, yet. */ QuotaResponse dryRun(String quotaGroup, QuotaRequestContext ctx, long numTokens); /** * 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 {@link #requestTokens(String, QuotaRequestContext, long)} with * the number of tokens that were eventually used. It is in {@link QuotaBackend} callers * discretion to ensure that {@link * com.google.gerrit.server.quota.QuotaBackend.WithResource#requestTokens(String, long)} is * called. */ QuotaResponse availableTokens(String quotaGroup, QuotaRequestContext ctx); /** * 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 {@link #requestTokens(String, QuotaRequestContext, long)} call * returned {@link QuotaResponse.Status#NO_OP}. */ void refill(String quotaGroup, QuotaRequestContext ctx, long numTokens); }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy