idnits 2.17.1 draft-ietf-httpbis-p5-range-20.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 : ---------------------------------------------------------------------------- -- The draft header indicates that this document obsoletes RFC2616, but the abstract doesn't seem to mention this, which it should. 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, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, 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 (July 16, 2012) is 4302 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: 'Part2' is defined on line 740, but no explicit reference was found in the text == Unused Reference: 'RFC2616' is defined on line 767, but no explicit reference was found in the text == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-20 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-20 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-20 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-20 -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 4288 (Obsoleted by RFC 6838) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 0 errors (**), 0 flaws (~~), 7 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPbis Working Group R. Fielding, Ed. 3 Internet-Draft Adobe 4 Obsoletes: 2616 (if approved) Y. Lafon, Ed. 5 Intended status: Standards Track W3C 6 Expires: January 17, 2013 J. Reschke, Ed. 7 greenbytes 8 July 16, 2012 10 HTTP/1.1, part 5: Range Requests 11 draft-ietf-httpbis-p5-range-20 13 Abstract 15 The Hypertext Transfer Protocol (HTTP) is an application-level 16 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 Editorial Note (To be removed by RFC Editor) 22 Discussion of this draft takes place on the HTTPBIS working group 23 mailing list (ietf-http-wg@w3.org), which is archived at 24 . 26 The current issues list is at 27 and related 28 documents (including fancy diffs) can be found at 29 . 31 The changes in this draft are summarized in Appendix E.1. 33 Status of This Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at http://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on January 17, 2013. 50 Copyright Notice 52 Copyright (c) 2012 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 This document may contain material from IETF Documents or IETF 66 Contributions published or made publicly available before November 67 10, 2008. The person(s) controlling the copyright in some of this 68 material may not have granted the IETF Trust the right to allow 69 modifications of such material outside the IETF Standards Process. 70 Without obtaining an adequate license from the person(s) controlling 71 the copyright in such materials, this document may not be modified 72 outside the IETF Standards Process, and derivative works of it may 73 not be created outside the IETF Standards Process, except to format 74 it for publication as an RFC or to translate it into languages other 75 than English. 77 Table of Contents 79 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 80 1.1. Conformance and Error Handling . . . . . . . . . . . . . . 4 81 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 5 82 2. Range Units . . . . . . . . . . . . . . . . . . . . . . . . . 5 83 2.1. Range Specifier Registry . . . . . . . . . . . . . . . . . 6 84 3. Status Code Definitions . . . . . . . . . . . . . . . . . . . 6 85 3.1. 206 Partial Content . . . . . . . . . . . . . . . . . . . 6 86 3.2. 416 Requested Range Not Satisfiable . . . . . . . . . . . 7 87 4. Responses to a Range Request . . . . . . . . . . . . . . . . . 7 88 4.1. Response to a Single and Multiple Ranges Request . . . . . 7 89 4.2. Combining Ranges . . . . . . . . . . . . . . . . . . . . . 8 90 5. Header Field Definitions . . . . . . . . . . . . . . . . . . . 9 91 5.1. Accept-Ranges . . . . . . . . . . . . . . . . . . . . . . 9 92 5.2. Content-Range . . . . . . . . . . . . . . . . . . . . . . 10 93 5.3. If-Range . . . . . . . . . . . . . . . . . . . . . . . . . 11 94 5.4. Range . . . . . . . . . . . . . . . . . . . . . . . . . . 12 95 5.4.1. Byte Ranges . . . . . . . . . . . . . . . . . . . . . 12 96 5.4.2. Range Retrieval Requests . . . . . . . . . . . . . . . 14 97 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 98 6.1. Status Code Registration . . . . . . . . . . . . . . . . . 15 99 6.2. Header Field Registration . . . . . . . . . . . . . . . . 15 100 6.3. Range Specifier Registration . . . . . . . . . . . . . . . 16 101 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16 102 7.1. Overlapping Ranges . . . . . . . . . . . . . . . . . . . . 16 103 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 104 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 105 9.1. Normative References . . . . . . . . . . . . . . . . . . . 16 106 9.2. Informative References . . . . . . . . . . . . . . . . . . 17 107 Appendix A. Internet Media Type multipart/byteranges . . . . . . 18 108 Appendix B. Changes from RFC 2616 . . . . . . . . . . . . . . . . 20 109 Appendix C. Imported ABNF . . . . . . . . . . . . . . . . . . . . 20 110 Appendix D. Collected ABNF . . . . . . . . . . . . . . . . . . . 21 111 Appendix E. Change Log (to be removed by RFC Editor before 112 publication) . . . . . . . . . . . . . . . . . . . . 22 113 E.1. Since draft-ietf-httpbis-p5-range-19 . . . . . . . . . . . 22 114 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 116 1. Introduction 118 HTTP clients often encounter interrupted data transfers as a result 119 of canceled requests or dropped connections. When a client has 120 stored a partial representation, it is desirable to request the 121 remainder of that representation in a subsequent request rather than 122 transfer the entire representation. There are also a number of Web 123 applications that benefit from being able to request only a subset of 124 a larger representation, such as a single page of a very large 125 document or only part of an image to be rendered by a device with 126 limited local storage. 128 This document defines HTTP/1.1 range requests, partial responses, and 129 the multipart/byteranges media type. The protocol for range requests 130 is an OPTIONAL feature of HTTP, designed so resources or recipients 131 that do not implement this feature can respond as if it is a normal 132 GET request without impacting interoperability. Partial responses 133 are indicated by a distinct status code to not be mistaken for full 134 responses by intermediate caches that might not implement the 135 feature. 137 Although the HTTP range request mechanism is designed to allow for 138 extensible range types, this specification only defines requests for 139 byte ranges. 141 1.1. Conformance and Error Handling 143 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 144 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 145 document are to be interpreted as described in [RFC2119]. 147 This specification targets conformance criteria according to the role 148 of a participant in HTTP communication. Hence, HTTP requirements are 149 placed on senders, recipients, clients, servers, user agents, 150 intermediaries, origin servers, proxies, gateways, or caches, 151 depending on what behavior is being constrained by the requirement. 152 See Section 2 of [Part1] for definitions of these terms. 154 The verb "generate" is used instead of "send" where a requirement 155 differentiates between creating a protocol element and merely 156 forwarding a received element downstream. 158 An implementation is considered conformant if it complies with all of 159 the requirements associated with the roles it partakes in HTTP. Note 160 that SHOULD-level requirements are relevant here, unless one of the 161 documented exceptions is applicable. 163 This document also uses ABNF to define valid protocol elements 164 (Section 1.2). In addition to the prose requirements placed upon 165 them, senders MUST NOT generate protocol elements that do not match 166 the grammar defined by the ABNF rules for those protocol elements 167 that are applicable to the sender's role. If a received protocol 168 element is processed, the recipient MUST be able to parse any value 169 that would match the ABNF rules for that protocol element, excluding 170 only those rules not applicable to the recipient's role. 172 Unless noted otherwise, a recipient MAY attempt to recover a usable 173 protocol element from an invalid construct. HTTP does not define 174 specific error handling mechanisms except when they have a direct 175 impact on security, since different applications of the protocol 176 require different error handling strategies. For example, a Web 177 browser might wish to transparently recover from a response where the 178 Location header field doesn't parse according to the ABNF, whereas a 179 systems control client might consider any form of error recovery to 180 be dangerous. 182 1.2. Syntax Notation 184 This specification uses the Augmented Backus-Naur Form (ABNF) 185 notation of [RFC5234] with the list rule extension defined in Section 186 1.2 of [Part1]. Appendix C describes rules imported from other 187 documents. Appendix D shows the collected ABNF with the list rule 188 expanded. 190 2. Range Units 192 HTTP/1.1 allows a client to request that only part (a range) of the 193 representation be included within the response. HTTP/1.1 uses range 194 units in the Range (Section 5.4) and Content-Range (Section 5.2) 195 header fields. A representation can be broken down into subranges 196 according to various structural units. 198 range-unit = bytes-unit / other-range-unit 199 bytes-unit = "bytes" 200 other-range-unit = token 202 HTTP/1.1 has been designed to allow implementations of applications 203 that do not depend on knowledge of ranges. The only range unit 204 defined by HTTP/1.1 is "bytes". Additional specifiers can be defined 205 as described in Section 2.1. 207 If a range unit is not understood in a request, a server MUST ignore 208 the whole Range header field (Section 5.4). If a range unit is not 209 understood in a response, an intermediary SHOULD pass the response to 210 the client; a client MUST fail. 212 2.1. Range Specifier Registry 214 The HTTP Range Specifier Registry defines the name space for the 215 range specifier names. 217 Registrations MUST include the following fields: 219 o Name 221 o Description 223 o Pointer to specification text 225 Values to be added to this name space require IETF Review (see 226 [RFC5226], Section 4.1). 228 The registry itself is maintained at 229 . 231 3. Status Code Definitions 233 3.1. 206 Partial Content 235 The server has fulfilled the partial GET request for the resource. 236 The request MUST have included a Range header field (Section 5.4) 237 indicating the desired range, and MAY have included an If-Range 238 header field (Section 5.3) to make the request conditional. 240 The response MUST include the following header fields: 242 o Either a Content-Range header field (Section 5.2) indicating the 243 range included with this response, or a multipart/byteranges 244 Content-Type including Content-Range fields for each part. If a 245 Content-Length header field is present in the response, its value 246 MUST match the actual number of octets transmitted in the message 247 body. 249 o Date 251 o Cache-Control, ETag, Expires, Content-Location and/or Vary, if the 252 header field would have been sent in a 200 (OK) response to the 253 same request 255 If a 206 is sent in response to a request with an If-Range header 256 field, it SHOULD NOT include other representation header fields. 257 Otherwise, the response MUST include all of the representation header 258 fields that would have been returned with a 200 (OK) response to the 259 same request. 261 Caches MAY use a heuristic (see Section 4.1.2 of [Part6]) to 262 determine freshness for 206 responses. 264 3.2. 416 Requested Range Not Satisfiable 266 A server SHOULD return a response with this status code if a request 267 included a Range header field (Section 5.4), and none of the ranges- 268 specifier values in this field overlap the current extent of the 269 selected resource, and the request did not include an If-Range header 270 field (Section 5.3). (For byte-ranges, this means that the first- 271 byte-pos of all of the byte-range-spec values were greater than the 272 current length of the selected resource.) 274 When this status code is returned for a byte-range request, the 275 response SHOULD include a Content-Range header field specifying the 276 current length of the representation (see Section 5.2). This 277 response MUST NOT use the multipart/byteranges content-type. For 278 example, 280 HTTP/1.1 416 Requested Range Not Satisfiable 281 Date: Mon, 20 Jan 2012 15:41:54 GMT 282 Content-Range: bytes */47022 283 Content-Type: image/gif 285 Note: Clients cannot depend on servers to send a 416 (Requested 286 Range Not Satisfiable) response instead of a 200 (OK) response for 287 an unsatisfiable Range header field, since not all servers 288 implement this header field. 290 4. Responses to a Range Request 292 4.1. Response to a Single and Multiple Ranges Request 294 When an HTTP message includes the content of a single range (for 295 example, a response to a request for a single range, or to a request 296 for a set of ranges that overlap without any holes), this content is 297 transmitted with a Content-Range header field, and a Content-Length 298 header field showing the number of bytes actually transferred. For 299 example, 301 HTTP/1.1 206 Partial Content 302 Date: Wed, 15 Nov 1995 06:25:24 GMT 303 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 304 Content-Range: bytes 21010-47021/47022 305 Content-Length: 26012 306 Content-Type: image/gif 308 When an HTTP message includes the content of multiple ranges (for 309 example, a response to a request for multiple non-overlapping 310 ranges), these are transmitted as a multipart message. The multipart 311 media type used for this purpose is "multipart/byteranges" as defined 312 in Appendix A. 314 A server MAY combine requested ranges when those ranges are 315 overlapping (see Section 7.1). 317 A response to a request for a single range MUST NOT be sent using the 318 multipart/byteranges media type. A response to a request for 319 multiple ranges, whose result is a single range, MAY be sent as a 320 multipart/byteranges media type with one part. A client that cannot 321 decode a multipart/byteranges message MUST NOT ask for multiple 322 ranges in a single request. 324 When a client asks for multiple ranges in one request, the server 325 SHOULD return them in the order that they appeared in the request. 327 4.2. Combining Ranges 329 A response might transfer only a subrange of a representation if the 330 connection closed prematurely or if the request used one or more 331 Range specifications. After several such transfers, a client might 332 have received several ranges of the same representation. These 333 ranges can only be safely combined if they all have in common the 334 same strong validator, where "strong validator" is defined to be 335 either an entity-tag that is not marked as weak (Section 2.3 of 336 [Part4]) or, if no entity-tag is provided, a Last-Modified value that 337 is strong in the sense defined by Section 2.2.2 of [Part4]. 339 When a client receives an incomplete 200 (OK) or 206 (Partial 340 Content) response and already has one or more stored responses for 341 the same method and effective request URI, all of the stored 342 responses with the same strong validator MAY be combined with the 343 partial content in this new response. If none of the stored 344 responses contain the same strong validator, then this new response 345 corresponds to a new representation and MUST NOT be combined with the 346 existing stored responses. 348 If the new response is an incomplete 200 (OK) response, then the 349 header fields of that new response are used for any combined response 350 and replace those of the matching stored responses. 352 If the new response is a 206 (Partial Content) response and at least 353 one of the matching stored responses is a 200 (OK), then the combined 354 response header fields consist of the most recent 200 response's 355 header fields. If all of the matching stored responses are 206 356 responses, then the stored response with the most header fields is 357 used as the source of header fields for the combined response, except 358 that the client MUST use other header fields provided in the new 359 response, aside from Content-Range, to replace all instances of the 360 corresponding header fields in the stored response. 362 The combined response message body consists of the union of partial 363 content ranges in the new response and each of the selected 364 responses. If the union consists of the entire range of the 365 representation, then the combined response MUST be recorded as a 366 complete 200 (OK) response with a Content-Length header field that 367 reflects the complete length. Otherwise, the combined response(s) 368 MUST include a Content-Range header field describing the included 369 range(s) and be recorded as incomplete. If the union consists of a 370 discontinuous range of the representation, then the client MAY store 371 it as either a multipart range response or as multiple 206 responses 372 with one continuous range each. 374 5. Header Field Definitions 376 This section defines the syntax and semantics of HTTP/1.1 header 377 fields related to range requests and partial responses. 379 5.1. Accept-Ranges 381 The "Accept-Ranges" header field allows a resource to indicate its 382 acceptance of range requests. 384 Accept-Ranges = acceptable-ranges 385 acceptable-ranges = 1#range-unit / "none" 387 Origin servers that accept byte-range requests MAY send 389 Accept-Ranges: bytes 391 but are not required to do so. Clients MAY generate range requests 392 without having received this header field for the resource involved. 393 Range units are defined in Section 2. 395 Servers that do not accept any kind of range request for a resource 396 MAY send 398 Accept-Ranges: none 400 to advise the client not to attempt a range request. 402 5.2. Content-Range 404 The "Content-Range" header field is sent with a partial 405 representation to specify where in the full representation the 406 payload body is intended to be applied. 408 Range units are defined in Section 2. 410 Content-Range = byte-content-range-spec 411 / other-content-range-spec 413 byte-content-range-spec = bytes-unit SP 414 byte-range-resp-spec "/" 415 ( instance-length / "*" ) 417 byte-range-resp-spec = (first-byte-pos "-" last-byte-pos) 418 / "*" 420 instance-length = 1*DIGIT 422 other-content-range-spec = other-range-unit SP 423 other-range-resp-spec 424 other-range-resp-spec = *CHAR 426 The header field SHOULD indicate the total length of the full 427 representation, unless this length is unknown or difficult to 428 determine. The asterisk "*" character means that the instance-length 429 is unknown at the time when the response was generated. 431 Unlike byte-ranges-specifier values (see Section 5.4.1), a byte- 432 range-resp-spec MUST only specify one range, and MUST contain 433 absolute byte positions for both the first and last byte of the 434 range. 436 A byte-content-range-spec with a byte-range-resp-spec whose last- 437 byte-pos value is less than its first-byte-pos value, or whose 438 instance-length value is less than or equal to its last-byte-pos 439 value, is invalid. The recipient of an invalid byte-content-range- 440 spec MUST ignore it and any content transferred along with it. 442 In the case of a byte range request: A server sending a response with 443 status code 416 (Requested Range Not Satisfiable) SHOULD include a 444 Content-Range field with a byte-range-resp-spec of "*". The 445 instance-length specifies the current length of the selected 446 resource. A response with status code 206 (Partial Content) MUST NOT 447 include a Content-Range field with a byte-range-resp-spec of "*". 449 The "Content-Range" header field has no meaning for status codes that 450 do not explicitly describe its semantic. Currently, only status 451 codes 206 (Partial Content) and 416 (Requested Range Not Satisfiable) 452 describe the meaning of this header field. 454 Examples of byte-content-range-spec values, assuming that the 455 representation contains a total of 1234 bytes: 457 o The first 500 bytes: 459 bytes 0-499/1234 461 o The second 500 bytes: 463 bytes 500-999/1234 465 o All except for the first 500 bytes: 467 bytes 500-1233/1234 469 o The last 500 bytes: 471 bytes 734-1233/1234 473 If the server ignores a byte-range-spec (for example if it is 474 syntactically invalid, or if it might be seen as a denial-of-service 475 attack), the server SHOULD treat the request as if the invalid Range 476 header field did not exist. (Normally, this means return a 200 (OK) 477 response containing the full representation). 479 5.3. If-Range 481 If a client has a partial copy of a representation and wishes to have 482 an up-to-date copy of the entire representation, it could use the 483 Range header field with a conditional GET (using either or both of 484 If-Unmodified-Since and If-Match.) However, if the condition fails 485 because the representation has been modified, the client would then 486 have to make a second request to obtain the entire current 487 representation. 489 The "If-Range" header field allows a client to "short-circuit" the 490 second request. Informally, its meaning is "if the representation is 491 unchanged, send me the part(s) that I am missing; otherwise, send me 492 the entire new representation". 494 If-Range = entity-tag / HTTP-date 496 Clients MUST NOT use an entity-tag marked as weak in an If-Range 497 field value and MUST NOT use a Last-Modified date in an If-Range 498 field value unless it has no entity-tag for the representation and 499 the Last-Modified date it does have for the representation is strong 500 in the sense defined by Section 2.2.2 of [Part4]. 502 A server that evaluates a conditional range request that is 503 applicable to one of its representations MUST evaluate the condition 504 as false if the entity-tag used as a validator is marked as weak or, 505 when an HTTP-date is used as the validator, if the date value is not 506 strong in the sense defined by Section 2.2.2 of [Part4]. (A server 507 can distinguish between a valid HTTP-date and any form of entity-tag 508 by examining the first two characters.) 510 The If-Range header field SHOULD only be sent by clients together 511 with a Range header field. The If-Range header field MUST be ignored 512 if it is received in a request that does not include a Range header 513 field. The If-Range header field MUST be ignored by a server that 514 does not support the sub-range operation. 516 If the validator given in the If-Range header field matches the 517 current validator for the selected representation of the target 518 resource, then the server SHOULD send the specified sub-range of the 519 representation using a 206 (Partial Content) response. If the 520 validator does not match, then the server SHOULD send the entire 521 representation using a 200 (OK) response. 523 5.4. Range 525 5.4.1. Byte Ranges 527 Since all HTTP representations are transferred as sequences of bytes, 528 the concept of a byte range is meaningful for any HTTP 529 representation. (However, not all clients and servers need to 530 support byte-range operations.) 532 Byte range specifications in HTTP apply to the sequence of bytes in 533 the representation body (not necessarily the same as the message 534 body). 536 A byte range operation MAY specify a single range of bytes, or a set 537 of ranges within a single representation. 539 byte-ranges-specifier = bytes-unit "=" byte-range-set 540 byte-range-set = 1#( byte-range-spec / suffix-byte-range-spec ) 541 byte-range-spec = first-byte-pos "-" [ last-byte-pos ] 542 first-byte-pos = 1*DIGIT 543 last-byte-pos = 1*DIGIT 545 The first-byte-pos value in a byte-range-spec gives the byte-offset 546 of the first byte in a range. The last-byte-pos value gives the 547 byte-offset of the last byte in the range; that is, the byte 548 positions specified are inclusive. Byte offsets start at zero. 550 If the last-byte-pos value is present, it MUST be greater than or 551 equal to the first-byte-pos in that byte-range-spec, or the byte- 552 range-spec is syntactically invalid. The recipient of a byte-range- 553 set that includes one or more syntactically invalid byte-range-spec 554 values MUST ignore the header field that includes that byte-range- 555 set. 557 If the last-byte-pos value is absent, or if the value is greater than 558 or equal to the current length of the representation body, last-byte- 559 pos is taken to be equal to one less than the current length of the 560 representation in bytes. 562 By its choice of last-byte-pos, a client can limit the number of 563 bytes retrieved without knowing the size of the representation. 565 suffix-byte-range-spec = "-" suffix-length 566 suffix-length = 1*DIGIT 568 A suffix-byte-range-spec is used to specify the suffix of the 569 representation body, of a length given by the suffix-length value. 570 (That is, this form specifies the last N bytes of a representation.) 571 If the representation is shorter than the specified suffix-length, 572 the entire representation is used. 574 If a syntactically valid byte-range-set includes at least one byte- 575 range-spec whose first-byte-pos is less than the current length of 576 the representation, or at least one suffix-byte-range-spec with a 577 non-zero suffix-length, then the byte-range-set is satisfiable. 578 Otherwise, the byte-range-set is unsatisfiable. If the byte-range- 579 set is unsatisfiable, the server SHOULD return a response with a 416 580 (Requested Range Not Satisfiable) status code. Otherwise, the server 581 SHOULD return a response with a 206 (Partial Content) status code 582 containing the satisfiable ranges of the representation. 584 In the byte range syntax, first-byte-pos, last-byte-pos, and suffix- 585 length are expressed as decimal number of octets. Since there is no 586 predefined limit to the length of an HTTP payload, recipients SHOULD 587 anticipate potentially large decimal numerals and prevent parsing 588 errors due to integer conversion overflows. 590 Examples of byte-ranges-specifier values (assuming a representation 591 of length 10000): 593 o The first 500 bytes (byte offsets 0-499, inclusive): 595 bytes=0-499 597 o The second 500 bytes (byte offsets 500-999, inclusive): 599 bytes=500-999 601 o The final 500 bytes (byte offsets 9500-9999, inclusive): 603 bytes=-500 605 Or: 607 bytes=9500- 609 o The first and last bytes only (bytes 0 and 9999): 611 bytes=0-0,-1 613 o Several legal but not canonical specifications of the second 500 614 bytes (byte offsets 500-999, inclusive): 616 bytes=500-600,601-999 617 bytes=500-700,601-999 619 5.4.2. Range Retrieval Requests 621 The "Range" header field defines the GET method (conditional or not) 622 to request one or more sub-ranges of the response representation 623 body, instead of the entire representation body. 625 Range = byte-ranges-specifier / other-ranges-specifier 626 other-ranges-specifier = other-range-unit "=" other-range-set 627 other-range-set = 1*CHAR 629 A server MAY ignore the Range header field. However, origin servers 630 and intermediate caches ought to support byte ranges when possible, 631 since Range supports efficient recovery from partially failed 632 transfers, and supports efficient partial retrieval of large 633 representations. 635 If the server supports the Range header field and the specified range 636 or ranges are appropriate for the representation: 638 o The presence of a Range header field in an unconditional GET 639 modifies what is returned if the GET is otherwise successful. In 640 other words, the response carries a status code of 206 (Partial 641 Content) instead of 200 (OK). 643 o The presence of a Range header field in a conditional GET (a 644 request using one or both of If-Modified-Since and If-None-Match, 645 or one or both of If-Unmodified-Since and If-Match) modifies what 646 is returned if the GET is otherwise successful and the condition 647 is true. It does not affect the 304 (Not Modified) response 648 returned if the conditional is false. 650 In some cases, it might be more appropriate to use the If-Range 651 header field (see Section 5.3) in addition to the Range header field. 653 If a proxy that supports ranges receives a Range request, forwards 654 the request to an inbound server, and receives an entire 655 representation in reply, it MAY only return the requested range to 656 its client. 658 6. IANA Considerations 660 6.1. Status Code Registration 662 The HTTP Status Code Registry located at 663 shall be updated 664 with the registrations below: 666 +-------+---------------------------------+-------------+ 667 | Value | Description | Reference | 668 +-------+---------------------------------+-------------+ 669 | 206 | Partial Content | Section 3.1 | 670 | 416 | Requested Range Not Satisfiable | Section 3.2 | 671 +-------+---------------------------------+-------------+ 673 6.2. Header Field Registration 675 The Message Header Field Registry located at shall be 677 updated with the permanent registrations below (see [RFC3864]): 679 +-------------------+----------+----------+-------------+ 680 | Header Field Name | Protocol | Status | Reference | 681 +-------------------+----------+----------+-------------+ 682 | Accept-Ranges | http | standard | Section 5.1 | 683 | Content-Range | http | standard | Section 5.2 | 684 | If-Range | http | standard | Section 5.3 | 685 | Range | http | standard | Section 5.4 | 686 +-------------------+----------+----------+-------------+ 688 The change controller is: "IETF (iesg@ietf.org) - Internet 689 Engineering Task Force". 691 6.3. Range Specifier Registration 693 The registration procedure for HTTP Range Specifiers is defined by 694 Section 2.1 of this document. 696 The HTTP Range Specifier Registry shall be created at 697 and be 698 populated with the registrations below: 700 +---------------+-------------------------------------+-------------+ 701 | Range | Description | Reference | 702 | Specifier | | | 703 | Name | | | 704 +---------------+-------------------------------------+-------------+ 705 | bytes | a range of octets | Section 2 | 706 | none | reserved as keyword, indicating no | Section 5.1 | 707 | | ranges are supported | | 708 +---------------+-------------------------------------+-------------+ 710 The change controller is: "IETF (iesg@ietf.org) - Internet 711 Engineering Task Force". 713 7. Security Considerations 715 This section is meant to inform application developers, information 716 providers, and users of the security limitations in HTTP/1.1 as 717 described by this document. The discussion does not include 718 definitive solutions to the problems revealed, though it does make 719 some suggestions for reducing security risks. 721 7.1. Overlapping Ranges 723 Range requests containing overlapping ranges can lead to the 724 situation where a server is sending far more data than the size of 725 the complete resource representation. 727 8. Acknowledgments 729 See Section 9 of [Part1]. 731 9. References 733 9.1. Normative References 735 [Part1] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 736 "HTTP/1.1, part 1: Message Routing and Syntax"", 737 draft-ietf-httpbis-p1-messaging-20 (work in progress), 738 July 2012. 740 [Part2] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 741 "HTTP/1.1, part 2: Semantics and Payloads", 742 draft-ietf-httpbis-p2-semantics-20 (work in progress), 743 July 2012. 745 [Part4] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 746 "HTTP/1.1, part 4: Conditional Requests", 747 draft-ietf-httpbis-p4-conditional-20 (work in progress), 748 July 2012. 750 [Part6] Fielding, R., Ed., Lafon, Y., Ed., Nottingham, M., Ed., 751 and J. Reschke, Ed., "HTTP/1.1, part 6: Caching", 752 draft-ietf-httpbis-p6-cache-20 (work in progress), 753 July 2012. 755 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 756 Extensions (MIME) Part Two: Media Types", RFC 2046, 757 November 1996. 759 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 760 Requirement Levels", BCP 14, RFC 2119, March 1997. 762 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 763 Specifications: ABNF", STD 68, RFC 5234, January 2008. 765 9.2. Informative References 767 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 768 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 769 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 771 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 772 Procedures for Message Header Fields", BCP 90, RFC 3864, 773 September 2004. 775 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 776 Registration Procedures", BCP 13, RFC 4288, December 2005. 778 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 779 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 780 May 2008. 782 Appendix A. Internet Media Type multipart/byteranges 784 When an HTTP 206 (Partial Content) response message includes the 785 content of multiple ranges (a response to a request for multiple non- 786 overlapping ranges), these are transmitted as a multipart message 787 body ([RFC2046], Section 5.1). The media type for this purpose is 788 called "multipart/byteranges". The following is to be registered 789 with IANA [RFC4288]. 791 The multipart/byteranges media type includes one or more parts, each 792 with its own Content-Type and Content-Range fields. The required 793 boundary parameter specifies the boundary string used to separate 794 each body-part. 796 Type name: multipart 798 Subtype name: byteranges 800 Required parameters: boundary 802 Optional parameters: none 804 Encoding considerations: only "7bit", "8bit", or "binary" are 805 permitted 807 Security considerations: none 809 Interoperability considerations: none 811 Published specification: This specification (see Appendix A). 813 Applications that use this media type: HTTP components supporting 814 multiple ranges in a single request. 816 Additional information: 818 Magic number(s): none 820 File extension(s): none 822 Macintosh file type code(s): none 824 Person and email address to contact for further information: See 825 Authors Section. 827 Intended usage: COMMON 829 Restrictions on usage: none 831 Author/Change controller: IESG 833 Note: Despite the name "multipart/byteranges" is not limited to 834 the byte ranges only. 836 For example: 838 HTTP/1.1 206 Partial Content 839 Date: Wed, 15 Nov 1995 06:25:24 GMT 840 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 841 Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 843 --THIS_STRING_SEPARATES 844 Content-type: application/pdf 845 Content-range: bytes 500-999/8000 847 ...the first range... 848 --THIS_STRING_SEPARATES 849 Content-type: application/pdf 850 Content-range: bytes 7000-7999/8000 852 ...the second range 853 --THIS_STRING_SEPARATES-- 855 Another example, using the "exampleunit" range unit: 857 HTTP/1.1 206 Partial Content 858 Date: Tue, 14 Nov 1995 06:25:24 GMT 859 Last-Modified: Tue, 14 July 04:58:08 GMT 860 Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 862 --THIS_STRING_SEPARATES 863 Content-type: video/example 864 Content-range: exampleunit 1.2-4.3/25 866 ...the first range... 867 --THIS_STRING_SEPARATES 868 Content-type: video/example 869 Content-range: exampleunit 11.2-14.3/25 871 ...the second range 872 --THIS_STRING_SEPARATES-- 874 Notes: 876 1. Additional CRLFs MAY precede the first boundary string in the 877 body. 879 2. Although [RFC2046] permits the boundary string to be quoted, some 880 existing implementations handle a quoted boundary string 881 incorrectly. 883 3. A number of clients and servers were coded to an early draft of 884 the byteranges specification to use a media type of multipart/ 885 x-byteranges, which is almost, but not quite compatible with the 886 version documented in HTTP/1.1. 888 Appendix B. Changes from RFC 2616 890 Introduce Range Specifier Registry. (Section 2.1) 892 Clarify that it is not ok to use a weak validator in a 206 response. 893 (Section 3.1) 895 Change ABNF productions for header fields to only define the field 896 value. (Section 5) 898 Clarify that multipart/byteranges can consist of a single part. 899 (Appendix A) 901 Appendix C. Imported ABNF 903 The following core rules are included by reference, as defined in 904 Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), 905 CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double 906 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 907 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII 908 character). 910 Note that all rules derived from token are to be compared case- 911 insensitively, like range-unit and acceptable-ranges. 913 The rules below are defined in [Part1]: 915 OWS = 916 token = 918 The rules below are defined in other parts: 920 HTTP-date = 921 entity-tag = 923 Appendix D. Collected ABNF 925 Accept-Ranges = acceptable-ranges 927 Content-Range = byte-content-range-spec / other-content-range-spec 929 HTTP-date = 931 If-Range = entity-tag / HTTP-date 933 OWS = 935 Range = byte-ranges-specifier / other-ranges-specifier 937 acceptable-ranges = ( *( "," OWS ) range-unit *( OWS "," [ OWS 938 range-unit ] ) ) / "none" 940 byte-content-range-spec = bytes-unit SP byte-range-resp-spec "/" ( 941 instance-length / "*" ) 942 byte-range-resp-spec = ( first-byte-pos "-" last-byte-pos ) / "*" 943 byte-range-set = *( "," OWS ) ( byte-range-spec / 944 suffix-byte-range-spec ) *( OWS "," [ OWS ( byte-range-spec / 945 suffix-byte-range-spec ) ] ) 946 byte-range-spec = first-byte-pos "-" [ last-byte-pos ] 947 byte-ranges-specifier = bytes-unit "=" byte-range-set 948 bytes-unit = "bytes" 950 entity-tag = 952 first-byte-pos = 1*DIGIT 954 instance-length = 1*DIGIT 956 last-byte-pos = 1*DIGIT 958 other-content-range-spec = other-range-unit SP other-range-resp-spec 959 other-range-resp-spec = *CHAR 960 other-range-set = 1*CHAR 961 other-range-unit = token 962 other-ranges-specifier = other-range-unit "=" other-range-set 964 range-unit = bytes-unit / other-range-unit 966 suffix-byte-range-spec = "-" suffix-length 967 suffix-length = 1*DIGIT 969 token = 971 Appendix E. Change Log (to be removed by RFC Editor before publication) 973 Changes up to the first Working Group Last Call draft are summarized 974 in . 977 E.1. Since draft-ietf-httpbis-p5-range-19 979 Closed issues: 981 o : "ABNF list 982 expansion code problem" 984 o : "ABNF 985 requirements for recipients" 987 o : "reserve 988 'none' as byte range unit" 990 o : "note 991 introduction of new IANA registries as normative changes" 993 o : "range units 994 vs leading zeroes vs size" 996 Index 998 2 999 206 Partial Content (status code) 6 1001 4 1002 416 Requested Range Not Satisfiable (status code) 7 1004 A 1005 Accept-Ranges header field 9 1007 C 1008 Content-Range header field 10 1010 G 1011 Grammar 1012 Accept-Ranges 9 1013 acceptable-ranges 9 1014 byte-content-range-spec 10 1015 byte-range-resp-spec 10 1016 byte-range-set 12 1017 byte-range-spec 12 1018 byte-ranges-specifier 12 1019 bytes-unit 5 1020 Content-Range 10 1021 first-byte-pos 12 1022 If-Range 11 1023 instance-length 10 1024 last-byte-pos 12 1025 other-range-unit 5 1026 Range 14 1027 range-unit 5 1028 ranges-specifier 12 1029 suffix-byte-range-spec 13 1030 suffix-length 13 1032 H 1033 Header Fields 1034 Accept-Ranges 9 1035 Content-Range 10 1036 If-Range 11 1037 Range 12 1039 I 1040 If-Range header field 11 1042 M 1043 Media Type 1044 multipart/byteranges 18 1045 multipart/x-byteranges 20 1046 multipart/byteranges Media Type 18 1047 multipart/x-byteranges Media Type 20 1049 R 1050 Range header field 12 1052 S 1053 Status Codes 1054 206 Partial Content 6 1055 416 Requested Range Not Satisfiable 7 1057 Authors' Addresses 1059 Roy T. Fielding (editor) 1060 Adobe Systems Incorporated 1061 345 Park Ave 1062 San Jose, CA 95110 1063 USA 1065 EMail: fielding@gbiv.com 1066 URI: http://roy.gbiv.com/ 1068 Yves Lafon (editor) 1069 World Wide Web Consortium 1070 W3C / ERCIM 1071 2004, rte des Lucioles 1072 Sophia-Antipolis, AM 06902 1073 France 1075 EMail: ylafon@w3.org 1076 URI: http://www.raubacapeu.net/people/yves/ 1078 Julian F. Reschke (editor) 1079 greenbytes GmbH 1080 Hafenweg 16 1081 Muenster, NW 48155 1082 Germany 1084 EMail: julian.reschke@greenbytes.de 1085 URI: http://greenbytes.de/tech/webdav/