source: draft-ietf-httpbis/22/draft-ietf-httpbis-p5-range-22.txt @ 2561

Last change on this file since 2561 was 2190, checked in by julian.reschke@…, 7 years ago

prepare -22 for release

  • Property svn:eol-style set to native
  • Property svn:executable set to *
File size: 47.5 KB
Line 
1
2
3
4HTTPbis Working Group                                   R. Fielding, Ed.
5Internet-Draft                                                     Adobe
6Obsoletes: 2616 (if approved)                              Y. Lafon, Ed.
7Intended status: Standards Track                                     W3C
8Expires: August 27, 2013                                 J. Reschke, Ed.
9                                                              greenbytes
10                                                       February 23, 2013
11
12
13         Hypertext Transfer Protocol (HTTP/1.1): Range Requests
14                     draft-ietf-httpbis-p5-range-22
15
16Abstract
17
18   The Hypertext Transfer Protocol (HTTP) is an application-level
19   protocol for distributed, collaborative, hypertext information
20   systems.  This document defines range requests and the rules for
21   constructing and combining responses to those requests.
22
23Editorial Note (To be removed by RFC Editor)
24
25   Discussion of this draft takes place on the HTTPBIS working group
26   mailing list (ietf-http-wg@w3.org), which is archived at
27   <http://lists.w3.org/Archives/Public/ietf-http-wg/>.
28
29   The current issues list is at
30   <http://tools.ietf.org/wg/httpbis/trac/report/3> and related
31   documents (including fancy diffs) can be found at
32   <http://tools.ietf.org/wg/httpbis/>.
33
34   The changes in this draft are summarized in Appendix E.3.
35
36Status of This Memo
37
38   This Internet-Draft is submitted in full conformance with the
39   provisions of BCP 78 and BCP 79.
40
41   Internet-Drafts are working documents of the Internet Engineering
42   Task Force (IETF).  Note that other groups may also distribute
43   working documents as Internet-Drafts.  The list of current Internet-
44   Drafts is at http://datatracker.ietf.org/drafts/current/.
45
46   Internet-Drafts are draft documents valid for a maximum of six months
47   and may be updated, replaced, or obsoleted by other documents at any
48   time.  It is inappropriate to use Internet-Drafts as reference
49   material or to cite them other than as "work in progress."
50
51   This Internet-Draft will expire on August 27, 2013.
52
53
54
55Fielding, et al.         Expires August 27, 2013                [Page 1]
56
57Internet-Draft           HTTP/1.1 Range Requests           February 2013
58
59
60Copyright Notice
61
62   Copyright (c) 2013 IETF Trust and the persons identified as the
63   document authors.  All rights reserved.
64
65   This document is subject to BCP 78 and the IETF Trust's Legal
66   Provisions Relating to IETF Documents
67   (http://trustee.ietf.org/license-info) in effect on the date of
68   publication of this document.  Please review these documents
69   carefully, as they describe your rights and restrictions with respect
70   to this document.  Code Components extracted from this document must
71   include Simplified BSD License text as described in Section 4.e of
72   the Trust Legal Provisions and are provided without warranty as
73   described in the Simplified BSD License.
74
75   This document may contain material from IETF Documents or IETF
76   Contributions published or made publicly available before November
77   10, 2008.  The person(s) controlling the copyright in some of this
78   material may not have granted the IETF Trust the right to allow
79   modifications of such material outside the IETF Standards Process.
80   Without obtaining an adequate license from the person(s) controlling
81   the copyright in such materials, this document may not be modified
82   outside the IETF Standards Process, and derivative works of it may
83   not be created outside the IETF Standards Process, except to format
84   it for publication as an RFC or to translate it into languages other
85   than English.
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111Fielding, et al.         Expires August 27, 2013                [Page 2]
112
113Internet-Draft           HTTP/1.1 Range Requests           February 2013
114
115
116Table of Contents
117
118   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  4
119     1.1.  Conformance and Error Handling . . . . . . . . . . . . . .  4
120     1.2.  Syntax Notation  . . . . . . . . . . . . . . . . . . . . .  4
121   2.  Range Units  . . . . . . . . . . . . . . . . . . . . . . . . .  4
122     2.1.  Byte Ranges  . . . . . . . . . . . . . . . . . . . . . . .  5
123     2.2.  Other Range Units  . . . . . . . . . . . . . . . . . . . .  7
124     2.3.  Accept-Ranges  . . . . . . . . . . . . . . . . . . . . . .  7
125   3.  Range Requests . . . . . . . . . . . . . . . . . . . . . . . .  7
126     3.1.  Range  . . . . . . . . . . . . . . . . . . . . . . . . . .  7
127     3.2.  If-Range . . . . . . . . . . . . . . . . . . . . . . . . .  9
128   4.  Responses to a Range Request . . . . . . . . . . . . . . . . .  9
129     4.1.  206 Partial Content  . . . . . . . . . . . . . . . . . . . 10
130     4.2.  Content-Range  . . . . . . . . . . . . . . . . . . . . . . 12
131     4.3.  Combining Ranges . . . . . . . . . . . . . . . . . . . . . 14
132     4.4.  416 Range Not Satisfiable  . . . . . . . . . . . . . . . . 15
133   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 15
134     5.1.  Range Unit Registry  . . . . . . . . . . . . . . . . . . . 15
135       5.1.1.  Procedure  . . . . . . . . . . . . . . . . . . . . . . 15
136       5.1.2.  Registrations  . . . . . . . . . . . . . . . . . . . . 16
137     5.2.  Status Code Registration . . . . . . . . . . . . . . . . . 16
138     5.3.  Header Field Registration  . . . . . . . . . . . . . . . . 16
139   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 17
140     6.1.  Denial of Service Attacks using Range  . . . . . . . . . . 17
141   7.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 17
142   8.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 17
143     8.1.  Normative References . . . . . . . . . . . . . . . . . . . 17
144     8.2.  Informative References . . . . . . . . . . . . . . . . . . 18
145   Appendix A.  Internet Media Type multipart/byteranges  . . . . . . 18
146   Appendix B.  Changes from RFC 2616 . . . . . . . . . . . . . . . . 20
147   Appendix C.  Imported ABNF . . . . . . . . . . . . . . . . . . . . 21
148   Appendix D.  Collected ABNF  . . . . . . . . . . . . . . . . . . . 21
149   Appendix E.  Change Log (to be removed by RFC Editor before
150                publication)  . . . . . . . . . . . . . . . . . . . . 23
151     E.1.  Since draft-ietf-httpbis-p5-range-19 . . . . . . . . . . . 23
152     E.2.  Since draft-ietf-httpbis-p5-range-20 . . . . . . . . . . . 23
153     E.3.  Since draft-ietf-httpbis-p5-range-21 . . . . . . . . . . . 23
154   Index  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
155
156
157
158
159
160
161
162
163
164
165
166
167Fielding, et al.         Expires August 27, 2013                [Page 3]
168
169Internet-Draft           HTTP/1.1 Range Requests           February 2013
170
171
1721.  Introduction
173
174   Hypertext Transfer Protocol (HTTP) clients often encounter
175   interrupted data transfers as a result of canceled requests or
176   dropped connections.  When a client has stored a partial
177   representation, it is desirable to request the remainder of that
178   representation in a subsequent request rather than transfer the
179   entire representation.  Likewise, devices with limited local storage
180   might benefit from being able to request only a subset of a larger
181   representation, such as a single page of a very large document, or
182   the dimensions of an embedded image.
183
184   This document defines HTTP/1.1 range requests, partial responses, and
185   the multipart/byteranges media type, obsoleting those parts
186   previously defined in [RFC2616].  Range requests are an OPTIONAL
187   feature of HTTP, designed so that recipients not implementing this
188   feature (or not supporting it for the target resource) can respond as
189   if it is a normal GET request without impacting interoperability.
190   Partial responses are indicated by a distinct status code to not be
191   mistaken for full responses by caches that might not implement the
192   feature.
193
194   Although the range request mechanism is designed to allow for
195   extensible range types, this specification only defines requests for
196   byte ranges.
197
1981.1.  Conformance and Error Handling
199
200   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
201   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
202   document are to be interpreted as described in [RFC2119].
203
204   Conformance criteria and considerations regarding error handling are
205   defined in Section 2.5 of [Part1].
206
2071.2.  Syntax Notation
208
209   This specification uses the Augmented Backus-Naur Form (ABNF)
210   notation of [RFC5234] with the list rule extension defined in Section
211   1.2 of [Part1].  Appendix C describes rules imported from other
212   documents.  Appendix D shows the collected ABNF with the list rule
213   expanded.
214
2152.  Range Units
216
217   A representation can be partitioned into subranges according to
218   various structural units, depending on the structure inherent in the
219   representation's media type.  This "range unit" is used in the
220
221
222
223Fielding, et al.         Expires August 27, 2013                [Page 4]
224
225Internet-Draft           HTTP/1.1 Range Requests           February 2013
226
227
228   Accept-Ranges (Section 2.3) response header field to advertise
229   support for range requests, the Range (Section 3.1) request header
230   field to delineate the parts of a representation that are requested,
231   and the Content-Range (Section 4.2) payload header field to describe
232   which part of a representation is being transferred.
233
234     range-unit       = bytes-unit / other-range-unit
235
2362.1.  Byte Ranges
237
238   Since representation data is transferred in payloads as a sequence of
239   octets, a byte range is a meaningful substructure for any
240   representation transferable over HTTP (Section 3 of [Part2]).  We
241   define the "bytes" range unit for expressing subranges of the data's
242   octet sequence.
243
244     bytes-unit       = "bytes"
245
246   A byte range operation MAY specify a single range of bytes, or a set
247   of ranges within a single representation.
248
249     byte-ranges-specifier = bytes-unit "=" byte-range-set
250     byte-range-set  = 1#( byte-range-spec / suffix-byte-range-spec )
251     byte-range-spec = first-byte-pos "-" [ last-byte-pos ]
252     first-byte-pos  = 1*DIGIT
253     last-byte-pos   = 1*DIGIT
254
255   The first-byte-pos value in a byte-range-spec gives the byte-offset
256   of the first byte in a range.  The last-byte-pos value gives the
257   byte-offset of the last byte in the range; that is, the byte
258   positions specified are inclusive.  Byte offsets start at zero.
259
260   Examples of byte-ranges-specifier values:
261
262   o  The first 500 bytes (byte offsets 0-499, inclusive):
263
264        bytes=0-499
265
266   o  The second 500 bytes (byte offsets 500-999, inclusive):
267
268        bytes=500-999
269
270   A byte-range-spec is invalid if the last-byte-pos value is present
271   and less than the first-byte-pos.
272
273   A client can limit the number of bytes requested without knowing the
274   size of the selected representation.  If the last-byte-pos value is
275   absent, or if the value is greater than or equal to the current
276
277
278
279Fielding, et al.         Expires August 27, 2013                [Page 5]
280
281Internet-Draft           HTTP/1.1 Range Requests           February 2013
282
283
284   length of the representation data, the byte range is interpreted as
285   the remainder of the representation (i.e., the server replaces the
286   value of last-byte-pos with a value that is one less than the current
287   length of the selected representation).
288
289   A client can request the last N bytes of the selected representation
290   using a suffix-byte-range-spec.
291
292     suffix-byte-range-spec = "-" suffix-length
293     suffix-length = 1*DIGIT
294
295   If the selected representation is shorter than the specified suffix-
296   length, the entire representation is used.  For example (assuming a
297   representation of length 10000):
298
299   o  The final 500 bytes (byte offsets 9500-9999, inclusive):
300
301        bytes=-500
302
303      Or:
304
305        bytes=9500-
306
307   o  The first and last bytes only (bytes 0 and 9999):
308
309        bytes=0-0,-1
310
311   o  Other valid (but not canonical) specifications of the second 500
312      bytes (byte offsets 500-999, inclusive):
313
314        bytes=500-600,601-999
315        bytes=500-700,601-999
316
317   If a valid byte-range-set includes at least one byte-range-spec with
318   a first-byte-pos that is less than the current length of the
319   representation, or at least one suffix-byte-range-spec with a non-
320   zero suffix-length, then the byte-range-set is satisfiable.
321   Otherwise, the byte-range-set is unsatisfiable.
322
323   In the byte range syntax, first-byte-pos, last-byte-pos, and suffix-
324   length are expressed as decimal number of octets.  Since there is no
325   predefined limit to the length of a payload, recipients ought to
326   anticipate potentially large decimal numerals and prevent parsing
327   errors due to integer conversion overflows.
328
329
330
331
332
333
334
335Fielding, et al.         Expires August 27, 2013                [Page 6]
336
337Internet-Draft           HTTP/1.1 Range Requests           February 2013
338
339
3402.2.  Other Range Units
341
342   Range units are intended to be extensible.  New range units ought to
343   be registered with IANA, as defined in Section 5.1.
344
345     other-range-unit = token
346
3472.3.  Accept-Ranges
348
349   The "Accept-Ranges" header field allows a server to indicate that it
350   supports range requests for the target resource.
351
352     Accept-Ranges     = acceptable-ranges
353     acceptable-ranges = 1#range-unit / "none"
354
355   Origin servers that support byte-range requests MAY send
356
357     Accept-Ranges: bytes
358
359   but are not required to do so.  Clients MAY generate range requests
360   without having received this header field for the resource involved.
361   Range units are defined in Section 2.
362
363   Servers that do not support any kind of range request for the target
364   resource resource MAY send
365
366     Accept-Ranges: none
367
368   to advise the client not to attempt a range request.
369
3703.  Range Requests
371
3723.1.  Range
373
374   The "Range" header field on a GET request modifies the method
375   semantics to request transfer of only one or more subranges of the
376   selected representation data, rather than the entire selected
377   representation data.
378
379     Range = byte-ranges-specifier / other-ranges-specifier
380     other-ranges-specifier = other-range-unit "=" other-range-set
381     other-range-set = 1*CHAR
382
383   A server MAY ignore the Range header field.  However, origin servers
384   and intermediate caches ought to support byte ranges when possible,
385   since Range supports efficient recovery from partially failed
386   transfers and partial retrieval of large representations.  A server
387   MUST ignore a Range header field received with a request method other
388
389
390
391Fielding, et al.         Expires August 27, 2013                [Page 7]
392
393Internet-Draft           HTTP/1.1 Range Requests           February 2013
394
395
396   than GET.
397
398   An origin server MUST ignore a Range header field that contains a
399   range unit it does not understand.  A proxy MAY either discard a
400   Range header field that contains a range unit it does not understand
401   or pass it to the next inbound server when forwarding the request.
402
403   A server that supports range requests ought to ignore or reject a
404   Range header field that consists of more than two overlapping ranges,
405   or a set of many small ranges that are not listed in ascending order,
406   since both are indications of either a broken client or a deliberate
407   denial of service attack (Section 6.1).  A client SHOULD NOT request
408   multiple ranges that are inherently less efficient to process and
409   transfer than a single range that encompasses the same data.
410
411   A client that is requesting multiple ranges SHOULD list those ranges
412   in ascending order (the order in which they would typically be
413   received in a complete representation) unless there is a specific
414   need to request a later part earlier.  For example, a user agent
415   processing a large representation with an internal catalog of parts
416   might need to request later parts first, particularly if the
417   representation consists of pages stored in reverse order and the user
418   agent wishes to transfer one page at a time.
419
420   The Range header field is evaluated after evaluating the
421   preconditions of [Part4] and only if the result of their evaluation
422   is leading toward a 200 (OK) response.  In other words, Range is
423   ignored when a conditional GET would result in a 304 (Not Modified)
424   response.
425
426   The If-Range header field (Section 3.2) can be used as a precondition
427   to applying the Range header field.
428
429   If all of the preconditions are true, the server supports the Range
430   header field for the target resource, and the specified range(s) are
431   valid and satisfiable (as defined in Section 2.1), the server SHOULD
432   send a 206 (Partial Content) response with a payload containing one
433   or more partial representations that correspond to the satisfiable
434   ranges requested, as defined in Section 4.
435
436   If all of the preconditions are true, the server supports the Range
437   header field for the target resource, and the specified range(s) are
438   invalid or unsatisfiable, the server SHOULD send a 416 (Range Not
439   Satisfiable) response.
440
441
442
443
444
445
446
447Fielding, et al.         Expires August 27, 2013                [Page 8]
448
449Internet-Draft           HTTP/1.1 Range Requests           February 2013
450
451
4523.2.  If-Range
453
454   If a client has a partial copy of a representation and wishes to have
455   an up-to-date copy of the entire representation, it could use the
456   Range header field with a conditional GET (using either or both of
457   If-Unmodified-Since and If-Match.)  However, if the condition fails
458   because the representation has been modified, the client would then
459   have to make a second request to obtain the entire current
460   representation.
461
462   The "If-Range" header field allows a client to "short-circuit" the
463   second request.  Informally, its meaning is: if the representation is
464   unchanged, send me the part(s) that I am requesting in Range;
465   otherwise, send me the entire representation.
466
467     If-Range = entity-tag / HTTP-date
468
469   Clients MUST NOT use an entity-tag marked as weak in an If-Range
470   field value and MUST NOT use a Last-Modified date in an If-Range
471   field value unless it has no entity-tag for the representation and
472   the Last-Modified date it does have for the representation is strong
473   in the sense defined by Section 2.2.2 of [Part4].
474
475   A server that evaluates a conditional range request that is
476   applicable to one of its representations MUST evaluate the condition
477   as false if the entity-tag used as a validator is marked as weak or,
478   when an HTTP-date is used as the validator, if the date value is not
479   strong in the sense defined by Section 2.2.2 of [Part4].  (A server
480   can distinguish between a valid HTTP-date and any form of entity-tag
481   by examining the first two characters.)
482
483   A client MUST NOT generate an If-Range header field in a request that
484   does not contain a Range header field.  A server MUST ignore an If-
485   Range header field received in a request that does not contain a
486   Range header field.  An origin server MUST ignore an If-Range header
487   field received in a request for a target resource that does not
488   support Range requests.
489
490   If the validator given in the If-Range header field matches the
491   current validator for the selected representation of the target
492   resource, then the server SHOULD process the Range header field as
493   requested.  If the validator does not match, then the server MUST
494   ignore the Range header field.
495
4964.  Responses to a Range Request
497
498
499
500
501
502
503Fielding, et al.         Expires August 27, 2013                [Page 9]
504
505Internet-Draft           HTTP/1.1 Range Requests           February 2013
506
507
5084.1.  206 Partial Content
509
510   The 206 (Partial Content) status code indicates that the server is
511   successfully fulfilling a range request for the target resource by
512   transferring one or more parts of the selected representation that
513   correspond to the satisfiable ranges found in the requests's Range
514   header field (Section 3.1).
515
516   If a single part is being transferred, the server generating the 206
517   response MUST generate a Content-Range header field, describing what
518   range of the selected representation is enclosed, and a payload
519   consisting of the range.  For example:
520
521     HTTP/1.1 206 Partial Content
522     Date: Wed, 15 Nov 1995 06:25:24 GMT
523     Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
524     Content-Range: bytes 21010-47021/47022
525     Content-Length: 26012
526     Content-Type: image/gif
527
528     ... 26012 bytes of partial image data ...
529
530   If multiple parts are being transferred, the server generating the
531   206 response MUST generate a "multipart/byteranges" payload, as
532   defined in Appendix A, and a Content-Type header field containing the
533   multipart/byteranges media type and its required boundary parameter.
534   To avoid confusion with single part responses, a server MUST NOT
535   generate a Content-Range header field in the HTTP header block of a
536   multiple part response (this field will be sent in each part
537   instead).
538
539   Within the header area of each body part in the multipart payload,
540   the server MUST generate a Content-Range header field corresponding
541   to the range being enclosed in that body part.  If the selected
542   representation would have had a Content-Type header field in a 200
543   (OK) response, the server SHOULD generate that same Content-Type
544   field in the header area of each body part.  For example:
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559Fielding, et al.         Expires August 27, 2013               [Page 10]
560
561Internet-Draft           HTTP/1.1 Range Requests           February 2013
562
563
564     HTTP/1.1 206 Partial Content
565     Date: Wed, 15 Nov 1995 06:25:24 GMT
566     Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
567     Content-Length: 1741
568     Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES
569
570     --THIS_STRING_SEPARATES
571     Content-Type: application/pdf
572     Content-Range: bytes 500-999/8000
573
574     ...the first range...
575     --THIS_STRING_SEPARATES
576     Content-Type: application/pdf
577     Content-Range: bytes 7000-7999/8000
578
579     ...the second range
580     --THIS_STRING_SEPARATES--
581
582   When multiple ranges are requested, a server MAY coalesce any of the
583   ranges that overlap or that are separated by a gap that is smaller
584   than the overhead of sending multiple parts, regardless of the order
585   in which the corresponding byte-range-spec appeared in the received
586   Range header field.  Since the typical overhead between parts of a
587   multipart/byteranges payload is around 80 bytes, depending on the
588   selected representation's media type and the chosen boundary
589   parameter length, it can be less efficient to transfer many small
590   disjoint parts than it is to transfer the entire selected
591   representation.
592
593   A server MUST NOT generate a multipart response to a request for a
594   single range, since a client that does not request multiple parts
595   might not support multipart responses.  However, a server MAY
596   generate a multipart/byteranges payload with only a single body part
597   if multiple ranges were requested and only one range was found to be
598   satisfiable or only one range remained after coalescing.  A client
599   that cannot process a multipart/byteranges response MUST NOT ask for
600   multiple ranges in a single request.
601
602   When a multipart response payload is generated, the server SHOULD
603   send the parts in the same order that the corresponding byte-range-
604   spec appeared in the received Range header field, excluding those
605   ranges that were deemed unsatisfiable or that were coalesced into
606   other ranges.  A client that receives a multipart response MUST
607   inspect the Content-Range header field present in each body part in
608   order to determine which range is contained in that body part; a
609   client cannot rely on receiving the same ranges that it requested,
610   nor the same order that it requested.
611
612
613
614
615Fielding, et al.         Expires August 27, 2013               [Page 11]
616
617Internet-Draft           HTTP/1.1 Range Requests           February 2013
618
619
620   When a 206 response is generated, the server MUST generate the
621   following header fields, in addition to those required above, if the
622   field would have been sent in a 200 (OK) response to the same
623   request: Date, Cache-Control, ETag, Expires, Content-Location, and
624   Vary.
625
626   If a 206 is generated in response to a request with an If-Range
627   header field, the sender SHOULD NOT generate other representation
628   header fields beyond those required above, because the client is
629   understood to already have a prior response containing those header
630   fields.  Otherwise, the sender MUST generate all of the
631   representation header fields that would have been sent in a 200 (OK)
632   response to the same request.
633
634   A 206 response is cacheable unless otherwise indicated by explicit
635   cache controls (see Section 4.1.2 of [Part6]).
636
6374.2.  Content-Range
638
639   The "Content-Range" header field is sent in a single part 206
640   (Partial Content) response to indicate the partial range of the
641   selected representation enclosed as the message payload, sent in each
642   part of a multipart 206 response to indicate the range enclosed
643   within each body part, and sent in 416 (Range Not Satisfiable)
644   responses to provide information about the selected representation.
645
646     Content-Range       = byte-content-range
647                         / other-content-range
648
649     byte-content-range  = bytes-unit SP
650                           ( byte-range-resp / unsatisfied-range )
651
652     byte-range-resp     = byte-range "/" ( complete-length / "*" )
653     byte-range          = first-byte-pos "-" last-byte-pos
654     unsatisfied-range   = "*/" complete-length
655
656     complete-length     = 1*DIGIT
657
658     other-content-range = other-range-unit SP other-range-resp
659     other-range-resp    = *CHAR
660
661   If a 206 (Partial Content) response contains a Content-Range header
662   field with a range unit (Section 2) that the recipient does not
663   understand, the recipient MUST NOT attempt to recombine it with a
664   stored representation.  A proxy that receives such a message SHOULD
665   forward it downstream.
666
667   For byte ranges, a sender SHOULD indicate the complete length of the
668
669
670
671Fielding, et al.         Expires August 27, 2013               [Page 12]
672
673Internet-Draft           HTTP/1.1 Range Requests           February 2013
674
675
676   representation from which the range has been extracted, unless the
677   complete length is unknown or difficult to determine.  An asterisk
678   character ("*") in place of the complete-length indicates that the
679   representation length was unknown when the header field was
680   generated.
681
682   The following example illustrates when the complete length of the
683   selected representation is known by the sender to be 1234 bytes:
684
685     Content-Range: bytes 42-1233/1234
686
687   and this second example illustrates when the complete length is
688   unknown:
689
690     Content-Range: bytes 42-1233/*
691
692   A Content-Range field value is invalid if it contains a byte-range-
693   resp that has a last-byte-pos value less than its first-byte-pos
694   value, or a complete-length value less than or equal to its last-
695   byte-pos value.  The recipient of an invalid Content-Range MUST NOT
696   attempt to recombine the received content with a stored
697   representation.
698
699   A server generating a 416 (Range Not Satisfiable) response to a byte
700   range request SHOULD send a Content-Range header field with an
701   unsatisfied-range value, as in the following example:
702
703     Content-Range: bytes */1234
704
705   The complete-length in a 416 response indicates the current length of
706   the selected representation.
707
708   The "Content-Range" header field has no meaning for status codes that
709   do not explicitly describe its semantic.  For this specification,
710   only the 206 (Partial Content) and 416 (Range Not Satisfiable) status
711   codes describe a meaning for Content-Range.
712
713   The following are examples of Content-Range values in which the
714   selected representation contains a total of 1234 bytes:
715
716   o  The first 500 bytes:
717
718        Content-Range: bytes 0-499/1234
719
720   o  The second 500 bytes:
721
722        Content-Range: bytes 500-999/1234
723
724
725
726
727Fielding, et al.         Expires August 27, 2013               [Page 13]
728
729Internet-Draft           HTTP/1.1 Range Requests           February 2013
730
731
732   o  All except for the first 500 bytes:
733
734        Content-Range: bytes 500-1233/1234
735
736   o  The last 500 bytes:
737
738        Content-Range: bytes 734-1233/1234
739
7404.3.  Combining Ranges
741
742   A response might transfer only a subrange of a representation if the
743   connection closed prematurely or if the request used one or more
744   Range specifications.  After several such transfers, a client might
745   have received several ranges of the same representation.  These
746   ranges can only be safely combined if they all have in common the
747   same strong validator, where "strong validator" is defined to be
748   either an entity-tag that is not marked as weak (Section 2.3 of
749   [Part4]) or, if no entity-tag is provided, a Last-Modified value that
750   is strong in the sense defined by Section 2.2.2 of [Part4].
751
752   A client that has received multiple partial responses to GET requests
753   on a target resource MAY combine those responses into a larger
754   continuous range if they share the same strong validator.
755
756   If the most recent response is an incomplete 200 (OK) response, then
757   the header fields of that response are used for any combined response
758   and replace those of the matching stored responses.
759
760   If the most recent response is a 206 (Partial Content) response and
761   at least one of the matching stored responses is a 200 (OK), then the
762   combined response header fields consist of the most recent 200
763   response's header fields.  If all of the matching stored responses
764   are 206 responses, then the stored response with the most recent
765   header fields is used as the source of header fields for the combined
766   response, except that the client MUST use other header fields
767   provided in the new response, aside from Content-Range, to replace
768   all instances of the corresponding header fields in the stored
769   response.
770
771   The combined response message body consists of the union of partial
772   content ranges in the new response and each of the selected
773   responses.  If the union consists of the entire range of the
774   representation, then the client MUST record the combined response as
775   if it were a complete 200 (OK) response, including a Content-Length
776   header field that reflects the complete length.  Otherwise, the
777   client MUST record the set of continuous ranges as one of the
778   following: an incomplete 200 (OK) response if the combined response
779   is a prefix of the representation, a single 206 (Partial Content)
780
781
782
783Fielding, et al.         Expires August 27, 2013               [Page 14]
784
785Internet-Draft           HTTP/1.1 Range Requests           February 2013
786
787
788   response containing a multipart/byteranges body, or multiple 206
789   (Partial Content) responses, each with one continuous range that is
790   indicated by a Content-Range header field.
791
7924.4.  416 Range Not Satisfiable
793
794   The 416 (Range Not Satisfiable) status code indicates that none of
795   the ranges in the request's Range header field (Section 3.1) overlap
796   the current extent of the selected resource or that the set of ranges
797   requested has been rejected due to invalid ranges or an excessive
798   request of small or overlapping ranges.
799
800   For byte ranges, failing to overlap the current extent means that the
801   first-byte-pos of all of the byte-range-spec values were greater than
802   the current length of the selected representation.  When this status
803   code is generated in response to a byte range request, the sender
804   SHOULD generate a Content-Range header field specifying the current
805   length of the selected representation (Section 4.2).
806
807   For example:
808
809     HTTP/1.1 416 Range Not Satisfiable
810     Date: Mon, 20 Jan 2012 15:41:54 GMT
811     Content-Range: bytes */47022
812
813      Note: Because servers are free to ignore Range, many
814      implementations will simply respond with 200 (OK) if the requested
815      ranges are invalid or not satisfiable.  That is partly because
816      most clients are prepared to receive a 200 (OK) to complete the
817      task (albeit less efficiently) and partly because clients might
818      not stop making an invalid partial request until they have
819      received a complete representation.  Thus, clients cannot depend
820      on receiving a 416 (Range Not Satisfiable) response even when it
821      is most appropriate.
822
8235.  IANA Considerations
824
8255.1.  Range Unit Registry
826
827   The HTTP Range Unit Registry defines the name space for the range
828   unit names and refers to their corresponding specifications.  The
829   registry is maintained at
830   <http://www.iana.org/assignments/http-parameters>.
831
8325.1.1.  Procedure
833
834   Registration of an HTTP Range Unit MUST include the following fields:
835
836
837
838
839Fielding, et al.         Expires August 27, 2013               [Page 15]
840
841Internet-Draft           HTTP/1.1 Range Requests           February 2013
842
843
844   o  Name
845
846   o  Description
847
848   o  Pointer to specification text
849
850   Values to be added to this name space require IETF Review (see
851   [RFC5226], Section 4.1).
852
8535.1.2.  Registrations
854
855   The initial HTTP Range Unit Registry shall contain the registrations
856   below:
857
858   +-------------+---------------------------------------+-------------+
859   | Range Unit  | Description                           | Reference   |
860   | Name        |                                       |             |
861   +-------------+---------------------------------------+-------------+
862   | bytes       | a range of octets                     | Section 2.1 |
863   | none        | reserved as keyword, indicating no    | Section 2.3 |
864   |             | ranges are supported                  |             |
865   +-------------+---------------------------------------+-------------+
866
867   The change controller is: "IETF (iesg@ietf.org) - Internet
868   Engineering Task Force".
869
8705.2.  Status Code Registration
871
872   The HTTP Status Code Registry located at
873   <http://www.iana.org/assignments/http-status-codes> shall be updated
874   with the registrations below:
875
876   +-------+-----------------------+-------------+
877   | Value | Description           | Reference   |
878   +-------+-----------------------+-------------+
879   | 206   | Partial Content       | Section 4.1 |
880   | 416   | Range Not Satisfiable | Section 4.4 |
881   +-------+-----------------------+-------------+
882
8835.3.  Header Field Registration
884
885   The Message Header Field Registry located at <http://www.iana.org/
886   assignments/message-headers/message-header-index.html> shall be
887   updated with the permanent registrations below (see [BCP90]):
888
889
890
891
892
893
894
895Fielding, et al.         Expires August 27, 2013               [Page 16]
896
897Internet-Draft           HTTP/1.1 Range Requests           February 2013
898
899
900   +-------------------+----------+----------+-------------+
901   | Header Field Name | Protocol | Status   | Reference   |
902   +-------------------+----------+----------+-------------+
903   | Accept-Ranges     | http     | standard | Section 2.3 |
904   | Content-Range     | http     | standard | Section 4.2 |
905   | If-Range          | http     | standard | Section 3.2 |
906   | Range             | http     | standard | Section 3.1 |
907   +-------------------+----------+----------+-------------+
908
909   The change controller is: "IETF (iesg@ietf.org) - Internet
910   Engineering Task Force".
911
9126.  Security Considerations
913
914   This section is meant to inform developers, information providers,
915   and users of known security concerns specific to the HTTP/1.1 range
916   request mechanisms.  More general security considerations are
917   addressed in HTTP messaging [Part1] and semantics [Part2].
918
9196.1.  Denial of Service Attacks using Range
920
921   Unconstrained multiple range requests are susceptible to denial of
922   service attacks because the effort required to request many
923   overlapping ranges of the same data is tiny compared to the time,
924   memory, and bandwidth consumed by attempting to serve the requested
925   data in many parts.  Servers ought to ignore, coalesce, or reject
926   egregious range requests, such as requests for more than two
927   overlapping ranges or for many small ranges in a single set,
928   particularly when the ranges are requested out of order for no
929   apparent reason.  Multipart range requests are not designed to
930   support random access.
931
9327.  Acknowledgments
933
934   See Section 9 of [Part1].
935
9368.  References
937
9388.1.  Normative References
939
940   [Part1]    Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
941              Protocol (HTTP/1.1): Message Syntax and Routing",
942              draft-ietf-httpbis-p1-messaging-22 (work in progress),
943              February 2013.
944
945   [Part2]    Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
946              Protocol (HTTP/1.1): Semantics and Content",
947              draft-ietf-httpbis-p2-semantics-22 (work in progress),
948
949
950
951Fielding, et al.         Expires August 27, 2013               [Page 17]
952
953Internet-Draft           HTTP/1.1 Range Requests           February 2013
954
955
956              February 2013.
957
958   [Part4]    Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
959              Protocol (HTTP/1.1): Conditional Requests",
960              draft-ietf-httpbis-p4-conditional-22 (work in progress),
961              February 2013.
962
963   [Part6]    Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
964              Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
965              draft-ietf-httpbis-p6-cache-22 (work in progress),
966              February 2013.
967
968   [RFC2046]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
969              Extensions (MIME) Part Two: Media Types", RFC 2046,
970              November 1996.
971
972   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
973              Requirement Levels", BCP 14, RFC 2119, March 1997.
974
975   [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
976              Specifications: ABNF", STD 68, RFC 5234, January 2008.
977
9788.2.  Informative References
979
980   [BCP13]    Freed, N., Klensin, J., and T. Hansen, "Media Type
981              Specifications and Registration Procedures", BCP 13,
982              RFC 6838, January 2013.
983
984   [BCP90]    Klyne, G., Nottingham, M., and J. Mogul, "Registration
985              Procedures for Message Header Fields", BCP 90, RFC 3864,
986              September 2004.
987
988   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
989              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
990              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
991
992   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
993              IANA Considerations Section in RFCs", BCP 26, RFC 5226,
994              May 2008.
995
996Appendix A.  Internet Media Type multipart/byteranges
997
998   When a 206 (Partial Content) response message includes the content of
999   multiple ranges, they are transmitted as body parts in a multipart
1000   message body ([RFC2046], Section 5.1) with the media type of
1001   "multipart/byteranges".  The following definition is to be registered
1002   with IANA [BCP13].
1003
1004
1005
1006
1007Fielding, et al.         Expires August 27, 2013               [Page 18]
1008
1009Internet-Draft           HTTP/1.1 Range Requests           February 2013
1010
1011
1012   The multipart/byteranges media type includes one or more body parts,
1013   each with its own Content-Type and Content-Range fields.  The
1014   required boundary parameter specifies the boundary string used to
1015   separate each body part.
1016
1017   Type name:  multipart
1018
1019   Subtype name:  byteranges
1020
1021   Required parameters:  boundary
1022
1023   Optional parameters:  none
1024
1025   Encoding considerations:  only "7bit", "8bit", or "binary" are
1026      permitted
1027
1028   Security considerations:  none
1029
1030   Interoperability considerations:  none
1031
1032   Published specification:  This specification (see Appendix A).
1033
1034   Applications that use this media type:  HTTP components supporting
1035      multiple ranges in a single request.
1036
1037   Additional information:
1038
1039      Magic number(s):  none
1040
1041      File extension(s):  none
1042
1043      Macintosh file type code(s):  none
1044
1045   Person and email address to contact for further information:  See
1046      Authors Section.
1047
1048   Intended usage:  COMMON
1049
1050   Restrictions on usage:  none
1051
1052   Author/Change controller:  IESG
1053
1054   Implementation Notes:
1055
1056   1.  Additional CRLFs might precede the first boundary string in the
1057       body.
1058
1059
1060
1061
1062
1063Fielding, et al.         Expires August 27, 2013               [Page 19]
1064
1065Internet-Draft           HTTP/1.1 Range Requests           February 2013
1066
1067
1068   2.  Although [RFC2046] permits the boundary string to be quoted, some
1069       existing implementations handle a quoted boundary string
1070       incorrectly.
1071
1072   3.  A number of clients and servers were coded to an early draft of
1073       the byteranges specification that used a media type of multipart/
1074       x-byteranges, which is almost (but not quite) compatible with
1075       this type.
1076
1077   Despite the name, the "multipart/byteranges" media type is not
1078   limited to byte ranges.  The following example uses an "exampleunit"
1079   range unit:
1080
1081     HTTP/1.1 206 Partial Content
1082     Date: Tue, 14 Nov 1995 06:25:24 GMT
1083     Last-Modified: Tue, 14 July 04:58:08 GMT
1084     Content-Length: 2331785
1085     Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES
1086
1087     --THIS_STRING_SEPARATES
1088     Content-Type: video/example
1089     Content-Range: exampleunit 1.2-4.3/25
1090
1091     ...the first range...
1092     --THIS_STRING_SEPARATES
1093     Content-Type: video/example
1094     Content-Range: exampleunit 11.2-14.3/25
1095
1096     ...the second range
1097     --THIS_STRING_SEPARATES--
1098
1099Appendix B.  Changes from RFC 2616
1100
1101   A weak validator cannot be used in a 206 response.  (Section 4.1)
1102
1103   The Content-Range header field only has meaning when the status code
1104   explicitly defines its use.  (Section 4.2)
1105
1106   Servers are given more leeway in how they respond to a range request,
1107   in order to mitigate abuse by malicious (or just greedy) clients.
1108
1109   multipart/byteranges can consist of a single part.  (Appendix A)
1110
1111   This specification introduces a Range Unit Registry.  (Section 5.1)
1112
1113
1114
1115
1116
1117
1118
1119Fielding, et al.         Expires August 27, 2013               [Page 20]
1120
1121Internet-Draft           HTTP/1.1 Range Requests           February 2013
1122
1123
1124Appendix C.  Imported ABNF
1125
1126   The following core rules are included by reference, as defined in
1127   Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return),
1128   CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double
1129   quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any
1130   8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII
1131   character).
1132
1133   Note that all rules derived from token are to be compared case-
1134   insensitively, like range-unit and acceptable-ranges.
1135
1136   The rules below are defined in [Part1]:
1137
1138     OWS        = <OWS, defined in [Part1], Section 3.2.3>
1139     token      = <token, defined in [Part1], Section 3.2.6>
1140
1141   The rules below are defined in other parts:
1142
1143     HTTP-date  = <HTTP-date, defined in [Part2], Section 7.1.1.1>
1144     entity-tag = <entity-tag, defined in [Part4], Section 2.3>
1145
1146Appendix D.  Collected ABNF
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175Fielding, et al.         Expires August 27, 2013               [Page 21]
1176
1177Internet-Draft           HTTP/1.1 Range Requests           February 2013
1178
1179
1180   Accept-Ranges = acceptable-ranges
1181
1182   Content-Range = byte-content-range / other-content-range
1183
1184   HTTP-date = <HTTP-date, defined in [Part2], Section 7.1.1.1>
1185
1186   If-Range = entity-tag / HTTP-date
1187
1188   OWS = <OWS, defined in [Part1], Section 3.2.3>
1189
1190   Range = byte-ranges-specifier / other-ranges-specifier
1191
1192   acceptable-ranges = ( *( "," OWS ) range-unit *( OWS "," [ OWS
1193    range-unit ] ) ) / "none"
1194
1195   byte-content-range = bytes-unit SP ( byte-range-resp /
1196    unsatisfied-range )
1197   byte-range = first-byte-pos "-" last-byte-pos
1198   byte-range-resp = byte-range "/" ( complete-length / "*" )
1199   byte-range-set = *( "," OWS ) ( byte-range-spec /
1200    suffix-byte-range-spec ) *( OWS "," [ OWS ( byte-range-spec /
1201    suffix-byte-range-spec ) ] )
1202   byte-range-spec = first-byte-pos "-" [ last-byte-pos ]
1203   byte-ranges-specifier = bytes-unit "=" byte-range-set
1204   bytes-unit = "bytes"
1205
1206   complete-length = 1*DIGIT
1207
1208   entity-tag = <entity-tag, defined in [Part4], Section 2.3>
1209
1210   first-byte-pos = 1*DIGIT
1211
1212   last-byte-pos = 1*DIGIT
1213
1214   other-content-range = other-range-unit SP other-range-resp
1215   other-range-resp = *CHAR
1216   other-range-set = 1*CHAR
1217   other-range-unit = token
1218   other-ranges-specifier = other-range-unit "=" other-range-set
1219
1220   range-unit = bytes-unit / other-range-unit
1221
1222   suffix-byte-range-spec = "-" suffix-length
1223   suffix-length = 1*DIGIT
1224
1225   token = <token, defined in [Part1], Section 3.2.6>
1226
1227   unsatisfied-range = "*/" complete-length
1228
1229
1230
1231Fielding, et al.         Expires August 27, 2013               [Page 22]
1232
1233Internet-Draft           HTTP/1.1 Range Requests           February 2013
1234
1235
1236Appendix E.  Change Log (to be removed by RFC Editor before publication)
1237
1238   Changes up to the first Working Group Last Call draft are summarized
1239   in <http://tools.ietf.org/html/
1240   draft-ietf-httpbis-p5-range-19#appendix-D>.
1241
1242E.1.  Since draft-ietf-httpbis-p5-range-19
1243
1244   Closed issues:
1245
1246   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/358>: "ABNF list
1247      expansion code problem"
1248
1249   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/361>: "ABNF
1250      requirements for recipients"
1251
1252   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/367>: "reserve
1253      'none' as byte range unit"
1254
1255   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/368>: "note
1256      introduction of new IANA registries as normative changes"
1257
1258   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/369>: "range units
1259      vs leading zeroes vs size"
1260
1261E.2.  Since draft-ietf-httpbis-p5-range-20
1262
1263   o  Conformance criteria and considerations regarding error handling
1264      are now defined in Part 1.
1265
1266E.3.  Since draft-ietf-httpbis-p5-range-21
1267
1268   Closed issues:
1269
1270   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/175>: "Security
1271      consideration: range flooding"
1272
1273   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/223>: "Allowing
1274      heuristic caching for new status codes"
1275
1276   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/311>: "Add
1277      limitations to Range to reduce its use as a denial-of-service
1278      tool"
1279
1280Index
1281
1282   2
1283      206 Partial Content (status code)  10
1284
1285
1286
1287Fielding, et al.         Expires August 27, 2013               [Page 23]
1288
1289Internet-Draft           HTTP/1.1 Range Requests           February 2013
1290
1291
1292   4
1293      416 Range Not Satisfiable (status code)  15
1294
1295   A
1296      Accept-Ranges header field  7
1297
1298   C
1299      Content-Range header field  12
1300
1301   G
1302      Grammar
1303         Accept-Ranges  7
1304         acceptable-ranges  7
1305         byte-content-range  12
1306         byte-range  12
1307         byte-range-resp  12
1308         byte-range-set  5
1309         byte-range-spec  5
1310         byte-ranges-specifier  5
1311         bytes-unit  5
1312         complete-length  12
1313         Content-Range  12
1314         first-byte-pos  5
1315         If-Range  9
1316         last-byte-pos  5
1317         other-content-range  12
1318         other-range-resp  12
1319         other-range-unit  5, 7
1320         Range  7
1321         range-unit  5
1322         ranges-specifier  5
1323         suffix-byte-range-spec  6
1324         suffix-length  6
1325         unsatisfied-range  12
1326
1327   I
1328      If-Range header field  9
1329
1330   M
1331      Media Type
1332         multipart/byteranges  18
1333         multipart/x-byteranges  20
1334      multipart/byteranges Media Type  18
1335      multipart/x-byteranges Media Type  20
1336
1337   R
1338      Range header field  7
1339
1340
1341
1342
1343Fielding, et al.         Expires August 27, 2013               [Page 24]
1344
1345Internet-Draft           HTTP/1.1 Range Requests           February 2013
1346
1347
1348Authors' Addresses
1349
1350   Roy T. Fielding (editor)
1351   Adobe Systems Incorporated
1352   345 Park Ave
1353   San Jose, CA  95110
1354   USA
1355
1356   EMail: fielding@gbiv.com
1357   URI:   http://roy.gbiv.com/
1358
1359
1360   Yves Lafon (editor)
1361   World Wide Web Consortium
1362   W3C / ERCIM
1363   2004, rte des Lucioles
1364   Sophia-Antipolis, AM  06902
1365   France
1366
1367   EMail: ylafon@w3.org
1368   URI:   http://www.raubacapeu.net/people/yves/
1369
1370
1371   Julian F. Reschke (editor)
1372   greenbytes GmbH
1373   Hafenweg 16
1374   Muenster, NW  48155
1375   Germany
1376
1377   EMail: julian.reschke@greenbytes.de
1378   URI:   http://greenbytes.de/tech/webdav/
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399Fielding, et al.         Expires August 27, 2013               [Page 25]
1400
Note: See TracBrowser for help on using the repository browser.