Assign relative weights to speculative push requests

Push Priority

Preliminaries

This note describes how to configure HTTP/2 speculative push protocol with weighted priorities for external resources associated with blue-phrase source documents.

The HTTP/2 speculative push protocol makes use of the multiplexed stream that is created when a browser sends a request to the server. The server can be configured to begin sending external resources that it knows the browser will need, even before the original source document has been fully sent. This is the speculative push (SP) protocol.

The server is capable of initiating SP requests for resources associated with blue-phrase documents using the linkmap that it creates during its parsing and caching procedure. Candidates for SP are CSS stylesheets, JavaScript files, fonts, images, videos, audio files, and embedded content. Only resource files located under the same domain as the host are eligible.

The blue-processor assembles a list of candidates when parsing the original BLUE source document. The following HTML tags are examined and considered for this:

HTML tag Sourceref attribute
<link rel=stylesheet> href
<link rel=preload> href
<script> src
<img> src
<source> src
<audio> src
<video> src
<track> src
<iframe> src
<embed> src
<object> data

The webmaster is responsible for configuring which of these candidates should retain their eligibility using the Push Priority handler.

In addition to defining eligibility, this handler also ascribes the relative importance of candidates. Using this mechanism, it is possible for a webmaster to instruct the server to SP, for example, CSS style sheets and JavaScript files before pushing images and other media. Importance is defined using arbitrary weighting numbers between 1 and 255, where a weight of 1 has lowest priority and a weight of 255 has highest priority. These are relative to each other. A typical set of weights would use numbers such as 10, 20, 40, 80, 160.

Consider the following configuration ...

Path Pattern Weight
*.css 80
*.js 40
*.jpg 20

... and the following set of external resource files ...

Filename File size
master.css 4K
purejoy.js 8K
background.jpg 8K
sale-priced.jpg 16K
red-ballons.jpg 32K

Initially, the total weighting allocated for puahing the five files would be 180 = (80*1) + (40*1) + (20*3). The server would theoretically allocate transport time-slots using the following percentages: 44% for master.css, 22% for purejoy.js, and 11% for each of the image files.

In this scenario, master.css and purejoy.js would both theoretically arrive at the browser at the same time. Meanwhile, the three images would have made some progress of their own, but as soon as the stylesheet and script file have completed their journey, each of their time-slots would be boosted to 33%. When background.jpg has finished being transported, the remaining two images would be boosted to 50%. Eventually, red-balloons.jpg would be the only file that hasn't finished being transported, and it would receive 100% of the stream's capacity.

Configuration

The server's push-priority section comprises a collection of entries, where each entry has a type declaration, a path-pattern, and a weight.

The type declaration is one of push or nopush. Typically, most entries will use the push keyword, to indicate that the associated pattern should be used to match push candidates. The special nopush keyword is needed when a path-pattern needs to be negated, to exclude certain paths from matching.

Refer to the separate note regarding Path Pattern rules.

Weights are integer numbers, between 1 (low priority) and 255 (high priority).

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

EBNF

SP ::= U+20
CR ::= U+0D
ASTERISK ::= U+2A
QUESTION-MARK ::= U+3F
SOLIDUS ::= U+2F
EQUALS-SIGN ::= U+3D
GRAVE-ACCENT ::= U+60
LEFT-CURLY-BRACKET ::= U+7B
RIGHT-CURLY-BRACKET ::= U+7D
file-system-chars ::= (ALPHA | DIGIT | )*
wildcards ::= ASTERISK | QUESTION-MARK
path-pattern ::= (SOLIDUS | file-system-chars | wildcards)*
delimited-path-pattern ::= GRAVE-ACCENT path-pattern GRAVE-ACCENT
weight ::= [1..255]
weight-specification ::= ASTERISK 'weight' EQUALS-SIGN weight
push-entry ::= 'push' delimited-path-pattern weight-specification CR
nopush-entry ::= 'nopush' delimited-path-pattern CR
push-priority-section ::= 'push-priority' SP LEFT-CURLY-BRACKET CR
(push-entry | nopush-entry)*
RIGHT-CURLY-BRACKET CR

† Legal file system characters vary by platform.

Cookbook

Example 1: Enabling the Push Priority module
server {
modules {
push-priority on
}
}
Example 2: Typical Push Priority settings
server {
response {
push-priority {
push `*/css/*.css` *weight=80
push `*/js/*.js` *weight=80
push `*/img/*.gif` *weight=20
push `*/img/*.png` *weight=20
push `*/img/*.jpg` *weight=20
}
}
}
Example 3: Explicit NOPUSH for path-patterns
server {
response {
push-priority {
nopush `*/css/alternate/*.css`
push `*/css/*.css` *weight=80
nopush `*/js/on-demand/*.js`
push `*/js/*.js` *weight=80
}
}
}

Review

Key points to remember:

  • The Push Priority handler is only used by the blue-processor.
  • Priorities are assigned using path-patterns with relative weights.
  • When a resource candidate does not match any path-pattern, it is disqualified from the speculative push protocol.

Assign relative weights to speculative push requests