.. _envoy_v3_api_file_envoy/type/v3/ratelimit_strategy.proto:

Rate Limit Strategies (proto)
=============================


.. warning::
   This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the :ref:`threat model <arch_overview_threat_model>`, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.







.. _envoy_v3_api_msg_type.v3.RateLimitStrategy:

type.v3.RateLimitStrategy
-------------------------


:repo:`[type.v3.RateLimitStrategy proto] <api/envoy/type/v3/ratelimit_strategy.proto#L21>`




.. code-block:: json
  :force:

  {
    "blanket_rule": ...,
    "requests_per_time_unit": {...},
    "token_bucket": {...}
  }

.. _envoy_v3_api_field_type.v3.RateLimitStrategy.blanket_rule:


blanket_rule
  (:ref:`type.v3.RateLimitStrategy.BlanketRule <envoy_v3_api_enum_type.v3.RateLimitStrategy.BlanketRule>`) Allow or Deny the requests.
  If unset, allow all.


  

  Precisely one of :ref:`blanket_rule <envoy_v3_api_field_type.v3.RateLimitStrategy.blanket_rule>`, :ref:`requests_per_time_unit <envoy_v3_api_field_type.v3.RateLimitStrategy.requests_per_time_unit>`, :ref:`token_bucket <envoy_v3_api_field_type.v3.RateLimitStrategy.token_bucket>` must be set.

.. _envoy_v3_api_field_type.v3.RateLimitStrategy.requests_per_time_unit:


requests_per_time_unit
  (:ref:`type.v3.RateLimitStrategy.RequestsPerTimeUnit <envoy_v3_api_msg_type.v3.RateLimitStrategy.RequestsPerTimeUnit>`) Best-effort limit of the number of requests per time unit, f.e. requests per second.
  Does not prescribe any specific rate limiting algorithm, see :ref:`RequestsPerTimeUnit
  <envoy_v3_api_msg_type.v3.RateLimitStrategy.RequestsPerTimeUnit>` for details.


  

  Precisely one of :ref:`blanket_rule <envoy_v3_api_field_type.v3.RateLimitStrategy.blanket_rule>`, :ref:`requests_per_time_unit <envoy_v3_api_field_type.v3.RateLimitStrategy.requests_per_time_unit>`, :ref:`token_bucket <envoy_v3_api_field_type.v3.RateLimitStrategy.token_bucket>` must be set.

.. _envoy_v3_api_field_type.v3.RateLimitStrategy.token_bucket:


token_bucket
  (:ref:`type.v3.TokenBucket <envoy_v3_api_msg_type.v3.TokenBucket>`) Limit the requests by consuming tokens from the Token Bucket.
  Allow the same number of requests as the number of tokens available in
  the token bucket.


  

  Precisely one of :ref:`blanket_rule <envoy_v3_api_field_type.v3.RateLimitStrategy.blanket_rule>`, :ref:`requests_per_time_unit <envoy_v3_api_field_type.v3.RateLimitStrategy.requests_per_time_unit>`, :ref:`token_bucket <envoy_v3_api_field_type.v3.RateLimitStrategy.token_bucket>` must be set.

.. _envoy_v3_api_msg_type.v3.RateLimitStrategy.RequestsPerTimeUnit:

type.v3.RateLimitStrategy.RequestsPerTimeUnit
---------------------------------------------


:repo:`[type.v3.RateLimitStrategy.RequestsPerTimeUnit proto] <api/envoy/type/v3/ratelimit_strategy.proto#L42>`

Best-effort limit of the number of requests per time unit.

Allows to specify the desired requests per second (RPS, QPS), requests per minute (QPM, RPM),
etc., without specifying a rate limiting algorithm implementation.

``RequestsPerTimeUnit`` strategy does not demand any specific rate limiting algorithm to be
used (in contrast to the :ref:`TokenBucket <envoy_v3_api_msg_type.v3.TokenBucket>`,
for example). It implies that the implementation details of rate limiting algorithm are
irrelevant as long as the configured number of "requests per time unit" is achieved.

Note that the ``TokenBucket`` is still a valid implementation of the ``RequestsPerTimeUnit``
strategy, and may be chosen to enforce the rate limit. However, there's no guarantee it will be
the ``TokenBucket`` in particular, and not the Leaky Bucket, the Sliding Window, or any other
rate limiting algorithm that fulfills the requirements.



.. code-block:: json
  :force:

  {
    "requests_per_time_unit": ...,
    "time_unit": ...
  }

.. _envoy_v3_api_field_type.v3.RateLimitStrategy.RequestsPerTimeUnit.requests_per_time_unit:


requests_per_time_unit
  (`uint64 <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) The desired number of requests per :ref:`time_unit
  <envoy_v3_api_field_type.v3.RateLimitStrategy.RequestsPerTimeUnit.time_unit>` to allow.
  If set to ``0``, deny all (equivalent to ``BlanketRule.DENY_ALL``).

  .. note::
    Note that the algorithm implementation determines the course of action for the requests
    over the limit. As long as the ``requests_per_time_unit`` converges on the desired value,
    it's allowed to treat this field as a soft-limit: allow bursts, redistribute the allowance
    over time, etc.



.. _envoy_v3_api_field_type.v3.RateLimitStrategy.RequestsPerTimeUnit.time_unit:


time_unit
  (:ref:`type.v3.RateLimitUnit <envoy_v3_api_enum_type.v3.RateLimitUnit>`) The unit of time. Ignored when :ref:`requests_per_time_unit
  <envoy_v3_api_field_type.v3.RateLimitStrategy.RequestsPerTimeUnit.requests_per_time_unit>`
  is ``0`` (deny all).



.. _envoy_v3_api_enum_type.v3.RateLimitStrategy.BlanketRule:

Enum type.v3.RateLimitStrategy.BlanketRule
------------------------------------------


:repo:`[type.v3.RateLimitStrategy.BlanketRule proto] <api/envoy/type/v3/ratelimit_strategy.proto#L23>`

Choose between allow all and deny all.



.. _envoy_v3_api_enum_value_type.v3.RateLimitStrategy.BlanketRule.ALLOW_ALL:


ALLOW_ALL
  *(DEFAULT)* ⁣

.. _envoy_v3_api_enum_value_type.v3.RateLimitStrategy.BlanketRule.DENY_ALL:


DENY_ALL
  ⁣