commit fc9817f3f31c9cf9f9f5473bbca6a74a8b13fcae
author Patrick Hiesel <hiesel@google.com> Mon Nov 12 15:08:35 2018 +0100
committer Patrick Hiesel <hiesel@google.com> Tue Dec 04 13:23:18 2018 +0100
tree ef0cf4ec78c1dba1ab5208cce4253106f04bdeb7
parent 474178eca18276b21709c7ea3c6ef900d7b6d38a

Add QuotaBackend and QuotaEnforcer extension point

In a recent discussion on the mailing list we agreed that Gerrit-core
would benefit from a mechanism to enforce various kinds of quotas.

As there is no gold-standard for quota checking and there are vastly
different quotas that one might want to enforce (HTTP-QPS,
number-of-projects, numBytesPerProject to name just a few) we provide
this as an extension point for plugins.

This commit implements the extension point in core using AutoValue
requests and responses to keep the interface as stable as possible. We
abstract away from this interface by implementing QuotaBackend and
DefaultQuotaBackend to centralize the plugin calling, provide a fluent
API for Gerrit-core to interact with and be able to provide a different
implementation that doesn't require plugins in tests and other settings
that might have such a need. The returned QuotaResponse.Aggregated
object offers throwing methods to assert that all quota checks passed
and eliminate try-catch-throw boiler-plate in callers.

Decoupling QuotaBackend from QuotaEnforcer also makes it so that we can
improve the fluent interface as we get more callers to make it easy to
use while keeping QuotaEnforcer stable to break as little plugins as
possible.

In the following paragraphs, I'll outline a bit of the thoughts that
went into the design of the interfaces:

For QuotaEnforcer, we don't want to throw exceptions, but have rich
return types instead. One reason is that the general Java world is
moving into the direction of UncheckedExceptions, another reason is that
we can be richer in expressing what happened in a returned object.

QuotaRequestContext contains all state besides the quota group and the
number of tokens we want to deduct. This is because this state might
change and be extended in the future. In this case we want existing
plugins to remain compatible.

Why are we passing Change.Id, Account.Id and Project.NameKey as Java
objects to plugins instead of just encompassing them as IdStrings in
the quota group (/projects/my-project/create)?
Mainly because we don't want plugins to have to parse this back into an
identifier they can use which would be wasteful and add complexity.

Why are we passing these at all?
There are uses cases where it matters which top-level entity the request
is for. For example: Limiting the number of bytes per project. We want
to support these as well.

Why is QuotaEnforcer offering a refill mechanism?
We offer a refill mechanism that basically tries to roll-back the last
quota request. This is only triggered when one of the QuotaEnforcers
denied the request, but other succeed. In this case, the succeeded ones
might have deducted quota for the request, even though others did not
and we let the request fail because of a lack of quota. In this case
we want to try to undo the action. This is best-effort and plugins
can choose not to do refilling.

Why is QuotaBackend *not* offering a refill mechanism?
We don't want to pollute core-Gerrit with try-catch-finally blocks that
refill quota. This is a design decision to keep the code simple. An
action in Gerrit that failed after it passed a quota check will have
deducted quota. Most QuotaEnforcer implementations are refilling, so
this is only a cosmetic issue that vanishes fast. Overall, we see the
QuotaBackend as a monolith, that can support internal rollbacks without
offering this mechanism to external callers.

In subsequent commits, we want to add quota checks to Gerrit-core and
adapt the Quota Plugin to use the new system instead of other hooks as
it does right now.

We will also provide tests where applicable.

Change-Id: I0ac9d4de583871f92040db55f0df29465029ad55