blob: cbd449587f8e7a616cb3edebe3e7f3635df2ba4c [file] [log] [blame] [view]
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:561# 103 Early Hints
2
3Contact: early-hints-experiment@chromium.org
4
Kenichi Ishibashicdbd1ec9e2021-09-03 00:24:475As of version 95, Chrome experimentally supports
Kenichi Ishibashi7e394ecd2021-08-24 07:28:246[Early Hints](https://datatracker.ietf.org/doc/html/rfc8297).
Kenichi Ishibashi6d43eb852022-04-20 02:28:547Early Hints enable browsers to preload subresources or preconnect to servers
8before the main response is served. See the
9[explainer](https://github.com/bashi/early-hints-explainer/blob/main/explainer.md)
10how it works.
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:5611
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2412Currently Chrome is running A/B testing in the field to evaluate the performance
13impact of Early Hints. Chrome also provides some ways to opt-in Early Hints for
14web developers who want to try the feature. This document describes the status
15of the current implementation and how to enable Early Hints support.
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:5616
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2417## What’s supported
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:5618
Kenichi Ishibashicdbd1ec9e2021-09-03 00:24:4719Chrome supports [preload](https://w3c.github.io/preload/) and
20[preconnect](https://w3c.github.io/resource-hints/#dfn-preconnect) in
Kenichi Ishibashi6d43eb852022-04-20 02:28:5421Early Hints for top-level frame navigation.
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:5622
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2423## What’s not supported
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:5624
Kenichi Ishibashi6d43eb852022-04-20 02:28:5425To reduce security and privacy implications, the HTML and Fetch living standards
26have some restrictions on when Early Hints can be handled. Chrome ignores Early
27Hints sent in the following situations to comply these specifications.
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:5628
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2429* Early Hints sent on subresource requests
30* Early Hints sent on iframe navigation
31* Early Hints sent on HTTP/1.1 or earlier
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:5632
Kenichi Ishibashi6d43eb852022-04-20 02:28:5433Chrome ignores the second and following Early Hints responses. Chrome only
34handles the first Early Hints response so that Chrome doesn't apply inconsistent
35security policies (e.g. Content-Security-Policy).
36
Kenichi Ishibashicdbd1ec9e2021-09-03 00:24:4737Chrome doesn’t handle
38[dns-prefetch](https://w3c.github.io/resource-hints/#dfn-dns-prefetch) and
39[prefetch](https://w3c.github.io/resource-hints/#dfn-prefetch) in Early Hints
40yet. We consider supporting them in the future.
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:5641
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2442## Activation
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:5643
Kenichi Ishibashicdbd1ec9e2021-09-03 00:24:4744Early Hints can be enabled by a command line flag, or via
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2445[Origin Trial](https://developer.chrome.com/blog/origin-trials/).
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:5646
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2447### Using command line flag
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:5648
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2449Passing the `--enable-features=EarlyHintsPreloadForNavigation` command line flag
Kenichi Ishibashicdbd1ec9e2021-09-03 00:24:4750to Chrome enables Early Hints support.
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:5651
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2452### Using Origin Trial
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:5653
Kenichi Ishibashi6d43eb852022-04-20 02:28:5454**Note**: As of version 98 the origin trial has expired. The Chrome networking
55team is preparing to ship the feature and the origin trial may be available
56again in the near future until it's fully shipped.
57
Kenichi Ishibashicdbd1ec9e2021-09-03 00:24:4758You can opt any page on your origin into Early Hints by
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2459[requesting a token for your origin](https://developer.chrome.com/origintrials/#/view_trial/2856408063659737089).
60Include the token in both Early Hints and the final response so that Chrome can
Kenichi Ishibashicdbd1ec9e2021-09-03 00:24:4761recognize your pages opted in Early Hints.
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:5662
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2463```
64HTTP/1.1 103 Early Hints
65Origin-Trial: **your token**
66Link: </style.css>; rel="preload"; as="style"
Kenichi Ishibashicdbd1ec9e2021-09-03 00:24:4767Link: <https://cdn.test>; rel="preconnect"
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:5668
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2469HTTP/1.1 200 OK
70Origin-Trial: **your token**
71Link: </style.css>; rel="preload"; as="style"
Kenichi Ishibashicdbd1ec9e2021-09-03 00:24:4772Link: <https://cdn.test>; rel="preconnect"
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2473Content-Type: text/html; charset=utf-8
Hiroki Nakagawa0c9ee9f92020-10-16 02:46:5674
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2475<!DOCTYPE html>
76...
77```
78
Eric Lawrence [MSFT]694be822021-09-03 23:34:2279`<meta http-equiv="origin-trial" content="**your token**">` also works for the
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2480final response but doesnt work for Early Hints since Early Hints cannot convey
81a response body.
82
Kenichi Ishibashicdbd1ec9e2021-09-03 00:24:4783### Checking Early Hints preload is working
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2484
85If a resource is preloaded by Early Hints, the corresponding
86[PerformanceResourceTiming](https://w3c.github.io/resource-timing/#sec-performanceresourcetiming)
87object reports `initiatorType` is "early-hints".
88```
Eric Lawrence [MSFT]694be822021-09-03 23:34:2289performance.getEntriesByName('https://a.test/style.css')[0].initiatorType
Kenichi Ishibashi7e394ecd2021-08-24 07:28:2490// => 'early-hints'
91```
92
93## Resources
94
95* [Fastly's test page](https://early-hints.fastlylabs.com/)