idnits 2.17.00 (12 Aug 2021) /tmp/idnits42826/draft-ietf-httpbis-priority-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (11 January 2021) is 495 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-34) exists of draft-ietf-quic-http-33 == Outdated reference: draft-ietf-quic-transport has been published as RFC 9000 == Outdated reference: draft-ietf-httpbis-header-structure has been published as RFC 8941 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP K. Oku 3 Internet-Draft Fastly 4 Intended status: Standards Track L. Pardue 5 Expires: 15 July 2021 Cloudflare 6 11 January 2021 8 Extensible Prioritization Scheme for HTTP 9 draft-ietf-httpbis-priority-03 11 Abstract 13 This document describes a scheme for prioritizing HTTP responses. 14 This scheme expresses the priority of each HTTP response using 15 absolute values, rather than as a relative relationship between a 16 group of HTTP responses. 18 This document defines the Priority header field for communicating the 19 initial priority in an HTTP version-independent manner, as well as 20 HTTP/2 and HTTP/3 frames for reprioritizing the responses. These 21 share a common format structure that is designed to provide future 22 extensibility. 24 Note to Readers 26 _RFC EDITOR: please remove this section before publication_ 28 Discussion of this draft takes place on the HTTP working group 29 mailing list (ietf-http-wg@w3.org), which is archived at 30 https://lists.w3.org/Archives/Public/ietf-http-wg/ 31 (https://lists.w3.org/Archives/Public/ietf-http-wg/). 33 Working Group information can be found at https://httpwg.org/ 34 (https://httpwg.org/); source code and issues list for this draft can 35 be found at https://github.com/httpwg/http-extensions/labels/ 36 priorities (https://github.com/httpwg/http-extensions/labels/ 37 priorities). 39 Status of This Memo 41 This Internet-Draft is submitted in full conformance with the 42 provisions of BCP 78 and BCP 79. 44 Internet-Drafts are working documents of the Internet Engineering 45 Task Force (IETF). Note that other groups may also distribute 46 working documents as Internet-Drafts. The list of current Internet- 47 Drafts is at https://datatracker.ietf.org/drafts/current/. 49 Internet-Drafts are draft documents valid for a maximum of six months 50 and may be updated, replaced, or obsoleted by other documents at any 51 time. It is inappropriate to use Internet-Drafts as reference 52 material or to cite them other than as "work in progress." 54 This Internet-Draft will expire on 15 July 2021. 56 Copyright Notice 58 Copyright (c) 2021 IETF Trust and the persons identified as the 59 document authors. All rights reserved. 61 This document is subject to BCP 78 and the IETF Trust's Legal 62 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 63 license-info) in effect on the date of publication of this document. 64 Please review these documents carefully, as they describe your rights 65 and restrictions with respect to this document. Code Components 66 extracted from this document must include Simplified BSD License text 67 as described in Section 4.e of the Trust Legal Provisions and are 68 provided without warranty as described in the Simplified BSD License. 70 Table of Contents 72 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 73 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 74 2. Motivation for Replacing HTTP/2 Priorities . . . . . . . . . 4 75 2.1. Disabling HTTP/2 Priorities . . . . . . . . . . . . . . . 5 76 3. Priority Parameters . . . . . . . . . . . . . . . . . . . . . 6 77 3.1. Urgency . . . . . . . . . . . . . . . . . . . . . . . . . 7 78 3.2. Incremental . . . . . . . . . . . . . . . . . . . . . . . 8 79 3.3. Defining New Parameters . . . . . . . . . . . . . . . . . 8 80 3.3.1. Registration . . . . . . . . . . . . . . . . . . . . 9 81 4. The Priority HTTP Header Field . . . . . . . . . . . . . . . 9 82 5. Reprioritization . . . . . . . . . . . . . . . . . . . . . . 10 83 6. The PRIORITY_UPDATE Frame . . . . . . . . . . . . . . . . . . 10 84 6.1. HTTP/2 PRIORITY_UPDATE Frame . . . . . . . . . . . . . . 11 85 6.2. HTTP/3 PRIORITY_UPDATE Frame . . . . . . . . . . . . . . 12 86 7. Merging Client- and Server-Driven Parameters . . . . . . . . 13 87 8. Client Scheduling . . . . . . . . . . . . . . . . . . . . . . 14 88 9. Server Scheduling . . . . . . . . . . . . . . . . . . . . . . 14 89 10. Fairness . . . . . . . . . . . . . . . . . . . . . . . . . . 16 90 10.1. Coalescing Intermediaries . . . . . . . . . . . . . . . 16 91 10.2. HTTP/1.x Back Ends . . . . . . . . . . . . . . . . . . . 17 92 10.3. Intentional Introduction of Unfairness . . . . . . . . . 17 93 11. Why use an End-to-End Header Field? . . . . . . . . . . . . . 17 94 12. Security Considerations . . . . . . . . . . . . . . . . . . . 18 95 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 96 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 97 14.1. Normative References . . . . . . . . . . . . . . . . . . 20 98 14.2. Informative References . . . . . . . . . . . . . . . . . 21 99 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 21 100 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 22 101 B.1. Since draft-ietf-httpbis-priority-01 . . . . . . . . . . 22 102 B.2. Since draft-ietf-httpbis-priority-01 . . . . . . . . . . 22 103 B.3. Since draft-ietf-httpbis-priority-00 . . . . . . . . . . 22 104 B.4. Since draft-kazuho-httpbis-priority-04 . . . . . . . . . 22 105 B.5. Since draft-kazuho-httpbis-priority-03 . . . . . . . . . 23 106 B.6. Since draft-kazuho-httpbis-priority-02 . . . . . . . . . 23 107 B.7. Since draft-kazuho-httpbis-priority-01 . . . . . . . . . 23 108 B.8. Since draft-kazuho-httpbis-priority-00 . . . . . . . . . 23 109 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 111 1. Introduction 113 It is common for an HTTP ([RFC7230]) resource representation to have 114 relationships to one or more other resources. Clients will often 115 discover these relationships while processing a retrieved 116 representation, leading to further retrieval requests. Meanwhile, 117 the nature of the relationship determines whether the client is 118 blocked from continuing to process locally available resources. For 119 example, visual rendering of an HTML document could be blocked by the 120 retrieval of a CSS file that the document refers to. In contrast, 121 inline images do not block rendering and get drawn incrementally as 122 the chunks of the images arrive. 124 To provide meaningful presentation of a document at the earliest 125 moment, it is important for an HTTP server to prioritize the HTTP 126 responses, or the chunks of those HTTP responses, that it sends. 128 HTTP/2 ([RFC7540]) provides such a prioritization scheme. A client 129 sends a series of PRIORITY frames to communicate to the server a 130 "priority tree"; this represents the client's preferred ordering and 131 weighted distribution of the bandwidth among the HTTP responses. 132 However, the design and implementation of this scheme has been 133 observed to have shortcomings, explained in Section 2. 135 This document defines the Priority HTTP header field that can be used 136 by both client and server to specify the precedence of HTTP responses 137 in a standardized, extensible, protocol-version-independent, end-to- 138 end format. Along with the protocol-version-specific frame for 139 reprioritization, this prioritization scheme acts as a substitute for 140 the original prioritization scheme of HTTP/2. 142 1.1. Notational Conventions 144 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 145 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 146 document are to be interpreted as described in [RFC2119]. 148 The terms sf-token and sf-boolean are imported from 149 [STRUCTURED-FIELDS]. 151 Example HTTP requests and responses use the HTTP/2-style formatting 152 from [RFC7540]. 154 This document uses the variable-length integer encoding from 155 [I-D.ietf-quic-transport]. 157 The term control stream is used to describe the HTTP/2 stream with 158 identifier 0x0, and HTTP/3 control stream; see [I-D.ietf-quic-http], 159 Section 6.2.1. 161 2. Motivation for Replacing HTTP/2 Priorities 163 An important feature of any implementation of a protocol that 164 provides multiplexing is the ability to prioritize the sending of 165 information. This was an important realization in the design of 166 HTTP/2. Prioritization is a difficult problem, so it will always be 167 suboptimal, particularly if one endpoint operates in ignorance of the 168 needs of its peer. 170 HTTP/2 introduced a complex prioritization signaling scheme that used 171 a combination of dependencies and weights, formed into an unbalanced 172 tree. This scheme has suffered from poor deployment and 173 interoperability. 175 The rich flexibility of client-driven HTTP/2 prioritization tree 176 building is rarely exercised. Experience has shown that clients tend 177 to choose a single model optimized for a web use case and experiment 178 within the model constraints, or do nothing at all. Furthermore, 179 many clients build their prioritization tree in a unique way, which 180 makes it difficult for servers to understand their intent and act or 181 intervene accordingly. 183 Many HTTP/2 server implementations do not include support for the 184 priority scheme. Some instead favor custom server-driven schemes 185 based on heuristics or other hints, such as resource content type or 186 request generation order. For example, a server, with knowledge of 187 the document structure, might want to prioritize the delivery of 188 images that are critical to user experience above other images, but 189 below the CSS files. Since client trees vary, it is impossible for 190 the server to determine how such images should be prioritized against 191 other responses. 193 The HTTP/2 scheme allows intermediaries to coalesce multiple client 194 trees into a single tree that is used for a single upstream HTTP/2 195 connection. However, most intermediaries do not support this. The 196 scheme does not define a method that can be used by a server to 197 express the priority of a response. Without such a method, 198 intermediaries cannot coordinate client-driven and server-driven 199 priorities. 201 HTTP/2 describes denial-of-service considerations for 202 implementations. On 2019-08-13 Netflix issued an advisory notice 203 about the discovery of several resource exhaustion vectors affecting 204 multiple HTTP/2 implementations. One attack, [CVE-2019-9513] aka 205 "Resource Loop", is based on manipulation of the priority tree. 207 The HTTP/2 scheme depends on in-order delivery of signals, leading to 208 challenges in porting the scheme to protocols that do not provide 209 global ordering. For example, the scheme cannot be used in HTTP/3 210 [I-D.ietf-quic-http] without changing the signal and its processing. 212 Considering the problems with deployment and adaptability to HTTP/3, 213 retaining the HTTP/2 priority scheme increases the complexity of the 214 entire system without any evidence that the value it provides offsets 215 that complexity. In fact, multiple experiments from independent 216 research have shown that simpler schemes can reach at least 217 equivalent performance characteristics compared to the more complex 218 HTTP/2 setups seen in practice, at least for the web use case. 220 2.1. Disabling HTTP/2 Priorities 222 The problems and insights set out above are motivation for allowing 223 endpoints to opt out of using the HTTP/2 priority scheme, in favor of 224 using an alternative such as the scheme defined in this 225 specification. The SETTINGS_DEPRECATE_HTTP2_PRIORITIES setting 226 described below enables endpoints to understand their peer's 227 intention. The value of the parameter MUST be 0 or 1. Any value 228 other than 0 or 1 MUST be treated as a connection error (see 229 [RFC7540], Section 5.4.1) of type PROTOCOL_ERROR. 231 Endpoints MUST send this SETTINGS parameter as part of the first 232 SETTINGS frame. When the peer receives the first SETTINGS frame, it 233 learns the sender has deprecated the HTTP/2 priority scheme if it 234 receives the SETTINGS_DEPRECATE_HTTP2_PRIORITIES parameter with the 235 value of 1. 237 A sender MUST NOT change the SETTINGS_DEPRECATE_HTTP2_PRIORITIES 238 parameter value after the first SETTINGS frame. Detection of a 239 change by a receiver MUST be treated as a connection error of type 240 PROTOCOL_ERROR. 242 Until the client receives the SETTINGS frame from the server, the 243 client SHOULD send both the priority signal defined in the HTTP/2 244 priority scheme and also that of this prioritization scheme. Once 245 the client learns that the HTTP/2 priority scheme is deprecated, it 246 SHOULD stop sending the HTTP/2 priority signals. If the client 247 learns that the HTTP/2 priority scheme is not deprecated, it SHOULD 248 stop sending PRIORITY_UPDATE frames (Section 6.1), but MAY continue 249 sending the Priority header field (Section 4), as it is an end-to-end 250 signal that might be useful to nodes behind the server that the 251 client is directly connected to. 253 The SETTINGS frame precedes any priority signal sent from a client in 254 HTTP/2, so a server can determine if it should respect the HTTP/2 255 scheme before building state. A server that receives 256 SETTINGS_DEPRECATE_HTTP2_PRIORITIES MUST ignore HTTP/2 priority 257 signals. 259 Where both endpoints disable HTTP/2 priorities, the client is 260 expected to send this scheme's priority signal. Handling of omitted 261 signals is described in Section 3. 263 3. Priority Parameters 265 The priority information is a sequence of key-value pairs, providing 266 room for future extensions. Each key-value pair represents a 267 priority parameter. 269 The Priority HTTP header field (Section 4) is an end-to-end way to 270 transmit this set of parameters when a request or a response is 271 issued. In order to reprioritize a request, HTTP-version-specific 272 frames (Section 6.1 and Section 6.2) are used by clients to transmit 273 the same information on a single hop. If intermediaries want to 274 specify prioritization on a multiplexed HTTP connection, they SHOULD 275 use a PRIORITY_UPDATE frame and SHOULD NOT change the Priority header 276 field. 278 In both cases, the set of priority parameters is encoded as a 279 Structured Fields Dictionary ([STRUCTURED-FIELDS]). 281 This document defines the urgency("u") and incremental("i") 282 parameters. When receiving an HTTP request that does not carry these 283 priority parameters, a server SHOULD act as if their default values 284 were specified. Note that handling of omitted parameters is 285 different when processing an HTTP response; see Section 7. 287 Unknown parameters, parameters with out-of-range values or values of 288 unexpected types MUST be ignored. 290 3.1. Urgency 292 The urgency parameter ("u") takes an integer between 0 and 7, in 293 descending order of priority. This range provides sufficient 294 granularity for prioritizing responses for ordinary web browsing, at 295 minimal complexity. 297 The value is encoded as an sf-integer. The default value is 3. 299 This parameter indicates the sender's recommendation, based on the 300 expectation that the server would transmit HTTP responses in the 301 order of their urgency values if possible. The smaller the value, 302 the higher the precedence. 304 The following example shows a request for a CSS file with the urgency 305 set to "0": 307 :method = GET 308 :scheme = https 309 :authority = example.net 310 :path = /style.css 311 priority = u=0 313 A client that fetches a document that likely consists of multiple 314 HTTP resources (e.g., HTML) SHOULD assign the default urgency level 315 to the main resource. This convention allows servers to refine the 316 urgency using knowledge specific to the web-site (see Section 7). 318 The lowest urgency level (7) is reserved for background tasks such as 319 delivery of software updates. This urgency level SHOULD NOT be used 320 for fetching responses that have impact on user interaction. 322 3.2. Incremental 324 The incremental parameter ("i") takes an sf-boolean as the value that 325 indicates if an HTTP response can be processed incrementally, i.e. 326 provide some meaningful output as chunks of the response arrive. 328 The default value of the incremental parameter is false ("0"). 330 A server might distribute the bandwidth of a connection between 331 incremental responses that share the same urgency, hoping that 332 providing those responses in parallel would be more helpful to the 333 client than delivering the responses one by one. 335 If a client makes concurrent requests with the incremental parameter 336 set to false, there is no benefit serving responses in parallel 337 because the client is not going to process those responses 338 incrementally. Serving non-incremental responses one by one, in the 339 order in which those requests were generated is considered to be the 340 best strategy. 342 The following example shows a request for a JPEG file with the 343 urgency parameter set to "5" and the incremental parameter set to 344 "true". 346 :method = GET 347 :scheme = https 348 :authority = example.net 349 :path = /image.jpg 350 priority = u=5, i 352 3.3. Defining New Parameters 354 When attempting to define new parameters, care must be taken so that 355 they do not adversely interfere with prioritization performed by 356 existing endpoints or intermediaries that do not understand the newly 357 defined parameter. Since unknown parameters are ignored, new 358 parameters should not change the interpretation of or modify the 359 predefined parameters in a way that is not backwards compatible or 360 fallback safe. 362 For example, if there is a need to provide more granularity than 363 eight urgency levels, it would be possible to subdivide the range 364 using an additional parameter. Implementations that do not recognize 365 the parameter can safely continue to use the less granular eight 366 levels. 368 Alternatively, the urgency can be augmented. For example, a 369 graphical user agent could send a "visible" parameter to indicate if 370 the resource being requested is within the viewport. 372 Generic parameters are preferred over vendor-specific, application- 373 specific or deployment-specific values. If a generic value cannot be 374 agreed upon in the community, the parameter's name should be 375 correspondingly specific (e.g., with a prefix that identifies the 376 vendor, application or deployment). 378 3.3.1. Registration 380 New Priority parameters can be defined by registering them in the 381 HTTP Priority Parameters Registry. 383 Registration requests are reviewed and approved by a Designated 384 Expert, as per [RFC8126], Section 4.5. A specification document is 385 appreciated, but not required. 387 The Expert(s) should consider the following factors when evaluating 388 requests: 390 * Community feedback 392 * If the parameters are sufficiently well-defined and adhere to the 393 guidance provided in Section 3.3. 395 Registration requests should use the following template: 397 * Name: [a name for the Priority Parameter that matches key] 399 * Description: [a description of the parameter semantics and value] 401 * Reference: [to a specification defining this parameter] 403 See the registry at https://iana.org/assignments/http-priority 404 (https://iana.org/assignments/http-priority) for details on where to 405 send registration requests. 407 4. The Priority HTTP Header Field 409 The Priority HTTP header field can appear in requests and responses. 410 A client uses it to specify the priority of the response. A server 411 uses it to inform the client that the priority was overwritten. An 412 intermediary can use the Priority information from client requests 413 and server responses to correct or amend the precedence to suit it 414 (see Section 7). 416 The Priority header field is an end-to-end signal of the request 417 priority from the client or the response priority from the server. 419 As is the ordinary case for HTTP caching ([RFC7234]), a response with 420 a Priority header field might be cached and re-used for subsequent 421 requests. When an origin server generates the Priority response 422 header field based on properties of an HTTP request it receives, the 423 server is expected to control the cacheability or the applicability 424 of the cached response, by using header fields that control the 425 caching behavior (e.g., Cache-Control, Vary). 427 An endpoint that fails to parse the Priority header field SHOULD use 428 default parameter values. 430 5. Reprioritization 432 After a client sends a request, it may be beneficial to change the 433 priority of the response. As an example, a web browser might issue a 434 prefetch request for a JavaScript file with the urgency parameter of 435 the Priority request header field set to "u=7" (background). Then, 436 when the user navigates to a page which references the new JavaScript 437 file, while the prefetch is in progress, the browser would send a 438 reprioritization signal with the priority field value set to "u=0". 439 The PRIORITY_UPDATE frame (Section 6) can be used for such 440 reprioritization. 442 6. The PRIORITY_UPDATE Frame 444 This document specifies a new PRIORITY_UPDATE frame for HTTP/2 445 ([RFC7540]) and HTTP/3 ([I-D.ietf-quic-http]). It carries priority 446 parameters and references the target of the prioritization based on a 447 version-specific identifier. In HTTP/2, this identifier is the 448 Stream ID; in HTTP/3, the identifier is either the Stream ID or Push 449 ID. Unlike the Priority header field, the PRIORITY_UPDATE frame is a 450 hop-by-hop signal. 452 PRIORITY_UPDATE frames are sent by clients on the control stream, 453 allowing them to be sent independent from the stream that carries the 454 response. This means they can be used to reprioritize a response or 455 a push stream; or signal the initial priority of a response instead 456 of the Priority header field. 458 A PRIORITY_UPDATE frame communicates a complete set of all parameters 459 in the Priority Field Value field. Omitting a parameter is a signal 460 to use the parameter's default value. Failure to parse the Priority 461 Field Value MUST be treated as a connection error. In HTTP/2 the 462 error is of type PROTOCOL_ERROR; in HTTP/3 the error is of type 463 H3_FRAME_ERROR. 465 A client MAY send a PRIORITY_UPDATE frame before the stream that it 466 references is open (except for HTTP/2 push streams; see Section 6.1). 467 Furthermore, HTTP/3 offers no guaranteed ordering across streams, 468 which could cause the frame to be received earlier than intended. 469 Either case leads to a race condition where a server receives a 470 PRIORITY_UPDATE frame that references a request stream that is yet to 471 be opened. To solve this condition, for the purposes of scheduling, 472 the most recently received PRIORITY_UPDATE frame can be considered as 473 the most up-to-date information that overrides any other signal. 474 Servers SHOULD buffer the most recently received PRIORITY_UPDATE 475 frame and apply it once the referenced stream is opened. Holding 476 PRIORITY_UPDATE frames for each stream requires server resources, 477 which can can be bound by local implementation policy. Although 478 there is no limit to the number of PRIORITY_UPDATES that can be sent, 479 storing only the most recently received frame limits resource 480 commitment. 482 6.1. HTTP/2 PRIORITY_UPDATE Frame 484 The HTTP/2 PRIORITY_UPDATE frame (type=0x10) is used by clients to 485 signal the initial priority of a response, or to reprioritize a 486 response or push stream. It carries the stream ID of the response 487 and the priority in ASCII text, using the same representation as the 488 Priority header field value. 490 The Stream Identifier field ([RFC7540], Section 4.1) in the 491 PRIORITY_UPDATE frame header MUST be zero (0x0). Receiving a 492 PRIORITY_UPDATE frame with a field of any other value MUST be treated 493 as a connection error of type PROTOCOL_ERROR. 495 0 1 2 3 496 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 497 +---------------------------------------------------------------+ 498 |R| Prioritized Stream ID (31) | 499 +---------------------------------------------------------------+ 500 | Priority Field Value (*) ... 501 +---------------------------------------------------------------+ 503 Figure 1: HTTP/2 PRIORITY_UPDATE Frame Payload 505 The PRIORITY_UPDATE frame payload has the following fields: 507 R: A reserved 1-bit field. The semantics of this bit are undefined, 508 and the bit MUST remain unset (0x0) when sending and MUST be 509 ignored when receiving. 511 Prioritized Stream ID: A 31-bit stream identifier for the stream 512 that is the target of the priority update. 514 Priority Field Value: The priority update value in ASCII text, 515 encoded using Structured Fields. 517 When the PRIORITY_UPDATE frame applies to a request stream, clients 518 SHOULD provide a Prioritized Stream ID that refers to a stream in the 519 "open", "half-closed (local)", or "idle" state. Servers can discard 520 frames where the Prioritized Stream ID refers to a stream in the 521 "half-closed (local)" or "closed" state. The number of streams which 522 have been prioritized but remain in the "idle" state plus the number 523 of active streams (those in the "open" or either "half-closed" state; 524 see section 5.1.2 of [RFC7540]) MUST NOT exceed the value of the 525 SETTINGS_MAX_CONCURRENT_STREAMS parameter. Servers that receive such 526 a PRIORITY_UPDATE MUST respond with a connection error of type 527 PROTOCOL_ERROR. 529 When the PRIORITY_UPDATE frame applies to a push stream, clients 530 SHOULD provide a Prioritized Stream ID that refers to a stream in the 531 "reserved (remote)" or "half-closed (local)" state. Servers can 532 discard frames where the Prioritized Stream ID refers to a stream in 533 the "closed" state. Clients MUST NOT provide a Prioritized Stream ID 534 that refers to a push stream in the "idle" state. Servers that 535 receive a PRIORITY_UPDATE for a push stream in the "idle" state MUST 536 respond with a connection error of type PROTOCOL_ERROR. 538 If a PRIORITY_UPDATE frame is received with a Prioritized Stream ID 539 of 0x0, the recipient MUST respond with a connection error of type 540 PROTOCOL_ERROR. 542 If a client receives a PRIORITY_UPDATE frame, it MUST respond with a 543 connection error of type PROTOCOL_ERROR. 545 6.2. HTTP/3 PRIORITY_UPDATE Frame 547 The HTTP/3 PRIORITY_UPDATE frame (type=0xF0700 or 0xF0701) is used by 548 clients to signal the initial priority of a response, or to 549 reprioritize a response or push stream. It carries the identifier of 550 the element that is being prioritized, and the updated priority in 551 ASCII text, using the same representation as that of the Priority 552 header field value. PRIORITY_UPDATE with a frame type of 0xF0700 is 553 used for request streams, while PRIORITY_UPDATE with a frame type of 554 0xF0701 is used for push streams. 556 The PRIORITY_UPDATE frame MUST be sent on the client control stream 557 ([I-D.ietf-quic-http], Section 6.2.1). Receiving a PRIORITY_UPDATE 558 frame on a stream other than the client control stream MUST be 559 treated as a connection error of type H3_FRAME_UNEXPECTED. 561 HTTP/3 PRIORITY_UPDATE Frame { 562 Type (i) = 0xF0700..0xF0701, 563 Length (i), 564 Prioritized Element ID (i), 565 Priority Field Value (..), 566 } 568 Figure 2: HTTP/3 PRIORITY_UPDATE Frame 570 The PRIORITY_UPDATE frame payload has the following fields: 572 Prioritized Element ID: The stream ID or push ID that is the target 573 of the priority update. 575 Priority Field Value: The priority update value in ASCII text, 576 encoded using Structured Fields. 578 The request-stream variant of PRIORITY_UPDATE (type=0xF0700) MUST 579 reference a request stream. If a server receives a PRIORITY_UPDATE 580 (type=0xF0700) for a Stream ID that is not a request stream, this 581 MUST be treated as a connection error of type H3_ID_ERROR. The 582 Stream ID MUST be within the client-initiated bidirectional stream 583 limit. If a server receives a PRIORITY_UPDATE (type=0xF0700) with a 584 Stream ID that is beyond the stream limits, this SHOULD be treated as 585 a connection error of type H3_ID_ERROR. 587 The push-stream variant PRIORITY_UPDATE (type=0xF0701) MUST reference 588 a promised push stream. If a server receives a PRIORITY_UPDATE 589 (type=0xF0701) with a Push ID that is greater than the maximum Push 590 ID or which has not yet been promised, this MUST be treated as a 591 connection error of type H3_ID_ERROR. 593 PRIORITY_UPDATE frames of either type are only sent by clients. If a 594 client receives a PRIORITY_UPDATE frame, this MUST be treated as a 595 connection error of type H3_FRAME_UNEXPECTED. 597 7. Merging Client- and Server-Driven Parameters 599 It is not always the case that the client has the best understanding 600 of how the HTTP responses deserve to be prioritized. The server 601 might have additional information that can be combined with the 602 client's indicated priority in order to improve the prioritization of 603 the response. For example, use of an HTML document might depend 604 heavily on one of the inline images; existence of such dependencies 605 is typically best known to the server. Or, a server that receives 606 requests for a font [RFC8081] and images with the same urgency might 607 give higher precedence to the font, so that a visual client can 608 render textual information at an early moment. 610 An origin can use the Priority response header field to indicate its 611 view on how an HTTP response should be prioritized. An intermediary 612 that forwards an HTTP response can use the parameters found in the 613 Priority response header field, in combination with the client 614 Priority request header field, as input to its prioritization 615 process. No guidance is provided for merging priorities, this is 616 left as an implementation decision. 618 Absence of a priority parameter in an HTTP response indicates the 619 server's disinterest in changing the client-provided value. This is 620 different from the logic being defined for the request header field, 621 in which omission of a priority parameter implies the use of their 622 default values (see Section 3). 624 As a non-normative example, when the client sends an HTTP request 625 with the urgency parameter set to "5" and the incremental parameter 626 set to "true" 628 :method = GET 629 :scheme = https 630 :authority = example.net 631 :path = /menu.png 632 priority = u=5, i 634 and the origin responds with 636 :status = 200 637 content-type = image/png 638 priority = u=1 640 the intermediary might alter its understanding of the urgency from 641 "5" to "1", because it prefers the server-provided value over the 642 client's. The incremental value continues to be "true", the value 643 specified by the client, as the server did not specify the 644 incremental("i") parameter. 646 8. Client Scheduling 648 A client MAY use priority values to make local processing or 649 scheduling choices about the requests it initiates. 651 9. Server Scheduling 653 Priority signals are input to a prioritization process. They do not 654 guarantee any particular processing or transmission order for one 655 response relative to any other response. An endpoint cannot force a 656 peer to process concurrent request in a particular order using 657 priority. Expressing priority is therefore only a suggestion. 659 A server can use priority signals along with other inputs to make 660 scheduling decisions. No guidance is provided about how this can or 661 should be done. Factors such as implementation choices or deployment 662 environment also play a role. Any given connection is likely to have 663 many dynamic permutations. For these reasons, there is no unilateral 664 perfect scheduler and this document only provides some basic 665 recommendations for implementations. 667 Clients cannot depend on particular treatment based on priority 668 signals. Servers can use other information to prioritize responses. 670 It is RECOMMENDED that, when possible, servers respect the urgency 671 parameter (Section 3.1), sending higher urgency responses before 672 lower urgency responses. 674 It is RECOMMENDED that, when possible, servers respect the 675 incremental parameter (Section 3.2). Non-incremental responses of 676 the same urgency SHOULD be served one-by-one based on the Stream ID, 677 which corresponds to the order in which clients make requests. Doing 678 so ensures that clients can use request ordering to influence 679 response order. Incremental responses of the same urgency SHOULD be 680 served in round-robin manner. 682 The incremental parameter indicates how a client processes response 683 bytes as they arrive. Non-incremental resources are only used when 684 all of the response payload has been received. Incremental resources 685 are used as parts, or chunks, of the response payload are received. 686 Therefore, the timing of response data reception at the client, such 687 as the time to early bytes or the time to receive the entire payload, 688 plays an important role in perceived performance. Timings depend on 689 resource size but this scheme provides no explicit guidance about how 690 a server should use size as an input to prioritization. Instead, the 691 following examples demonstrate how a server that strictly abides the 692 scheduling guidance based on urgency and request generation order 693 could find that early requests prevent serving of later requests. 695 1. At the same urgency level, a non-incremental request for a large 696 resource followed by an incremental request for a small resource. 698 2. At the same urgency level, an incremental request of 699 indeterminate length followed by a non-incremental large 700 resource. 702 It is RECOMMENDED that servers avoid such starvation where possible. 703 The method to do so is an implementation decision. For example, a 704 server might pre-emptively send responses of a particular incremental 705 type based on other information such as content size. 707 Optimal scheduling of server push is difficult, especially when 708 pushed resources contend with active concurrent requests. Servers 709 can consider many factors when scheduling, such as the type or size 710 of resource being pushed, the priority of the request that triggered 711 the push, the count of active concurrent responses, the priority of 712 other active concurrent responses, etc. There is no general guidance 713 on the best way to apply these. A server that is too simple could 714 easily push at too high a priority and block client requests, or push 715 at too low a priority and delay the response, negating intended goals 716 of server push. 718 Priority signals are a factor for server push scheduling. The 719 concept of parameter value defaults applies slightly differently 720 because there is no explicit client-signalled initial priority. A 721 server can apply priority signals provided in an origin response; see 722 the merging guidance given in Section 7. In the absence of origin 723 signals, applying default parameter values could be suboptimal. How 724 ever a server decides to schedule a pushed response, it can signal 725 the intended priority to the client by including the Priority field 726 in a PUSH_PROMISE or HEADERS frame. 728 10. Fairness 730 As a general guideline, a server SHOULD NOT use priority information 731 for making schedule decisions across multiple connections, unless it 732 knows that those connections originate from the same client. Due to 733 this, priority information conveyed over a non-coalesced HTTP 734 connection (e.g., HTTP/1.1) might go unused. 736 The remainder of this section discusses scenarios where unfairness is 737 problematic and presents possible mitigations, or where unfairness is 738 desirable. 740 10.1. Coalescing Intermediaries 742 When an intermediary coalesces HTTP requests coming from multiple 743 clients into one HTTP/2 or HTTP/3 connection going to the backend 744 server, requests that originate from one client might have higher 745 precedence than those coming from others. 747 It is sometimes beneficial for the server running behind an 748 intermediary to obey to the value of the Priority header field. As 749 an example, a resource-constrained server might defer the 750 transmission of software update files that would have the background 751 urgency being associated. However, in the worst case, the asymmetry 752 between the precedence declared by multiple clients might cause 753 responses going to one user agent to be delayed totally after those 754 going to another. 756 In order to mitigate this fairness problem, a server could use 757 knowledge about the intermediary as another signal in its 758 prioritization decisions. For instance, if a server knows the 759 intermediary is coalescing requests, then it could serve the 760 responses in round-robin manner. This can work if the constrained 761 resource is network capacity between the intermediary and the user 762 agent, as the intermediary buffers responses and forwards the chunks 763 based on the prioritization scheme it implements. 765 A server can determine if a request came from an intermediary through 766 configuration, or by consulting if that request contains one of the 767 following header fields: 769 * Forwarded, X-Forwarded-For ([RFC7239]) 771 * Via ([RFC7230], Section 5.7.1) 773 10.2. HTTP/1.x Back Ends 775 It is common for CDN infrastructure to support different HTTP 776 versions on the front end and back end. For instance, the client- 777 facing edge might support HTTP/2 and HTTP/3 while communication to 778 back end servers is done using HTTP/1.1. Unlike with connection 779 coalescing, the CDN will "de-mux" requests into discrete connections 780 to the back end. As HTTP/1.1 and older do not provide a way to 781 concurrently transmit multiple responses, there is no immediate 782 fairness issue in protocol. However, back end servers MAY still use 783 client headers for request scheduling. Back end servers SHOULD only 784 schedule based on client priority information where that information 785 can be scoped to individual end clients. Authentication and other 786 session information might provide this linkability. 788 10.3. Intentional Introduction of Unfairness 790 It is sometimes beneficial to deprioritize the transmission of one 791 connection over others, knowing that doing so introduces a certain 792 amount of unfairness between the connections and therefore between 793 the requests served on those connections. 795 For example, a server might use a scavenging congestion controller on 796 connections that only convey background priority responses such as 797 software update images. Doing so improves responsiveness of other 798 connections at the cost of delaying the delivery of updates. 800 11. Why use an End-to-End Header Field? 802 Contrary to the prioritization scheme of HTTP/2 that uses a hop-by- 803 hop frame, the Priority header field is defined as end-to-end. 805 The rationale is that the Priority header field transmits how each 806 response affects the client's processing of those responses, rather 807 than how relatively urgent each response is to others. The way a 808 client processes a response is a property associated to that client 809 generating that request. Not that of an intermediary. Therefore, it 810 is an end-to-end property. How these end-to-end properties carried 811 by the Priority header field affect the prioritization between the 812 responses that share a connection is a hop-by-hop issue. 814 Having the Priority header field defined as end-to-end is important 815 for caching intermediaries. Such intermediaries can cache the value 816 of the Priority header field along with the response, and utilize the 817 value of the cached header field when serving the cached response, 818 only because the header field is defined as end-to-end rather than 819 hop-by-hop. 821 It should also be noted that the use of a header field carrying a 822 textual value makes the prioritization scheme extensible; see the 823 discussion below. 825 12. Security Considerations 827 [CVE-2019-9513] aka "Resource Loop", is a DoS attack based on 828 manipulation of the HTTP/2 priority tree. Extensible priorities does 829 not use stream dependencies, which mitigates this vulnerability. 831 TBD: depending on the outcome of reprioritization discussions, 832 following paragraphs may change or be removed. 834 [RFC7540], Section 5.3.4 describes a scenario where closure of 835 streams in the priority tree could cause suboptimal prioritization. 836 To avoid this, [RFC7540] states that "an endpoint SHOULD retain 837 stream prioritization state for a period after streams become 838 closed". Retaining state for streams no longer counted towards 839 stream concurrency consumes server resources. Furthermore, [RFC7540] 840 identifies that reprioritization of a closed stream could affect 841 dependents; it recommends updating the priority tree if sufficient 842 state is stored, which will also consume server resources. To limit 843 this commitment, it is stated that "The amount of prioritization 844 state that is retained MAY be limited" and "If a limit is applied, 845 endpoints SHOULD maintain state for at least as many streams as 846 allowed by their setting for SETTINGS_MAX_CONCURRENT_STREAMS.". 847 Extensible priorities does not use stream dependencies, which 848 minimizes most of the resource concerns related to this scenario. 850 [RFC7540], Section 5.3.4 also presents considerations about the state 851 required to store priority information about streams in an "idle" 852 state. This state can be limited by adopting the guidance about 853 concurrency limits described above. Extensible priorities is subject 854 to a similar consideration because PRIORITY_UPDATE frames may arrive 855 before the request that they reference. A server is required to 856 store the information in order to apply the most up-to-date signal to 857 the request. However, HTTP/3 implementations might have practical 858 barriers to determining reasonable stream concurrency limits 859 depending on the information that is available to them from the QUIC 860 transport layer. TODO: so what can we suggest? 862 13. IANA Considerations 864 This specification registers the following entry in the Permanent 865 Message Header Field Names registry established by [RFC3864]: 867 Header field name: Priority 869 Applicable protocol: http 871 Status: standard 873 Author/change controller: IETF 875 Specification document(s): This document 877 Related information: n/a 879 This specification registers the following entry in the HTTP/2 880 Settings registry established by [RFC7540]: 882 Name: SETTINGS_DEPRECATE_HTTP2_PRIORITIES 884 Code: 0x9 886 Initial value: 0 888 Specification: This document 890 This specification registers the following entry in the HTTP/2 Frame 891 Type registry established by [RFC7540]: 893 Frame Type: PRIORITY_UPDATE 895 Code: 0x10 897 Specification: This document 899 This specification registers the following entries in the HTTP/3 900 Frame Type registry established by [I-D.ietf-quic-http]: 902 Frame Type: PRIORITY_UPDATE 904 Code: 0xF0700 and 0xF0701 906 Specification: This document 908 Upon publication, please create the HTTP Priority Parameters registry 909 at https://iana.org/assignments/http-priority 910 (https://iana.org/assignments/http-priority) and populate it with the 911 types defined in Section 3; see Section 3.3.1 for its associated 912 procedures. 914 14. References 916 14.1. Normative References 918 [I-D.ietf-quic-http] 919 Bishop, M., "Hypertext Transfer Protocol Version 3 920 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 921 quic-http-33, 15 December 2020, . 924 [I-D.ietf-quic-transport] 925 Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed 926 and Secure Transport", Work in Progress, Internet-Draft, 927 draft-ietf-quic-transport-33, 13 December 2020, 928 . 931 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 932 Requirement Levels", BCP 14, RFC 2119, 933 DOI 10.17487/RFC2119, March 1997, 934 . 936 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 937 Protocol (HTTP/1.1): Message Syntax and Routing", 938 RFC 7230, DOI 10.17487/RFC7230, June 2014, 939 . 941 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 942 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 943 DOI 10.17487/RFC7540, May 2015, 944 . 946 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 947 Writing an IANA Considerations Section in RFCs", BCP 26, 948 RFC 8126, DOI 10.17487/RFC8126, June 2017, 949 . 951 [STRUCTURED-FIELDS] 952 Nottingham, M. and P. Kamp, "Structured Field Values for 953 HTTP", Work in Progress, Internet-Draft, draft-ietf- 954 httpbis-header-structure-19, 3 June 2020, 955 . 958 14.2. Informative References 960 [CVE-2019-9513] 961 Common Vulnerabilities and Exposures, "CVE-2019-9513", 1 962 March 2019, . 965 [I-D.lassey-priority-setting] 966 Lassey, B. and L. Pardue, "Declaring Support for HTTP/2 967 Priorities", Work in Progress, Internet-Draft, draft- 968 lassey-priority-setting-00, 25 July 2019, 969 . 972 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 973 Procedures for Message Header Fields", BCP 90, RFC 3864, 974 DOI 10.17487/RFC3864, September 2004, 975 . 977 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 978 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 979 RFC 7234, DOI 10.17487/RFC7234, June 2014, 980 . 982 [RFC7239] Petersson, A. and M. Nilsson, "Forwarded HTTP Extension", 983 RFC 7239, DOI 10.17487/RFC7239, June 2014, 984 . 986 [RFC8081] Lilley, C., "The "font" Top-Level Media Type", RFC 8081, 987 DOI 10.17487/RFC8081, February 2017, 988 . 990 Appendix A. Acknowledgements 992 Roy Fielding presented the idea of using a header field for 993 representing priorities in http://tools.ietf.org/agenda/83/slides/ 994 slides-83-httpbis-5.pdf (http://tools.ietf.org/agenda/83/slides/ 995 slides-83-httpbis-5.pdf). In https://github.com/pmeenan/http3- 996 prioritization-proposal (https://github.com/pmeenan/http3- 997 prioritization-proposal), Patrick Meenan advocates for representing 998 the priorities using a tuple of urgency and concurrency. The ability 999 to deprecate HTTP/2 prioritization is based on 1000 [I-D.lassey-priority-setting], authored by Brad Lassey and Lucas 1001 Pardue, with modifications based on feedback that was not 1002 incorporated into an update to that document. 1004 The motivation for defining an alternative to HTTP/2 priorities is 1005 drawn from discussion within the broad HTTP community. Special 1006 thanks to Roberto Peon, Martin Thomson and Netflix for text that was 1007 incorporated explicitly in this document. 1009 In addition to the people above, this document owes a lot to the 1010 extensive discussion in the HTTP priority design team, consisting of 1011 Alan Frindell, Andrew Galloni, Craig Taylor, Ian Swett, Kazuho Oku, 1012 Lucas Pardue, Matthew Cox, Mike Bishop, Roberto Peon, Robin Marx, Roy 1013 Fielding. 1015 Appendix B. Change Log 1017 B.1. Since draft-ietf-httpbis-priority-01 1019 * Describe considerations for server push prioritisation (#1056, 1020 #1345) 1022 * Define HTTP/2 PRIORITY_UPDATE ID limits in HTTP/2 terms (#1261, 1023 #1344) 1025 * Add a Parameters registry (#1371) 1027 B.2. Since draft-ietf-httpbis-priority-01 1029 * PRIORITY_UPDATE frame changes (#1096, #1079, #1167, #1262, #1267, 1030 #1271) 1032 * Add section to describe server scheduling considerations (#1215, 1033 #1232, #1266) 1035 * Remove specific instructions related to intermediary fairness 1036 (#1022, #1264) 1038 B.3. Since draft-ietf-httpbis-priority-00 1040 * Move text around (#1217, #1218) 1042 * Editorial change to the default urgency. The value is 3, which 1043 was always the intent of previous changes. 1045 B.4. Since draft-kazuho-httpbis-priority-04 1046 * Minimize semantics of Urgency levels (#1023, #1026) 1048 * Reduce guidance about how intermediary implements merging priority 1049 signals (#1026) 1051 * Remove mention of CDN-Loop (#1062) 1053 * Editorial changes 1055 * Make changes due to WG adoption 1057 * Removed outdated Consideration (#118) 1059 B.5. Since draft-kazuho-httpbis-priority-03 1061 * Changed numbering from "[-1,6]" to "[0,7]" (#78) 1063 * Replaced priority scheme negotiation with HTTP/2 priority 1064 deprecation (#100) 1066 * Shorten parameter names (#108) 1068 * Expand on considerations (#105, #107, #109, #110, #111, #113) 1070 B.6. Since draft-kazuho-httpbis-priority-02 1072 * Consolidation of the problem statement (#61, #73) 1074 * Define SETTINGS_PRIORITIES for negotiation (#58, #69) 1076 * Define PRIORITY_UPDATE frame for HTTP/2 and HTTP/3 (#51) 1078 * Explain fairness issue and mitigations (#56) 1080 B.7. Since draft-kazuho-httpbis-priority-01 1082 * Explain how reprioritization might be supported. 1084 B.8. Since draft-kazuho-httpbis-priority-00 1086 * Expand urgency levels from 3 to 8. 1088 Authors' Addresses 1090 Kazuho Oku 1091 Fastly 1093 Email: kazuhooku@gmail.com 1094 Lucas Pardue 1095 Cloudflare 1097 Email: lucaspardue.24.7@gmail.com