From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc8297.txt | 395 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 395 insertions(+) create mode 100644 doc/rfc/rfc8297.txt (limited to 'doc/rfc/rfc8297.txt') diff --git a/doc/rfc/rfc8297.txt b/doc/rfc/rfc8297.txt new file mode 100644 index 0000000..2ed08df --- /dev/null +++ b/doc/rfc/rfc8297.txt @@ -0,0 +1,395 @@ + + + + + + +Internet Engineering Task Force (IETF) K. Oku +Request for Comments: 8297 Fastly +Category: Experimental December 2017 +ISSN: 2070-1721 + + + An HTTP Status Code for Indicating Hints + +Abstract + + This memo introduces an informational HTTP status code that can be + used to convey hints that help a client make preparations for + processing the final response. + +Status of This Memo + + This document is not an Internet Standards Track specification; it is + published for examination, experimental implementation, and + evaluation. + + This document defines an Experimental Protocol for the Internet + community. This document is a product of the Internet Engineering + Task Force (IETF). It represents the consensus of the IETF + community. It has received public review and has been approved for + publication by the Internet Engineering Steering Group (IESG). Not + all documents approved by the IESG are a candidate for any level of + Internet Standard; see Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc8297. + +Copyright Notice + + Copyright (c) 2017 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (https://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + + +Oku Experimental [Page 1] + +RFC 8297 Early Hints December 2017 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 + 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 + 2. HTTP Status Code 103: Early Hints . . . . . . . . . . . . . . 3 + 3. Security Considerations . . . . . . . . . . . . . . . . . . . 5 + 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 + 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 5.1. Normative References . . . . . . . . . . . . . . . . . . 6 + 5.2. Informative References . . . . . . . . . . . . . . . . . 6 + Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 7 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 + +1. Introduction + + It is common for HTTP responses to contain links to external + resources that need to be fetched prior to their use, for example, + rendering HTML by a web browser. Having such links available to the + client as early as possible helps to minimize perceived latency. + + The "preload" [Preload] link relation can be used to convey such + links in the Link header field of an HTTP response. However, it is + not always possible for an origin server to generate the header block + of a final response immediately after receiving a request. For + example, the origin server might delegate a request to an upstream + HTTP server running at a distant location, or the status code might + depend on the result of a database query. + + The dilemma here is that even though it is preferable for an origin + server to send some header fields as soon as it receives a request, + it cannot do so until the status code and the full header fields of + the final HTTP response are determined. + + HTTP/2 [RFC7540] server push can accelerate the delivery of + resources, but only resources for which the server is authoritative. + The other limitation of server push is that the response will be + transmitted regardless of whether the client has the response cached. + At the cost of spending one extra round trip compared to server push + in the worst case, delivering Link header fields in a timely fashion + is more flexible and might consume less bandwidth. + + This memo defines a status code for sending an informational response + ([RFC7231], Section 6.2) that contains header fields that are likely + to be included in the final response. A server can send the + informational response containing some of the header fields to help + the client start making preparations for processing the final + response, and then run time-consuming operations to generate the + + + + +Oku Experimental [Page 2] + +RFC 8297 Early Hints December 2017 + + + final response. The informational response can also be used by an + origin server to trigger HTTP/2 server push at a caching + intermediary. + +1.1. Notational Conventions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + +2. HTTP Status Code 103: Early Hints + + The 103 (Early Hints) informational status code indicates to the + client that the server is likely to send a final response with the + header fields included in the informational response. + + Typically, a server will include the header fields sent in a 103 + (Early Hints) response in the final response as well. However, there + might be cases when this is not desirable, such as when the server + learns that the header fields in the 103 (Early Hints) response are + not correct before the final response is sent. + + A client can speculatively evaluate the header fields included in a + 103 (Early Hints) response while waiting for the final response. For + example, a client might recognize a Link header field value + containing the relation type "preload" and start fetching the target + resource. However, these header fields only provide hints to the + client; they do not replace the header fields on the final response. + + Aside from performance optimizations, such evaluation of the 103 + (Early Hints) response's header fields MUST NOT affect how the final + response is processed. A client MUST NOT interpret the 103 (Early + Hints) response header fields as if they applied to the informational + response itself (e.g., as metadata about the 103 (Early Hints) + response). + + A server MAY use a 103 (Early Hints) response to indicate only some + of the header fields that are expected to be found in the final + response. A client SHOULD NOT interpret the nonexistence of a header + field in a 103 (Early Hints) response as a speculation that the + header field is unlikely to be part of the final response. + + The following example illustrates a typical message exchange that + involves a 103 (Early Hints) response. + + + + + +Oku Experimental [Page 3] + +RFC 8297 Early Hints December 2017 + + + Client request: + + GET / HTTP/1.1 + Host: example.com + + + Server response: + + HTTP/1.1 103 Early Hints + Link: ; rel=preload; as=style + Link: ; rel=preload; as=script + + HTTP/1.1 200 OK + Date: Fri, 26 May 2017 10:02:11 GMT + Content-Length: 1234 + Content-Type: text/html; charset=utf-8 + Link: ; rel=preload; as=style + Link: ; rel=preload; as=script + + + [... rest of the response body is omitted from the example ...] + + As is the case with any informational response, a server might emit + more than one 103 (Early Hints) response prior to sending a final + response. This can happen, for example, when a caching intermediary + generates a 103 (Early Hints) response based on the header fields of + a stale-cached response, and then forwards a 103 (Early Hints) + response and a final response that were sent from the origin server + in response to a revalidation request. + + A server MAY emit multiple 103 (Early Hints) responses with + additional header fields as new information becomes available while + the request is being processed. It does not need to repeat the + fields that were already emitted, though it doesn't have to exclude + them either. The client can consider any combination of header + fields received in multiple 103 (Early Hints) responses when + anticipating the list of header fields expected in the final + response. + + The following example illustrates a series of responses that a server + might emit. In the example, the server uses two 103 (Early Hints) + responses to notify the client that it is likely to send three Link + header fields in the final response. Two of the three expected + header fields are found in the final response. The other header + field is replaced by another Link header field that contains a + different value. + + + + + +Oku Experimental [Page 4] + +RFC 8297 Early Hints December 2017 + + + HTTP/1.1 103 Early Hints + Link: ; rel=preload; as=style + + HTTP/1.1 103 Early Hints + Link: ; rel=preload; as=style + Link: ; rel=preload; as=script + + HTTP/1.1 200 OK + Date: Fri, 26 May 2017 10:02:11 GMT + Content-Length: 1234 + Content-Type: text/html; charset=utf-8 + Link: ; rel=preload; as=style + Link: ; rel=preload; as=style + Link: ; rel=preload; as=script + + + [... rest of the response body is omitted from the example ...] + +3. Security Considerations + + Some clients might have issues handling a 103 (Early Hints) response, + because informational responses are rarely used in reply to requests + not including an Expect header field ([RFC7231], Section 5.1.1). + + In particular, an HTTP/1.1 client that mishandles an informational + response as a final response is likely to consider all responses to + the succeeding requests sent over the same connection to be part of + the final response. Such behavior might constitute a cross-origin + information disclosure vulnerability in case the client multiplexes + requests to different origins onto a single persistent connection. + + Therefore, a server might refrain from sending 103 (Early Hints) + responses over HTTP/1.1 unless the client is known to handle + informational responses correctly. + + HTTP/2 clients are less likely to suffer from incorrect framing since + handling of the response header fields does not affect how the end of + the response body is determined. + + + + + + + + + + + + + +Oku Experimental [Page 5] + +RFC 8297 Early Hints December 2017 + + +4. IANA Considerations + + The following entry has been registered in the "HTTP Status Codes" + registry: + + o Code: 103 + + o Description: Early Hints + + o Specification: RFC 8297 (this document) + +5. References + +5.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer + Protocol (HTTP/1.1): Semantics and Content", RFC 7231, + DOI 10.17487/RFC7231, June 2014, + . + + [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext + Transfer Protocol Version 2 (HTTP/2)", RFC 7540, + DOI 10.17487/RFC7540, May 2015, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + +5.2. Informative References + + [Preload] Grigorik, I., Ed. and Y. Weiss, Ed., "Preload", W3C + Candidate Recommendation, October 2017, + . + + + + + + + + + + + + +Oku Experimental [Page 6] + +RFC 8297 Early Hints December 2017 + + +Acknowledgements + + Thanks to Tatsuhiro Tsujikawa for coming up with the idea of sending + the Link header fields using an informational response. + + Mark Nottingham and Willy Tarreau provided substantial help in + clarifying the semantics of the status code. + + Early stages of the author's work on this document was supported by + DeNA Co., Ltd. during his employment there. + +Author's Address + + Kazuho Oku + Fastly + + Email: kazuhooku@gmail.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Oku Experimental [Page 7] + -- cgit v1.2.3