idnits 2.17.1 draft-kazuho-httpbis-priority-01.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 (July 21, 2019) is 1741 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 497 -- Looks like a reference, but probably isn't: '2' on line 498 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-header-structure-11 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) == Outdated reference: A later version (-34) exists of draft-ietf-quic-http-22 Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 3 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: January 22, 2020 Cloudflare 6 July 21, 2019 8 The Priority HTTP Header Field 9 draft-kazuho-httpbis-priority-01 11 Abstract 13 This document describes the Priority HTTP header field. This header 14 field can be used by endpoints to specify the absolute precedence of 15 an HTTP response in an HTTP-version-independent way. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on January 22, 2020. 34 Copyright Notice 36 Copyright (c) 2019 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 53 2. The Priority HTTP Header Field . . . . . . . . . . . . . . . 4 54 2.1. urgency . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 2.1.1. prerequisite . . . . . . . . . . . . . . . . . . . . 5 56 2.1.2. default . . . . . . . . . . . . . . . . . . . . . . . 5 57 2.1.3. supplementary . . . . . . . . . . . . . . . . . . . . 5 58 2.1.4. background . . . . . . . . . . . . . . . . . . . . . 6 59 2.2. progressive . . . . . . . . . . . . . . . . . . . . . . . 6 60 3. Merging Client- and Server-Driven Parameters . . . . . . . . 7 61 4. Coexistence with HTTP/2 Priorities . . . . . . . . . . . . . 7 62 4.1. The SETTINGS_HEADER_BASED_PRIORITY SETTINGS Parameter . . 8 63 5. Considerations . . . . . . . . . . . . . . . . . . . . . . . 8 64 5.1. Why use an End-to-End Header Field? . . . . . . . . . . . 8 65 5.2. Why do Urgencies Have Meanings? . . . . . . . . . . . . . 9 66 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 67 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 68 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 69 8.1. Normative References . . . . . . . . . . . . . . . . . . 10 70 8.2. Informative References . . . . . . . . . . . . . . . . . 10 71 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11 72 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 11 73 B.1. Since draft-kazuho-httpbis-priority-00 . . . . . . . . . 11 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 76 1. Introduction 78 It is common for an HTTP ([RFC7230]) resource representation to have 79 relationships to one or more other resources. Clients will often 80 discover these relationships while processing a retrieved 81 representation, leading to further retrieval requests. Meanwhile, 82 the nature of the relationship determines whether the client is 83 blocked from continuing to process locally available resources. For 84 example, visual rendering of an HTML document could be blocked by the 85 retrieval of a CSS file that the document refers to. In contrast, 86 inline images do not block rendering and get drawn progressively as 87 the chunks of the images arrive. 89 To provide meaningful representation of a document at the earliest 90 moment, it is important for an HTTP server to prioritize the HTTP 91 responses, or the chunks of those HTTP responses, that it sends. 93 HTTP/2 ([RFC7540]) provides such a prioritization scheme. A client 94 sends a series of PRIORITY frames to communicate to the server a 95 "priority tree"; this represents the client's preferred ordering and 96 weighted distribution of the bandwidth among the HTTP responses. 97 However, the design has shortcomings: 99 o Its complexity has led to varying levels of support by HTTP/2 100 clients and servers. 102 o It is hard to coordinate with server-driven prioritization. For 103 example, a server, with knowledge of the document structure, might 104 want to prioritize the delivery of images that are critical to 105 user experience above other images, but below the CSS files. But 106 with the HTTP/2 prioritization scheme, it is impossible for the 107 server to determine how such images should be prioritized against 108 other responses that use the client-driven prioritization tree, 109 because every client builds the HTTP/2 prioritization tree in a 110 different way. 112 o It does not define a method that can be used by a server to 113 express the priority of a response. Without such a method, 114 intermediaries cannot coordinate client-driven and server-driven 115 priorities. 117 o The design cannot be ported cleanly to HTTP/3 118 ([I-D.ietf-quic-http]). One of the primary goals of HTTP/3 is to 119 minimize head-of-line blocking. Transmitting the evolving 120 representation of a "prioritization tree" from the client to the 121 server requires head-of-line blocking. 123 Based on these observations, this document defines the Priority HTTP 124 header field that can be used by both the client and the server to 125 specify the precedence of HTTP responses in a standardized, 126 extensible, protocol-version- independent, end-to-end format. This 127 header-based prioritization scheme can act as a substitute for the 128 HTTP/2 frame-based prioritization scheme (see Section 4). 130 1.1. Notational Conventions 132 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 133 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 134 document are to be interpreted as described in [RFC2119]. 136 The terms sh-token and sh-boolean are imported from 137 [I-D.ietf-httpbis-header-structure]. 139 Example HTTP requests and responses use the HTTP/2-style formatting 140 from [RFC7540]. 142 2. The Priority HTTP Header Field 144 The Priority HTTP header field can appear in requests and responses. 145 A client uses it to specify the priority of the response. A server 146 uses it to inform the client that the priority was overwritten. An 147 intermediary can use the Priority information from client requests 148 and server responses to correct or amend the precedence to suit it 149 (see Section 3). 151 The value of the Priority header field is a Structured Headers 152 [I-D.ietf-httpbis-header-structure] Dictionary. Each dictionary 153 member represents a parameter of the Priority header field. This 154 document defines the "urgency" and "progressive" parameters. Values 155 of these parameters MUST always be present. When any of the defined 156 parameters are omitted, or if the Priority header field is not used, 157 their default values SHOULD be applied. 159 Unknown parameters MUST be ignored. 161 2.1. urgency 163 The "urgency" parameter takes an integer between -1 and 6 as shown 164 below: 166 +-----------------+-------------------------------+ 167 | Urgency | Definition | 168 +-----------------+-------------------------------+ 169 | -1 | prerequisite (Section 2.1.1) | 170 | 0 | default (Section 2.1.2) | 171 | between 1 and 5 | supplementary (Section 2.1.3) | 172 | 6 | background (Section 2.1.4) | 173 +-----------------+-------------------------------+ 175 Table 1: Urgencies 177 The value is encoded as an sh-integer. The default value is zero. 179 A server SHOULD transmit HTTP responses in the order of their urgency 180 values. The lower the value, the higher the precedence. 182 The following example shows a request for a CSS file with the urgency 183 set to "-1": 185 :method = GET 186 :scheme = https 187 :authority = example.net 188 :path = /style.css 189 priority = urgency=-1 190 The definition of the urgencies and their expected use-case are 191 described below. Endpoints SHOULD respect the definition of the 192 values when assigning urgencies. 194 2.1.1. prerequisite 196 The prerequisite urgency (value -1) indicates that the response 197 prevents other responses with an urgency of prerequisite or default 198 from being used. 200 For example, use of an external stylesheet can block a web browser 201 from rendering the HTML. In such case, the stylesheet is given the 202 prerequisite urgency. 204 2.1.2. default 206 The default urgency (value 0) indicates a response that is to be used 207 as it is delivered to the client, but one that does not block other 208 responses from being used. 210 For example, when a user using a web browser navigates to a new HTML 211 document, the request for that HTML is given the default urgency. 212 When that HTML document uses a custom font, the request for that 213 custom font SHOULD also be given the default urgency. This is 214 because the availability of the custom font is likely a precondition 215 for the user to use that portion of the HTML document, which is to be 216 rendered by that font. 218 2.1.3. supplementary 220 The supplementary urgency indicates a response that is helpful to the 221 client using a composition of responses, even though the response 222 itself is not mandatory for using those responses. 224 For example, inline images (i.e., images being fetched and displayed 225 as part of the document) are visually important elements of an HTML 226 document. As such, users will typically not be prevented from using 227 the document, at least to some degree, before any or all of these 228 images are loaded. Display of those images are thus considered to be 229 an improvement for visual clients rather than a prerequisite for all 230 user agents. Therefore, such images will be given the supplementary 231 urgency. 233 Values between 1 and 5 are used to represent this urgency, to provide 234 flexibility to the endpoints for giving some responses more or less 235 precedence than others that belong to the supplementary group. 236 Section 3 explains how these values might be used. 238 Clients SHOULD NOT use values 1 and 5. Servers MAY use these values 239 to prioritize a response above or below other supplementary 240 responses. 242 Clients MAY use values 2 to indicate that a request is given 243 relatively high priority, or 4 to indicate relatively low priority, 244 within the supplementary urgency group. 246 For example, an image certain to be visible at the top of the page, 247 might be assigned a value of 2 instead of 3, as it will have a high 248 visual impact for the user. Conversely, an asynchronously loaded 249 JavaScript file might be assigned an urgency value of 4, as it is 250 less likely to have a visual impact. 252 When none of the considerations above is applicable, the value of 3 253 SHOULD be used. 255 2.1.4. background 257 The background urgency (value 6) is used for responses of which the 258 delivery can be postponed without having an impact on using other 259 responses. 261 As an example, the download of a large file in a web browser would be 262 assigned the background urgency so it would not impact further page 263 loads on the same connection. 265 2.2. progressive 267 The "progressive" parameter takes an sh-boolean as the value that 268 indicates if a response can be processed progressively, i.e. provide 269 some meaningful output as chunks of the response arrive. 271 The default value of the "progressive" parameter is "0". 273 A server SHOULD distribute the bandwidth of a connection between 274 progressive responses that share the same urgency. 276 A server SHOULD transmit non-progressive responses one by one, 277 preferably in the order the requests were generated. Doing so 278 maximizes the chance of the client making progress in using the 279 composition of the HTTP responses at the earliest moment. 281 The following example shows a request for a JPEG file with the 282 urgency parameter set to "3" and the progressive parameter set to 283 "1". 285 :method = GET 286 :scheme = https 287 :authority = example.net 288 :path = /image.jpg 289 priority = urgency=3, progressive=?1 291 3. Merging Client- and Server-Driven Parameters 293 It is not always the case that the client has the best understanding 294 of how the HTTP responses deserve to be prioritized. For example, 295 use of an HTML document might depend heavily on one of the inline 296 images. Existence of such dependencies is typically best known to 297 the server. 299 By using the "Priority" response header, a server can override the 300 prioritization hints provided by the client. When used, the 301 parameters found in the response header field overrides those 302 specified by the client. 304 For example, when the client sends an HTTP request with 306 :method = GET 307 :scheme = https 308 :authority = example.net 309 :path = /menu.png 310 priority = urgency=3, progressive=?1 312 and the origin responds with 314 :status = 200 315 content-type = image/png 316 priority = urgency=1 318 the intermediary's understanding of the urgency is promoted from "3" 319 to "1", because the server-provided value overrides the value 320 provided by the client. The progressiveness continues to be "1", the 321 value specified by the client, as the server did not specify the 322 "progressive" parameter. 324 4. Coexistence with HTTP/2 Priorities 326 Standard HTTP/2 ([RFC7540]) endpoints use frame-based prioritization, 327 whereby a client sends priority information in dedicated fields 328 present in HEADERS and PRIORITY frames. A client might instead 329 choose to use header-based prioritization as specified in this 330 document. 332 4.1. The SETTINGS_HEADER_BASED_PRIORITY SETTINGS Parameter 334 To improve communication of the client's intended prioritization 335 scheme, this document specifies a new HTTP/2 SETTINGS parameter with 336 the name "SETTINGS_HEADER_BASED_PRIORITY". The value of the 337 parameter MUST be 0 or 1; the initial value is 0. Frame-based 338 prioritization is respected when the value is 0, or when the server 339 does not recognize the setting. 341 An HTTP/2 client that uses header-based priority SHOULD send a 342 "SETTINGS_HEADER_BASED_PRIORITY" parameter with a value of 1 when 343 connecting to a server. 345 An intermediary SHOULD send a "SETTINGS_HEADER_BASED_PRIORITY" 346 parameter with a value of 1 for a connection it establishes when, and 347 only when, all the requests to be sent over that connection originate 348 from a client that utilizes this header-based prioritization scheme. 349 Otherwise this settings parameter SHOULD be set to 0. 351 A client or intermediary MUST NOT send a 352 "SETTINGS_HEADER_BASED_PRIORITY" parameter with the value of 0 after 353 previously sending a value of 1. 355 A server MUST NOT send a "SETTINGS_HEADER_BASED_PRIORITY" parameter. 356 Upon receipt, a client that supports header-based prioritization MUST 357 close the connection with a protocol error. Non-supporting clients 358 will ignore this extension element (see [RFC7540], Section 5.5). 360 5. Considerations 362 5.1. Why use an End-to-End Header Field? 364 Contrary to the prioritization scheme of HTTP/2 that uses a hop-by- 365 hop frame, the Priority header field is defined as end-to-end. 367 The rationale is that the Priority header field transmits how each 368 response affects the client's processing of those responses, rather 369 than how relatively urgent each response is to others. The way a 370 client processes a response is a property associated to that client 371 generating that request. Not that of an intermediary. Therefore, it 372 is an end-to-end property. How these end-to-end properties carried 373 by the Priority header field affect the prioritization between the 374 responses that share a connection is a hop-by-hop issue. 376 Having the Priority header field defined as end-to-end is important 377 for caching intermediaries. Such intermediaries can cache the value 378 of the Priority header field along with the response, and utilize the 379 value of the cached header field when serving the cached response, 380 only because the header field is defined as end-to-end rather than 381 hop-by-hop. 383 It should also be noted that the use of a header field carrying a 384 textual value makes the prioritization scheme extensible; see the 385 discussion below. 387 5.2. Why do Urgencies Have Meanings? 389 One of the aims of this specification is to define a mechanism for 390 merging client- and server-provided hints for prioritizing the 391 responses. For that to work, each urgency level needs to have a 392 well-defined meaning. As an example, a server can assign the highest 393 precedence among the supplementary responses to an HTTP response 394 carrying an icon, because the meaning of "urgency=1" is shared among 395 the endpoints. 397 This specification restricts itself to defining a minimum set of 398 urgency levels in order to provide sufficient granularity for 399 prioritizing responses for ordinary web browsing, at minimal 400 complexity. 402 However, that does not mean that the prioritization scheme would 403 forever be stuck to the eight levels. The design provides 404 extensibility. If deemed necessary, it would be possible to 405 subdivide any of the eight urgency levels that are currently defined. 406 Or, a graphical user-agent could send a "visible" parameter to 407 indicate if the resource being requested is within the viewport. 409 A server can combine the hints provided in the Priority header field 410 with other information in order to improve the prioritization of 411 responses. For example, a server that receives requests for a font 412 [RFC8081] and images with the same urgency might give higher 413 precedence to the font, so that a visual client can render textual 414 information at an early moment. 416 6. Security Considerations 418 TBD 420 7. IANA Considerations 422 This specification registers the following entry in the Permanent 423 Message Header Field Names registry established by [RFC3864]: 425 Header field name: Priority 427 Applicable protocol: http 428 Status: standard 430 Author/change controller: IETF 432 Specification document(s): This document 434 Related information: n/a 436 This specification registers the following entry in the HTTP/2 437 Settings registry established by [RFC7540]: 439 Name: SETTINGS_HEADER_BASED_PRIORITY: 441 Code: 0xTBD 443 Initial value: 0 445 Specification: This document 447 8. References 449 8.1. Normative References 451 [I-D.ietf-httpbis-header-structure] 452 Nottingham, M. and P. Kamp, "Structured Headers for HTTP", 453 draft-ietf-httpbis-header-structure-11 (work in progress), 454 July 2019. 456 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 457 Requirement Levels", BCP 14, RFC 2119, 458 DOI 10.17487/RFC2119, March 1997, 459 . 461 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 462 Protocol (HTTP/1.1): Message Syntax and Routing", 463 RFC 7230, DOI 10.17487/RFC7230, June 2014, 464 . 466 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 467 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 468 DOI 10.17487/RFC7540, May 2015, 469 . 471 8.2. Informative References 473 [I-D.ietf-quic-http] 474 Bishop, M., "Hypertext Transfer Protocol Version 3 475 (HTTP/3)", draft-ietf-quic-http-22 (work in progress), 476 July 2019. 478 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 479 Procedures for Message Header Fields", BCP 90, RFC 3864, 480 DOI 10.17487/RFC3864, September 2004, 481 . 483 [RFC8081] Lilley, C., "The "font" Top-Level Media Type", RFC 8081, 484 DOI 10.17487/RFC8081, February 2017, 485 . 487 8.3. URIs 489 [1] http://tools.ietf.org/agenda/83/slides/slides-83-httpbis-5.pdf 491 [2] https://github.com/pmeenan/http3-prioritization-proposal 493 Appendix A. Acknowledgements 495 Roy Fielding presented the idea of using a header field for 496 representing priorities in http://tools.ietf.org/agenda/83/slides/ 497 slides-83-httpbis-5.pdf [1]. In https://github.com/pmeenan/http3- 498 prioritization-proposal [2], Patrick Meenan advocates for 499 representing the priorities using a tuple of urgency and concurrency. 501 Many thanks to Robin Marx, Patrick Meenan and Ian Swett for their 502 feedback. 504 Appendix B. Change Log 506 B.1. Since draft-kazuho-httpbis-priority-00 508 o Expand urgency levels from 3 to 8. 510 Authors' Addresses 512 Kazuho Oku 513 Fastly 515 Email: kazuhooku@gmail.com 516 Lucas Pardue 517 Cloudflare 519 Email: lucaspardue.24.7@gmail.com