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/