Requesting early arrival of special resources

Preload Push

Preliminaries

This note describes how to use the HTTP 'link' request header to retrieve resources earlier using HTTP/2 push.

The HTTP/2 push protocol allows multiple resources to be retrieved from the server with a single browser request. To make use of this, the requestor can include a special link header with the request. This can be accomplished with XMLHttpRequest or asynchronous fetch calls initiated via JavaScript.

Use of this feature may, for example, may improve the user experience for an embedded <iframe>, where the request for a document and all its dependent resources are made in a single fetch.

Note that the HTML <link> element is similar in purpose, but its usage is applied by the browser after the HTML document has been retrieved and parsed. Because of this, it is not truly a server push operation. The browser uses all of its normal fetching and caching algorithms and the server treats it as a normal HTTP request/response.

Configuration

The link request header, by specification, may take these attributes:

  • The URL of the resource being requested, which must be delimited with an opening < and a closing >.
  • The rel=preload attribute, which is required.
  • The nopush attribute, which is optional.
  • The as attribute, which identifies a generic resource type, but which is not used by the server.
  • The crossorigin attribute, which is not used by the server.
  • The media attribute, which is not used by the server.

The URL may be a fully specified URL (with protocol, hostname, port, and resource path) or it may be an absolute or relative resource path.

If the origin of the JavaScript document that sends the link header is different from the URL's origin, then a proper CORS configuration must be in place or else the browser will block the request.

When the optional nopush attribute is included in the link header, no push processing will occur.

The use of more than one link request header is not supported. Only the last one will apply.

More than one resource may be requested in a single link header, by using a comma-separated concatenation of the resources. Each resource must redundantly include the rel=preload attribute.

The as attribute may be omitted. It is used by browser-initiated preloads only. The server instead relies on its configured content-types to definitively assign a mime-type to the resource, and to send that mime-type in the content-type response header.

The push-priority module must be on in the module section for any of this to be effective.

Cookbook

Example 1: Link header with fully specified URL
link: <https://example.com/other/styles.css>; rel=preload    
Example 2: Link header with absolute path
link: </styles.css>; rel=preload    
Example 3: Link header with relative path
link: <../../styles.css>; rel=preload    
Example 4: Link header for preloading multiple resources
link: <https://example.com/styles.css>; rel=preload, <https://example.com/ecmascript.js>; rel=preload, <https://example.com/neue.woff2>; rel=preload
Example 5: Explicit NOPUSH to disable preloading
link: <https://example.com/styles.css>; rel=preload; nopush            

Review

Key points to remember:

  • The push-priority module must be on for preload-push to work.
  • Only JavaScript-initiated requests can trigger a preload-push.
  • A single <link> request header is used to request multiple resources.

Requesting early arrival of special resources