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, 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.