draft-ietf-httpapi-ratelimit-headers-02.unpg.txt   draft-ietf-httpapi-ratelimit-headers-latest.txt 
HTTPAPI Working Group R. Polli HTTPAPI Working Group R. Polli
Internet-Draft Team Digitale, Italian Government Internet-Draft Team Digitale, Italian Government
Intended status: Standards Track A. Martinez Intended status: Standards Track A. Martinez
Expires: May 14, 2022 Red Hat Expires: July 14, 2022 Red Hat
November 10, 2021 January 10, 2022
RateLimit Fields for HTTP RateLimit Fields for HTTP
draft-ietf-httpapi-ratelimit-headers-02 draft-ietf-httpapi-ratelimit-headers-latest
Abstract Abstract
This document defines the RateLimit-Limit, RateLimit-Remaining, This document defines the RateLimit-Limit, RateLimit-Remaining,
RateLimit-Reset fields for HTTP, thus allowing servers to publish RateLimit-Reset fields for HTTP, thus allowing servers to publish
current service limits and clients to shape their request policy and current service limits and clients to shape their request policy and
avoid being throttled out. avoid being throttled out.
Note to Readers Note to Readers
skipping to change at line 47 skipping to change at page 1, line 48
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 14, 2022. This Internet-Draft will expire on July 14, 2022.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2022 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents
1. Introduction
1.1. Goals
1.2. Notational Conventions
2. Expressing rate-limit policies
2.1. Time window
2.2. Service limit
2.3. Quota policy
3. Providing RateLimit fields
3.1. Performance considerations
4. Receiving RateLimit fields
4.1. Intermediaries
4.2. Caching
5. Fields definition
5.1. RateLimit-Limit
5.2. RateLimit-Remaining
5.3. RateLimit-Reset
6. Security Considerations
6.1. Throttling does not prevent clients from issuing requests
6.2. Information disclosure
6.3. Remaining quota-units are not granted requests
6.4. Reliability of RateLimit-Reset
6.5. Resource exhaustion
6.6. Denial of Service
7. IANA Considerations
7.1. RateLimit Parameters Registration
8. References
8.1. Normative References
8.2. Informative References
8.3. URIs
Appendix A. Rate-limiting and quotas
A.1. Interoperability issues
Appendix B. Examples
B.1. Unparameterized responses
B.1.1. Throttling information in responses
B.1.2. Use in conjunction with custom fields
B.1.3. Use for limiting concurrency
B.1.4. Use in throttled responses
B.2. Parameterized responses
B.2.1. Throttling window specified via parameter
B.2.2. Dynamic limits with parameterized windows
B.2.3. Dynamic limits for pushing back and slowing down
B.3. Dynamic limits for pushing back with Retry-After and slow
down
B.3.1. Missing Remaining information
B.3.2. Use with multiple windows
Appendix C. Acknowledgements
Appendix D. FAQ
RateLimit fields currently used on the web
Changes
F.1. Since draft-ietf-httpapi-ratelimit-headers-01
F.2. Since draft-ietf-httpapi-ratelimit-headers-00
Authors' Addresses
1. Introduction 1. Introduction
The widespreading of HTTP as a distributed computation protocol The widespreading of HTTP as a distributed computation protocol
requires an explicit way of communicating service status and usage requires an explicit way of communicating service status and usage
quotas. quotas.
This was partially addressed by the "Retry-After" header field This was partially addressed by the "Retry-After" header field
defined in [SEMANTICS] to be returned in "429 Too Many Requests" (see defined in [SEMANTICS] to be returned in "429 Too Many Requests" (see
[STATUS429]) or "503 Service Unavailable" responses. [STATUS429]) or "503 Service Unavailable" responses.
skipping to change at line 243 skipping to change at page 4, line 49
requests that the server is willing to accept from one or more requests that the server is willing to accept from one or more
clients on a given basis (originating IP, authenticated user, clients on a given basis (originating IP, authenticated user,
geographical, ..) during a "time-window" as defined in Section 2.1. geographical, ..) during a "time-window" as defined in Section 2.1.
The "service-limit" is expressed in "quota-units" and has the The "service-limit" is expressed in "quota-units" and has the
following syntax: following syntax:
service-limit = quota-units service-limit = quota-units
quota-units = sf-integer quota-units = sf-integer
where quota-units is a non-negative sf-integer. where "quota-units" is a non-negative sf-integer.
The "service-limit" SHOULD match the maximum number of acceptable The "service-limit" SHOULD match the maximum number of acceptable
requests. requests.
The "service-limit" MAY differ from the total number of acceptable The "service-limit" MAY differ from the total number of acceptable
requests when weight mechanisms, bursts, or other server policies are requests when weight mechanisms, bursts, or other server policies are
implemented. implemented.
If the "service-limit" does not match the maximum number of If the "service-limit" does not match the maximum number of
acceptable requests the relation with that SHOULD be communicated acceptable requests the relation with that SHOULD be communicated
skipping to change at line 280 skipping to change at page 5, line 40
This specification allows describing a quota policy with the This specification allows describing a quota policy with the
following syntax: following syntax:
quota-policy = sf-item quota-policy = sf-item
where the associated bare-item is a service-limit and parameters are where the associated bare-item is a service-limit and parameters are
supported. supported.
The following parameters are defined: The following parameters are defined:
w: The "w" parameter specifies a time window. Its syntax is a "time- w: The REQUIRED "w" parameter specifies a time window. Its syntax is
window" defined in Section 2.1. a "time-window" defined in Section 2.1.
Other parameters are allowed and can be regarded as comments. They Other parameters are allowed and can be regarded as comments. They
ought to be registered within the "Hypertext Transfer Protocol (HTTP) ought to be registered within the "Hypertext Transfer Protocol (HTTP)
RateLimit Parameters Registry", as described in Section 7.1. RateLimit Parameters Registry", as described in Section 7.1.
An example policy of 100 quota-units per minute. An example policy of 100 quota-units per minute.
100;w=60 100;w=60
The definition of a quota-policy does not imply any specific The definition of a quota-policy does not imply any specific
distribution of quota-units over time. Such service specific details distribution of quota-units over time. Such service specific details
can be conveyed as parameters. can be conveyed as parameters.
Two examples of providing further details via custom parameters Two policy examples containing further details via custom parameters
100;w=60;comment="fixed window" 100;w=60;comment="fixed window"
12;w=1;burst=1000;policy="leaky bucket" 12;w=1;burst=1000;policy="leaky bucket"
3. Providing RateLimit fields 3. Providing RateLimit fields
A server MAY use one or more "RateLimit" response fields defined in A server uses the "RateLimit" response fields defined in this
this document to communicate its quota policies. document to communicate its quota policies according to the following
rules:
o "RateLimit-Limit" and "RateLimit-Reset" are REQUIRED;
o "RateLimit-Remaining" is RECOMMENDED.
The returned values refers to the metrics used to evaluate if the The returned values refers to the metrics used to evaluate if the
current request respects the quota policy and MAY not apply to current request respects the quota policy and MAY not apply to
subsequent requests. subsequent requests.
Example: a successful response with the following fields Example: a successful response with the following fields
RateLimit-Limit: 10 RateLimit-Limit: 10
RateLimit-Remaining: 1 RateLimit-Remaining: 1
RateLimit-Reset: 7 RateLimit-Reset: 7
skipping to change at line 361 skipping to change at page 7, line 34
Under certain conditions, a server MAY artificially lower "RateLimit" Under certain conditions, a server MAY artificially lower "RateLimit"
field values between subsequent requests, e.g. to respond to Denial field values between subsequent requests, e.g. to respond to Denial
of Service attacks or in case of resource saturation. of Service attacks or in case of resource saturation.
Servers usually establish whether the request is in-quota before Servers usually establish whether the request is in-quota before
creating a response, so the RateLimit field values should be already creating a response, so the RateLimit field values should be already
available in that moment. Nonetheless servers MAY decide to send the available in that moment. Nonetheless servers MAY decide to send the
"RateLimit" fields in a trailer section. "RateLimit" fields in a trailer section.
To ease the migration from existing rate limit headers, a server
SHOULD be able to provide the "RateLimit-Limit" field even without
the optional "quota-policy" section.
3.1. Performance considerations 3.1. Performance considerations
Servers are not required to return "RateLimit" fields in every Servers are not required to return "RateLimit" fields in every
response, and clients need to take this into account. For example, response, and clients need to take this into account. For example,
an implementer concerned with performance might provide "RateLimit" an implementer concerned with performance might provide "RateLimit"
fields only when a given quota is going to expire. fields only when a given quota is going to expire.
Implementers concerned with response fields' size, might take into Implementers concerned with response fields' size, might take into
account their ratio with respect to the payload data, or use header- account their ratio with respect to the payload data, or use header-
compression http features such as [HPACK]. compression http features such as [HPACK].
skipping to change at line 1222 skipping to change at page 26, line 18
Response: Response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
RateLimit-Limit: 5000, 1000;w=3600, 5000;w=86400 RateLimit-Limit: 5000, 1000;w=3600, 5000;w=86400
RateLimit-Remaining: 100 RateLimit-Remaining: 100
RateLimit-Reset: 36000 RateLimit-Reset: 36000
{"hello": "world"} {"hello": "world"}
Appendix C. Acknowledgements FAQ
Thanks to Willi Schoenborn, Alejandro Martinez Ruiz, Alessandro
Ranellucci, Amos Jeffries, Martin Thomson, Erik Wilde and Mark
Nottingham for being the initial contributors of these
specifications. Kudos to the first community implementers: Aapo
Talvensaari, Nathan Friedly and Sanyam Dogra.
Appendix D. FAQ _RFC Editor: Please remove this section before publication._
1. Why defining standard fields for throttling? 1. Why defining standard fields for throttling?
To simplify enforcement of throttling policies. To simplify enforcement of throttling policies.
2. Can I use RateLimit-* in throttled responses (eg with status code 2. Can I use RateLimit-* in throttled responses (eg with status code
429)? 429)?
Yes, you can. Yes, you can.
skipping to change at line 1432 skipping to change at page 30, line 31
RateLimit-Reset: 1 RateLimit-Reset: 1
If this is the case, the optimal solution is to achieve If this is the case, the optimal solution is to achieve
RateLimit-Limit: 12, 12;w=1 RateLimit-Limit: 12, 12;w=1
RateLimit-Remaining: 1 ; using 100% of throughput, that is 12 units/s RateLimit-Remaining: 1 ; using 100% of throughput, that is 12 units/s
RateLimit-Reset: 1 RateLimit-Reset: 1
At this point you should stop increasing your request rate. At this point you should stop increasing your request rate.
Acknowledgements
Thanks to Willi Schoenborn, Alejandro Martinez Ruiz, Alessandro
Ranellucci, Amos Jeffries, Martin Thomson, Erik Wilde and Mark
Nottingham for being the initial contributors of these
specifications. Kudos to the first community implementers: Aapo
Talvensaari, Nathan Friedly and Sanyam Dogra.
In addition to the people above, this document owes a lot to the
extensive discussion in the HTTPAPI workgroup, including Rich Salz,
Darrel Miller and Julian Reschke.
Changes Changes
_RFC Editor: Please remove this section before publication._ _RFC Editor: Please remove this section before publication._
F.1. Since draft-ietf-httpapi-ratelimit-headers-01 F.1. Since draft-ietf-httpapi-ratelimit-headers-01
o Update IANA considerations #60 o Update IANA considerations #60
o Use Structured fields #58 o Use Structured fields #58
o Reorganize document #67 o Reorganize document #67
F.2. Since draft-ietf-httpapi-ratelimit-headers-00 F.2. Since draft-ietf-httpapi-ratelimit-headers-00
o Use I-D.httpbis-semantics, which includes referencing "delay- o Use I-D.httpbis-semantics, which includes referencing "delay-
seconds" instead of "delta-seconds". #5 seconds" instead of "delta-seconds". #5
Authors' Addresses Authors' Addresses
Roberto Polli Roberto Polli
 End of changes. 14 change blocks. 
75 lines changed or deleted 34 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/