Abstract

This specification defines the preconnect relationship and extends the preload relationship 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 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 http://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. If you wish to make comments regarding this document, please send them to public-web-perf@w3.org (subscribe, archives). All comments are welcome.

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 5 February 2004 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 1 August 2014 W3C Process Document.

Table of Contents

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, early fetching of resources, and preloading and processing 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 preconnect relationship and extends the preload relationship 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 to improve page performance.

2. Resource Hints

2.1 Preconnect

The preconnect relation 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.

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

The optimal number of connections per origin is dependent on the negotiated protocol, users current connectivity profile, available device resources, and other context specific variables. As a result, this decision is deferred to the user agent, which is in the best position to determine the optimal number of connections per origin.

The user agent SHOULD initiate the handshake as early as possible 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.

2.2 Preload

The preload relationship is used to declare a resource and its fetch properties. This specification extends its functionality with additional processing policies that enable efficient fetching of resources that might be required by the next navigation, such that the user agent can deliver a faster response once the resource is requested.

Example 2
<!-- fetch and preprocess for next navigation -->
<link rel="preload" href="//example.com/next-page.html" as="html" loadpolicy="next">

<!-- fetch and do not preprocess for next navigation -->
<link rel="preload" href="//example.com/next-component.html" as="html" loadpolicy="next inert">
Note
The "next inert" loadpolicy is equivalent to rel=prefetch implemented by some browsers; "next" loadpolicy is semantically equivalent to rel=prerender implemented by some browsers. This specification standardizes and extends previous prefetch and prerender functionality with additional capabilities.

2.2.1 next load and processing policy

This specification extends the loadpolicy of preload relation, which consists of a space-separated set of keywords. These keywords determine the load and processing policy of the specified resource:

Example 3
<link rel="preload" href="/assets/font.woff" as="font" loadpolicy="next">
<link rel="preload" href="/assets/logo.webp" as="image" loadpolicy="next inert">
next
Indicates that the specified resource may be required by the next navigation context (i.e. speculative preload), and that the user agent SHOULD fetch the resource if possible.

Resource fetches that may be required for the next navigation can negatively impact the performance of the current navigation context due to additional contention for the CPU, GPU, memory, and network resources. To address this, the user agent SHOULD implement logic to reduce and eliminate such contention:

  • Resource fetches required for the next navigation SHOULD have lower relative priority and SHOULD NOT block or interfere with resource fetches required by the current navigation context.
  • The optimal time to initiate a resource fetch required for the next navigation is dependent on the negotiated transport protocol, users current connectivity profile, available device resources, and other context specific variables. The user agent is left to determine the optimal time at which to initiate the fetch - e.g. the user agent MAY decide to wait until all other downloads are finished, or MAY choose to pipeline requests with low priority if the negotiated protocol supports the necessary primitives. Alternatively, the user agent MAY opt-out from initiating the fetch due to resource constraints, user preferences, or other factors.

Speculative preload hints may be combined with other preload policies:

  • For HTML responses marked with the next policy:
    • If inert policy is omitted, the user agent MAY preprocess the HTML response by also fetching the necessary subresources and executing them (i.e. prerender the response). The decision for which prerendering steps are performed is deferred to the user agent. The user agent MAY:
      • Allocate fewer CPU, GPU, or memory resources to prerendered content.
      • Delay some requests until the requested HTML resource is made visible - e.g. media downloads, plugin content, and so on.
      • Prevent prerendering from being initiated when there are limited resources available.
      • Abandon prerendering due to high resource requirements - e.g. exceeded memory requirements, high CPU usage, and so on.
      • Abandon prerendering due to the type or properties of the preloaded content:
        • If the target exhibits non-idempotent behavior: mutations to shared local storage, XMLHttpRequest with a verb other than GET, HEAD, or OPTION, and so on.
        • If the target triggers a condition that requires user input: confirmation dialogs, authentication prompts, alerts, and so on.
    • If inert policy is present the user agent MUST NOT prerender the response.
  • For all other content-types with the next policy:
    • If inert policy is omitted, the user agent MAY perform appropriate preprocessing on the fetched response - e.g. preparse HTML, CSS, or JavaScript responses, decode an image ahead of time, and so on, but it MUST NOT automatically execute or apply it against the current page context.
    • If inert policy is present, the user agent SHOULD NOT apply any preprocessing on the response and MUST NOT automatically execute or apply it against the current page context.

The above processing strategies are not an exhaustive list. The user agent MAY implement other and additional strategies.

Note

To ensure compatibility and improve the success rate of prerendering requests the target page can use the [PAGE-VISIBILITY] to determine the visibility state of the page as it is being rendered and implement appropriate logic to avoid actions that may cause the preload 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.1 Hint probability

In addition to specifying the hint type, its fetch parameters, and the resource URL, the developer can communicate the expected probability that the specified resource hint will be used.

Example 4
<link rel="preconnect" href="//cdn.example.com" pr="0.42">
<link rel="preload" href="//example.com/next-page.html" pr="0.75" loadpolicy="next">
<link rel="preload" href="//example.com/thankyou.html" pr="0.25" loadpolicy="next">

The pr attribute is a float value in the [0.0-1.0] range that MAY be used in the following cases:

If the pr attribute is omitted for above cases, the user agent MAY assign a default probability value based on own heuristics, past navigation data, and so on.

A hint probability of 1.0 does not guarantee that the hint will be executed by the user agent. Resource hints MAY be processed on a best effort basis by the user agent, and decision to process the hint MAY be based on the runtime context of the user agent — availability of CPU, GPU, memory, and networking resources — developer specified probability indicating the likelihood of that resource being used, specified user preferences, and other variables. The user agent MAY decide to:

Note

To optimize the overall user experience the user agent should account for local context and specified probability of a speculative hint. For example, on a resource constrained device the user agent may decide to only execute high probability hints. Alternatively, it may decide to perform partial processing of the hint, such as downgrading speculative preload to a preconnect, performing partial preprocessing, and so on. Performing a partial optimization allows the user agent to improve performance even if a full optimization cannot be performed. Conversely, on a device with sufficient resources, the user agent may execute all of the specified hints as far as possible.

3.2 Load and error events

The user agent MUST NOT delay the load event of the document due to outstanding preconnect or speculative preload 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 (preload)

The preload 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 preload relations, set their loadpolicy to next to indicate that the resources are intended for next navigation, and optionally specify the probability (via pr attribute) of each resource being used.

4.4 Reactive resource prefetching (preload)

The preload hint 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 speculative preload 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 speculative preload relation may be allowed to persist across navigations.

4.5 Prerendering (preload)

The preload 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 preload relations, each of which points to a destination page (an HTML resource), and set their loadpolicy to next to indicate that the resources are intended for the next navigation. 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. Alternatively, if the application wants to only prefetch the HTML response, it can set the loadpolicy to next inert, to indicate that the response should not be prerendered.

Finally, because prerendering may require a lot of resources, the application can specify the probability (via pr attribute) of each target to help the user agent deliver the best user experience.

5. 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 NOT, SHOULD, and SHOULD NOT are to be interpreted as described in [RFC2119].

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

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

[HTML]
Ian Hickson. HTML. Living Standard. URL: https://html.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC5988]
M. Nottingham. Web Linking. October 2010. Proposed Standard. URL: https://tools.ietf.org/html/rfc5988

B.2 Informative references

[PAGE-VISIBILITY]
Jatinder Mann; Arvind Jain. Page Visibility (Second Edition). 29 October 2013. W3C Recommendation. URL: http://www.w3.org/TR/page-visibility/