RFC 8297

RFC 8297: An HTTP Status Code for Indicating Hints 🎀

okay bestie, let's talk about RFC 8297 💖 It's titled An HTTP Status Code for Indicating Hints, and it's written by K. Oku at Fastly 🌸 It's classed as Experimental and dated December 2017, with ISSN 2070-1721. The title block doesn't list anything it obsoletes or updates ✨

Abstract ✨

okay so this memo introduces an informational HTTP status code 🦋 Its whole job is to carry hints that help a client get ready to process the final response. no cap, it's a little head start 🏃‍♀️💨

---

Status of This Memo 📜

bestie, this part is important 🙈 This document is not an Internet Standards Track specification. It's being shared for examination, experimental implementation, and evaluation 🧪

It defines an Experimental Protocol for the Internet community 💜 It's a product of the Internet Engineering Task Force (IETF), and it represents the consensus of the IETF community. It went through public review and was approved for publication by the Internet Engineering Steering Group (IESG). Not every IESG-approved document is a candidate for any level of Internet Standard, so see Section 2 of RFC 7841 for that 🤓

If you want the current status, any errata, or a way to send feedback, go to 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. Please read these carefully, because they describe your rights and restrictions for this document 🫶 Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Simplified BSD License.

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 ✨

okay so it's super common for HTTP responses to include links to outside resources that need fetching before they can be used 🧚 Like, a web browser rendering HTML needs those. Getting those links to the client as early as possible helps cut down on perceived latency 💨

The "preload" [Preload] link relation can carry these links in the Link header field of an HTTP response 🎀 The catch is that an origin server can't always generate the header block of a final response right after it gets a request 💀 Maybe the origin server hands the request off to an upstream HTTP server at a distant location, or the status code depends on the result of a database query. Lowkey relatable 😭

So here's the dilemma. Even though it's better for an origin server to send some header fields as soon as it gets a request, it can't, because the status code and the full header fields of the final HTTP response aren't decided yet 🙃

HTTP/2 [RFC7540] server push can speed up resource delivery, but only for resources the server is authoritative for 🦋 Server push also has a limitation: the response gets transmitted whether or not the client already has it cached 🙈 Delivering Link header fields in a timely way is more flexible and might use less bandwidth, even though it costs one extra round trip compared to server push in the worst case 👑

This memo defines a status code for sending an informational response ([RFC7231], Section 6.2) that carries header fields likely to show up in the final response 💖 The server can send that informational response with some of those header fields so the client starts preparing early, and then run the time-consuming operations to build 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 📝

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 🧠 Only the ALL CAPS versions count, so lowercase ones are just regular words 💅

---

2. HTTP Status Code 103: Early Hints ✨

okay so the 103 (Early Hints) informational status code tells the client that the server will likely send a final response with the header fields included in the informational response 🔮

Usually, a server also includes the header fields it sent in a 103 (Early Hints) response in the final response 🎀 But sometimes that isn't what you want, like when the server finds out before the final response goes out that the header fields in the 103 (Early Hints) response are wrong 😬

A client can speculatively evaluate the header fields in a 103 (Early Hints) response while it waits for the final response 🏃‍♀️ For example, a client might spot a Link header field value with the relation type "preload" and start fetching the target resource 🧚 Just remember these header fields are only hints 💜 They do not replace the header fields on the final response 🙅‍♀️

Aside from performance optimizations, that speculative evaluation 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, like they were metadata about the 103 (Early Hints) response 🙈

A server MAY use a 103 (Early Hints) response to indicate only some of the header fields it expects to find in the final response ✨ And a client SHOULD NOT read a header field being missing from a 103 (Early Hints) response as a sign that the field is unlikely to show up in the final response 🫣

Here's a typical message exchange with 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 with any informational response, a server might send more than one 103 (Early Hints) response before the final response 🌈 That can happen when a caching intermediary makes a 103 (Early Hints) response from the header fields of a stale-cached response, and then forwards a 103 (Early Hints) response plus a final response that the origin server sent after a revalidation request 🔁

A server MAY send multiple 103 (Early Hints) responses with more header fields as new information shows up while the request is being processed 💫 It doesn't have to repeat fields it already sent, though it also doesn't have to leave them out 🍓 The client can consider any combination of header fields from multiple 103 (Early Hints) responses when it predicts the list of header fields the final response will have 🧠

This example shows a series of responses a server might send 🎬 The server uses two 103 (Early Hints) responses to tell the client it will probably send three Link header fields in the final response. Two of those three show up in the final response. The third gets swapped out for a different Link header field with 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 ...]

Acknowledgements 🫶

okay bestie, big thanks first 💖 Tatsuhiro Tsujikawa came up with the idea of sending the Link header fields in an informational response. literally genius, we love a clever idea ✨

Mark Nottingham and Willy Tarreau gave a ton of help making the semantics of the status code clear. iconic support 👑

The early work on this document was supported by DeNA Co., Ltd. while the author was working there 🌸

Author's Address 🎀

Kazuho Oku Fastly

Email: kazuhooku@gmail.com 💜