Draft: draft-ietf-httpapi-ratelimit-headers

Commentary: no trailers , but no normative language add explanation in FAQ , noting that it could be addressed in future specifications 
 If you 're going to preclude trailers , you should more prominently call it a ' header field ' rather than just a ' field ' ( including in the title ? ) 
 I thought about it . Since I was guessing whether a future extension I - D could address this point , I did n't want to be strict : but please let me know . 
 A future RFC could expand the scope of these to trailers , yes . In this draft , it 's important to communicate consistently and clearly , so you should use ' header field ' not just ' field ' . 
 will do , but I wo n't probably make it for the next meeting . 
 The defined fields are allowed to be used as trailers . While there might be some use cases where it 's necessary , using trailers comes at a cost ; some implementations do n't expose them , and some intermediary hops will drop them . So , some advice about their use as trailers should be included , at a minimum . E.g. , encouraging their use in headers wherever possible , and warning about the issues with trailers ( briefly ) . Also , if they 're allowed in both headers and trailers , something should be said about what happens when they 're in both places -- is that allowed , does one override the other , or are they combined ? Keep in mind that 9110 effectively made headers and trailers semantically distinct buckets . For RateLimit - Policy , what 's the use case for putting it in a trailer ? Generally , if it 's not something that can change while a response is being generated , it should be a header , as that 's more interoperable and available . 
 Do you think this matter should be addressed in each field definition or in a specific section ( e.g. in ) ? Clarification proposal : fields can appear both in header and trailer section fields MAY be combined in the header section the same field MUST NOT appear at the same time in headers and trailers warn that trailers might be dropped by intermediaries Anyway ff you think there are significant interoperability issues at stake , and since I think that these fields are actually computed before serving , I think it 's ok for them to just be headers : there 's no implementation afaik that sends these fields as trailers . 
 For a large or expensive response it might be desirable to include RateLimit - Remaining in a trailer as the current request could have a significant impact on the remaining value . 
 Right , but the tradeoff is that you have to : that it might appear in trailers for your API clients that expect and can process it as a trailer have any intermediaries in the path that will drop the trailer 
 If you have the pre - current request remaining value in the header and the post - current request value in the trailer , then clients that do receive the value from the trailer and can process it get a slightly more up - to - date value . To be honest , I ' m not sure it is worth the additional complexity though .
Paragraph (version A):
This document defines the RateLimit-Limit, RateLimit-Remaining,
RateLimit-Reset and RateLimit-Policy HTTP fields for servers to
advertise their current service rate limits, thereby allowing clients
to avoid being throttled.
Paragraph (version B):
This document defines the RateLimit-Limit, RateLimit-Remaining,
RateLimit-Reset and RateLimit-Policy HTTP header fields for servers
to advertise their current service rate limits, thereby allowing
clients to avoid being throttled.
Paragraph (version A):
The behavior of the RateLimit-Reset field is compatible with the
delay-seconds notation of Retry-After.
Paragraph (version B):
The behavior of the RateLimit-Reset header field is compatible with
the delay-seconds notation of Retry-After.
Paragraph (version A):
RateLimit fields are not meant to support authorization or other
kinds of access controls.
Paragraph (version B):
RateLimit header fields are not meant to support authorization or
other kinds of access controls.
Paragraph (version A):
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 B):
RateLimit header 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):
The fields defined in this document are collectively referred to as
"RateLimit fields".
Paragraph (version B):
The header fields defined in this document are collectively referred
to as "RateLimit header fields".
Paragraph (version A):
The following RateLimit response fields are defined.
Paragraph (version A):
The "RateLimit-Limit" response field indicates the service-limit
associated with the client in the current time-window.  If the client
exceeds that limit, it MAY not be served.
Paragraph (version B):
The following RateLimit response header fields are defined.
Paragraph (version B):
The "RateLimit-Limit" response header field indicates the service-
limit associated with the client in the current time-window.  If the
client exceeds that limit, it MAY not be served.
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 policies
currently associated with the client.  Its value is informative.
Paragraph (version B):
The RateLimit-Policy header field (see ratelimit-policy-field), might
contain information on the associated time window.
Paragraph (version B):
The "RateLimit-Policy" response header field indicates the quota
policies currently associated with the client.  Its value is
informative.
Paragraph (version A):
The "RateLimit-Remaining" response field indicates the remaining
quota units associated with the expiring-limit.
Paragraph (version A):
Clients MUST NOT assume that a positive RateLimit-Remaining field
value is a guarantee that further requests will be served.
Paragraph (version A):
The "RateLimit-Reset" field response field indicates the number of
seconds until the quota associated with the expiring-limit resets.
Paragraph (version B):
The "RateLimit-Remaining" response header field indicates the
remaining quota units associated with the expiring-limit.
Paragraph (version B):
Clients MUST NOT assume that a positive RateLimit-Remaining header
field value is a guarantee that further requests will be served.
Paragraph (version B):
The "RateLimit-Reset" response header field indicates the number of
seconds until the quota associated with the expiring-limit resets.
Paragraph (version A):
An example of RateLimit-Reset field use is below.
Paragraph (version A):
The client MUST NOT assume that all its service limit will be reset
at the moment indicated by the RateLimit-Reset field.  The server MAY
arbitrarily alter the RateLimit-Reset field value between subsequent
requests; for example, in case of resource saturation or to implement
sliding window policies.
Paragraph (version A):
A server uses the RateLimit fields to communicate its quota policies.
Sending the RateLimit-Limit and RateLimit-Reset fields is REQUIRED;
sending RateLimit-Remaining field is RECOMMENDED.
Paragraph (version A):
A server MAY return RateLimit fields independently of the response
status code.  This includes on throttled responses.  This document
does not mandate any correlation between the RateLimit field values
and the returned status code.
Paragraph (version A):
Servers should be careful when returning RateLimit fields in
redirection responses (i.e., responses with 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 A):
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 A):
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 A):
A service using 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 a quota policy uses 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):
The client MUST NOT assume that all its service limit will be reset
at the moment indicated by the RateLimit-Reset header field.  The
server MAY arbitrarily alter the RateLimit-Reset header field value
between subsequent requests; for example, in case of resource
saturation or to implement sliding window policies.
Paragraph (version B):
A server uses the RateLimit header fields to communicate its quota
policies.  Sending the RateLimit-Limit and RateLimit-Reset header
fields is REQUIRED; sending RateLimit-Remaining header field is
RECOMMENDED.
Paragraph (version B):
A server MAY return RateLimit header fields independently of the
response status code.  This includes on throttled responses.  This
document does not mandate any correlation between the RateLimit
header field values and the returned status code.
Paragraph (version B):
Servers should be careful when returning RateLimit header fields in
redirection responses (i.e., responses with 3xx status codes) because
a low RateLimit-Remaining header field value could prevent the client
from issuing requests.  For example, given the RateLimit header
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 header field value is 0.
Paragraph (version B):
If a response contains both the Retry-After and the RateLimit-Reset
header fields, the RateLimit-Reset header 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 header fields related to the time
window with the lower RateLimit-Remaining header field values.
Paragraph (version B):
A service using RateLimit header 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 header field values (see sec-resource-exhaustion);
this is especially important when a quota policy uses a large time
window.
Paragraph (version B):
Under certain conditions, a server MAY artificially lower RateLimit
header field values between subsequent requests, e.g. to respond to
Denial of Service attacks or in case of resource saturation.
Paragraph (version B):
Servers are not required to return RateLimit header fields in every
response, and clients need to take this into account.  For example,
an implementer concerned with performance might provide RateLimit
header fields only when a given quota is going to expire.
Paragraph (version A):
The RateLimit fields can be used by clients to determine whether the
associated request respected the server's quota policy, and as an
indication of whether subsequent requests will.  However, the server
might apply other criteria when servicing future requests, and so the
quota policy may not completely reflect whether they will succeed.
Paragraph (version B):
The RateLimit header fields can be used by clients to determine
whether the associated request respected the server's quota policy,
and as an indication of whether subsequent requests will.  However,
the server might apply other criteria when servicing future requests,
and so the quota policy may not completely reflect whether they will
succeed.
Paragraph (version A):
A client is responsible for ensuring that RateLimit field values
returned cause reasonable client behavior with respect to throughput
and latency (see sec-resource-exhaustion and sec-dos).
Paragraph (version A):
A client receiving RateLimit fields MUST NOT assume that future
responses will contain the same RateLimit fields, or any RateLimit
fields at all.
Paragraph (version A):
Malformed RateLimit fields MUST be ignored.
Paragraph (version A):
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 A):
A client MAY still probe the server if the RateLimit-Reset field is
considered too high.
Paragraph (version A):
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 A):
The details provided in RateLimit-Policy field are informative and
MAY be ignored.
Paragraph (version A):
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 B):
A client is responsible for ensuring that RateLimit header field
values returned cause reasonable client behavior with respect to
throughput and latency (see sec-resource-exhaustion and sec-dos).
Paragraph (version B):
A client receiving RateLimit header fields MUST NOT assume that
future responses will contain the same RateLimit header fields, or
any RateLimit header fields at all.
Paragraph (version B):
Malformed RateLimit header fields MUST be ignored.
Paragraph (version B):
A client SHOULD NOT exceed the quota units conveyed by the RateLimit-
Remaining header field before the time window expressed in RateLimit-
Reset header field.
Paragraph (version B):
A client MAY still probe the server if the RateLimit-Reset header
field is considered too high.
Paragraph (version B):
The value of the RateLimit-Reset header 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 header field moment intended by the
server.
Paragraph (version B):
The details provided in the RateLimit-Policy header 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 header field MAY be ignored.
Paragraph (version A):
An intermediary that is not part of the originating service
infrastructure and is not aware of the quota policy semantic used by
the Origin Server SHOULD NOT alter the RateLimit fields' values in
such a way as to communicate a more permissive quota policy; this
includes removing the RateLimit fields.
Paragraph (version B):
An intermediary that is not part of the originating service
infrastructure and is not aware of the quota policy semantic used by
the Origin Server SHOULD NOT alter the RateLimit header fields'
values in such a way as to communicate a more permissive quota
policy; this includes removing the RateLimit header fields.
Paragraph (version A):
An intermediary SHOULD forward a request even when presuming that it
might not be serviced; the service returning the RateLimit fields is
the sole responsible of enforcing the communicated quota policy, and
it is always free to service incoming requests.
Paragraph (version B):
An intermediary SHOULD forward a request even when presuming that it
might not be serviced; the service returning the RateLimit header
fields is the sole responsible of enforcing the communicated quota
policy, and it is always free to service incoming requests.
Paragraph (version A):
HTTP-CACHING defines how responses can be stored and reused for
subsequent requests, including those with RateLimit fields.  Because
the information in RateLimit fields on a cached response may not be
current, they SHOULD be ignored on responses that come from cache
(i.e., those with a positive current_age; see Section 4.2.3 of HTTP-
CACHING).
Paragraph (version B):
HTTP-CACHING defines how responses can be stored and reused for
subsequent requests, including those with RateLimit header fields.
Because the information in RateLimit header fields on a cached
response may not be current, they SHOULD be ignored on responses that
come from cache (i.e., those with a positive current_age; see
Section 4.2.3 of HTTP-CACHING).
Paragraph (version A):
As intermediaries might retransmit requests and consume quota units
without prior knowledge of the user agent, RateLimit fields might
reveal the existence of an intermediary to the user agent.
Paragraph (version A):
RateLimit fields convey hints from the server to the clients in order
to help them avoid being throttled out.
Paragraph (version A):
Clients MUST NOT consider the service-limit returned in RateLimit-
Remaining field as a service level agreement.
Paragraph (version B):
As intermediaries might retransmit requests and consume quota units
without prior knowledge of the user agent, RateLimit header fields
might reveal the existence of an intermediary to the user agent.
Paragraph (version B):
RateLimit header fields convey hints from the server to the clients
in order to help them avoid being throttled out.
Paragraph (version B):
Clients MUST NOT consider the service-limit returned in RateLimit-
Remaining header field as a service level agreement.
Paragraph (version A):
Consider that service limit might not be restored after the moment
referenced by RateLimit-Reset field, and the RateLimit-Reset field
value may not be fixed nor constant.
Paragraph (version A):
Subsequent requests might return a higher RateLimit-Reset field value
to limit concurrency or implement dynamic or adaptive throttling
policies.
Paragraph (version A):
When returning RateLimit-Reset field you must be aware that many
throttled clients may come back at the very moment specified.
Paragraph (version B):
Consider that service limit might not be restored after the moment
referenced by RateLimit-Reset header field, and the RateLimit-Reset
header field value may not be fixed nor constant.
Paragraph (version B):
Subsequent requests might return a higher RateLimit-Reset header
field value to limit concurrency or implement dynamic or adaptive
throttling policies.
Paragraph (version B):
When returning RateLimit-Reset header field you must be aware that
many throttled clients may come back at the very moment specified.
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
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 A):
or a high RateLimit-Reset field value could inhibit clients to
contact the server (e.g. similarly to receiving "Retry-after:
1000000").
Paragraph (version B):
This behavior can be even triggered by the provided RateLimit header
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
header field and RateLimit-Reset header field could infer an average
throughput of 1000 quota units per second, while the RateLimit-Limit
header 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 header field value or an higher
RateLimit-Reset header field value.  Moreover, complementing large
time window quota policies with a short time window one mitigates
those risks.
Paragraph (version B):
or a high RateLimit-Reset header field value could inhibit clients to
contact the server (e.g. similarly to receiving "Retry-after:
1000000").
Paragraph (version A):
The considerations above are not limited to RateLimit fields, but
apply to all fields affecting how clients behave in subsequent
requests (e.g.  Retry-After).
Paragraph (version B):
The considerations above are not limited to RateLimit header fields,
but apply to all fields affecting how clients behave in subsequent
requests (e.g.  Retry-After).
Paragraph (version A):
Privacy enhancing infrastructures using RateLimit fields can define
specific techniques to mitigate the risks of re-identification.
Paragraph (version B):
Privacy enhancing infrastructures using RateLimit header fields can
define specific techniques to mitigate the risks of re-
identification.
Paragraph (version A):
Field name: The RateLimit field for which the parameter is
registered.  If a parameter is intended to be used with multiple
fields, it has to be registered for each one.
Paragraph (version B):
Field name: The RateLimit header field for which the parameter is
registered.  If a parameter is intended to be used with multiple
fields, it has to be registered for each one.