idnits 2.17.1 draft-polli-retry-scope-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (9 March 2020) is 1508 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 7230 (ref. 'MESSAGING') (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (ref. 'SEMANTICS') (Obsoleted by RFC 9110) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Polli 3 Internet-Draft Team Digitale, Italian Government 4 Intended status: Standards Track 9 March 2020 5 Expires: 10 September 2020 7 Retry-Scope header field 8 draft-polli-retry-scope-00 10 Abstract 12 This document defines the Retry-Scope header field for HTTP thus 13 allowing a server to communicate the scope of the returned Retry- 14 After header field. 16 Note to Readers 18 _RFC EDITOR: please remove this section before publication_ 20 Discussion of this draft takes place on the HTTP working group 21 mailing list (ietf-http-wg@w3.org), which is archived at 22 https://lists.w3.org/Archives/Public/ietf-http-wg/ 23 (https://lists.w3.org/Archives/Public/ietf-http-wg/). 25 The source code and issues list for this draft can be found at 26 https://github.com/ioggstream/draft-polli-Retry-Scope 27 (https://github.com/ioggstream/draft-polli-Retry-Scope). 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on 10 September 2020. 46 Copyright Notice 48 Copyright (c) 2020 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 53 license-info) in effect on the date of publication of this document. 54 Please review these documents carefully, as they describe your rights 55 and restrictions with respect to this document. Code Components 56 extracted from this document must include Simplified BSD License text 57 as described in Section 4.e of the Trust Legal Provisions and are 58 provided without warranty as described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 63 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 64 2. Header Specifications . . . . . . . . . . . . . . . . . . . . 3 65 2.1. Retry-Scope . . . . . . . . . . . . . . . . . . . . . . . 3 66 3. Security Considerations . . . . . . . . . . . . . . . . . . . 4 67 3.1. Role of intermediaries . . . . . . . . . . . . . . . . . 4 68 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 69 4.1. Retry-Scope Header Field Registration . . . . . . . . . . 4 70 5. Normative References . . . . . . . . . . . . . . . . . . . . 4 71 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 5 72 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 73 Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5 76 1. Introduction 78 The Retry-After header defined in Section 7.1.3 of [SEMANTICS] allows 79 a server to indicate how long the user agent ought to wait before 80 making a follow-up request. 82 While Retry-After applies to the issued request, it may be useful for 83 the server to communicate to the user agent that the conditions that 84 lead to returning Retry-After are broader in scope than a single 85 request. 87 This proposal allows a server to convey that scope in the Retry-Scope 88 response header field, and ask the client to temporarily refrain from 89 making other requests to the same resource, or even to all resources 90 on the same server. 92 1.1. Notational Conventions 94 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 95 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 96 "OPTIONAL" in this document are to be interpreted as described in 97 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 98 capitals, as shown here. These words may also appear in this 99 document in lower case as plain English words, absent their normative 100 meanings. 102 This document uses the Augmented BNF defined in [RFC5234] and updated 103 by [RFC7405] along with the "#rule" extension defined in Section 7 of 104 [MESSAGING] and the URI-reference rule defined in Section 2.7 of 105 [MESSAGING]. 107 The terms "intermediaries" and "target URI" are to be interpreted as 108 described in [MESSAGING]. 110 2. Header Specifications 112 The following header is defined 114 2.1. Retry-Scope 116 The Retry-Scope response header field indicates that the conditions 117 that lead to returning Retry-After are broader in scope than a single 118 request. 120 Retry-Scope = URI-reference 122 Two examples of Retry-Scope: 124 Retry-Scope: /books 125 Retry-Scope: https://api.example/ 127 A user agent receiving the Retry-Scope header field in conjunction 128 with a Retry-After header field ought to wait before making further 129 request to the resource identified by the Retry-Scope field value. 131 This header MUST NOT be repeated; if a user agent receives multiple 132 Retry-Scope header fields, then it SHOULD ignore them. 134 Intermediaries aware of the Retry-Scope semantics (eg. reverse 135 proxies) MAY modify the Retry-Scope in order to help the user agent 136 to correctly identify the scope and ensure that the field value 137 matches the target URI, like they would have done for the Location 138 header field defined in Section 7.1.2 of [SEMANTICS]. 140 3. Security Considerations 142 3.1. Role of intermediaries 144 An intermediary, by chance or purpose, might alter the scope of the 145 Retry-Scope thus causing the user agent to refrain contacting other 146 server resource. 148 When the server originating the Retry-Scope is behind one or more 149 intermediaries it is possible that the field value is not consistent 150 with the target URI. 152 4. IANA Considerations 154 4.1. Retry-Scope Header Field Registration 156 This section registers the "Retry-Scope" header field in the 157 "Permanent Message Header Field Names" registry ([RFC3864]). 159 Header field name: "Retry-Scope" 161 Applicable protocol: http 163 Status: standard 165 Author/Change controller: IETF 167 Specification document(s): Section 2.1 of this document 169 5. Normative References 171 [MESSAGING] 172 Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 173 Protocol (HTTP/1.1): Message Syntax and Routing", 174 RFC 7230, DOI 10.17487/RFC7230, June 2014, 175 . 177 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 178 Requirement Levels", BCP 14, RFC 2119, 179 DOI 10.17487/RFC2119, March 1997, 180 . 182 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 183 Procedures for Message Header Fields", BCP 90, RFC 3864, 184 DOI 10.17487/RFC3864, September 2004, 185 . 187 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 188 Specifications: ABNF", STD 68, RFC 5234, 189 DOI 10.17487/RFC5234, January 2008, 190 . 192 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 193 RFC 7405, DOI 10.17487/RFC7405, December 2014, 194 . 196 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 197 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 198 May 2017, . 200 [SEMANTICS] 201 Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 202 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 203 DOI 10.17487/RFC7231, June 2014, 204 . 206 Appendix A. Acknowledgements 208 This specification was born from a thread created by Martin Thomson, 209 and the subsequent discussion. 211 FAQ 213 Q: Why not using link relations? This solution is simpler and was 214 previously discussed here (https://github.com/httpwg/http-core/ 215 pull/317#issuecomment-585868767). 217 Change Log 219 RFC EDITOR PLEASE DELETE THIS SECTION. 221 Author's Address 223 Roberto Polli 224 Team Digitale, Italian Government 226 Email: robipolli@gmail.com