Priority Placeholders in HTTP/2

Stream Priority is described in , Section 5.3. Priority is communicated using PRIORITY frames and with reference to other streams, with stream 0 being the root of the tree. Each stream depends on one other stream with a particular weight; these weights represent relative priorities among the multiple children of a stream. Unfortunately, the scheme as specified encourages servers to actively maintain closed streams in the priority tree, since other streams might reference them later. This produces an unbounded state commitment on the part of the server if it is to correctly reflect any possible reference the client might make. While priorities are only advisory and the server is free to discard as much state as it needs to, references to streams which are no longer in the server’s state are treated as references to the root of the tree. This can result in wildly different conceptions of the priority tree between client and server, a situation which all parties would prefer to avoid.

The words “MUST”, “MUST NOT”, “SHOULD”, and “MAY” are used in this document. It’s not shouting; when they are capitalized, they have the special meaning defined in .

This extension consists of an additional setting , changes to the set of HTTP/2 frames , and modified state management logic on the server .

An HTTP/2 peer that supports Priority Placeholders indicates this using the HTTP/2 SETTINGS_PLACEHOLDERS (0xSETTING-TBD) setting. When a value for the SETTINGS_PLACEHOLDERS setting is not set, this indicates that the peer does not support the extension, and other protocol elements in this document MUST NOT be used. A client that supports this extension SHOULD set this value to 0 (0x00). A server which supports this extension MUST set this value to a non-zero number indicating the number of placeholders it is willing to make available to the client, which MUST be at most 2^31-1. Clients MUST NOT use the protocol elements in this document unless the server has indicated support by setting a non-zero value.

HTTP/2 permits settings to change during the course of a connection. This setting can be freely increased at any time without consequence, and servers SHOULD NOT reduce the value during the lifetime of a connection. If a client receives a reduction in the number of permitted placeholders, it MUST assume that all placeholders over the new limit have been pruned from the tree and SHOULD immediately issue PRIORITY and PLACEHOLDER_PRIORITY frames as necessary to rebuild the priority tree as desired. Once the SETTINGS frame has been acknowledged, servers should treat the excess placeholders as inactive and prune them following the same logic in .

When client and server have opted in to this extension, the HTTP/2 PRIORITY frame and HEADERS frame contain one additional flag: When set, bit 1 indicates that the value in the Stream Dependency field is a Placeholder ID rather than a Stream ID. In HEADERS, this flag MUST NOT be set if the PRIORITY flag is not set.

The PLACEHOLDER_PRIORITY (type=0xFRAME-TBD) frame specifies the sender-advised priority of a placeholder. It MUST be sent only on Stream 0. The semantics of the Stream Dependency, Weight, and E flag are the same as in the HTTP/2 PRIORITY frame. The flags defined are: Indicates that the stream dependency is exclusive (see , Section 5.3). When set, bit 1 indicates that the value in the Stream Dependency field is a Placeholder ID rather than a Stream ID.

The PLACEHOLDER_PRIORITY frame payload has the following fields: A 31-bit stream identifier for the request stream whose priority is being updated. A 31-bit stream or placeholder identifier for the request stream that this stream depends on (see , Section 5.3). An unsigned 8-bit integer representing a priority weight for the stream (see , Section 5.3). Add one to the value to obtain a weight between 1 and 256. A PLACEHOLDER_PRIORITY frame MUST have a payload length of nine octets. A PLACEHOLDER_PRIORITY frame of any other length MUST be treated as a connection error of type PROTOCOL_ERROR if the sender has advertised support for this extension, and ignored otherwise.

This extension provides a mechanism for servers to limit how many additional IDs which do not refer to an active request will be used to maintain priority state. Because the server commits to maintain these inactive IDs, clients can use them with confidence that the server will not have discarded the state without warning. In exchange, the server knows it can aggressively prune inactive regions from the priority tree, because placeholders will be used to “root” any persistent structure of the tree which the client cares about retaining. For prioritization purposes, a node in the tree is considered “inactive” when the corresponding stream has been closed for at least two round-trip times (using any reasonable estimate available on the server). This delay helps mitigate race conditions where the server has pruned a node the client believed was still active and used as a Stream Dependency. Specifically, the server MAY at any time: Identify and discard branches of the tree containing only inactive nodes (i.e. a node with only other inactive nodes as descendants, along with those descendants) Identify and condense interior regions of the tree containing only inactive nodes, allocating weight appropriately

I ==> A / \ | | A I A A | | A A ]]> In the example in , P represents a Placeholder, A represents an active node, and I represents an inactive node. In the first step, the server discards two inactive branches (each a single node). In the second step, the server condenses an interior inactive node. Note that these transformations will result in no change in the resources allocated to a particular active stream. Clients MUST assume the server is actively performing such pruning and MUST NOT declare a dependency on a stream it knows to have been closed.