| 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 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 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
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.
Client request:
GET / HTTP/1.1 Host: example.com
Server response:
HTTP/1.1 103 Early Hints Link: </style.css>; rel=preload; as=style Link: </script.js>; 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: </style.css>; rel=preload; as=style Link: </script.js>; rel=preload; as=script <!doctype html> [... 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.
HTTP/1.1 103 Early Hints Link: </main.css>; rel=preload; as=style HTTP/1.1 103 Early Hints Link: </style.css>; rel=preload; as=style Link: </script.js>; 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: </main.css>; rel=preload; as=style Link: </newstyle.css>; rel=preload; as=style Link: </script.js>; rel=preload; as=script <!doctype html> [... 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], DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc7231>.
Appendix A. 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.