Resource Hints

W3C Working Draft

This version:
https://www.w3.org/TR/2020/WD-resource-hints-20201005/
Latest published version:
https://www.w3.org/TR/resource-hints/
Latest editor's draft:
https://w3c.github.io/resource-hints/
Previous version:
https://www.w3.org/TR/2019/WD-resource-hints-20190702/
Editor:
(Google)
Participate:
GitHub w3c/resource-hints
File a bug
Commit history
Pull requests

Abstract

This specification defines the dns-prefetch, preconnect, prefetch, and prerender relationships of the HTML Link Element (<link>). These primitives enable the developer, and the server generating or delivering the resources, to assist the user agent in the decision process of which origins it should connect to, and which resources it should fetch and preprocess to improve page performance.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the Web Performance Working Group as a Working Draft. This document is intended to become a W3C Recommendation.

GitHub Issues are preferred for discussion of this specification.

Publication as a Working Draft does not imply endorsement by the W3C Membership.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 1 August 2017 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 15 September 2020 W3C Process Document.

1. Introduction

Modern browsers leverage a wide variety of speculative optimization techniques to anticipate user input and intent, which allows them to hide some of the networking, processing, and rendering latencies: preconnects, prefetching of resources, and prerendering of resources for subsequent navigation.

The decision to initiate one or more of the above optimizations is typically based on heuristic rules based on document markup and structure, navigation history, and context of the user - e.g., type of device, available compute and memory resources, network connectivity, user preferences, and so on. These techniques have proven to be successful, but can be further improved by leveraging the knowledge a developer has about the front-end and back-end generation and delivery of the resources of a web application.

For example, the application may provide the following resource hints to the user agent:

Many web applications already leverage a variety of prefetching techniques. This includes, but is not limited to, using XMLHttpRequest to fetch and cache assets before they are needed. However, these implementations are application specific, are not interoperable, and do not provide the same level of performance as the browser-provided primitives. Worse, these implementations sometimes conflict with the browser logic and result in delayed or unnecessary resource fetches that degrade overall page performance.

This specification defines the dns-prefetch, preconnect, prefetch, and prerender relationships of the HTML Link Element (<link>). These primitives enable the developer, and the server generating or delivering the resources, to assist the user agent in the decision process of which origins it should connect to, and which resources it should fetch and preprocess to improve page performance.

2. Resource Hints

2.1 DNS Prefetch

The dns-prefetch link relation type is used to indicate an origin that will be used to fetch required resources, and that the user agent SHOULD resolve as early as possible.

<link rel="dns-prefetch" href="//example.com">

2.2 Preconnect

The preconnect link relation type is used to indicate an origin that will be used to fetch required resources. Initiating an early connection, which includes the DNS lookup, TCP handshake, and optional TLS negotiation, allows the user agent to mask the high latency costs of establishing a connection.

<link rel="preconnect" href="//example.com">
<link rel="preconnect" href="//cdn.example.com" crossorigin>

To initiate a preconnect, the user agent MUST run these steps:

  1. Resolve the URL given by the href attribute.
    1. If that is successful, let preconnect URL be the resulting absolute URL, and otherwise abort these steps.
    2. If preconnect URL's scheme is not one of "http" or "https" then abort these steps.
  2. Let origin be preconnect URL's origin.
  3. Let corsAttributeState be the current state of the element's crossorigin content attribute.
  4. Let credentials be a boolean value set to true.
  5. If corsAttributeState is Anonymous and origin is not equal to current Document's origin, set credentials to false.
  6. Attempt to obtain connection with origin and credentials.

The user agent SHOULD attempt to initiate a preconnect and perform the full connection handshake (DNS+TCP for HTTP, and DNS+TCP+TLS for HTTPS origins) whenever possible, but is allowed to elect to perform a partial handshake (DNS only for HTTP, and DNS or DNS+TCP for HTTPS origins), or skip it entirely, due to resource constraints or other reasons.

The optimal number of connections per origin is dependent on the negotiated protocol, users current connectivity profile, available device resources, global connection limits, and other context specific variables. As a result, the decision for how many connections should be opened is deferred to the user agent.

2.3 Prefetch

The prefetch link relation type is used to identify a resource that might be required by the next navigation, and that the user agent SHOULD fetch, such that the user agent can deliver a faster response once the resource is requested in the future.

<link rel="prefetch" href="//example.com/next-page.html" as="document" crossorigin="use-credentials">
<link rel="prefetch" href="/library.js" as="script">
Note
The as attribute can be used by the application to communicate the resource destination context, such that the user agent can optimize the fetching process - e.g. set appropriate request headers, transport priority, and so on.

2.4 Prerender

The prerender link relation type is used to identify a resource that might be required by the next navigation, and that the user agent SHOULD fetch and execute, such that the user agent can deliver a faster response once the resource is requested in the future.

<link rel="prerender" href="//example.com/next-page.html">

The user agent MAY preprocess the HTML response by also fetching the necessary subresources and executing them (i.e. prerender the page). The decision for which prerendering steps are performed is deferred to the user agent. The user agent MAY:

When prerendering a document the user agent MUST set the document's visibilityState ([PAGE-VISIBILITY]) value to prerender.

Note
The prerender hint can be used by the application to indicate the next likely HTML navigation target: the user agent will fetch and process the specified resource as an HTML response. To fetch other content-types with appropriate request headers, or if HTML preprocessing is not desired, the application can use the prefetch hint.
Note
To ensure compatibility and improve the success rate of prerendering requests the target page can use the Page Visibility API to determine the visibility state of the page as it is being rendered and implement appropriate logic to avoid actions that may cause the prerender to be abandoned (e.g. non-idempotent requests), or unwanted side-effects from being triggered (e.g. analytics beacons firing prior to the page being displayed).

3. Process

3.2 Load and error events

The user agent MUST NOT delay the load event of the document due to outstanding preconnect or speculative fetch initiated requests.

The decision on whether a resource hint is executed, and if so, whether full or partial processing is applied is deferred to the user agent. As a result, element-level load and error JavaScripts events are not guaranteed to fire, and if they do, do not guarantee that full processing was applied. However, the user agent SHOULD fire the appropriate load and error events when possible, to allow the application to track which hints were executed and when.

4. Use cases

4.1 Dynamic request URL (preconnect)

The full resource URL may not be known until the page is being constructed by the user agent - e.g. conditional loading logic, UA adaptation, etc. However, the origin from which one or more of these resources will be fetched is often known ahead of time by the developer or the server generating the response. In such cases, a preconnect hint can be used to initiate an early connection handshake such that when the resource URL is determined, the user agent can dispatch the request without first blocking on connection negotiation.

4.2 Anonymizing redirect (preconnect)

Many sites rely on redirect services for analytics, malware protection, and to anonymize the referrer before sending the user to the final destination. Because the destination is known ahead of time, a preconnect hint can be used to initiate the connection handshake with the destination origin (without revealing any private information) in parallel with the processing of the redirect - this masks the redirect latency and reduces navigation time to final destination.

4.3 Speculative resource prefetching (prefetch)

The prefetch hint can be used to implement a prefetch strategy that leverages app-specific knowledge about the next navigation based on content, structure, analytics, or other signals - e.g. high-likelihood search results, paginated content or step-driven flows, aggregated analytics or per-user behavior, and so on.

For example, an image gallery may have knowledge about the likelihood of the next photo or page that may be requested by the user. To provide an improved experience the application can ask the user agent to begin fetching required resources (individual photos, critical resources, or the full page) before the next navigation is triggered.

To achieve the above behavior the application can specify one or more prefetch relations of each resource being used.

4.4 Reactive resource prefetching (prefetch)

The prefetch can be used to implement a "reactive prefetch strategy" that leverages the knowledge of where the user is heading next and enables the application to begin prefetching critical resources in parallel with the navigation request.

To achieve the above behavior the application can listen for click, or other user and application generated events, and dynamically insert relevant prefetch relations for critical resources required by the next navigation. In turn, the user agent can fetch the hinted resources in parallel with the navigation request, making the critical resources available sooner.

The enabling feature of this strategy is that requests initiated via prefetch relation may be allowed to persist across navigations.

4.5 Prerendering (prerender)

The prerender hint can be used to prerender the destination page, enabling an instant navigation experience once the user triggers the navigation.

To deliver an instant navigation experience the application can specify one or more prerender relations, each of which points to a destination page (an HTML resource). In turn, the user agent may fetch and process the HTML document, fetch its subresources, and perform other work to deliver an instant navigation - i.e. "prerender" the page.

5. Security and Privacy

The use of resource hints can provide new means to expose information about both the current page and user's activity on it. For example, observing the content of prefetched or prerendered resources, or observing the DNS, IP, and hostname information exposed during connection establishment, both for secure and plain-text connections, can reveal information about the page initiating such requests, and where dynamic resource hints are used, user's activity on it.

To mitigate some of the above risks, the user agent MUST:

Additionally, the user agent MAY provide user setting to control the use of resource hints.

The site author SHOULD take necessary precautions to specify the relevant [MIXED-CONTENT], [CSP3], and [REFERRER-POLICY] policies to allow the user agent to register and apply them prior to processing a resource hint link:

6. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, OPTIONAL, SHOULD, and SHOULD NOT 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.

There is only one class of product that can claim conformance to this specification: a user agent.

7. IANA Considerations

The link relation types below have been registered by IANA per Section 6.2.1 of [RFC5988]:

A. Acknowledgments

This document reuses text from the [HTML] specification, edited by Ian Hickson, as permitted by the license of that specification.

B. References

B.1 Normative references

[CSP3]
Content Security Policy Level 3. Mike West. W3C. 15 October 2018. W3C Working Draft. URL: https://www.w3.org/TR/CSP3/
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[MIXED-CONTENT]
Mixed Content. Mike West. W3C. 2 August 2016. W3C Candidate Recommendation. URL: https://www.w3.org/TR/mixed-content/
[PAGE-VISIBILITY]
Page Visibility (Second Edition). Jatinder Mann; Arvind Jain. W3C. 29 October 2013. W3C Recommendation. URL: https://www.w3.org/TR/page-visibility/
[PRELOAD]
Preload. Ilya Grigorik; Yoav Weiss. W3C. 26 June 2019. W3C Candidate Recommendation. URL: https://www.w3.org/TR/preload/
[REFERRER-POLICY]
Referrer Policy. Jochen Eisinger; Emily Stark. W3C. 26 January 2017. W3C Candidate Recommendation. URL: https://www.w3.org/TR/referrer-policy/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC5988]
Web Linking. M. Nottingham. IETF. October 2010. Proposed Standard. URL: https://tools.ietf.org/html/rfc5988
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174