idnits 2.17.1 draft-ietf-httpbis-p5-range-17.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, 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 (October 31, 2011) is 4562 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) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-17 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-17 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-17 -- 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 (~~), 4 warnings (==), 5 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) J. Gettys 5 Intended status: Standards Track Alcatel-Lucent 6 Expires: May 3, 2012 J. Mogul 7 HP 8 H. Frystyk 9 Microsoft 10 L. Masinter 11 Adobe 12 P. Leach 13 Microsoft 14 T. Berners-Lee 15 W3C/MIT 16 Y. Lafon, Ed. 17 W3C 18 J. Reschke, Ed. 19 greenbytes 20 October 31, 2011 22 HTTP/1.1, part 5: Range Requests and Partial Responses 23 draft-ietf-httpbis-p5-range-17 25 Abstract 27 The Hypertext Transfer Protocol (HTTP) is an application-level 28 protocol for distributed, collaborative, hypertext information 29 systems. HTTP has been in use by the World Wide Web global 30 information initiative since 1990. This document is Part 5 of the 31 seven-part specification that defines the protocol referred to as 32 "HTTP/1.1" and, taken together, obsoletes RFC 2616. 34 Part 5 defines range-specific requests and the rules for constructing 35 and combining responses to those requests. 37 Editorial Note (To be removed by RFC Editor) 39 Discussion of this draft should take place on the HTTPBIS working 40 group mailing list (ietf-http-wg@w3.org), which is archived at 41 . 43 The current issues list is at 44 and related 45 documents (including fancy diffs) can be found at 46 . 48 The changes in this draft are summarized in Appendix D.18. 50 Status of This Memo 52 This Internet-Draft is submitted in full conformance with the 53 provisions of BCP 78 and BCP 79. 55 Internet-Drafts are working documents of the Internet Engineering 56 Task Force (IETF). Note that other groups may also distribute 57 working documents as Internet-Drafts. The list of current Internet- 58 Drafts is at http://datatracker.ietf.org/drafts/current/. 60 Internet-Drafts are draft documents valid for a maximum of six months 61 and may be updated, replaced, or obsoleted by other documents at any 62 time. It is inappropriate to use Internet-Drafts as reference 63 material or to cite them other than as "work in progress." 65 This Internet-Draft will expire on May 3, 2012. 67 Copyright Notice 69 Copyright (c) 2011 IETF Trust and the persons identified as the 70 document authors. All rights reserved. 72 This document is subject to BCP 78 and the IETF Trust's Legal 73 Provisions Relating to IETF Documents 74 (http://trustee.ietf.org/license-info) in effect on the date of 75 publication of this document. Please review these documents 76 carefully, as they describe your rights and restrictions with respect 77 to this document. Code Components extracted from this document must 78 include Simplified BSD License text as described in Section 4.e of 79 the Trust Legal Provisions and are provided without warranty as 80 described in the Simplified BSD License. 82 This document may contain material from IETF Documents or IETF 83 Contributions published or made publicly available before November 84 10, 2008. The person(s) controlling the copyright in some of this 85 material may not have granted the IETF Trust the right to allow 86 modifications of such material outside the IETF Standards Process. 87 Without obtaining an adequate license from the person(s) controlling 88 the copyright in such materials, this document may not be modified 89 outside the IETF Standards Process, and derivative works of it may 90 not be created outside the IETF Standards Process, except to format 91 it for publication as an RFC or to translate it into languages other 92 than English. 94 Table of Contents 96 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 97 1.1. Conformance and Error Handling . . . . . . . . . . . . . . 5 98 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 6 99 1.2.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 6 100 1.2.2. ABNF Rules defined in other Parts of the 101 Specification . . . . . . . . . . . . . . . . . . . . 6 102 2. Range Units . . . . . . . . . . . . . . . . . . . . . . . . . 6 103 2.1. Range Specifier Registry . . . . . . . . . . . . . . . . . 7 104 3. Status Code Definitions . . . . . . . . . . . . . . . . . . . 7 105 3.1. 206 Partial Content . . . . . . . . . . . . . . . . . . . 7 106 3.2. 416 Requested Range Not Satisfiable . . . . . . . . . . . 8 107 4. Combining Ranges . . . . . . . . . . . . . . . . . . . . . . . 8 108 5. Header Field Definitions . . . . . . . . . . . . . . . . . . . 9 109 5.1. Accept-Ranges . . . . . . . . . . . . . . . . . . . . . . 9 110 5.2. Content-Range . . . . . . . . . . . . . . . . . . . . . . 10 111 5.3. If-Range . . . . . . . . . . . . . . . . . . . . . . . . . 12 112 5.4. Range . . . . . . . . . . . . . . . . . . . . . . . . . . 13 113 5.4.1. Byte Ranges . . . . . . . . . . . . . . . . . . . . . 13 114 5.4.2. Range Retrieval Requests . . . . . . . . . . . . . . . 15 115 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 116 6.1. Status Code Registration . . . . . . . . . . . . . . . . . 16 117 6.2. Header Field Registration . . . . . . . . . . . . . . . . 16 118 6.3. Range Specifier Registration . . . . . . . . . . . . . . . 16 119 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 120 7.1. Overlapping Ranges . . . . . . . . . . . . . . . . . . . . 17 121 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17 122 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 123 9.1. Normative References . . . . . . . . . . . . . . . . . . . 17 124 9.2. Informative References . . . . . . . . . . . . . . . . . . 18 125 Appendix A. Internet Media Type multipart/byteranges . . . . . . 18 126 Appendix B. Compatibility with Previous Versions . . . . . . . . 21 127 B.1. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 21 128 Appendix C. Collected ABNF . . . . . . . . . . . . . . . . . . . 22 129 Appendix D. Change Log (to be removed by RFC Editor before 130 publication) . . . . . . . . . . . . . . . . . . . . 23 131 D.1. Since RFC 2616 . . . . . . . . . . . . . . . . . . . . . . 23 132 D.2. Since draft-ietf-httpbis-p5-range-00 . . . . . . . . . . . 23 133 D.3. Since draft-ietf-httpbis-p5-range-01 . . . . . . . . . . . 23 134 D.4. Since draft-ietf-httpbis-p5-range-02 . . . . . . . . . . . 23 135 D.5. Since draft-ietf-httpbis-p5-range-03 . . . . . . . . . . . 24 136 D.6. Since draft-ietf-httpbis-p5-range-04 . . . . . . . . . . . 24 137 D.7. Since draft-ietf-httpbis-p5-range-05 . . . . . . . . . . . 24 138 D.8. Since draft-ietf-httpbis-p5-range-06 . . . . . . . . . . . 24 139 D.9. Since draft-ietf-httpbis-p5-range-07 . . . . . . . . . . . 25 140 D.10. Since draft-ietf-httpbis-p5-range-08 . . . . . . . . . . . 25 141 D.11. Since draft-ietf-httpbis-p5-range-09 . . . . . . . . . . . 25 142 D.12. Since draft-ietf-httpbis-p5-range-10 . . . . . . . . . . . 25 143 D.13. Since draft-ietf-httpbis-p5-range-11 . . . . . . . . . . . 25 144 D.14. Since draft-ietf-httpbis-p5-range-12 . . . . . . . . . . . 26 145 D.15. Since draft-ietf-httpbis-p5-range-13 . . . . . . . . . . . 26 146 D.16. Since draft-ietf-httpbis-p5-range-14 . . . . . . . . . . . 26 147 D.17. Since draft-ietf-httpbis-p5-range-15 . . . . . . . . . . . 26 148 D.18. Since draft-ietf-httpbis-p5-range-16 . . . . . . . . . . . 26 149 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 151 1. Introduction 153 HTTP clients often encounter interrupted data transfers as a result 154 of cancelled requests or dropped connections. When a client has 155 stored a partial representation, it is desirable to request the 156 remainder of that representation in a subsequent request rather than 157 transfer the entire representation. There are also a number of Web 158 applications that benefit from being able to request only a subset of 159 a larger representation, such as a single page of a very large 160 document or only part of an image to be rendered by a device with 161 limited local storage. 163 This document defines HTTP/1.1 range requests, partial responses, and 164 the multipart/byteranges media type. The protocol for range requests 165 is an OPTIONAL feature of HTTP, designed so resources or recipients 166 that do not implement this feature can respond as if it is a normal 167 GET request without impacting interoperability. Partial responses 168 are indicated by a distinct status code to not be mistaken for full 169 responses by intermediate caches that might not implement the 170 feature. 172 Although the HTTP range request mechanism is designed to allow for 173 extensible range types, this specification only defines requests for 174 byte ranges. 176 1.1. Conformance and Error Handling 178 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 179 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 180 document are to be interpreted as described in [RFC2119]. 182 This document defines conformance criteria for several roles in HTTP 183 communication, including Senders, Recipients, Clients, Servers, User- 184 Agents, Origin Servers, Intermediaries, Proxies and Gateways. See 185 Section 2 of [Part1] for definitions of these terms. 187 An implementation is considered conformant if it complies with all of 188 the requirements associated with its role(s). Note that SHOULD-level 189 requirements are relevant here, unless one of the documented 190 exceptions is applicable. 192 This document also uses ABNF to define valid protocol elements 193 (Section 1.2). In addition to the prose requirements placed upon 194 them, Senders MUST NOT generate protocol elements that are invalid. 196 Unless noted otherwise, Recipients MAY take steps to recover a usable 197 protocol element from an invalid construct. However, HTTP does not 198 define specific error handling mechanisms, except in cases where it 199 has direct impact on security. This is because different uses of the 200 protocol require different error handling strategies; for example, a 201 Web browser may wish to transparently recover from a response where 202 the Location header field doesn't parse according to the ABNF, 203 whereby in a systems control protocol using HTTP, this type of error 204 recovery could lead to dangerous consequences. 206 1.2. Syntax Notation 208 This specification uses the ABNF syntax defined in Section 1.2 of 209 [Part1] (which extends the syntax defined in [RFC5234] with a list 210 rule). Appendix C shows the collected ABNF, with the list rule 211 expanded. 213 The following core rules are included by reference, as defined in 214 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 215 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 216 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 217 sequence of data), SP (space), and VCHAR (any visible US-ASCII 218 character). 220 Note that all rules derived from token are to be compared case- 221 insensitively, like range-unit and acceptable-ranges. 223 1.2.1. Core Rules 225 The core rules below are defined in [Part1] and [Part2]: 227 OWS = 228 token = 229 HTTP-date = 231 1.2.2. ABNF Rules defined in other Parts of the Specification 233 The ABNF rules below are defined in other parts: 235 entity-tag = 237 2. Range Units 239 HTTP/1.1 allows a client to request that only part (a range) of the 240 representation be included within the response. HTTP/1.1 uses range 241 units in the Range (Section 5.4) and Content-Range (Section 5.2) 242 header fields. A representation can be broken down into subranges 243 according to various structural units. 245 range-unit = bytes-unit / other-range-unit 246 bytes-unit = "bytes" 247 other-range-unit = token 249 HTTP/1.1 has been designed to allow implementations of applications 250 that do not depend on knowledge of ranges. The only range unit 251 defined by HTTP/1.1 is "bytes". Additional specifiers can be defined 252 as described in Section 2.1. 254 If a range unit is not understood in a request, a server MUST ignore 255 the whole Range header field (Section 5.4). If a range unit is not 256 understood in a response, an intermediary SHOULD pass the response to 257 the client; a client MUST fail. 259 2.1. Range Specifier Registry 261 The HTTP Range Specifier Registry defines the name space for the 262 range specifier names. 264 Registrations MUST include the following fields: 266 o Name 268 o Description 270 o Pointer to specification text 272 Values to be added to this name space are subject to IETF review 273 ([RFC5226], Section 4.1). 275 The registry itself is maintained at 276 . 278 3. Status Code Definitions 280 3.1. 206 Partial Content 282 The server has fulfilled the partial GET request for the resource. 283 The request MUST have included a Range header field (Section 5.4) 284 indicating the desired range, and MAY have included an If-Range 285 header field (Section 5.3) to make the request conditional. 287 The response MUST include the following header fields: 289 o Either a Content-Range header field (Section 5.2) indicating the 290 range included with this response, or a multipart/byteranges 291 Content-Type including Content-Range fields for each part. If a 292 Content-Length header field is present in the response, its value 293 MUST match the actual number of octets transmitted in the message- 294 body. 296 o Date 298 o Cache-Control, ETag, Expires, Content-Location, Last-Modified, 299 and/or Vary, if the header field would have been sent in a 200 300 response to the same request 302 If the 206 response is the result of an If-Range request, the 303 response SHOULD NOT include other representation header fields. 304 Otherwise, the response MUST include all of the representation header 305 fields that would have been returned with a 200 (OK) response to the 306 same request. 308 3.2. 416 Requested Range Not Satisfiable 310 A server SHOULD return a response with this status code if a request 311 included a Range header field (Section 5.4), and none of the ranges- 312 specifier values in this field overlap the current extent of the 313 selected resource, and the request did not include an If-Range header 314 field (Section 5.3). (For byte-ranges, this means that the first- 315 byte-pos of all of the byte-range-spec values were greater than the 316 current length of the selected resource.) 318 When this status code is returned for a byte-range request, the 319 response SHOULD include a Content-Range header field specifying the 320 current length of the representation (see Section 5.2). This 321 response MUST NOT use the multipart/byteranges content-type. 323 4. Combining Ranges 325 A response might transfer only a subrange of a representation if the 326 connection closed prematurely or if the request used one or more 327 Range specifications. After several such transfers, a client might 328 have received several ranges of the same representation. These 329 ranges can only be safely combined if they all have in common the 330 same strong validator, where "strong validator" is defined to be 331 either an entity-tag that is not marked as weak (Section 2.3 of 332 [Part4]) or, if no entity-tag is provided, a Last-Modified value that 333 is strong in the sense defined by Section 2.2.2 of [Part4]. 335 When a client receives an incomplete 200 (OK) or 206 (Partial 336 Content) response and already has one or more stored responses for 337 the same method and effective request URI, all of the stored 338 responses with the same strong validator MAY be combined with the 339 partial content in this new response. If none of the stored 340 responses contain the same strong validator, then this new response 341 corresponds to a new representation and MUST NOT be combined with the 342 existing stored responses. 344 If the new response is an incomplete 200 (OK) response, then the 345 header fields of that new response are used for any combined response 346 and replace those of the matching stored responses. 348 If the new response is a 206 (Partial Content) response and at least 349 one of the matching stored responses is a 200 (OK), then the combined 350 response header fields consist of the most recent 200 response's 351 header fields. If all of the matching stored responses are 206 352 responses, then the stored response with the most header fields is 353 used as the source of header fields for the combined response, except 354 that the client MUST use other header fields provided in the new 355 response, aside from Content-Range, to replace all instances of the 356 corresponding header fields in the stored response. 358 The combined response message-body consists of the union of partial 359 content ranges in the new response and each of the selected 360 responses. If the union consists of the entire range of the 361 representation, then the combined response MUST be recorded as a 362 complete 200 (OK) response with a Content-Length header field that 363 reflects the complete length. Otherwise, the combined response(s) 364 MUST include a Content-Range header field describing the included 365 range(s) and be recorded as incomplete. If the union consists of a 366 discontinuous range of the representation, then the client MAY store 367 it as either a multipart range response or as multiple 206 responses 368 with one continuous range each. 370 5. Header Field Definitions 372 This section defines the syntax and semantics of HTTP/1.1 header 373 fields related to range requests and partial responses. 375 5.1. Accept-Ranges 377 The "Accept-Ranges" header field allows a resource to indicate its 378 acceptance of range requests. 380 Accept-Ranges = acceptable-ranges 381 acceptable-ranges = 1#range-unit / "none" 383 Origin servers that accept byte-range requests MAY send 385 Accept-Ranges: bytes 387 but are not required to do so. Clients MAY generate range requests 388 without having received this header field for the resource involved. 389 Range units are defined in Section 2. 391 Servers that do not accept any kind of range request for a resource 392 MAY send 394 Accept-Ranges: none 396 to advise the client not to attempt a range request. 398 5.2. Content-Range 400 The "Content-Range" header field is sent with a partial 401 representation to specify where in the full representation the 402 payload body is intended to be applied. 404 Range units are defined in Section 2. 406 Content-Range = byte-content-range-spec 407 / other-content-range-spec 409 byte-content-range-spec = bytes-unit SP 410 byte-range-resp-spec "/" 411 ( instance-length / "*" ) 413 byte-range-resp-spec = (first-byte-pos "-" last-byte-pos) 414 / "*" 416 instance-length = 1*DIGIT 418 other-content-range-spec = other-range-unit SP 419 other-range-resp-spec 420 other-range-resp-spec = *CHAR 422 The header field SHOULD indicate the total length of the full 423 representation, unless this length is unknown or difficult to 424 determine. The asterisk "*" character means that the instance-length 425 is unknown at the time when the response was generated. 427 Unlike byte-ranges-specifier values (see Section 5.4.1), a byte- 428 range-resp-spec MUST only specify one range, and MUST contain 429 absolute byte positions for both the first and last byte of the 430 range. 432 A byte-content-range-spec with a byte-range-resp-spec whose last- 433 byte-pos value is less than its first-byte-pos value, or whose 434 instance-length value is less than or equal to its last-byte-pos 435 value, is invalid. The recipient of an invalid byte-content-range- 436 spec MUST ignore it and any content transferred along with it. 438 In the case of a byte range request: A server sending a response with 439 status code 416 (Requested range not satisfiable) SHOULD include a 440 Content-Range field with a byte-range-resp-spec of "*". The 441 instance-length specifies the current length of the selected 442 resource. A response with status code 206 (Partial Content) MUST NOT 443 include a Content-Range field with a byte-range-resp-spec of "*". 445 The "Content-Range" header field has no meaning for status codes that 446 do not explicitly describe its semantic. Currently, only status 447 codes 206 (Partial Content) and 416 (Requested range not satisfiable) 448 describe the meaning of this header field. 450 Examples of byte-content-range-spec values, assuming that the 451 representation contains a total of 1234 bytes: 453 o The first 500 bytes: 455 bytes 0-499/1234 457 o The second 500 bytes: 459 bytes 500-999/1234 461 o All except for the first 500 bytes: 463 bytes 500-1233/1234 465 o The last 500 bytes: 467 bytes 734-1233/1234 469 When an HTTP message includes the content of a single range (for 470 example, a response to a request for a single range, or to a request 471 for a set of ranges that overlap without any holes), this content is 472 transmitted with a Content-Range header field, and a Content-Length 473 header field showing the number of bytes actually transferred. For 474 example, 476 HTTP/1.1 206 Partial Content 477 Date: Wed, 15 Nov 1995 06:25:24 GMT 478 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 479 Content-Range: bytes 21010-47021/47022 480 Content-Length: 26012 481 Content-Type: image/gif 483 When an HTTP message includes the content of multiple ranges (for 484 example, a response to a request for multiple non-overlapping 485 ranges), these are transmitted as a multipart message. The multipart 486 media type used for this purpose is "multipart/byteranges" as defined 487 in Appendix A. 489 A response to a request for a single range MUST NOT be sent using the 490 multipart/byteranges media type. A response to a request for 491 multiple ranges, whose result is a single range, MAY be sent as a 492 multipart/byteranges media type with one part. A client that cannot 493 decode a multipart/byteranges message MUST NOT ask for multiple 494 ranges in a single request. 496 When a client requests multiple ranges in one request, the server 497 SHOULD return them in the order that they appeared in the request. 499 If the server ignores a byte-range-spec because it is syntactically 500 invalid, the server SHOULD treat the request as if the invalid Range 501 header field did not exist. (Normally, this means return a 200 502 response containing the full representation). 504 If the server receives a request (other than one including an If- 505 Range header field) with an unsatisfiable Range header field (that 506 is, all of whose byte-range-spec values have a first-byte-pos value 507 greater than the current length of the selected resource), it SHOULD 508 return a response code of 416 (Requested range not satisfiable) 509 (Section 3.2). 511 Note: Clients cannot depend on servers to send a 416 (Requested 512 range not satisfiable) response instead of a 200 (OK) response for 513 an unsatisfiable Range header field, since not all servers 514 implement this header field. 516 5.3. If-Range 518 If a client has a partial copy of a representation and wishes to have 519 an up-to-date copy of the entire representation, it could use the 520 Range header field with a conditional GET (using either or both of 521 If-Unmodified-Since and If-Match.) However, if the condition fails 522 because the representation has been modified, the client would then 523 have to make a second request to obtain the entire current 524 representation. 526 The "If-Range" header field allows a client to "short-circuit" the 527 second request. Informally, its meaning is "if the representation is 528 unchanged, send me the part(s) that I am missing; otherwise, send me 529 the entire new representation". 531 If-Range = entity-tag / HTTP-date 533 Clients MUST NOT use an entity-tag marked as weak in an If-Range 534 field value and MUST NOT use a Last-Modified date in an If-Range 535 field value unless it has no entity-tag for the representation and 536 the Last-Modified date it does have for the representation is strong 537 in the sense defined by Section 2.2.2 of [Part4]. 539 A server that evaluates a conditional range request that is 540 applicable to one of its representations MUST evaluate the condition 541 as false if the entity-tag used as a validator is marked as weak or, 542 when an HTTP-date is used as the validator, if the date value is not 543 strong in the sense defined by Section 2.2.2 of [Part4]. (A server 544 can distinguish between a valid HTTP-date and any form of entity-tag 545 by examining the first two characters.) 547 The If-Range header field SHOULD only be sent by clients together 548 with a Range header field. The If-Range header field MUST be ignored 549 if it is received in a request that does not include a Range header 550 field. The If-Range header field MUST be ignored by a server that 551 does not support the sub-range operation. 553 If the validator given in the If-Range header field matches the 554 current validator for the selected representation of the target 555 resource, then the server SHOULD send the specified sub-range of the 556 representation using a 206 (Partial Content) response. If the 557 validator does not match, then the server SHOULD send the entire 558 representation using a 200 (OK) response. 560 5.4. Range 562 5.4.1. Byte Ranges 564 Since all HTTP representations are transferred as sequences of bytes, 565 the concept of a byte range is meaningful for any HTTP 566 representation. (However, not all clients and servers need to 567 support byte-range operations.) 569 Byte range specifications in HTTP apply to the sequence of bytes in 570 the representation body (not necessarily the same as the message- 571 body). 573 A byte range operation MAY specify a single range of bytes, or a set 574 of ranges within a single representation. 576 byte-ranges-specifier = bytes-unit "=" byte-range-set 577 byte-range-set = 1#( byte-range-spec / suffix-byte-range-spec ) 578 byte-range-spec = first-byte-pos "-" [ last-byte-pos ] 579 first-byte-pos = 1*DIGIT 580 last-byte-pos = 1*DIGIT 582 The first-byte-pos value in a byte-range-spec gives the byte-offset 583 of the first byte in a range. The last-byte-pos value gives the 584 byte-offset of the last byte in the range; that is, the byte 585 positions specified are inclusive. Byte offsets start at zero. 587 If the last-byte-pos value is present, it MUST be greater than or 588 equal to the first-byte-pos in that byte-range-spec, or the byte- 589 range-spec is syntactically invalid. The recipient of a byte-range- 590 set that includes one or more syntactically invalid byte-range-spec 591 values MUST ignore the header field that includes that byte-range- 592 set. 594 If the last-byte-pos value is absent, or if the value is greater than 595 or equal to the current length of the representation body, last-byte- 596 pos is taken to be equal to one less than the current length of the 597 representation in bytes. 599 By its choice of last-byte-pos, a client can limit the number of 600 bytes retrieved without knowing the size of the representation. 602 suffix-byte-range-spec = "-" suffix-length 603 suffix-length = 1*DIGIT 605 A suffix-byte-range-spec is used to specify the suffix of the 606 representation body, of a length given by the suffix-length value. 607 (That is, this form specifies the last N bytes of a representation.) 608 If the representation is shorter than the specified suffix-length, 609 the entire representation is used. 611 If a syntactically valid byte-range-set includes at least one byte- 612 range-spec whose first-byte-pos is less than the current length of 613 the representation, or at least one suffix-byte-range-spec with a 614 non-zero suffix-length, then the byte-range-set is satisfiable. 615 Otherwise, the byte-range-set is unsatisfiable. If the byte-range- 616 set is unsatisfiable, the server SHOULD return a response with a 416 617 (Requested range not satisfiable) status code. Otherwise, the server 618 SHOULD return a response with a 206 (Partial Content) status code 619 containing the satisfiable ranges of the representation. 621 Examples of byte-ranges-specifier values (assuming a representation 622 of length 10000): 624 o The first 500 bytes (byte offsets 0-499, inclusive): 626 bytes=0-499 628 o The second 500 bytes (byte offsets 500-999, inclusive): 630 bytes=500-999 632 o The final 500 bytes (byte offsets 9500-9999, inclusive): 634 bytes=-500 636 Or: 638 bytes=9500- 640 o The first and last bytes only (bytes 0 and 9999): 642 bytes=0-0,-1 644 o Several legal but not canonical specifications of the second 500 645 bytes (byte offsets 500-999, inclusive): 647 bytes=500-600,601-999 648 bytes=500-700,601-999 650 5.4.2. Range Retrieval Requests 652 The "Range" header field defines the GET method (conditional or not) 653 to request one or more sub-ranges of the response representation 654 body, instead of the entire representation body. 656 Range = byte-ranges-specifier / other-ranges-specifier 657 other-ranges-specifier = other-range-unit "=" other-range-set 658 other-range-set = 1*CHAR 660 A server MAY ignore the Range header field. However, origin servers 661 and intermediate caches ought to support byte ranges when possible, 662 since Range supports efficient recovery from partially failed 663 transfers, and supports efficient partial retrieval of large 664 representations. 666 If the server supports the Range header field and the specified range 667 or ranges are appropriate for the representation: 669 o The presence of a Range header field in an unconditional GET 670 modifies what is returned if the GET is otherwise successful. In 671 other words, the response carries a status code of 206 (Partial 672 Content) instead of 200 (OK). 674 o The presence of a Range header field in a conditional GET (a 675 request using one or both of If-Modified-Since and If-None-Match, 676 or one or both of If-Unmodified-Since and If-Match) modifies what 677 is returned if the GET is otherwise successful and the condition 678 is true. It does not affect the 304 (Not Modified) response 679 returned if the conditional is false. 681 In some cases, it might be more appropriate to use the If-Range 682 header field (see Section 5.3) in addition to the Range header field. 684 If a proxy that supports ranges receives a Range request, forwards 685 the request to an inbound server, and receives an entire 686 representation in reply, it MAY only return the requested range to 687 its client. 689 6. IANA Considerations 691 6.1. Status Code Registration 693 The HTTP Status Code Registry located at 694 shall be updated 695 with the registrations below: 697 +-------+---------------------------------+-------------+ 698 | Value | Description | Reference | 699 +-------+---------------------------------+-------------+ 700 | 206 | Partial Content | Section 3.1 | 701 | 416 | Requested Range Not Satisfiable | Section 3.2 | 702 +-------+---------------------------------+-------------+ 704 6.2. Header Field Registration 706 The Message Header Field Registry located at shall be 708 updated with the permanent registrations below (see [RFC3864]): 710 +-------------------+----------+----------+-------------+ 711 | Header Field Name | Protocol | Status | Reference | 712 +-------------------+----------+----------+-------------+ 713 | Accept-Ranges | http | standard | Section 5.1 | 714 | Content-Range | http | standard | Section 5.2 | 715 | If-Range | http | standard | Section 5.3 | 716 | Range | http | standard | Section 5.4 | 717 +-------------------+----------+----------+-------------+ 719 The change controller is: "IETF (iesg@ietf.org) - Internet 720 Engineering Task Force". 722 6.3. Range Specifier Registration 724 The registration procedure for HTTP Range Specifiers is defined by 725 Section 2.1 of this document. 727 The HTTP Range Specifier Registry shall be created at 728 and be 729 populated with the registrations below: 731 +----------------------+-------------------+----------------------+ 732 | Range Specifier Name | Description | Reference | 733 +----------------------+-------------------+----------------------+ 734 | bytes | a range of octets | (this specification) | 735 +----------------------+-------------------+----------------------+ 737 The change controller is: "IETF (iesg@ietf.org) - Internet 738 Engineering Task Force". 740 7. Security Considerations 742 This section is meant to inform application developers, information 743 providers, and users of the security limitations in HTTP/1.1 as 744 described by this document. The discussion does not include 745 definitive solutions to the problems revealed, though it does make 746 some suggestions for reducing security risks. 748 7.1. Overlapping Ranges 750 Range requests containing overlapping ranges may lead to the 751 situation where a server is sending far more data than the size of 752 the complete resource representation. 754 8. Acknowledgments 756 See Section 11 of [Part1]. 758 9. References 760 9.1. Normative References 762 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 763 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 764 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 765 and Message Parsing", draft-ietf-httpbis-p1-messaging-17 766 (work in progress), October 2011. 768 [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 769 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 770 and J. Reschke, Ed., "HTTP/1.1, part 2: Message 771 Semantics", draft-ietf-httpbis-p2-semantics-17 (work in 772 progress), October 2011. 774 [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 775 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 776 and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional 777 Requests", draft-ietf-httpbis-p4-conditional-17 (work in 778 progress), October 2011. 780 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 781 Extensions (MIME) Part Two: Media Types", RFC 2046, 782 November 1996. 784 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 785 Requirement Levels", BCP 14, RFC 2119, March 1997. 787 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 788 Specifications: ABNF", STD 68, RFC 5234, January 2008. 790 9.2. Informative References 792 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 793 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 794 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 796 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 797 Procedures for Message Header Fields", BCP 90, RFC 3864, 798 September 2004. 800 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 801 Registration Procedures", BCP 13, RFC 4288, December 2005. 803 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 804 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 805 May 2008. 807 Appendix A. Internet Media Type multipart/byteranges 809 When an HTTP 206 (Partial Content) response message includes the 810 content of multiple ranges (a response to a request for multiple non- 811 overlapping ranges), these are transmitted as a multipart message- 812 body ([RFC2046], Section 5.1). The media type for this purpose is 813 called "multipart/byteranges". The following is to be registered 814 with IANA [RFC4288]. 816 Note: Despite the name "multipart/byteranges" is not limited to 817 the byte ranges only. 819 The multipart/byteranges media type includes one or more parts, each 820 with its own Content-Type and Content-Range fields. The required 821 boundary parameter specifies the boundary string used to separate 822 each body-part. 824 Type name: multipart 826 Subtype name: byteranges 828 Required parameters: boundary 830 Optional parameters: none 832 Encoding considerations: only "7bit", "8bit", or "binary" are 833 permitted 835 Security considerations: none 837 Interoperability considerations: none 839 Published specification: This specification (see Appendix A). 841 Applications that use this media type: 843 Additional information: 845 Magic number(s): none 847 File extension(s): none 849 Macintosh file type code(s): none 851 Person and email address to contact for further information: See 852 Authors Section. 854 Intended usage: COMMON 856 Restrictions on usage: none 858 Author/Change controller: IESG 859 For example: 861 HTTP/1.1 206 Partial Content 862 Date: Wed, 15 Nov 1995 06:25:24 GMT 863 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 864 Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 866 --THIS_STRING_SEPARATES 867 Content-type: application/pdf 868 Content-range: bytes 500-999/8000 870 ...the first range... 871 --THIS_STRING_SEPARATES 872 Content-type: application/pdf 873 Content-range: bytes 7000-7999/8000 875 ...the second range 876 --THIS_STRING_SEPARATES-- 878 Other example: 880 HTTP/1.1 206 Partial Content 881 Date: Tue, 14 Nov 1995 06:25:24 GMT 882 Last-Modified: Tue, 14 July 04:58:08 GMT 883 Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 885 --THIS_STRING_SEPARATES 886 Content-type: video/example 887 Content-range: exampleunit 1.2-4.3/25 889 ...the first range... 890 --THIS_STRING_SEPARATES 891 Content-type: video/example 892 Content-range: exampleunit 11.2-14.3/25 894 ...the second range 895 --THIS_STRING_SEPARATES-- 897 Notes: 899 1. Additional CRLFs MAY precede the first boundary string in the 900 body. 902 2. Although [RFC2046] permits the boundary string to be quoted, some 903 existing implementations handle a quoted boundary string 904 incorrectly. 906 3. A number of browsers and servers were coded to an early draft of 907 the byteranges specification to use a media type of multipart/ 908 x-byteranges, which is almost, but not quite compatible with the 909 version documented in HTTP/1.1. 911 Appendix B. Compatibility with Previous Versions 913 B.1. Changes from RFC 2616 915 Clarify that it is not ok to use a weak validator in a 206 response. 916 (Section 3.1) 918 Change ABNF productions for header fields to only define the field 919 value. (Section 5) 921 Clarify that multipart/byteranges can consist of a single part. 922 (Appendix A) 924 Appendix C. Collected ABNF 926 Accept-Ranges = acceptable-ranges 928 Content-Range = byte-content-range-spec / other-content-range-spec 930 HTTP-date = 932 If-Range = entity-tag / HTTP-date 934 OWS = 936 Range = byte-ranges-specifier / other-ranges-specifier 938 acceptable-ranges = ( *( "," OWS ) range-unit *( OWS "," [ OWS 939 range-unit ] ) ) / "none" 941 byte-content-range-spec = bytes-unit SP byte-range-resp-spec "/" ( 942 instance-length / "*" ) 943 byte-range-resp-spec = ( first-byte-pos "-" last-byte-pos ) / "*" 944 byte-range-set = ( *( "," OWS ) byte-range-spec ) / ( 945 suffix-byte-range-spec *( OWS "," [ ( OWS byte-range-spec ) / 946 suffix-byte-range-spec ] ) ) 947 byte-range-spec = first-byte-pos "-" [ last-byte-pos ] 948 byte-ranges-specifier = bytes-unit "=" byte-range-set 949 bytes-unit = "bytes" 951 entity-tag = 953 first-byte-pos = 1*DIGIT 955 instance-length = 1*DIGIT 957 last-byte-pos = 1*DIGIT 959 other-content-range-spec = other-range-unit SP other-range-resp-spec 960 other-range-resp-spec = *CHAR 961 other-range-set = 1*CHAR 962 other-range-unit = token 963 other-ranges-specifier = other-range-unit "=" other-range-set 965 range-unit = bytes-unit / other-range-unit 967 suffix-byte-range-spec = "-" suffix-length 968 suffix-length = 1*DIGIT 970 token = 971 ABNF diagnostics: 973 ; Accept-Ranges defined but not used 974 ; Content-Range defined but not used 975 ; If-Range defined but not used 976 ; Range defined but not used 978 Appendix D. Change Log (to be removed by RFC Editor before publication) 980 D.1. Since RFC 2616 982 Extracted relevant partitions from [RFC2616]. 984 D.2. Since draft-ietf-httpbis-p5-range-00 986 Closed issues: 988 o : "Cache 989 validators in 206 responses" 990 () 992 o : "Normative and 993 Informative references" 995 o : "Normative up- 996 to-date references" 998 D.3. Since draft-ietf-httpbis-p5-range-01 1000 Closed issues: 1002 o : "Updating to 1003 RFC4288" 1005 Ongoing work on ABNF conversion 1006 (): 1008 o Add explicit references to BNF syntax and rules imported from 1009 other parts of the specification. 1011 D.4. Since draft-ietf-httpbis-p5-range-02 1013 Ongoing work on IANA Message Header Field Registration 1014 (): 1016 o Reference RFC 3984, and update header field registrations for 1017 headers defined in this document. 1019 D.5. Since draft-ietf-httpbis-p5-range-03 1021 None. 1023 D.6. Since draft-ietf-httpbis-p5-range-04 1025 Closed issues: 1027 o : "multipart/ 1028 byteranges minimum number of parts" 1030 Ongoing work on ABNF conversion 1031 (): 1033 o Use "/" instead of "|" for alternatives. 1035 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 1036 whitespace ("OWS") and required whitespace ("RWS"). 1038 o Rewrite ABNFs to spell out whitespace rules, factor out header 1039 field value format definitions. 1041 D.7. Since draft-ietf-httpbis-p5-range-05 1043 Closed issues: 1045 o : "State base 1046 for *-byte-pos and suffix-length" 1048 Ongoing work on Custom Ranges 1049 (): 1051 o Remove bias in favor of byte ranges; allow custom ranges in ABNF. 1053 Final work on ABNF conversion 1054 (): 1056 o Add appendix containing collected and expanded ABNF, reorganize 1057 ABNF introduction. 1059 D.8. Since draft-ietf-httpbis-p5-range-06 1061 Closed issues: 1063 o : "base for 1064 numeric protocol elements" 1066 D.9. Since draft-ietf-httpbis-p5-range-07 1068 Closed issues: 1070 o Fixed discrepancy in the If-Range definition about allowed 1071 validators. 1073 o : "multipart/ 1074 byteranges for custom range units" 1076 o : "range unit 1077 missing from other-ranges-specifier in Range header" 1079 o : "move IANA 1080 registrations for optional status codes" 1082 D.10. Since draft-ietf-httpbis-p5-range-08 1084 No significant changes. 1086 D.11. Since draft-ietf-httpbis-p5-range-09 1088 No significant changes. 1090 D.12. Since draft-ietf-httpbis-p5-range-10 1092 Closed issues: 1094 o : "Clarify 1095 'Requested Variant'" 1097 o : "Clarify 1098 entity / representation / variant terminology" 1100 o : "consider 1101 removing the 'changes from 2068' sections" 1103 Ongoing work on Custom Ranges 1104 (): 1106 o Add IANA registry. 1108 D.13. Since draft-ietf-httpbis-p5-range-11 1110 Closed issues: 1112 o : "Caches can't 1113 be required to serve ranges" 1115 D.14. Since draft-ietf-httpbis-p5-range-12 1117 Closed issues: 1119 o : "Header 1120 Classification" 1122 D.15. Since draft-ietf-httpbis-p5-range-13 1124 Closed issues: 1126 o : "untangle 1127 ABNFs for header fields" 1129 D.16. Since draft-ietf-httpbis-p5-range-14 1131 None. 1133 D.17. Since draft-ietf-httpbis-p5-range-15 1135 Closed issues: 1137 o : "Security 1138 consideration: range flooding" 1140 D.18. Since draft-ietf-httpbis-p5-range-16 1142 Closed issues: 1144 o : "Document 1145 HTTP's error-handling philosophy" 1147 o : "Content- 1148 Range on responses other than 206" 1150 o : "case 1151 sensitivity of ranges in p5" 1153 Index 1155 2 1156 206 Partial Content (status code) 7 1158 4 1159 416 Requested Range Not Satisfiable (status code) 8 1161 A 1162 Accept-Ranges header field 9 1164 C 1165 Content-Range header field 10 1167 G 1168 Grammar 1169 Accept-Ranges 9 1170 acceptable-ranges 9 1171 byte-content-range-spec 10 1172 byte-range-resp-spec 10 1173 byte-range-set 13 1174 byte-range-spec 13 1175 byte-ranges-specifier 13 1176 bytes-unit 6 1177 Content-Range 10 1178 first-byte-pos 13 1179 If-Range 12 1180 instance-length 10 1181 last-byte-pos 13 1182 other-range-unit 6 1183 Range 15 1184 range-unit 6 1185 ranges-specifier 13 1186 suffix-byte-range-spec 14 1187 suffix-length 14 1189 H 1190 Header Fields 1191 Accept-Ranges 9 1192 Content-Range 10 1193 If-Range 12 1194 Range 13 1196 I 1197 If-Range header field 12 1199 M 1200 Media Type 1201 multipart/byteranges 18 1202 multipart/x-byteranges 21 1203 multipart/byteranges Media Type 18 1204 multipart/x-byteranges Media Type 21 1206 R 1207 Range header field 13 1209 S 1210 Status Codes 1211 206 Partial Content 7 1212 416 Requested Range Not Satisfiable 8 1214 Authors' Addresses 1216 Roy T. Fielding (editor) 1217 Adobe Systems Incorporated 1218 345 Park Ave 1219 San Jose, CA 95110 1220 USA 1222 EMail: fielding@gbiv.com 1223 URI: http://roy.gbiv.com/ 1225 Jim Gettys 1226 Alcatel-Lucent Bell Labs 1227 21 Oak Knoll Road 1228 Carlisle, MA 01741 1229 USA 1231 EMail: jg@freedesktop.org 1232 URI: http://gettys.wordpress.com/ 1234 Jeffrey C. Mogul 1235 Hewlett-Packard Company 1236 HP Labs, Large Scale Systems Group 1237 1501 Page Mill Road, MS 1177 1238 Palo Alto, CA 94304 1239 USA 1241 EMail: JeffMogul@acm.org 1243 Henrik Frystyk Nielsen 1244 Microsoft Corporation 1245 1 Microsoft Way 1246 Redmond, WA 98052 1247 USA 1249 EMail: henrikn@microsoft.com 1250 Larry Masinter 1251 Adobe Systems Incorporated 1252 345 Park Ave 1253 San Jose, CA 95110 1254 USA 1256 EMail: LMM@acm.org 1257 URI: http://larry.masinter.net/ 1259 Paul J. Leach 1260 Microsoft Corporation 1261 1 Microsoft Way 1262 Redmond, WA 98052 1264 EMail: paulle@microsoft.com 1266 Tim Berners-Lee 1267 World Wide Web Consortium 1268 MIT Computer Science and Artificial Intelligence Laboratory 1269 The Stata Center, Building 32 1270 32 Vassar Street 1271 Cambridge, MA 02139 1272 USA 1274 EMail: timbl@w3.org 1275 URI: http://www.w3.org/People/Berners-Lee/ 1277 Yves Lafon (editor) 1278 World Wide Web Consortium 1279 W3C / ERCIM 1280 2004, rte des Lucioles 1281 Sophia-Antipolis, AM 06902 1282 France 1284 EMail: ylafon@w3.org 1285 URI: http://www.raubacapeu.net/people/yves/ 1286 Julian F. Reschke (editor) 1287 greenbytes GmbH 1288 Hafenweg 16 1289 Muenster, NW 48155 1290 Germany 1292 Phone: +49 251 2807760 1293 Fax: +49 251 2807761 1294 EMail: julian.reschke@greenbytes.de 1295 URI: http://greenbytes.de/tech/webdav/