Defining HTTP/2 Server Push More Carefully

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].

[RFC7540], Section 8.2 requires that promised requests be cacheable, safe, and not have a request body.

In practice, this means that GET and HEAD can be pushed. A few other methods are cacheable and safe, but since a request body is prohibited (both by the HTTP/2 spec and wire format), it’s not practical to use them.

GET operates as we’d expect; it makes a representation available as if it had been previously requested and cached, roughly.

In theory, HEAD should operate in a similar fashion; it would be as if the client had performed a HEAD and used the pushed response to update the cache, as per [RFC7234], Section 4.3.5 (“Freshening Responses via HEAD”). This might be useful, for example, to update the metadata of that response. However, the same effect can also be achieved by using a conditional request; see Section 2.3.

Of other status codes, perhaps the most interesting would be OPTIONS, because of its use by CORS ([WHATWG.fetch]). See Section 2.9.

In principle, any HTTP status code can be pushed in a response. Success (2xx), redirection (300, 301, 302, 303, 307, 308) and eror (4xx and 5xx) status codes all have the same caching semantics, described in [RFC7234].

This implies that if they are pushed to the client, any of these status codes should behave as if the client had requested them previously and stored the response. For example, a 403 (Forbidden) can be pushed and stored just as a 200 (OK) – even if this would be of very limited use.

There are a few complications to consider, however.

• 304 (Not Modified) has special interaction with caches and validation that is described in Section 2.3.
• Other 3xx Redirection codes indicate, when pushed, that if the client were to make that request, it will be redirected. That does not mean that the Location header’s URL should be followed immediately; it is only upon an actual request from the client that it should be acted upon. Therefore, the caching semantics of 3xx redirects take effect.
• 1xx Informational codes don’t make much sense as a Push payload, because the headers they convey are lost in most implementations (to be subsumed by the headers in the final response). For example, the headers on a 100 (Continue) response are a no-op; effectively, it’s a one-bit “go ahead” signal. Since HTTP/2 already has protocol-level signalling mechanisms, it’s probably best to say that 1xx responses SHOULD NOT be sent in Server Push, and MUST be ignored when received.
• 401 (Unauthenticated) and 407 (Proxy-Authenticate) are covered in Section 2.7.
• Many other 4xx and 5xx status codes don’t have any practical use in Server Push; e.g., 405 (Method Not Allowed), 408 (Request Timeout), 411 (Length Required) and 414 (URI Too Long) are all reactions to problems with the request. Since the server has sent that request, their use is somewhat self-defeating; however, this does not mean that a client encountering them should generate an error, or fail to use the response. At the very least, if the response is available in devtools, debugging will be easier; additionally, someone might find a creative, appropriate use for them some day.

The interaction of Content Negotiation and Server Push is tricky, because it requires the server to guess what the client would have sent, in order to negotiate upon it.

However, it becomes much simpler if we assume that the client SHOULD NOT check a PUSH_PROMISE request’s headers to see whether or not it would have sent that request.

This means, for example, that if you PUSH_PROMISE the “wrong” User-Agent, Accept-Encoding, User-Agent or even Cookie header field, the client SHOULD still use the pushed response; all they’re looking for is a matching request method and URL.

• The pushed request and response MUST still “agree”; i.e., if you’re using gzip encoding, Accept-Encoding and Content-Encoding should be pushed with appropriate values.
• The pushed response MUST have an appropriate Vary header field, if it is cacheable. This is so that the cache operates properly.

Additionally, the server needs to know what the base capabilities and preferences of the client are, to allow it to select the appropriate responses to push. To aid this, we suggest that servers create a response by copying the values of the request header fields mentioned in the Vary response header field from the request that is identified by the PUSH_PROMISE frame’s Stream ID.

:method: GET
:scheme: https
:authority: www.example.com
:path: /
User-Agent: FooAgent/1.0
Accept-Encoding: gzip, br
Accept-Language: en, fr
Accept: text/html,s application/example, image/*
Cookie: abc=123

:status: 200
Vary: Accept-Encoding
Content-Type: image/png
Cache-Control: max-age=3600

:method: GET
:scheme: https
:authority: www.example.com
:path: /images/123.png
Accept-Encoding: gzip, br
Vary: Accept-Encoding

This approach has its limits. For example, use of [I-D.ietf-httpbis-client-hints] might not be practical with server push (since in some circumstances, hints might change between the base page request and the request for what’s been pushed).

Server Push has a strong tie to HTTP caching ([RFC7234]).

• The index portion of a PDF file
• The first segments or a video or audio file (and, in some formats, the last)
• The header of an image file, as it might contain layout-critical metadata

However, it’s believed that support for partial content in many caches (in particular, browser caches) is poor.

401 (Unauthorized) has the side effect of prompting the user for their credentials. Again, this does not mean that the User Agent ought to do so when receiving a pushed 401; rather, this could be seen as a mechanism to avoid the round trip that would otherwise be required – just as in other intended uses of Server Push.

Presumably, the PUSH_PROMISE for such a request would omit the Authentication header field.

407 (Proxy Authenticate) is probably best not to push, since it’s confusing authority of the network vs. the origin. Clients SHOULD ignore such pushes.

• If a client receives a PUSH_PROMISE that does not include a complete and valid set of header fields or the :method pseudo-header field identifies a method that is not safe, it MUST respond with a stream error (Section 5.4.2) of type PROTOCOL_ERROR.

“Complete” in this context is a bit fuzzy. The strictest reading would be that it MUST include the required pseudo-headers, along with any request headers specified by a later Vary (as discussed in Section 2.4).

There are a few headers that are interesting to consider, however.

Use of the Host request header field is discouraged in HTTP/2, and SHOULD be omitted.

The following request headers could be copied from the parent Stream ID’s request, but are unlikely to be useful (unless specified in Vary), and SHOULD be omitted otherwise: * User-Agent * Cookie * DNT

The Referer header could be copied from the parent Stream ID’s request, but in most cases this would be a waste of bytes; it SHOULD be omitted.

Expect doesn’t make much sense in a push, as discussed in Section 2.2; it SHOULD be omitted.

Origin is discussed in Section 2.9.

As described in Section 2.4, none of these headers should cause a client to ignore the push or generate an error.

[WHATWG.fetch] defines CORS, which uses the OPTIONS method to pre-flight certain requests to assure that the server has opted into them, as well as discover what headers and methods are allowed on such a request.

OPTIONS is safe and (in this case) does not have a request body (although technically, it has a zero-length body, that can probably be overlooked).

Pushing OPTIONS as a means of pre-seeding CORS information would only work in very limited circumstances; because CORS is, by nature, cross-origin, the two origins in question would need some way of coordinating the push; the first origin would effectively tell the second origin that a request is imminent, so it should initiate a push.

This seems fairly unlikely, unless the origins have an unusually close relationship. Conceivably, this might be possible if the origins are coalesced onto the same connection, since they would be represented by the same server.

Whether or not it’s worth the specification and implementation work remains a separate question, especially when conveying site-wide CORS information via other mechanisms is under discussion.

CORS also defines the use of several headers to control the reuse of content across origins. Presumably these would operate the same way whether or not they are pushed. Notably, the Origin request header is used to determine where the content that originated the request is from.

• Origin: https://www.example.com/

when loading content from https://other.example.net/foo.

• Access-Control-Allow-Origin: https://www.example.com/

then the browser will allow the page to have access to that content.

It’s not clear how this interacts with server push. Presumably, it will ignore the value of any Origin header in the PUSH_PROMISE, synthesising an appropriate value.

However, the PUSH_PROMISE might still need to send an Origin header value, if the response contains Vary: Origin; otherwise, a cached response might be incorrectly used for another origin’s request.

See recent discussion on-list.

• The server MUST include a value in the :authority pseudo-header field for which the server is authoritative (see Section 10.1). A client MUST treat a PUSH_PROMISE for which the server is not authoritative as a stream error (Section 5.4.2) of type PROTOCOL_ERROR.

Interestingly, it does not say anything about the relationship of the authority of the stream which a PUSH_PROMISE appears upon and its embedded request. Is it valid (and a good idea) for a stream from foo.example.com to push a stream to bar.example.net (for example)?

• Once a client receives a PUSH_PROMISE frame and chooses to accept the pushed response, the client SHOULD NOT issue any requests for the promised response until after the promised stream has closed. If the client determines, for any reason, that it does not wish to receive the pushed response from the server or if the server takes too long to begin sending the promised response, the client can send a RST_STREAM frame, using either the CANCEL or REFUSED_STREAM code and referencing the pushed stream’s identifier.

Unfortunately, this doesn’t give the server much information about why the push was refused. New HTTP error codes are collected below, in an attempt to start to give this information.