Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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.

...