idnits 2.17.1 draft-fielding-httpbis-http-range-00.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 seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 5, 2018) is 2237 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) == Unused Reference: 'RFC7233' is defined on line 875, but no explicit reference was found in the text -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 7233 (Obsoleted by RFC 9110) Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Fielding, Ed. 3 Internet-Draft Adobe 4 Obsoletes: 7233 (if approved) Y. Lafon, Ed. 5 Intended status: Standards Track W3C 6 Expires: September 6, 2018 J. Reschke, Ed. 7 greenbytes 8 March 5, 2018 10 Hypertext Transfer Protocol (HTTP): Range Requests 11 draft-fielding-httpbis-http-range-00 13 Abstract 15 The Hypertext Transfer Protocol (HTTP) is a stateless application- 16 level protocol for distributed, collaborative, hypertext information 17 systems. This document defines range requests and the rules for 18 constructing and combining responses to those requests. 20 This document obsoletes RFC 7233. 22 Editorial Note 24 This note is to be removed before publishing as an RFC. 26 _This is a temporary document for the purpose of planning the 27 revisions of RFCs 7230 to 7235. This is not yet an official work 28 item of the HTTP Working Group._ 30 Discussion of this draft takes place on the HTTP working group 31 mailing list (ietf-http-wg@w3.org), which is archived at 32 . 34 Errata for RFC 7233 have been collected at , and an additional issues list 36 lives at . 38 The changes in this draft are summarized in Appendix E.1. 40 Status of This Memo 42 This Internet-Draft is submitted in full conformance with the 43 provisions of BCP 78 and BCP 79. 45 Internet-Drafts are working documents of the Internet Engineering 46 Task Force (IETF). Note that other groups may also distribute 47 working documents as Internet-Drafts. The list of current Internet- 48 Drafts is at https://datatracker.ietf.org/drafts/current/. 50 Internet-Drafts are draft documents valid for a maximum of six months 51 and may be updated, replaced, or obsoleted by other documents at any 52 time. It is inappropriate to use Internet-Drafts as reference 53 material or to cite them other than as "work in progress." 55 This Internet-Draft will expire on September 6, 2018. 57 Copyright Notice 59 Copyright (c) 2018 IETF Trust and the persons identified as the 60 document authors. All rights reserved. 62 This document is subject to BCP 78 and the IETF Trust's Legal 63 Provisions Relating to IETF Documents 64 (https://trustee.ietf.org/license-info) in effect on the date of 65 publication of this document. Please review these documents 66 carefully, as they describe your rights and restrictions with respect 67 to this document. Code Components extracted from this document must 68 include Simplified BSD License text as described in Section 4.e of 69 the Trust Legal Provisions and are provided without warranty as 70 described in the Simplified BSD License. 72 This document may contain material from IETF Documents or IETF 73 Contributions published or made publicly available before November 74 10, 2008. The person(s) controlling the copyright in some of this 75 material may not have granted the IETF Trust the right to allow 76 modifications of such material outside the IETF Standards Process. 77 Without obtaining an adequate license from the person(s) controlling 78 the copyright in such materials, this document may not be modified 79 outside the IETF Standards Process, and derivative works of it may 80 not be created outside the IETF Standards Process, except to format 81 it for publication as an RFC or to translate it into languages other 82 than English. 84 Table of Contents 86 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 87 1.1. Conformance and Error Handling . . . . . . . . . . . . . 4 88 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 4 89 2. Range Units . . . . . . . . . . . . . . . . . . . . . . . . . 4 90 2.1. Byte Ranges . . . . . . . . . . . . . . . . . . . . . . . 4 91 2.2. Other Range Units . . . . . . . . . . . . . . . . . . . . 6 92 2.3. Accept-Ranges . . . . . . . . . . . . . . . . . . . . . . 6 93 3. Range Requests . . . . . . . . . . . . . . . . . . . . . . . 7 94 3.1. Range . . . . . . . . . . . . . . . . . . . . . . . . . . 7 95 3.2. If-Range . . . . . . . . . . . . . . . . . . . . . . . . 8 96 4. Responses to a Range Request . . . . . . . . . . . . . . . . 9 97 4.1. 206 Partial Content . . . . . . . . . . . . . . . . . . . 9 98 4.2. Content-Range . . . . . . . . . . . . . . . . . . . . . . 11 99 4.3. Combining Ranges . . . . . . . . . . . . . . . . . . . . 13 100 4.4. 416 Range Not Satisfiable . . . . . . . . . . . . . . . . 14 101 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 102 5.1. Range Unit Registry . . . . . . . . . . . . . . . . . . . 15 103 5.1.1. Procedure . . . . . . . . . . . . . . . . . . . . . . 15 104 5.1.2. Registrations . . . . . . . . . . . . . . . . . . . . 15 105 5.2. Status Code Registration . . . . . . . . . . . . . . . . 16 106 5.3. Header Field Registration . . . . . . . . . . . . . . . . 16 107 5.4. Internet Media Type Registration . . . . . . . . . . . . 16 108 5.4.1. Internet Media Type multipart/byteranges . . . . . . 16 109 6. Security Considerations . . . . . . . . . . . . . . . . . . . 17 110 6.1. Denial-of-Service Attacks Using Range . . . . . . . . . . 18 111 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 112 7.1. Normative References . . . . . . . . . . . . . . . . . . 18 113 7.2. Informative References . . . . . . . . . . . . . . . . . 19 114 Appendix A. Internet Media Type multipart/byteranges . . . . . . 20 115 Appendix B. Changes from RFC 7233 . . . . . . . . . . . . . . . 21 116 Appendix C. Imported ABNF . . . . . . . . . . . . . . . . . . . 21 117 Appendix D. Collected ABNF . . . . . . . . . . . . . . . . . . . 21 118 Appendix E. Change Log . . . . . . . . . . . . . . . . . . . . . 23 119 E.1. Since RFC 7233 . . . . . . . . . . . . . . . . . . . . . 23 120 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 121 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 24 122 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 124 1. Introduction 126 Hypertext Transfer Protocol (HTTP) clients often encounter 127 interrupted data transfers as a result of canceled requests or 128 dropped connections. When a client has stored a partial 129 representation, it is desirable to request the remainder of that 130 representation in a subsequent request rather than transfer the 131 entire representation. Likewise, devices with limited local storage 132 might benefit from being able to request only a subset of a larger 133 representation, such as a single page of a very large document, or 134 the dimensions of an embedded image. 136 This document defines HTTP/1.1 range requests, partial responses, and 137 the multipart/byteranges media type. Range requests are an OPTIONAL 138 feature of HTTP, designed so that recipients not implementing this 139 feature (or not supporting it for the target resource) can respond as 140 if it is a normal GET request without impacting interoperability. 141 Partial responses are indicated by a distinct status code to not be 142 mistaken for full responses by caches that might not implement the 143 feature. 145 Although the range request mechanism is designed to allow for 146 extensible range types, this specification only defines requests for 147 byte ranges. 149 This specification obsoletes RFC 7233, with the changes being 150 summarized in Appendix B. 152 1.1. Conformance and Error Handling 154 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 155 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 156 document are to be interpreted as described in [RFC2119]. 158 Conformance criteria and considerations regarding error handling are 159 defined in Section 2.5 of [MESSGNG]. 161 1.2. Syntax Notation 163 This specification uses the Augmented Backus-Naur Form (ABNF) 164 notation of [RFC5234] with a list extension, defined in Section 7 of 165 [MESSGNG], that allows for compact definition of comma-separated 166 lists using a '#' operator (similar to how the '*' operator indicates 167 repetition). Appendix C describes rules imported from other 168 documents. Appendix D shows the collected grammar with all list 169 operators expanded to standard ABNF notation. 171 2. Range Units 173 A representation can be partitioned into subranges according to 174 various structural units, depending on the structure inherent in the 175 representation's media type. This "range unit" is used in the 176 Accept-Ranges (Section 2.3) response header field to advertise 177 support for range requests, the Range (Section 3.1) request header 178 field to delineate the parts of a representation that are requested, 179 and the Content-Range (Section 4.2) payload header field to describe 180 which part of a representation is being transferred. 182 range-unit = bytes-unit / other-range-unit 184 2.1. Byte Ranges 186 Since representation data is transferred in payloads as a sequence of 187 octets, a byte range is a meaningful substructure for any 188 representation transferable over HTTP (Section 3 of [SEMNTCS]). The 189 "bytes" range unit is defined for expressing subranges of the data's 190 octet sequence. 192 bytes-unit = "bytes" 194 A byte-range request can specify a single range of bytes or a set of 195 ranges within a single representation. 197 byte-ranges-specifier = bytes-unit "=" byte-range-set 198 byte-range-set = 1#( byte-range-spec / suffix-byte-range-spec ) 199 byte-range-spec = first-byte-pos "-" [ last-byte-pos ] 200 first-byte-pos = 1*DIGIT 201 last-byte-pos = 1*DIGIT 203 The first-byte-pos value in a byte-range-spec gives the byte-offset 204 of the first byte in a range. The last-byte-pos value gives the 205 byte-offset of the last byte in the range; that is, the byte 206 positions specified are inclusive. Byte offsets start at zero. 208 Examples of byte-ranges-specifier values: 210 o The first 500 bytes (byte offsets 0-499, inclusive): 212 bytes=0-499 214 o The second 500 bytes (byte offsets 500-999, inclusive): 216 bytes=500-999 218 A byte-range-spec is invalid if the last-byte-pos value is present 219 and less than the first-byte-pos. 221 A client can limit the number of bytes requested without knowing the 222 size of the selected representation. If the last-byte-pos value is 223 absent, or if the value is greater than or equal to the current 224 length of the representation data, the byte range is interpreted as 225 the remainder of the representation (i.e., the server replaces the 226 value of last-byte-pos with a value that is one less than the current 227 length of the selected representation). 229 A client can request the last N bytes of the selected representation 230 using a suffix-byte-range-spec. 232 suffix-byte-range-spec = "-" suffix-length 233 suffix-length = 1*DIGIT 235 If the selected representation is shorter than the specified suffix- 236 length, the entire representation is used. 238 Additional examples, assuming a representation of length 10000: 240 o The final 500 bytes (byte offsets 9500-9999, inclusive): 242 bytes=-500 244 Or: 246 bytes=9500- 248 o The first and last bytes only (bytes 0 and 9999): 250 bytes=0-0,-1 252 o Other valid (but not canonical) specifications of the second 500 253 bytes (byte offsets 500-999, inclusive): 255 bytes=500-600,601-999 256 bytes=500-700,601-999 258 If a valid byte-range-set includes at least one byte-range-spec with 259 a first-byte-pos that is less than the current length of the 260 representation, or at least one suffix-byte-range-spec with a non- 261 zero suffix-length, then the byte-range-set is satisfiable. 262 Otherwise, the byte-range-set is unsatisfiable. 264 In the byte-range syntax, first-byte-pos, last-byte-pos, and suffix- 265 length are expressed as decimal number of octets. Since there is no 266 predefined limit to the length of a payload, recipients MUST 267 anticipate potentially large decimal numerals and prevent parsing 268 errors due to integer conversion overflows. 270 2.2. Other Range Units 272 Range units are intended to be extensible. New range units ought to 273 be registered with IANA, as defined in Section 5.1. 275 other-range-unit = token 277 2.3. Accept-Ranges 279 The "Accept-Ranges" header field allows a server to indicate that it 280 supports range requests for the target resource. 282 Accept-Ranges = acceptable-ranges 283 acceptable-ranges = 1#range-unit / "none" 285 An origin server that supports byte-range requests for a given target 286 resource MAY send 288 Accept-Ranges: bytes 290 to indicate what range units are supported. A client MAY generate 291 range requests without having received this header field for the 292 resource involved. Range units are defined in Section 2. 294 A server that does not support any kind of range request for the 295 target resource MAY send 297 Accept-Ranges: none 299 to advise the client not to attempt a range request. 301 3. Range Requests 303 3.1. Range 305 The "Range" header field on a GET request modifies the method 306 semantics to request transfer of only one or more subranges of the 307 selected representation data, rather than the entire selected 308 representation data. 310 Range = byte-ranges-specifier / other-ranges-specifier 311 other-ranges-specifier = other-range-unit "=" other-range-set 312 other-range-set = 1*VCHAR 314 A server MAY ignore the Range header field. However, origin servers 315 and intermediate caches ought to support byte ranges when possible, 316 since Range supports efficient recovery from partially failed 317 transfers and partial retrieval of large representations. A server 318 MUST ignore a Range header field received with a request method other 319 than GET. 321 An origin server MUST ignore a Range header field that contains a 322 range unit it does not understand. A proxy MAY discard a Range 323 header field that contains a range unit it does not understand. 325 A server that supports range requests MAY ignore or reject a Range 326 header field that consists of more than two overlapping ranges, or a 327 set of many small ranges that are not listed in ascending order, 328 since both are indications of either a broken client or a deliberate 329 denial-of-service attack (Section 6.1). A client SHOULD NOT request 330 multiple ranges that are inherently less efficient to process and 331 transfer than a single range that encompasses the same data. 333 A client that is requesting multiple ranges SHOULD list those ranges 334 in ascending order (the order in which they would typically be 335 received in a complete representation) unless there is a specific 336 need to request a later part earlier. For example, a user agent 337 processing a large representation with an internal catalog of parts 338 might need to request later parts first, particularly if the 339 representation consists of pages stored in reverse order and the user 340 agent wishes to transfer one page at a time. 342 The Range header field is evaluated after evaluating the precondition 343 header fields defined in [CONDTNL], and only if the result in absence 344 of the Range header field would be a 200 (OK) response. In other 345 words, Range is ignored when a conditional GET would result in a 304 346 (Not Modified) response. 348 The If-Range header field (Section 3.2) can be used as a precondition 349 to applying the Range header field. 351 If all of the preconditions are true, the server supports the Range 352 header field for the target resource, and the specified range(s) are 353 valid and satisfiable (as defined in Section 2.1), the server SHOULD 354 send a 206 (Partial Content) response with a payload containing one 355 or more partial representations that correspond to the satisfiable 356 ranges requested, as defined in Section 4. 358 If all of the preconditions are true, the server supports the Range 359 header field for the target resource, and the specified range(s) are 360 invalid or unsatisfiable, the server SHOULD send a 416 (Range Not 361 Satisfiable) response. 363 3.2. If-Range 365 If a client has a partial copy of a representation and wishes to have 366 an up-to-date copy of the entire representation, it could use the 367 Range header field with a conditional GET (using either or both of 368 If-Unmodified-Since and If-Match.) However, if the precondition 369 fails because the representation has been modified, the client would 370 then have to make a second request to obtain the entire current 371 representation. 373 The "If-Range" header field allows a client to "short-circuit" the 374 second request. Informally, its meaning is as follows: if the 375 representation is unchanged, send me the part(s) that I am requesting 376 in Range; otherwise, send me the entire representation. 378 If-Range = entity-tag / HTTP-date 380 A client MUST NOT generate an If-Range header field in a request that 381 does not contain a Range header field. A server MUST ignore an If- 382 Range header field received in a request that does not contain a 383 Range header field. An origin server MUST ignore an If-Range header 384 field received in a request for a target resource that does not 385 support Range requests. 387 A client MUST NOT generate an If-Range header field containing an 388 entity-tag that is marked as weak. A client MUST NOT generate an If- 389 Range header field containing an HTTP-date unless the client has no 390 entity-tag for the corresponding representation and the date is a 391 strong validator in the sense defined by Section 2.2.2 of [CONDTNL]. 393 A server that evaluates an If-Range precondition MUST use the strong 394 comparison function when comparing entity-tags (Section 2.3.2 of 395 [CONDTNL]) and MUST evaluate the condition as false if an HTTP-date 396 validator is provided that is not a strong validator in the sense 397 defined by Section 2.2.2 of [CONDTNL]. A valid entity-tag can be 398 distinguished from a valid HTTP-date by examining the first two 399 characters for a DQUOTE. 401 If the validator given in the If-Range header field matches the 402 current validator for the selected representation of the target 403 resource, then the server SHOULD process the Range header field as 404 requested. If the validator does not match, the server MUST ignore 405 the Range header field. Note that this comparison by exact match, 406 including when the validator is an HTTP-date, differs from the 407 "earlier than or equal to" comparison used when evaluating an If- 408 Unmodified-Since conditional. 410 4. Responses to a Range Request 412 4.1. 206 Partial Content 414 The 206 (Partial Content) status code indicates that the server is 415 successfully fulfilling a range request for the target resource by 416 transferring one or more parts of the selected representation that 417 correspond to the satisfiable ranges found in the request's Range 418 header field (Section 3.1). 420 If a single part is being transferred, the server generating the 206 421 response MUST generate a Content-Range header field, describing what 422 range of the selected representation is enclosed, and a payload 423 consisting of the range. For example: 425 HTTP/1.1 206 Partial Content 426 Date: Wed, 15 Nov 1995 06:25:24 GMT 427 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 428 Content-Range: bytes 21010-47021/47022 429 Content-Length: 26012 430 Content-Type: image/gif 432 ... 26012 bytes of partial image data ... 434 If multiple parts are being transferred, the server generating the 435 206 response MUST generate a "multipart/byteranges" payload, as 436 defined in Appendix A, and a Content-Type header field containing the 437 multipart/byteranges media type and its required boundary parameter. 438 To avoid confusion with single-part responses, a server MUST NOT 439 generate a Content-Range header field in the HTTP header section of a 440 multiple part response (this field will be sent in each part 441 instead). 443 Within the header area of each body part in the multipart payload, 444 the server MUST generate a Content-Range header field corresponding 445 to the range being enclosed in that body part. If the selected 446 representation would have had a Content-Type header field in a 200 447 (OK) response, the server SHOULD generate that same Content-Type 448 field in the header area of each body part. For example: 450 HTTP/1.1 206 Partial Content 451 Date: Wed, 15 Nov 1995 06:25:24 GMT 452 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 453 Content-Length: 1741 454 Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 456 --THIS_STRING_SEPARATES 457 Content-Type: application/pdf 458 Content-Range: bytes 500-999/8000 460 ...the first range... 461 --THIS_STRING_SEPARATES 462 Content-Type: application/pdf 463 Content-Range: bytes 7000-7999/8000 465 ...the second range 466 --THIS_STRING_SEPARATES-- 468 When multiple ranges are requested, a server MAY coalesce any of the 469 ranges that overlap, or that are separated by a gap that is smaller 470 than the overhead of sending multiple parts, regardless of the order 471 in which the corresponding byte-range-spec appeared in the received 472 Range header field. Since the typical overhead between parts of a 473 multipart/byteranges payload is around 80 bytes, depending on the 474 selected representation's media type and the chosen boundary 475 parameter length, it can be less efficient to transfer many small 476 disjoint parts than it is to transfer the entire selected 477 representation. 479 A server MUST NOT generate a multipart response to a request for a 480 single range, since a client that does not request multiple parts 481 might not support multipart responses. However, a server MAY 482 generate a multipart/byteranges payload with only a single body part 483 if multiple ranges were requested and only one range was found to be 484 satisfiable or only one range remained after coalescing. A client 485 that cannot process a multipart/byteranges response MUST NOT generate 486 a request that asks for multiple ranges. 488 When a multipart response payload is generated, the server SHOULD 489 send the parts in the same order that the corresponding byte-range- 490 spec appeared in the received Range header field, excluding those 491 ranges that were deemed unsatisfiable or that were coalesced into 492 other ranges. A client that receives a multipart response MUST 493 inspect the Content-Range header field present in each body part in 494 order to determine which range is contained in that body part; a 495 client cannot rely on receiving the same ranges that it requested, 496 nor the same order that it requested. 498 When a 206 response is generated, the server MUST generate the 499 following header fields, in addition to those required above, if the 500 field would have been sent in a 200 (OK) response to the same 501 request: Date, Cache-Control, ETag, Expires, Content-Location, and 502 Vary. 504 If a 206 is generated in response to a request with an If-Range 505 header field, the sender SHOULD NOT generate other representation 506 header fields beyond those required above, because the client is 507 understood to already have a prior response containing those header 508 fields. Otherwise, the sender MUST generate all of the 509 representation header fields that would have been sent in a 200 (OK) 510 response to the same request. 512 A 206 response is cacheable by default; i.e., unless otherwise 513 indicated by explicit cache controls (see Section 4.2.2 of 514 [CACHING]). 516 4.2. Content-Range 518 The "Content-Range" header field is sent in a single part 206 519 (Partial Content) response to indicate the partial range of the 520 selected representation enclosed as the message payload, sent in each 521 part of a multipart 206 response to indicate the range enclosed 522 within each body part, and sent in 416 (Range Not Satisfiable) 523 responses to provide information about the selected representation. 525 Content-Range = byte-content-range 526 / other-content-range 528 byte-content-range = bytes-unit SP 529 ( byte-range-resp / unsatisfied-range ) 531 byte-range-resp = byte-range "/" ( complete-length / "*" ) 532 byte-range = first-byte-pos "-" last-byte-pos 533 unsatisfied-range = "*/" complete-length 535 complete-length = 1*DIGIT 537 other-content-range = other-range-unit SP other-range-resp 538 other-range-resp = *CHAR 540 If a 206 (Partial Content) response contains a Content-Range header 541 field with a range unit (Section 2) that the recipient does not 542 understand, the recipient MUST NOT attempt to recombine it with a 543 stored representation. A proxy that receives such a message SHOULD 544 forward it downstream. 546 For byte ranges, a sender SHOULD indicate the complete length of the 547 representation from which the range has been extracted, unless the 548 complete length is unknown or difficult to determine. An asterisk 549 character ("*") in place of the complete-length indicates that the 550 representation length was unknown when the header field was 551 generated. 553 The following example illustrates when the complete length of the 554 selected representation is known by the sender to be 1234 bytes: 556 Content-Range: bytes 42-1233/1234 558 and this second example illustrates when the complete length is 559 unknown: 561 Content-Range: bytes 42-1233/* 563 A Content-Range field value is invalid if it contains a byte-range- 564 resp that has a last-byte-pos value less than its first-byte-pos 565 value, or a complete-length value less than or equal to its last- 566 byte-pos value. The recipient of an invalid Content-Range MUST NOT 567 attempt to recombine the received content with a stored 568 representation. 570 A server generating a 416 (Range Not Satisfiable) response to a byte- 571 range request SHOULD send a Content-Range header field with an 572 unsatisfied-range value, as in the following example: 574 Content-Range: bytes */1234 576 The complete-length in a 416 response indicates the current length of 577 the selected representation. 579 The Content-Range header field has no meaning for status codes that 580 do not explicitly describe its semantic. For this specification, 581 only the 206 (Partial Content) and 416 (Range Not Satisfiable) status 582 codes describe a meaning for Content-Range. 584 The following are examples of Content-Range values in which the 585 selected representation contains a total of 1234 bytes: 587 o The first 500 bytes: 589 Content-Range: bytes 0-499/1234 591 o The second 500 bytes: 593 Content-Range: bytes 500-999/1234 595 o All except for the first 500 bytes: 597 Content-Range: bytes 500-1233/1234 599 o The last 500 bytes: 601 Content-Range: bytes 734-1233/1234 603 4.3. Combining Ranges 605 A response might transfer only a subrange of a representation if the 606 connection closed prematurely or if the request used one or more 607 Range specifications. After several such transfers, a client might 608 have received several ranges of the same representation. These 609 ranges can only be safely combined if they all have in common the 610 same strong validator (Section 2.1 of [CONDTNL]). 612 A client that has received multiple partial responses to GET requests 613 on a target resource MAY combine those responses into a larger 614 continuous range if they share the same strong validator. 616 If the most recent response is an incomplete 200 (OK) response, then 617 the header fields of that response are used for any combined response 618 and replace those of the matching stored responses. 620 If the most recent response is a 206 (Partial Content) response and 621 at least one of the matching stored responses is a 200 (OK), then the 622 combined response header fields consist of the most recent 200 623 response's header fields. If all of the matching stored responses 624 are 206 responses, then the stored response with the most recent 625 header fields is used as the source of header fields for the combined 626 response, except that the client MUST use other header fields 627 provided in the new response, aside from Content-Range, to replace 628 all instances of the corresponding header fields in the stored 629 response. 631 The combined response message body consists of the union of partial 632 content ranges in the new response and each of the selected 633 responses. If the union consists of the entire range of the 634 representation, then the client MUST process the combined response as 635 if it were a complete 200 (OK) response, including a Content-Length 636 header field that reflects the complete length. Otherwise, the 637 client MUST process the set of continuous ranges as one of the 638 following: an incomplete 200 (OK) response if the combined response 639 is a prefix of the representation, a single 206 (Partial Content) 640 response containing a multipart/byteranges body, or multiple 206 641 (Partial Content) responses, each with one continuous range that is 642 indicated by a Content-Range header field. 644 4.4. 416 Range Not Satisfiable 646 The 416 (Range Not Satisfiable) status code indicates that none of 647 the ranges in the request's Range header field (Section 3.1) overlap 648 the current extent of the selected resource or that the set of ranges 649 requested has been rejected due to invalid ranges or an excessive 650 request of small or overlapping ranges. 652 For byte ranges, failing to overlap the current extent means that the 653 first-byte-pos of all of the byte-range-spec values were greater than 654 the current length of the selected representation. When this status 655 code is generated in response to a byte-range request, the sender 656 SHOULD generate a Content-Range header field specifying the current 657 length of the selected representation (Section 4.2). 659 For example: 661 HTTP/1.1 416 Range Not Satisfiable 662 Date: Fri, 20 Jan 2012 15:41:54 GMT 663 Content-Range: bytes */47022 665 Note: Because servers are free to ignore Range, many 666 implementations will simply respond with the entire selected 667 representation in a 200 (OK) response. That is partly because 668 most clients are prepared to receive a 200 (OK) to complete the 669 task (albeit less efficiently) and partly because clients might 670 not stop making an invalid partial request until they have 671 received a complete representation. Thus, clients cannot depend 672 on receiving a 416 (Range Not Satisfiable) response even when it 673 is most appropriate. 675 5. IANA Considerations 677 5.1. Range Unit Registry 679 The "HTTP Range Unit Registry" defines the namespace for the range 680 unit names and refers to their corresponding specifications. The 681 registry has been created and is now maintained at 682 . 684 5.1.1. Procedure 686 Registration of an HTTP Range Unit MUST include the following fields: 688 o Name 690 o Description 692 o Pointer to specification text 694 Values to be added to this namespace require IETF Review (see 695 [RFC5226], Section 4.1). 697 5.1.2. Registrations 699 The initial range unit registry contains the registrations below: 701 +-------------+-----------------------------------------+-----------+ 702 | Range Unit | Description | Reference | 703 | Name | | | 704 +-------------+-----------------------------------------+-----------+ 705 | bytes | a range of octets | Section 2 | 706 | | | .1 | 707 | none | reserved as keyword, indicating no | Section 2 | 708 | | ranges are supported | .3 | 709 +-------------+-----------------------------------------+-----------+ 711 The change controller is: "IETF (iesg@ietf.org) - Internet 712 Engineering Task Force". 714 5.2. Status Code Registration 716 The "Hypertext Transfer Protocol (HTTP) Status Code Registry" located 717 at has been 718 updated to include the registrations below: 720 +-------+-----------------------+--------------+ 721 | Value | Description | Reference | 722 +-------+-----------------------+--------------+ 723 | 206 | Partial Content | Section 4.1 | 724 | 416 | Range Not Satisfiable | Section 4.4 | 725 +-------+-----------------------+--------------+ 727 5.3. Header Field Registration 729 HTTP header fields are registered within the "Message Headers" 730 registry maintained at . 733 This document defines the following HTTP header fields, so their 734 associated registry entries have been updated according to the 735 permanent registrations below (see [BCP90]): 737 +-------------------+----------+----------+--------------+ 738 | Header Field Name | Protocol | Status | Reference | 739 +-------------------+----------+----------+--------------+ 740 | Accept-Ranges | http | standard | Section 2.3 | 741 | Content-Range | http | standard | Section 4.2 | 742 | If-Range | http | standard | Section 3.2 | 743 | Range | http | standard | Section 3.1 | 744 +-------------------+----------+----------+--------------+ 746 The change controller is: "IETF (iesg@ietf.org) - Internet 747 Engineering Task Force". 749 5.4. Internet Media Type Registration 751 IANA maintains the registry of Internet media types [BCP13] at 752 . 754 This document serves as the specification for the Internet media type 755 "multipart/byteranges". The following has been registered with IANA. 757 5.4.1. Internet Media Type multipart/byteranges 759 Type name: multipart 761 Subtype name: byteranges 762 Required parameters: boundary 764 Optional parameters: N/A 766 Encoding considerations: only "7bit", "8bit", or "binary" are 767 permitted 769 Security considerations: see Section 6 771 Interoperability considerations: N/A 773 Published specification: This specification (see Appendix A). 775 Applications that use this media type: HTTP components supporting 776 multiple ranges in a single request. 778 Fragment identifier considerations: N/A 780 Additional information: 782 Deprecated alias names for this type: N/A 784 Magic number(s): N/A 786 File extension(s): N/A 788 Macintosh file type code(s): N/A 790 Person and email address to contact for further information: See Aut 791 hors' Addresses section. 793 Intended usage: COMMON 795 Restrictions on usage: N/A 797 Author: See Authors' Addresses section. 799 Change controller: IESG 801 6. Security Considerations 803 This section is meant to inform developers, information providers, 804 and users of known security concerns specific to the HTTP range 805 request mechanisms. More general security considerations are 806 addressed in HTTP messaging [MESSGNG] and semantics [SEMNTCS]. 808 6.1. Denial-of-Service Attacks Using Range 810 Unconstrained multiple range requests are susceptible to denial-of- 811 service attacks because the effort required to request many 812 overlapping ranges of the same data is tiny compared to the time, 813 memory, and bandwidth consumed by attempting to serve the requested 814 data in many parts. Servers ought to ignore, coalesce, or reject 815 egregious range requests, such as requests for more than two 816 overlapping ranges or for many small ranges in a single set, 817 particularly when the ranges are requested out of order for no 818 apparent reason. Multipart range requests are not designed to 819 support random access. 821 7. References 823 7.1. Normative References 825 [CACHING] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 826 Ed., "Hypertext Transfer Protocol (HTTP): Caching", draft- 827 fielding-httpbis-http-cache-00 (work in progress), March 828 2018. 830 [CONDTNL] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 831 Protocol (HTTP): Conditional Requests", draft-fielding- 832 httpbis-http-conditional-00 (work in progress), March 833 2018. 835 [MESSGNG] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 836 Protocol (HTTP/1.1): Message Syntax and Routing", draft- 837 fielding-httpbis-http-messaging-00 (work in progress), 838 March 2018. 840 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 841 Extensions (MIME) Part Two: Media Types", RFC 2046, 842 DOI 10.17487/RFC2046, November 1996, 843 . 845 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 846 Requirement Levels", BCP 14, RFC 2119, 847 DOI 10.17487/RFC2119, March 1997, 848 . 850 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 851 Specifications: ABNF", STD 68, RFC 5234, 852 DOI 10.17487/RFC5234, January 2008, 853 . 855 [SEMNTCS] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 856 Protocol (HTTP): Semantics and Content", draft-fielding- 857 httpbis-http-semantics-00 (work in progress), March 2018. 859 7.2. Informative References 861 [BCP13] Freed, N., Klensin, J., and T. Hansen, "Media Type 862 Specifications and Registration Procedures", BCP 13, 863 RFC 6838, January 2013, 864 . 866 [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration 867 Procedures for Message Header Fields", BCP 90, RFC 3864, 868 September 2004, . 870 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 871 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 872 DOI 10.17487/RFC5226, May 2008, 873 . 875 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 876 "Hypertext Transfer Protocol (HTTP): Range Requests", 877 RFC 7233, DOI 10.17487/RFC7233, June 2014, 878 . 880 Appendix A. Internet Media Type multipart/byteranges 882 When a 206 (Partial Content) response message includes the content of 883 multiple ranges, they are transmitted as body parts in a multipart 884 message body ([RFC2046], Section 5.1) with the media type of 885 "multipart/byteranges". 887 The multipart/byteranges media type includes one or more body parts, 888 each with its own Content-Type and Content-Range fields. The 889 required boundary parameter specifies the boundary string used to 890 separate each body part. 892 Implementation Notes: 894 1. Additional CRLFs might precede the first boundary string in the 895 body. 897 2. Although [RFC2046] permits the boundary string to be quoted, some 898 existing implementations handle a quoted boundary string 899 incorrectly. 901 3. A number of clients and servers were coded to an early draft of 902 the byteranges specification that used a media type of multipart/ 903 x-byteranges, which is almost (but not quite) compatible with 904 this type. 906 Despite the name, the "multipart/byteranges" media type is not 907 limited to byte ranges. The following example uses an "exampleunit" 908 range unit: 910 HTTP/1.1 206 Partial Content 911 Date: Tue, 14 Nov 1995 06:25:24 GMT 912 Last-Modified: Tue, 14 July 04:58:08 GMT 913 Content-Length: 2331785 914 Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 916 --THIS_STRING_SEPARATES 917 Content-Type: video/example 918 Content-Range: exampleunit 1.2-4.3/25 920 ...the first range... 921 --THIS_STRING_SEPARATES 922 Content-Type: video/example 923 Content-Range: exampleunit 11.2-14.3/25 925 ...the second range 926 --THIS_STRING_SEPARATES-- 928 Appendix B. Changes from RFC 7233 930 None yet. 932 Appendix C. Imported ABNF 934 The following core rules are included by reference, as defined in 935 Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), 936 CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double 937 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 938 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII 939 character). 941 Note that all rules derived from token are to be compared case- 942 insensitively, like range-unit and acceptable-ranges. 944 The rules below are defined in [MESSGNG]: 946 OWS = 947 token = 949 The rules below are defined in other parts: 951 HTTP-date = 952 entity-tag = 954 Appendix D. Collected ABNF 956 In the collected ABNF below, list rules are expanded as per 957 Section 1.2 of [MESSGNG]. 959 Accept-Ranges = acceptable-ranges 961 Content-Range = byte-content-range / other-content-range 963 HTTP-date = 965 If-Range = entity-tag / HTTP-date 967 OWS = 969 Range = byte-ranges-specifier / other-ranges-specifier 971 acceptable-ranges = ( *( "," OWS ) range-unit *( OWS "," [ OWS 972 range-unit ] ) ) / "none" 974 byte-content-range = bytes-unit SP ( byte-range-resp / 975 unsatisfied-range ) 976 byte-range = first-byte-pos "-" last-byte-pos 977 byte-range-resp = byte-range "/" ( complete-length / "*" ) 978 byte-range-set = *( "," OWS ) ( byte-range-spec / 979 suffix-byte-range-spec ) *( OWS "," [ OWS ( byte-range-spec / 980 suffix-byte-range-spec ) ] ) 981 byte-range-spec = first-byte-pos "-" [ last-byte-pos ] 982 byte-ranges-specifier = bytes-unit "=" byte-range-set 983 bytes-unit = "bytes" 985 complete-length = 1*DIGIT 987 entity-tag = 989 first-byte-pos = 1*DIGIT 991 last-byte-pos = 1*DIGIT 993 other-content-range = other-range-unit SP other-range-resp 994 other-range-resp = *CHAR 995 other-range-set = 1*VCHAR 996 other-range-unit = token 997 other-ranges-specifier = other-range-unit "=" other-range-set 999 range-unit = bytes-unit / other-range-unit 1001 suffix-byte-range-spec = "-" suffix-length 1002 suffix-length = 1*DIGIT 1004 token = 1006 unsatisfied-range = "*/" complete-length 1008 Appendix E. Change Log 1010 This section is to be removed before publishing as an RFC. 1012 E.1. Since RFC 7233 1014 The changes in this draft are purely editorial: 1016 o Change boilerplate and abstract to indicate the "draft" status, 1017 and update references to ancestor specifications. 1019 o Remove version "1.1" from document title, indicating that this 1020 specification applies to all HTTP versions. 1022 o Adjust historical notes. 1024 o Update links to sibling specifications. 1026 o Replace sections listing changes from RFC 2616 by new empty 1027 sections referring to RFC 723x. 1029 o Remove acknowledgements specific to RFC 723x. 1031 o Move "Acknowledgements" to the very end and make them unnumbered. 1033 Index 1035 2 1036 206 Partial Content (status code) 9 1038 4 1039 416 Range Not Satisfiable (status code) 14 1041 A 1042 Accept-Ranges header field 6 1044 C 1045 Content-Range header field 11 1047 G 1048 Grammar 1049 Accept-Ranges 6 1050 acceptable-ranges 6 1051 byte-content-range 12 1052 byte-range 12 1053 byte-range-resp 12 1054 byte-range-set 5 1055 byte-range-spec 5 1056 byte-ranges-specifier 5 1057 bytes-unit 4 1058 complete-length 12 1059 Content-Range 12 1060 first-byte-pos 5 1061 If-Range 8 1062 last-byte-pos 5 1063 other-content-range 12 1064 other-range-resp 12 1065 other-range-unit 4, 6 1066 Range 7 1067 range-unit 4 1068 ranges-specifier 5 1069 suffix-byte-range-spec 5 1070 suffix-length 5 1071 unsatisfied-range 12 1073 I 1074 If-Range header field 8 1076 M 1077 Media Type 1078 multipart/byteranges 16, 20 1079 multipart/x-byteranges 20 1080 multipart/byteranges Media Type 16, 20 1081 multipart/x-byteranges Media Type 20 1083 R 1084 Range header field 7 1086 Acknowledgments 1088 See Appendix "Acknowledgments" of [MESSGNG]. 1090 Authors' Addresses 1092 Roy T. Fielding (editor) 1093 Adobe Systems Incorporated 1094 345 Park Ave 1095 San Jose, CA 95110 1096 USA 1098 EMail: fielding@gbiv.com 1099 URI: http://roy.gbiv.com/ 1100 Yves Lafon (editor) 1101 World Wide Web Consortium 1102 W3C / ERCIM 1103 2004, rte des Lucioles 1104 Sophia-Antipolis, AM 06902 1105 France 1107 EMail: ylafon@w3.org 1108 URI: http://www.raubacapeu.net/people/yves/ 1110 Julian F. Reschke (editor) 1111 greenbytes GmbH 1112 Hafenweg 16 1113 Muenster, NW 48155 1114 Germany 1116 EMail: julian.reschke@greenbytes.de 1117 URI: http://greenbytes.de/tech/webdav/