trait ClientQuotaCallback extends Configurable {

  /**
    * Quota callback invoked to determine the quota limit to be applied for a request.
    * 
    * @param session The session for which quota is requested
    * @param clientId The client id associated with the request
    * @param quotaType Type of quota requested
    *                  
    * @return the quota including the limit and metric tags that indicate which other entities share this quota
    */
  def quota(session: Session, clientId: String, quotaType: ClientQuotaType): ClientQuota

  /**
   * Returns the quota limit associated with the provided metric tags. These tags were returned from
   * a previous call to [[ClientQuotaCallback.quota()]]. This method is invoked by quota managers to
   * obtain the current quota limit applied to a metric after a quota update or partition 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), None is returned.
   *
   * @param metricTags Metric tags for a quota metric of type `quotaType`
   * @param quotaType Type of quota requested
   * @return the quota limit for the provided metric tags or None if the metric tags are no longer in use
   */
  def quotaLimit(metricTags: Map[String, String], quotaType: ClientQuotaType): Option[Double]

   /**
    * Metadata update callback that is invoked whenever UpdateMetadata request is received from
    * the controller. This is useful if quota computation is takes partitions into account.
    * The full list of partitions in the cluster will be provided including those whose leader is
    * this broker. The metadata for each partition will include the current leader information.
    * Deleted partitions will not be included in `partitions`. 
    * 
     * @param partitions All Partitionspartitions and their metadata including partition leader 
    * @return true if quotas have changed
    */
  def updatePartitionMetadata(partitions: Map[TopicPartition, PartitionMetadata]): Boolean

  /**
    * Quota configuration update callback that is invoked whenever quota configuration in ZooKeeper
    * is updated. This is useful to track configured quotas if the built-in quota configuration tools
    * are used.
    * 
    * @param quotaEntity The quota entity for which quota is being updated.
    * @param quotaType Type of quota being updated.
    * @param newValue The new quota value. If None, the quota configuration for `quotaEntity` is deleted.
    * @return true if quotas have changed
    */
  def updateQuota(quotaEntity: ClientQuotaEntity, quotaType: ClientQuotaType, newValue: Option[Double]) : Boolean

  /**
    * Closes this instance.
    */
  def close(): Unit
}

/**
  * Partition metadata that may be used in quota computation. This is provided
  * by the broker when UpdateMetadata request is received from the controller.
  */
trait PartitionMetadata {
  def leader: Option[Int]
}