Assign relative weights to speculative push requests

Push Priority


This note describes how to configure HTTP/2 speculative push protocol with weighted priorities for external resources associated with BLUEPHRASE 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 BLUEPHRASE 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 pushing 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.


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.


SP ::= U+20
CR ::= U+0D
file-system-chars ::= (ALPHA | DIGIT | )*
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)*

† Legal file system characters vary by platform.


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
Example 3: Aggressive 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 4: 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


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

🔗 🔎