THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
As such, reasoning around quotas can be complex, as it's not immediately obvious which quotas may apply to a given user and/or client ID. Providing descriptive information is a goal of this KIP.
Public Interfaces
Common
...
types in package org.apache.kafka.common.quota:
Code Block |
---|
/** * RepresentsDescribes thea default name for an entity, i.e. the entity that's matchedfully-qualified entity. */ public class QuotaEntity { /** * whenType of an exact match isn't foundentity entry. */ public final static String QUOTA_ENTITY_DEFAULT = // implementation defined enum Type { USER, /** CLIENT_ID; * Describes an entity type. } /**/ public enum* QuotaEntityTypeRepresents { the default name for an USERentity, i.e. the entity that's matched // The user* principal. when an exact match isn't found. CLIENT_ID, // The client ID. */ public final static // Note others may be added in the future. }String QUOTA_ENTITY_NAME_DEFAULT = // implementation defined /** * `entries` Describesdescribes athe fully-qualified entity. The key is a */ public class QuotaEntity { /** * `entries` describes the fully-qualified entity. The key is a QuotaEntityType string, however {@code Type} string, however * there may also exist keys that are not enumerated by {@code Type} that still apply, e.g. * the server may internally associate another type. It's necessary to return all quota types * therebecause mayquota alsovalues existfor keysthese thattypes aremay notinfluence enumeratedthe byeffective QuotaEntityTypequota that still apply, e.g.value. However, * altering a quota, *any thetypes serverthat mayaren't internallyspecified associateshould anotherbe type. It's necessary to return all quota types able to be inferred by the * server, otherwise an error is returned. * because quota values* for these types may influence* theFor effective quota value. Howeverexample, {("CLIENT_ID" -> "test-client"), * * altering a quota, any types that aren't specified should be able to be inferred by the ("USER" -> "test-user"), * * server, otherwise an error is returned. ("GROUP" -> "internal-group")}. */ public QuotaEntity(Map<String, String> entries); } /** * ForDescribes example, {("CLIENT_ID" -> "test-client"), a quota key. */ public class QuotaKey { /** * The quota types. ("USER" -> "test-user"),*/ public enum Type { * CONSUMER_BYTE_RATE, ("GROUP" -> "internal-group")}. PRODUCER_BYTE_RATE, REQUEST_PERCENTAGE; */} /** public QuotaEntity(Map<String, String> entries); public Map<String, String> entries(); } * The units for a quota value. Note there may be multiple units for a given quota type /** that * The influences quota typesbehavior. */ public enum QuotaTypeUnits { CONSUMER_BYTE_RATE,RATE_BPS; } PRODUCER_BYTE_RATE,/** * @param REQUEST_PERCENTAGE, type the quota type * //@param Noteunits othersthe mayunits befor addedthe in the future.quota type } /** */ * The units forpublic QuotaKey(Type type, Units units); } /** * Describes a quota valueentity filter. Note there may be multiple units for a given quota type*/ public class QuotaFilter { public enum Rule { * that influences quotaEXACT, behavior. *// exact public enum QuotaUnits {name match RATE_BPS, PREFIX; // Notematches othersall may be added innames with the future, e.g. RATE_BPS_PER_BROKER, SHARES.given prefix } /** * Describes a quota keyA filtering rule to be applied. */ public class* QuotaKey@param { entityType the entity type the rule applies /** to * @param typerule the rule quotato typeapply * @param unitsmatch the non-null unitsstring forthat's theapplied quotaby type the rule */ public QuotaFilter(QuotaEntity.Type entityType, public QuotaKey(QuotaType typeRule rule, QuotaUnitsString unitsmatch); } |
DescribeQuotas API:
Code Block |
---|
public class DescribeQuotasOptions extends AbstractOptions<DescribeQuotasOptions> { public QuotaType type(); public QuotaUnits units(); } |
DescribeQuotas
Code Block |
---|
public class QuotaFilter { public enum Rule { EXACT, // exact name match NOT, // matches all non-matching names// Empty. } /** * The result of the {@link Admin#describeQuotas(Collection<QuotaFilter>, DescribeQuotasOptions)} call. * * The API of this class is evolving, see {@link Admin} for details. */ public class DescribeQuotasResult { /** * Maps an entity to its configured quota value(s). Note if no value is defined for a quota * type for that entity's config, then it is not included in the resulting value map. * * @param PREFIX,entities the collection //of matchesentities allthat names withmatched the given prefixfilter */ DescribeQuotasResult(KafkaFuture<Map<QuotaEntity, Map<QuotaKey, // Note others may be added in the future. } /** * A filtering rule to be applied.Double>>> entities); /** * Returns a map from quota entity to a future which can be used to check the status of the operation. */ public KafkaFuture<Map<QuotaEntity, Map<QuotaKey, * Double>>> entities(); } public interface Admin extends AutoCloseable { * @param... entity the entity the/** rule applies to * Describes all entities matching all *provided @paramfilters rule(logical theAND) rulethat tohave apply at least one * @paramquota matchvalue the non-null string that's applied by the rule */defined. * * @param filters filtering rules to apply to matching entities * @param publicoptions QuotaFilter(QuotaEntity entity, Rule rule, String match); the options to use * @return result containing publicall QuotaEntity entity();matching entities */ public Rule rule(DescribeQuotasResult describeQuotas(Collection<QuotaFilter> filters, DescribeQuotasOptions options); } |
DescribeEffectiveQuotas
Code Block |
---|
public class DescribeEffectiveQuotasOptions extends AbstractOptions<DescribeEffectiveQuotasOptions> { public String match(); /** } * Whether to publicinclude classthe DescribeQuotasOptionslist { of overridden values for every quota type in //the Defaultresult. }*/ DescribeEffectiveQuotasOptions public class DescribeQuotasResult { /** * Maps an entity to its configured quota value(s). Note if no value is defined for a quota * type for that entity's config, then it is not included in the resulting value map. * * @return the collection of entities that matched the filter */ KafkaFuture<Map<QuotaEntity, Map<QuotaKey, Double>>> entities(); } public interface Admin extends AutoCloseable { /** * Describes all entities matching all provided filters (logical AND) that have at least one * quota value defined. * * @param filters filtering rules to apply to matching entities * @param options the options to use * @return result containing all matching entities */ DescribeQuotasResult describeQuotas(Collection<QuotaFilter> filters, DescribeQuotasOptions options); } |
DescribeEffectiveQuotas
Code Block |
---|
public class DescribeEffectiveQuotasOptions { // Whether to include the list of overridden values for every quota type in the result. // // Default: false. DescribeQuotasOptions setOmitOverriddenValues(boolean omitOverriddenValues); } public class DescribeEffectiveQuotasResult { /** * Information about a specific quota configuration entry. */ public class Entry { /** * @param source the entity source for the value * @param value the non-null value */ public Entry(QuotaEntity source, Double value); public QuotaEntity source(); public Double value(); } /** * Information about the value for a quota type. */ public class Value { /** * @param entry the quota entry * @param overriddenEntries all values that are overridden due to being lower in * specificity, or null if not requested */ public Value(Entry entry, List<Entry> overriddenEntries); public Entry entry(); public List<Entry> overriddenEntries();setOmitOverriddenValues(boolean omitOverriddenValues); } /** * The result of the {@link Admin#describeEffectiveQuotas(Collection<QuotaEntity>, DescribeEffectiveQuotasOptions)} call. * * The API of this class is evolving, see {@link Admin} for details. */ public class DescribeEffectiveQuotasResult { /** * Information about a specific quota configuration entry. */ public class Entry { /** } * @param source the entity source for the /**value * Maps a quota type to its configuration.@param value the non-null value */ public Map<QuotaEntity, KafkaFuture<Map<QuotaKeyEntry(QuotaEntity source, Value>>>Double config(value); } public interface Admin extends AutoCloseable { /** * Describes the effective quotas for the provided entities. Information about the value for a quota type. */ public class Value { * @param entities the entities to describe the effective quotas for /** * @param optionsentry the optionsquota to useentry * @param overriddenEntries @returnall thevalues effectivethat quotasare foroverridden thedue entities to being lower in */ * DescribeEffectiveQuotasResult describeEffectiveQuotas(Collection<QuotaEntity> entities, specificity, or null if not requested */ public Value(Entry entry, List<Entry> overriddenEntries); } /** * Maps a collection DescribeEffectiveQuotasOptions options); } |
AlterQuotas
Code Block |
---|
public class AlterQuotasEntry {of entities to their effective quota values. * * @param config publicthe classquota Opconfiguration { for the requested entities */ /** public DescribeEffectiveQuotasResult(Map<QuotaEntity, KafkaFuture<Map<QuotaKey, Value>>> config); /** * Returns @parama keymap thefrom quota type and unitsentity to alter a future which can be used to check the status of the operation. * @param value if set*/ then the existing valuepublic isMap<QuotaEntity, updatedKafkaFuture<Map<QuotaKey, Value>>> config(); /** * Returns *a future which succeeds only if all quota descriptions succeed. otherwise*/ if null, the existingpublic value is cleared KafkaFuture<Void> all(); } public interface Admin extends AutoCloseable { ... /**/ * Describes the effective quotas for the public Op(QuotaKey key, Double value); provided entities. * * @param publicentities QuotaKey key(); the entities to describe the effective quotas for * public@param Double value(); options the options to use } * @return the effective quotas for the /**entities */ *DescribeEffectiveQuotasResult describeEffectiveQuotas(Collection<QuotaEntity> entities, DescribeEffectiveQuotasOptions options); } |
AlterQuotas
Code Block |
---|
public class AlterQuotasOptions extends AbstractOptions<AlterQuotasOptions> { @param entity the entity whose config will be modified /** * @paramSets opswhether the alterationrequest toshould performbe -validated ifwithout value is set, then the existing value is updated,altering the configs. */ *public AlterQuotasOptions validateOnly(boolean validateOnly); } /** * The result of the {@link Admin#alterQuotas(Collection<AlterQuotasEntry>, otherwise if null, the existing value is cleared AlterQuotasOptions)} call. * * The API of this class is evolving, see {@link Admin} for details. */ public class AlterQuotasResult { public AlterQuotasEntryAlterQuotasResult(QuotaEntity entityMap<QuotaEntity, Collection<Op>KafkaFuture<Void>> opsfutures); public QuotaEntity entity();/** * Returns a publicmap Collection<Ops> ops(); } public class AlterQuotasOptions { // Default. } from quota entity to a future which can be used to check the status of the operation. */ public classMap<QuotaEntity, AlterQuotasResult { KafkaFuture<Void>> values(); /** * @return map ofReturns a quotafuture entitywhich updatesucceeds to its future only if all quota alterations succeed. */ public Map<QuotaEntity, KafkaFuture<Void>> futuresKafkaFuture<Void> all(); } public interface Admin extends AutoCloseable { ... /** * Alters the quotas as specified for the entries. * * @param alterations the alterations to perform * @return the result of the alterations */ AlterQuotasResult alterQuotas(Collection<AlterQuotasEntry> entries, AlterQuotasOptions options); } |
Proposed Changes
TODO: Wire protocol.
...