draft-ietf-httpapi-ratelimit-headers-04.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: December 1, 2022 Red Hat | Expires: December 23, 2022 Red Hat | |||
May 30, 2022 | June 21, 2022 | |||
RateLimit Fields for HTTP | RateLimit Fields for HTTP | |||
draft-ietf-httpapi-ratelimit-headers-04 | 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 December 1, 2022. | This Internet-Draft will expire on December 23, 2022. | |||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2022 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 | Table of Contents | |||
1. Introduction | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 | |||
1.1. Goals | 1.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
1.2. Notational Conventions | 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 5 | |||
2. Expressing rate-limit policies | 2. Expressing rate-limit policies . . . . . . . . . . . . . . . 5 | |||
2.1. Time window | 2.1. Time window . . . . . . . . . . . . . . . . . . . . . . . 5 | |||
2.2. Service limit | 2.2. Service limit . . . . . . . . . . . . . . . . . . . . . . 6 | |||
2.3. Quota policy | 2.3. Quota policy . . . . . . . . . . . . . . . . . . . . . . 6 | |||
3. Providing RateLimit fields | 3. Providing RateLimit fields . . . . . . . . . . . . . . . . . 7 | |||
3.1. Performance considerations | 3.1. Performance considerations . . . . . . . . . . . . . . . 9 | |||
4. Receiving RateLimit fields | 4. Receiving RateLimit fields . . . . . . . . . . . . . . . . . 9 | |||
4.1. Intermediaries | 4.1. Intermediaries . . . . . . . . . . . . . . . . . . . . . 10 | |||
4.2. Caching | 4.2. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 10 | |||
5. Fields definition | 5. Fields definition . . . . . . . . . . . . . . . . . . . . . . 11 | |||
5.1. RateLimit-Limit | 5.1. RateLimit-Limit . . . . . . . . . . . . . . . . . . . . . 11 | |||
5.2. RateLimit-Policy | 5.2. RateLimit-Policy . . . . . . . . . . . . . . . . . . . . 11 | |||
5.3. RateLimit-Remaining | 5.3. RateLimit-Remaining . . . . . . . . . . . . . . . . . . . 12 | |||
5.4. RateLimit-Reset | 5.4. RateLimit-Reset . . . . . . . . . . . . . . . . . . . . . 12 | |||
6. Security Considerations | 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 | |||
6.1. Throttling does not prevent clients from issuing requests | 6.1. Throttling does not prevent clients from issuing requests 13 | |||
6.2. Information disclosure | 6.2. Information disclosure . . . . . . . . . . . . . . . . . 13 | |||
6.3. Remaining quota-units are not granted requests | 6.3. Remaining quota-units are not granted requests . . . . . 13 | |||
6.4. Reliability of RateLimit-Reset | 6.4. Reliability of RateLimit-Reset . . . . . . . . . . . . . 14 | |||
6.5. Resource exhaustion | 6.5. Resource exhaustion . . . . . . . . . . . . . . . . . . . 14 | |||
6.6. Denial of Service | 6.6. Denial of Service . . . . . . . . . . . . . . . . . . . . 15 | |||
7. Privacy Considerations | 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 15 | |||
8. IANA Considerations | 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 | |||
8.1. RateLimit Parameters Registration | 8.1. RateLimit Parameters Registration . . . . . . . . . . . . 16 | |||
9. References | 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 | |||
9.1. Normative References | 9.1. Normative References . . . . . . . . . . . . . . . . . . 17 | |||
9.2. Informative References | 9.2. Informative References . . . . . . . . . . . . . . . . . 17 | |||
9.3. URIs | 9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 18 | |||
Appendix A. Rate-limiting and quotas | ||||
A.1. Interoperability issues | Appendix A. Rate-limiting and quotas . . . . . . . . . . . . . . 19 | |||
Appendix B. Examples | A.1. Interoperability issues . . . . . . . . . . . . . . . . . 20 | |||
B.1. Unparameterized responses | Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 20 | |||
B.1.1. Throttling information in responses | B.1. Unparameterized responses . . . . . . . . . . . . . . . . 20 | |||
B.1.2. Use in conjunction with custom fields | B.1.1. Throttling information in responses . . . . . . . . . 20 | |||
B.1.3. Use for limiting concurrency | B.1.2. Use in conjunction with custom fields . . . . . . . . 21 | |||
B.1.4. Use in throttled responses | B.1.3. Use for limiting concurrency . . . . . . . . . . . . 22 | |||
B.2. Parameterized responses | B.1.4. Use in throttled responses . . . . . . . . . . . . . 23 | |||
B.2.1. Throttling window specified via parameter | B.2. Parameterized responses . . . . . . . . . . . . . . . . . 23 | |||
B.2.2. Dynamic limits with parameterized windows | B.2.1. Throttling window specified via parameter . . . . . . 23 | |||
B.2.3. Dynamic limits for pushing back and slowing down | B.2.2. Dynamic limits with parameterized windows . . . . . . 24 | |||
B.2.3. Dynamic limits for pushing back and slowing down . . 25 | ||||
B.3. Dynamic limits for pushing back with Retry-After and slow | B.3. Dynamic limits for pushing back with Retry-After and slow | |||
down | down . . . . . . . . . . . . . . . . . . . . . . . . . . 25 | |||
B.3.1. Missing Remaining information | B.3.1. Missing Remaining information . . . . . . . . . . . . 26 | |||
B.3.2. Use with multiple windows | B.3.2. Use with multiple windows . . . . . . . . . . . . . . 27 | |||
FAQ | FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 | |||
RateLimit fields currently used on the web | RateLimit fields currently used on the web . . . . . . . . . . . 31 | |||
Acknowledgements | Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 33 | |||
Changes | Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 | |||
F.1. Since draft-ietf-httpapi-ratelimit-headers-03 | F.1. Since draft-ietf-httpapi-ratelimit-headers-03 . . . . . . 33 | |||
F.2. Since draft-ietf-httpapi-ratelimit-headers-02 | F.2. Since draft-ietf-httpapi-ratelimit-headers-02 . . . . . . 33 | |||
F.3. Since draft-ietf-httpapi-ratelimit-headers-01 | F.3. Since draft-ietf-httpapi-ratelimit-headers-01 . . . . . . 33 | |||
F.4. Since draft-ietf-httpapi-ratelimit-headers-00 | F.4. Since draft-ietf-httpapi-ratelimit-headers-00 . . . . . . 33 | |||
Authors' Addresses | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 | |||
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 Request) (see | defined in [SEMANTICS] to be returned in 429 (Too Many Request) (see | |||
[STATUS429]) or 503 (Service Unavailable) responses. | [STATUS429]) or 503 (Service Unavailable) responses. | |||
skipping to change at line 709 ¶ | skipping to change at page 16, line 5 ¶ | |||
Privacy enhancing infrastructures using RateLimit fields can define | Privacy enhancing infrastructures using RateLimit fields can define | |||
specific techniques to mitigate the risks of re-identification. | specific techniques to mitigate the risks of re-identification. | |||
8. IANA Considerations | 8. IANA Considerations | |||
IANA is requested to update one registry and create one new registry. | IANA is requested to update one registry and create one new registry. | |||
Please add the following entries to the "Hypertext Transfer Protocol | Please add the following entries to the "Hypertext Transfer Protocol | |||
(HTTP) Field Name Registry" registry ([SEMANTICS]): | (HTTP) Field Name Registry" registry ([SEMANTICS]): | |||
+---------------------+-----------+------------------------+ | +---------------------+-----------+------------------------+ | |||
| Field Name | Status | Specification | | | Field Name | Status | Specification | | |||
+---------------------+-----------+------------------------+ | +---------------------+-----------+------------------------+ | |||
| RateLimit-Limit | permanent | Section 5.1 of ThisRFC | | | RateLimit-Limit | permanent | Section 5.1 of ThisRFC | | |||
| RateLimit-Remaining | permanent | Section 5.3 of ThisRFC | | | RateLimit-Remaining | permanent | Section 5.3 of ThisRFC | | |||
| RateLimit-Reset | permanent | Section 5.4 of ThisRFC | | | RateLimit-Reset | permanent | Section 5.4 of ThisRFC | | |||
| RateLimit-Policy | permanent | Section 5.2 of ThisRFC | | | RateLimit-Policy | permanent | Section 5.2 of ThisRFC | | |||
+---------------------+-----------+------------------------+ | +---------------------+-----------+------------------------+ | |||
8.1. RateLimit Parameters Registration | 8.1. RateLimit Parameters Registration | |||
IANA is requested to create a new registry to be called "Hypertext | IANA is requested to create a new registry to be called "Hypertext | |||
Transfer Protocol (HTTP) RateLimit Parameters Registry", to be | Transfer Protocol (HTTP) RateLimit Parameters Registry", to be | |||
located at https://www.iana.org/assignments/http-ratelimit-parameters | located at https://www.iana.org/assignments/http-ratelimit-parameters | |||
[3]. Registration is done on the advice of a Designated Expert, | [3]. Registration is done on the advice of a Designated Expert, | |||
appointed by the IESG or their delegate. All entries are | appointed by the IESG or their delegate. All entries are | |||
Specification Required ([IANA], Section 4.6). | Specification Required ([IANA], Section 4.6). | |||
skipping to change at line 1479 ¶ | skipping to change at page 32, line 36 ¶ | |||
* X-RateLimit-Limit and X-Rate-Limit-Limit | * X-RateLimit-Limit and X-Rate-Limit-Limit | |||
* X-RateLimit-Remaining and X-Rate-Limit-Remaining | * X-RateLimit-Remaining and X-Rate-Limit-Remaining | |||
* X-RateLimit-Reset and X-Rate-Limit-Reset | * X-RateLimit-Reset and X-Rate-Limit-Reset | |||
The semantic of RateLimit-Remaining depends on the windowing | The semantic of RateLimit-Remaining depends on the windowing | |||
algorithm. A sliding window policy for example may result in having | algorithm. A sliding window policy for example may result in having | |||
a "RateLimit-Remaining" value related to the ratio between the | a "RateLimit-Remaining" value related to the ratio between the | |||
current and the maximum throughput. e.g. | current and the maximum throughput. e.g. | |||
RateLimit-Limit: 12 | RateLimit-Limit: 12 | |||
RateLimit-Policy: 12;w=1 | RateLimit-Policy: 12;w=1 | |||
RateLimit-Remaining: 6 ; using 50% of throughput, that is 6 units/s | RateLimit-Remaining: 6 ; using 50% of throughput, that is 6 units/s | |||
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 | RateLimit-Limit: 12 | |||
RateLimit-Policy: 12;w=1 | RateLimit-Policy: 12;w=1 | |||
End of changes. 7 change blocks. | ||||
68 lines changed or deleted | 69 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/ |