Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: editorial references ( SELF , HTTP , STRUCTURED - FIELDS ) remove backticks remove ABNF 
 editorial cleanup according to 
 Addressed in
Paragraph (version A):
This document defines the RateLimit-Limit, RateLimit-Remaining,
RateLimit-Reset fields for HTTP, thus allowing servers to publish
current service limits and clients to shape their request policy and
avoid being throttled out.
Paragraph (version B):
This document defines the RateLimit-Limit, RateLimit-Remaining,
RateLimit-Reset and RateLimit-Policy fields for HTTP, thus allowing
servers to publish current service limits and clients to shape their
request policy and avoid being throttled out.
Paragraph (version A):
References to "ThisRFC" in the IANA Considerations section would be
replaced with the RFC number when assigned.
Paragraph (version A):
This was partially addressed by the "Retry-After" header field
defined in SEMANTICS to be returned in 429 (Too Many Request) (see
STATUS429) or 503 (Service Unavailable) responses.
Paragraph (version B):
This was partially addressed by the "Retry-After" header field
defined in HTTP to be returned in 429 (Too Many Request) (see
STATUS429) or 503 (Service Unavailable) responses.
Paragraph (version A):
"RateLimit-Policy": containing the quota policy information.
Paragraph (version A):
The behavior of "RateLimit-Reset" is compatible with the "delay-
seconds" notation of "Retry-After".
Paragraph (version B):
RateLimit-Policy: containing the quota policy information.
Paragraph (version B):
The behavior of the RateLimit-Reset field is compatible with the
delay-seconds notation of Retry-After.
Paragraph (version A):
This specification does not cover the throttling scope, that may
be the given resource-target, its parent path or the whole Origin
(see Section 7 of RFC6454).  This can be addressed using
extensibility mechanisms such as the parameter registry iana-
ratelimit-parameters.
Paragraph (version A):
RateLimit fields may be returned in both successful (see
Section 15.3 of SEMANTICS) and non-successful responses.  This
specification does not cover whether non Successful responses
count on quota usage, nor it mandates any correlation between the
RateLimit values and the returned status code.
Paragraph (version B):
This specification does not cover the throttling scope, that may
be the given resource-target, its parent path or the whole Origin
(see Section 7 of WEB-ORIGIN).  This can be addressed using
extensibility mechanisms such as the parameter registry iana-
ratelimit-parameters.
Paragraph (version B):
RateLimit fields may be returned in both successful (see
Section 15.3 of HTTP) and non-successful responses.  This
specification does not cover whether non Successful responses
count on quota usage, nor it mandates any correlation between the
RateLimit values and the returned status code.
Paragraph (version A):
This document uses the Augmented BNF defined in RFC5234 and updated
by RFC7405 along with the "#rule" extension defined in Section 5.6.1
of SEMANTICS.
Paragraph (version A):
The term Origin is to be interpreted as described in Section 7 of
RFC6454.
Paragraph (version A):
This document uses the following terminology from Section 3 of SF to
specify syntax and parsing: List, Item, String, Token and Integer
together with the concept of bare item.
Paragraph (version A):
Rate limit policies limit the number of acceptable requests in a
given time window.
Paragraph (version A):
Where "delay-seconds" is a non-negative Integer compatible with the
"delay-seconds" rule defined in Section 10.2.3 of SEMANTICS.
Paragraph (version A):
The service-limit is a value associated to the maximum number of
requests that the server is willing to accept from one or more
clients on a given basis (originating IP, authenticated user,
geographical, ..) during a "time-window" as defined in time-window.
Paragraph (version A):
where "quota-units" is a non-negative Integer.
Paragraph (version A):
The "service-limit" SHOULD match the maximum number of acceptable
requests.
Paragraph (version A):
The "service-limit" MAY differ from the total number of acceptable
requests when weight mechanisms, bursts, or other server policies are
implemented.
Paragraph (version A):
If the "service-limit" does not match the maximum number of
acceptable requests the relation with that SHOULD be communicated
out-of-band.
Paragraph (version B):
This document uses the Augmented BNF defined in RFC5234 and updated
by RFC7405 along with the "#rule" extension defined in Section 5.6.1
of HTTP.
Paragraph (version B):
The term Origin is to be interpreted as described in Section 7 of
WEB-ORIGIN.
Paragraph (version B):
This document uses the following terminology from Section 3 of
STRUCTURED-FIELDS to specify syntax and parsing: List, Item and
Integer together with the concept of bare item.
Paragraph (version B):
The fields defined in this document are collectively named "RateLimit
fields".
Paragraph (version B):
Rate limit policies limit the number of acceptable requests in a
given time interval.
Paragraph (version B):
The "time-window" is a non-negative Integer value expressing such
interval in seconds compatible with the "delay-seconds" rule defined
in Section 10.2.3 of HTTP.
Paragraph (version B):
The "service-limit" is a value associated to the maximum number of
requests that the server is willing to accept from one or more
clients on a given basis (originating IP, authenticated user,
geographical, ..) during a time-window.
Paragraph (version B):
The service-limit is a non-negative Integer expressed in "quota-
units".
Paragraph (version B):
The service-limit SHOULD match the maximum number of acceptable
requests.
Paragraph (version B):
The service-limit MAY differ from the total number of acceptable
requests when weight mechanisms, bursts, or other server policies are
implemented.
Paragraph (version B):
If the service-limit does not match the maximum number of acceptable
requests the relation with that SHOULD be communicated out-of-band.
Paragraph (version A):
where the associated bare-item is a service-limit and parameters are
supported.
Paragraph (version A):
The REQUIRED "w" parameter specifies a time window.  Its syntax is
a "time-window" defined in time-window.
Paragraph (version B):
A "quota-policy" describes a quota policy in terms of service-limit
and time-window.  Its value is an Item where the associated bare item
is a service-limit and parameters are supported.
Paragraph (version B):
The REQUIRED "w" parameter value conveys a "time-window" value as
defined in time-window.
Paragraph (version A):
"RateLimit-Remaining" is RECOMMENDED.
Paragraph (version B):
RateLimit-Remaining field is RECOMMENDED.
Paragraph (version A):
A server MAY return "RateLimit" response fields independently of the
response status code.  This includes throttled responses.
Paragraph (version A):
This document does not mandate any correlation between the
"RateLimit" values and the returned status code.
Paragraph (version A):
Servers should be careful in returning "RateLimit" fields in
redirection responses (e.g. 3xx status codes) because a low
"RateLimit-Remaining" value could prevent the client from issuing
requests.  For example, given the rate limiting fields below, a
client could decide to wait 10 seconds before following the
"Location" header, because "RateLimit-Remaining" is 0.
Paragraph (version A):
If a response contains both the "Retry-After" and the "RateLimit-
Reset" fields, the value of "RateLimit-Reset" SHOULD reference the
same point in time as "Retry-After".
Paragraph (version A):
When using a policy involving more than one "time-window", the server
MUST reply with the "RateLimit" fields related to the window with the
lower "RateLimit-Remaining" values.
Paragraph (version A):
A service returning "RateLimit" fields MUST NOT convey values
exposing an unwanted volume of requests and SHOULD implement
mechanisms to cap the ratio between "RateLimit-Remaining" and
"RateLimit-Reset" (see sec-resource-exhaustion); this is especially
important when quota-policies use a large "time-window".
Paragraph (version A):
Under certain conditions, a server MAY artificially lower "RateLimit"
field values between subsequent requests, e.g. to respond to Denial
of Service attacks or in case of resource saturation.
Paragraph (version A):
Servers usually establish whether the request is in-quota before
creating a response, so the RateLimit field values should be already
available in that moment.  Nonetheless servers MAY decide to send the
"RateLimit" fields in a trailer section.
Paragraph (version A):
Servers are not required to return "RateLimit" fields in every
response, and clients need to take this into account.  For example,
an implementer concerned with performance might provide "RateLimit"
fields only when a given quota is going to expire.
Paragraph (version B):
A server MAY return RateLimit fields independently of the response
status code.  This includes throttled responses.
Paragraph (version B):
This document does not mandate any correlation between the RateLimit
field values and the returned status code.
Paragraph (version B):
Servers should be careful in returning RateLimit fields in
redirection responses (e.g. 3xx status codes) because a low
RateLimit-Remaining field value could prevent the client from issuing
requests.  For example, given the RateLimit fields below, a client
could decide to wait 10 seconds before following the "Location"
header field (see Section 10.2.2 of HTTP), because the RateLimit-
Remaining field value is 0.
Paragraph (version B):
If a response contains both the Retry-After and the RateLimit-Reset
fields, the RateLimit-Reset field value SHOULD reference the same
point in time as the Retry-After field value.
Paragraph (version B):
When using a policy involving more than one time-window, the server
MUST reply with the RateLimit fields related to the time window with
the lower RateLimit-Remaining field values.
Paragraph (version B):
A service returning RateLimit fields MUST NOT convey values exposing
an unwanted volume of requests and SHOULD implement mechanisms to cap
the ratio between RateLimit-Remaining and RateLimit-Reset field
values (see sec-resource-exhaustion); this is especially important
when quota-policies use a large time-window.
Paragraph (version B):
Under certain conditions, a server MAY artificially lower RateLimit
field values between subsequent requests, e.g. to respond to Denial
of Service attacks or in case of resource saturation.
Paragraph (version B):
Servers usually establish whether the request is in-quota before
creating a response, so the RateLimit field values should be already
available in that moment.  Nonetheless servers MAY decide to send the
RateLimit fields in a trailer section.
Paragraph (version B):
Servers are not required to return RateLimit fields in every
response, and clients need to take this into account.  For example,
an implementer concerned with performance might provide RateLimit
fields only when a given quota is going to expire.
Paragraph (version A):
A client MUST process the received "RateLimit" fields.
Paragraph (version A):
A client MUST validate the values received in the "RateLimit" fields
before using them and check if there are significant discrepancies
with the expected ones.  This includes a "RateLimit-Reset" moment too
far in the future or a "service-limit" too high.
Paragraph (version A):
A client receiving "RateLimit" fields MUST NOT assume that subsequent
responses contain the same "RateLimit" fields, or any "RateLimit"
fields at all.
Paragraph (version A):
Malformed "RateLimit" fields MAY be ignored.
Paragraph (version A):
A client SHOULD NOT exceed the "quota-units" expressed in "RateLimit-
Remaining" before the "time-window" expressed in "RateLimit-Reset".
Paragraph (version A):
A client MAY still probe the server if the "RateLimit-Reset" is
considered too high.
Paragraph (version A):
The value of "RateLimit-Reset" is generated at response time: a
client aware of a significant network latency MAY behave accordingly
and use other information (e.g. the "Date" response header field, or
otherwise gathered metrics) to better estimate the "RateLimit-Reset"
moment intended by the server.
Paragraph (version A):
The details provided in "RateLimit-Policy" are informative and MAY be
ignored.
Paragraph (version A):
If a response contains both the "RateLimit-Reset" and "Retry-After"
fields, "Retry-After" MUST take precedence and "RateLimit-Reset" MAY
be ignored.
Paragraph (version B):
A client MUST validate the values received in the RateLimit fields
before using them and check if there are significant discrepancies
with the expected ones.  This includes a RateLimit-Reset field moment
too far in the future (e.g. similarly to receiving "Retry-after:
1000000") or a service-limit too high.
Paragraph (version B):
A client receiving RateLimit fields MUST NOT assume that subsequent
responses contain the same RateLimit fields, or any RateLimit fields
at all.
Paragraph (version B):
Malformed RateLimit fields MAY be ignored.
Paragraph (version B):
A client SHOULD NOT exceed the quota-units conveyed by the RateLimit-
Remaining field before the time-window expressed in RateLimit-Reset
field.
Paragraph (version B):
A client MAY still probe the server if the RateLimit-Reset field is
considered too high.
Paragraph (version B):
The value of RateLimit-Reset field is generated at response time: a
client aware of a significant network latency MAY behave accordingly
and use other information (e.g. the "Date" response header field, or
otherwise gathered metrics) to better estimate the RateLimit-Reset
field moment intended by the server.
Paragraph (version B):
The details provided in RateLimit-Policy field are informative and
MAY be ignored.
Paragraph (version B):
If a response contains both the RateLimit-Reset and Retry-After
fields, the Retry-After field MUST take precedence and the RateLimit-
Reset field MAY be ignored.
Paragraph (version A):
This section documents the considerations advised in Section 16.3.2
of SEMANTICS.
Paragraph (version B):
This section documents the considerations advised in Section 16.3.2
of HTTP.
Paragraph (version A):
As is the ordinary case for HTTP caching (RFC7234), a response with
RateLimit fields might be cached and re-used for subsequent requests.
A cached "RateLimit" response does not modify quota counters but
could contain stale information.  Clients interested in determining
the freshness of the "RateLimit" fields could rely on fields such as
"Date" and on the "time-window" of a "quota-policy".
Paragraph (version A):
The "RateLimit-Limit" response field indicates the "service-limit"
associated to the client in the current "time-window".
Paragraph (version A):
The field is a non-negative Integer.  Its value is named "expiring-
limit".
Paragraph (version A):
The "RateLimit-Policy" field (see ratelimit-policy-field), might
contain information on the associated "time-window".
Paragraph (version A):
The "RateLimit-Policy" response field indicates the "quota"
associated to the client and its value is informative.
Paragraph (version A):
The field is a non-empty List of quota policies (see quota-policy).
Paragraph (version A):
A "time-window" associated to "expiring-limit" can be communicated
via "RateLimit-Policy", like shown in the following example.
Paragraph (version A):
The "RateLimit-Remaining" response field indicates the remaining
"quota-units" defined in service-limit associated to the client.
Paragraph (version A):
The field is a non-negative Integer expressed in "quota-units".
Paragraph (version A):
Clients MUST NOT assume that a positive "RateLimit-Remaining" value
is a guarantee that further requests will be served.
Paragraph (version A):
A low "RateLimit-Remaining" value is like a yellow traffic-light for
either the number of requests issued in the "time-window" or the
request throughput: the red light may arrive suddenly (see providing-
ratelimit-fields).
Paragraph (version A):
One example of "RateLimit-Remaining" use is below.
Paragraph (version A):
The "RateLimit-Reset" response field indicates the number of seconds
until the quota resets.
Paragraph (version A):
The field is a non-negative Integer.
Paragraph (version B):
privacy provide further guidance on intermediaries.
Paragraph (version B):
As is the ordinary case for HTTP caching (HTTP-CACHING), a response
with RateLimit fields might be cached and re-used for subsequent
requests.  A cached response containing RateLimit fields does not
modify quota counters but could contain stale information.  Clients
interested in determining the freshness of the RateLimit fields could
rely on fields such as the Date header field and on the time-window
of a quota-policy.
Paragraph (version B):
The "RateLimit-Limit" response field indicates the service-limit
associated to the client in the current time-window.
Paragraph (version B):
The field is an Item and its value is a non-negative Integer named
"expiring-limit".  Parameters are not allowed.
Paragraph (version B):
The RateLimit-Policy field (see ratelimit-policy-field), might
contain information on the associated time-window.
Paragraph (version B):
The RateLimit-Policy field response field indicates the quota
associated to the client and its value is informative.
Paragraph (version B):
The field is a non-empty List of Items.  Each item is a quota-policy.
Paragraph (version B):
This field can convey the time-window associated to the expiring-
limit, like shown in the following example.
Paragraph (version B):
The RateLimit-Remaining field response field indicates the remaining
quota-units defined in service-limit associated to the client.
Paragraph (version B):
The field is an Item and its value is a non-negative Integer
expressed in service-limit.  Parameters are not allowed.
Paragraph (version B):
Clients MUST NOT assume that a positive RateLimit-Remaining field
value is a guarantee that further requests will be served.
Paragraph (version B):
A low RateLimit-Remaining field value is like a yellow traffic-light
for either the number of requests issued in the time-window or the
request throughput: the red light may arrive suddenly (see providing-
ratelimit-fields).
Paragraph (version B):
One example of RateLimit-Remaining field use is below.
Paragraph (version B):
The RateLimit-Reset field response field indicates the number of
seconds until the quota resets.
Paragraph (version A):
An example of "RateLimit-Reset" use is below.
Paragraph (version A):
The client MUST NOT assume that all its "service-limit" will be
restored after the moment referenced by "RateLimit-Reset".  The
server MAY arbitrarily alter the "RateLimit-Reset" value between
subsequent requests e.g. in case of resource saturation or to
implement sliding window policies.
Paragraph (version B):
An example of RateLimit-Reset field use is below.
Paragraph (version B):
The client MUST NOT assume that all its service-limit will be
restored after the moment referenced by RateLimit-Reset field.  The
server MAY arbitrarily alter the RateLimit-Reset field value between
subsequent requests e.g. in case of resource saturation or to
implement sliding window policies.
Paragraph (version A):
"RateLimit-*" fields convey hints from the server to the clients in
order to avoid being throttled out.
Paragraph (version A):
Clients MUST NOT consider the "quota-units" returned in "RateLimit-
Remaining" as a service level agreement.
Paragraph (version B):
RateLimit fields convey hints from the server to the clients in order
to avoid being throttled out.
Paragraph (version B):
Clients MUST NOT consider the service-limit returned in RateLimit-
Remaining field as a service level agreement.
Paragraph (version A):
Consider that "service-limit" may not be restored after the moment
referenced by "RateLimit-Reset", and the "RateLimit-Reset" value
should not be considered fixed nor constant.
Paragraph (version A):
Subsequent requests may return a higher "RateLimit-Reset" value to
limit concurrency or implement dynamic or adaptive throttling
policies.
Paragraph (version A):
When returning "RateLimit-Reset" you must be aware that many
throttled clients may come back at the very moment specified.
Paragraph (version A):
This is true for "Retry-After" too.
Paragraph (version B):
Consider that service-limit might not be restored after the moment
referenced by RateLimit-Reset field, and the RateLimit-Reset field
value do not be considered fixed nor constant.
Paragraph (version B):
Subsequent requests might return a higher RateLimit-Reset field value
to limit concurrency or implement dynamic or adaptive throttling
policies.
Paragraph (version B):
When returning RateLimit-Reset field you must be aware that many
throttled clients may come back at the very moment specified.
Paragraph (version B):
This is true for Retry-After too.
Paragraph (version A):
Resource exhaustion issues can be associated with quota policies
using a large "time-window", because a user agent by chance or on
purpose might consume most of its quota-units in a significantly
shorter interval.
Paragraph (version A):
This behavior can be even triggered by the provided "RateLimit"
fields.  The following example describes a service with an unconsumed
quota-policy of 10000 quota-units per 1000 seconds.
Paragraph (version A):
A client implementing a simple ratio between "RateLimit-Remaining"
and "RateLimit-Reset" could infer an average throughput of 1000
quota-units per second, while "RateLimit-Limit" conveys a quota-
policy with an average of 10 quota-units per second.  If the service
cannot handle such load, it should return either a lower "RateLimit-
Remaining" value or an higher "RateLimit-Reset" value.  Moreover,
complementing large "time-window" quota-policies with a short "time-
window" one mitigates those risks.
Paragraph (version A):
or an high "RateLimit-Reset" value could inhibit clients to contact
the server.
Paragraph (version B):
Resource exhaustion issues can be associated with quota policies
using a large time-window, because a user agent by chance or on
purpose might consume most of its quota-units in a significantly
shorter interval.
Paragraph (version B):
This behavior can be even triggered by the provided RateLimit fields.
The following example describes a service with an unconsumed quota-
policy of 10000 quota-units per 1000 seconds.
Paragraph (version B):
A client implementing a simple ratio between RateLimit-Remaining
field and RateLimit-Reset field could infer an average throughput of
1000 quota-units per second, while the RateLimit-Limit field conveys
a quota-policy with an average of 10 quota-units per second.  If the
service cannot handle such load, it should return either a lower
RateLimit-Remaining field value or an higher RateLimit-Reset field
value.  Moreover, complementing large time-window quota-policies with
a short time-window one mitigates those risks.
Paragraph (version B):
or an high RateLimit-Reset field value could inhibit clients to
contact the server.
Paragraph (version A):
Parameter name: The parameter name, conforming to SF.
Paragraph (version B):
Parameter name: The parameter name, conforming to STRUCTURED-
FIELDS.