103 Early Hints

103 Early Hints is an experimental status code. It can be used by a server to preemptively send headers to a client or intermediary. A client might be able to use these headers to make certain optimizations as early as possible in the process.

The specific use-case in RFC8297 is preloading. A server might tell a browser that it’s very likely to require certain css stylesheets or scripts to render the document using the Link header:

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

When a client receives these headers, it might immediately start fetching those resource in anticipation of the HTML document using them.

The 103 Early Hints status code can move those headers up even earlier.

A response to a HTTP GET request might then look like this:

HTTP/1.1 103 Early Hints
Link: </style.css>; rel=preload; as=style
Link: </script.js>; rel=preload; as=script
wait a few hundred milliseconds
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

This GET request got 2 responses The 103 Early Hints status codes were in this case sent as soon as the server could, while the real response (with 200 OK) took a bit longer to produce. This could allow a client to quickly fetch these additional resources.

Another use-case for this might be a HTTP/2-enabled proxy or CDN. This CDN might be able to read these 103 responses and turn the preload links into HTTP/2 pushes.

A caveat

Any header sent with the 103 status codes should be treated just as hints, and might not be ‘correct’. Only once you get the final status code, a client can find out what the real headers should have been.

For that reason any headers supplied in the 103 should not cause any changes to how the real responses were interpreted.

Using this status

The 2 languages I looked at for using this status were PHP and Node.js. PHP does not support 103 Early Hints, because it doesn’t have a native ability to send more than 1 status code back to a client.

Node.js does support it. The HTTP/1 version looks like this (and looks a bit like a hack, as it uses a private function):

// Assuming `res` is an instance of http.ServerResponse
res._writeRaw(`HTTP/1.1 103 Early Hints\r\nLink: </foo>; rel="prefetch"\r\n\r\n`, 'ascii', (err, result) => {
  // yup
});

The HTTP/2 library has a vetted public API.

// Assuming `stream` is an instance of `http2.Http2Stream`
stream.additionalHeaders({
  ':status' : 103,
  'link' => '</foo>; rel="prefetch"'
});

103 Checkpoint

When internet standards were at a standstill, Google once tried to move the web forward via their Gears project. This project proposed a number of extensions to the web, and also had a proposal for resumable uploads.

This proposal predates 103 Early Hints and proposed using the status for 103 Checkpoint, which could be used to occasionally send the client some information about how many bytes the server had received thusfar.

We know now that 103 Checkpoint never became standard. Yet, it seems pretty useful. I think most applications that require resumable uploads, tend to now do so by splitting up large files in many chunks and using many HTTP requests to do the upload. This doesn’t feel as elegant to me.

References

HTTP series

This article is part of an ongoing series about the HTTP protocol.

If you want to follow along as I write them, you can Subscribe to my Atom feed or Mailing list.

Informational 1xx

Successful 2xx

Redirection 3xx

Client Error 4xx

Web mentions