Page History

/**
 * Quota callback interface for brokers that enables customization of client quota computation.
 */
public interface ClientQuotaCallback extends Configurable {

    /**
     * Quota callback invoked to determine the quota metric tags to be applied for a request.
     * Quota limits are associated with quota metrics and all clients which use the same
     * metric tags share the quota limit.
     *
     * @param quotaType Type of quota requested
     * @param principal The user principal of the connection for which quota is requested
     * @param clientId  The client id associated with the request
     * @param quotaType Type of quota requested
     * @return quota metric tags that indicate which other clients share this quota
     */
    Map<String, String> quotaMetricTags(ClientQuotaType quotaType, KafkaPrincipal principal, String clientId, ClientQuotaType quotaType);

    /**
     * Returns the quota limit associated with the provided metric tags. These tags were returned from
     * a previous call to {@link #quotaMetricTags(ClientQuotaType, KafkaPrincipal, String, ClientQuotaType)}. This method is
     * invoked by quota managers to obtain the current quota limit applied to a metric when the first request
     * using these tags is processed. It is also invoked after a quota update or cluster metadata change.
     * If the tags are no longer in use after the update, (e.g. this is a {user, client-id} quota metric
     * and the quota now in use is a {user} quota), null is returned.
     *
     * @param metricTagsquotaType Metric tagsType forof aquota quotarequested
 metric of type `quotaType`
 * @param metricTags Metric *tags @paramfor quotaTypea quota Typemetric of quotatype requested`quotaType`
     * @return the quota limit for the provided metric tags or null if the metric tags are no longer in use
     */
    Double quotaLimit(ClientQuotaType quotaType, Map<String, String> metricTags, ClientQuotaType quotaType);

    /**
     * Quota Metadataconfiguration update callback that is invoked when wheneverquota UpdateMetadataconfiguration requestfor isan receivedentity fromis
     * updated thein controllerZooKeeper. This is useful ifto track quotaconfigured computationquotas takesif partitionsbuilt-in intoquota account.configuration
     * Topics thattools are beingused deletedfor will not be included in `cluster`quota management.
     *
     * @param clusterquotaType Cluster metadata includingType partitionsof andquota their leaders if knownbeing updated
     * @return@param true if quotas have changed and metric configs may need to be updatedquotaEntity The quota entity for which quota is being updated
     * @param newValue    The new quota value
     */
    booleanvoid updateClusterMetadata(Cluster clusterupdateQuota(ClientQuotaType quotaType, ClientQuotaEntity quotaEntity, double newValue);

    /**
     * Quota configuration updateremoval callback that is invoked when quota configuration for an entity is
     * updatedremoved in ZooKeeper. This is useful to track configured quotas if built-in quota configuration
     * tools are used for quota management.
     *
     * @param quotaEntityquotaType The quota entityType for whichof quota is being updated
     * @param quotaEntity quotaTypeThe quota entity Typefor ofwhich quota is being updated
     * @param newValue    The new quota value/
    void removeQuota(ClientQuotaType quotaType, ClientQuotaEntity quotaEntity);

    /**
     * @returnReturns true if quotasany haveof changedthe and metric configs may need to be updatedexisting quota configs may have been updated since the last call
     * to this method for the provided quota type. Quota updates as a result of calls to
     * {@link #updateClusterMetadata(Cluster)}, {@link #updateQuota(ClientQuotaType, ClientQuotaEntity, double)}
     * and {@link #removeQuota(ClientQuotaType, ClientQuotaEntity)} are automatically processed.
     * So callbacks that rely only on built-in quota configuration tools always return false. Quota callbacks
     * with external quota configuration or custom reconfigurable quota configs that affect quota limits must
     * return true if existing metric configs may need to be updated. This method is invoked on every request
     * and hence is expected to be handled by callbacks as a simple flag that is updated when quotas change.
     *
     * @param quotaType Type of quota
     */
    boolean updateQuotaquotaResetRequired(ClientQuotaEntity quotaEntity, ClientQuotaType quotaType, double newValue);

    /**
     * QuotaMetadata configuration removalupdate callback that is invoked whenwhenever quotaUpdateMetadata configurationrequest foris anreceived entity isfrom
     * removedthe in ZooKeepercontroller. This is useful to track configured quotas if built-in quota configuration
computation takes    * tools are used for quota managementpartitions into account.
     *
 Topics that are being *deleted @paramwill quotaEntitynot Thebe quotaincluded entityin for`cluster`.
 which quota is being updated.*
     * @param quotaTypecluster Cluster metadata including partitions Typeand oftheir quotaleaders beingif updated.known
     * @return true if quotas have changed and metric configs may need to be updated
     */
    boolean removeQuotaupdateClusterMetadata(ClientQuotaEntity quotaEntity, ClientQuotaType quotaTypeCluster cluster);

    /**
     * Closes this instance.
     */
    void close();
}