source: draft-ietf-httpbis/latest/p5-range.xml @ 99

Last change on this file since 99 was 99, checked in by julian.reschke@…, 12 years ago

Use consistent "Changes" sections throughout.

  • Property svn:eol-style set to native
File size: 41.8 KB
Line 
1<?xml version="1.0" encoding="utf-8"?>
2<!DOCTYPE rfc [
3  <!ENTITY MAY "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>MAY</bcp14>">
4  <!ENTITY MUST "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>MUST</bcp14>">
5  <!ENTITY MUST-NOT "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>MUST NOT</bcp14>">
6  <!ENTITY OPTIONAL "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>OPTIONAL</bcp14>">
7  <!ENTITY RECOMMENDED "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>RECOMMENDED</bcp14>">
8  <!ENTITY REQUIRED "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>REQUIRED</bcp14>">
9  <!ENTITY SHALL "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>SHALL</bcp14>">
10  <!ENTITY SHALL-NOT "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>SHALL NOT</bcp14>">
11  <!ENTITY SHOULD "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>SHOULD</bcp14>">
12  <!ENTITY SHOULD-NOT "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>SHOULD NOT</bcp14>">
13  <!ENTITY ID-VERSION "latest">
14  <!ENTITY ID-MONTH "December">
15  <!ENTITY ID-YEAR "2007">
16  <!ENTITY messaging                  "<xref target='Part1' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
17  <!ENTITY weak-and-strong-validators "<xref target='Part4' x:rel='#weak.and.strong.validators' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
18]>
19<?rfc toc="yes" ?>
20<?rfc symrefs="yes" ?>
21<?rfc sortrefs="yes" ?>
22<?rfc compact="yes"?>
23<?rfc subcompact="no" ?>
24<?rfc linkmailto="no" ?>
25<?rfc editing="no" ?>
26<?rfc-ext allow-markup-in-artwork="yes" ?>
27<?rfc-ext include-references-in-index="yes" ?>
28<rfc obsoletes="2068, 2616" category="std"
29     ipr="full3978" docName="draft-ietf-httpbis-p5-range-&ID-VERSION;"
30     xmlns:x='http://purl.org/net/xml2rfc/ext' xmlns:ed="http://greenbytes.de/2002/rfcedit">
31<front>
32
33  <title abbrev="HTTP/1.1">HTTP/1.1, part 5: Range Requests and Partial Responses</title>
34
35  <author initials="R." surname="Fielding" fullname="Roy T. Fielding" role="editor">
36    <organization abbrev="Day Software">Day Software</organization>
37    <address>
38      <postal>
39        <street>23 Corporate Plaza DR, Suite 280</street>
40        <city>Newport Beach</city>
41        <region>CA</region>
42        <code>92660</code>
43        <country>USA</country>
44      </postal>
45      <phone>+1-949-706-5300</phone>
46      <facsimile>+1-949-706-5305</facsimile>
47      <email>fielding@gbiv.com</email>
48      <uri>http://roy.gbiv.com/</uri>
49    </address>
50  </author>
51
52  <author initials="J." surname="Gettys" fullname="Jim Gettys">
53    <organization>One Laptop per Child</organization>
54    <address>
55      <postal>
56        <street>21 Oak Knoll Road</street>
57        <city>Carlisle</city>
58        <region>MA</region>
59        <code>01741</code>
60        <country>USA</country>
61      </postal>
62      <email>jg@laptop.org</email>
63      <uri>http://www.laptop.org/</uri>
64    </address>
65  </author>
66 
67  <author initials="J." surname="Mogul" fullname="Jeffrey C. Mogul">
68    <organization abbrev="HP">Hewlett-Packard Company</organization>
69    <address>
70      <postal>
71        <street>HP Labs, Large Scale Systems Group</street>
72        <street>1501 Page Mill Road, MS 1177</street>
73        <city>Palo Alto</city>
74        <region>CA</region>
75        <code>94304</code>
76        <country>USA</country>
77      </postal>
78      <email>JeffMogul@acm.org</email>
79    </address>
80  </author>
81
82  <author initials="H." surname="Frystyk" fullname="Henrik Frystyk Nielsen">
83    <organization abbrev="Microsoft">Microsoft Corporation</organization>
84    <address>
85      <postal>
86        <street>1 Microsoft Way</street>
87        <city>Redmond</city>
88        <region>WA</region>
89        <code>98052</code>
90        <country>USA</country>
91      </postal>
92      <email>henrikn@microsoft.com</email>
93    </address>
94  </author>
95
96  <author initials="L." surname="Masinter" fullname="Larry Masinter">
97    <organization abbrev="Adobe Systems">Adobe Systems, Incorporated</organization>
98    <address>
99      <postal>
100        <street>345 Park Ave</street>
101        <city>San Jose</city>
102        <region>CA</region>
103        <code>95110</code>
104        <country>USA</country>
105      </postal>
106      <email>LMM@acm.org</email>
107      <uri>http://larry.masinter.net/</uri>
108    </address>
109  </author>
110 
111  <author initials="P." surname="Leach" fullname="Paul J. Leach">
112    <organization abbrev="Microsoft">Microsoft Corporation</organization>
113    <address>
114      <postal>
115        <street>1 Microsoft Way</street>
116        <city>Redmond</city>
117        <region>WA</region>
118        <code>98052</code>
119      </postal>
120      <email>paulle@microsoft.com</email>
121    </address>
122  </author>
123   
124  <author initials="T." surname="Berners-Lee" fullname="Tim Berners-Lee">
125    <organization abbrev="W3C/MIT">World Wide Web Consortium</organization>
126    <address>
127      <postal>
128        <street>MIT Computer Science and Artificial Intelligence Laboratory</street>
129        <street>The Stata Center, Building 32</street>
130        <street>32 Vassar Street</street>
131        <city>Cambridge</city>
132        <region>MA</region>
133        <code>02139</code>
134        <country>USA</country>
135      </postal>
136      <email>timbl@w3.org</email>
137      <uri>http://www.w3.org/People/Berners-Lee/</uri>
138    </address>
139  </author>
140
141  <author initials="Y." surname="Lafon" fullname="Yves Lafon" role="editor">
142    <organization abbrev="W3C">World Wide Web Consortium</organization>
143    <address>
144      <postal>
145        <street>W3C / ERCIM</street>
146        <street>2004, rte des Lucioles</street>
147        <city>Sophia-Antipolis</city>
148        <region>AM</region>
149        <code>06902</code>
150        <country>France</country>
151      </postal>
152      <email>ylafon@w3.org</email>
153      <uri>http://www.raubacapeu.net/people/yves/</uri>
154    </address>
155  </author>
156
157  <author initials="J. F." surname="Reschke" fullname="Julian F. Reschke" role="editor">
158    <organization abbrev="greenbytes">greenbytes GmbH</organization>
159    <address>
160      <postal>
161        <street>Hafenweg 16</street>
162        <city>Muenster</city><region>NW</region><code>48155</code>
163        <country>Germany</country>
164      </postal>
165      <phone>+49 251 2807760</phone>   
166      <facsimile>+49 251 2807761</facsimile>   
167      <email>julian.reschke@greenbytes.de</email>       
168      <uri>http://greenbytes.de/tech/webdav/</uri>     
169    </address>
170  </author>
171
172  <date month="&ID-MONTH;" year="&ID-YEAR;"/>
173
174<abstract>
175<t>
176   The Hypertext Transfer Protocol (HTTP) is an application-level
177   protocol for distributed, collaborative, hypermedia information
178   systems. HTTP has been in use by the World Wide Web global information
179   initiative since 1990. This document is Part 5 of the seven-part specification
180   that defines the protocol referred to as "HTTP/1.1" and, taken together,
181   obsoletes RFC 2616.  Part 5 defines range-specific requests and
182   the rules for constructing and combining responses to those requests.
183</t>
184</abstract>
185
186<note title="Editorial Note (To be removed by RFC Editor)">
187  <t>
188    This version of the HTTP specification contains only minimal editorial
189    changes from <xref target="RFC2616"/> (abstract, introductory paragraph,
190    and authors' addresses).  All other changes are due to partitioning the
191    original into seven mostly independent parts.  The intent is for readers
192    of future drafts to able to use draft 00 as the basis for comparison
193    when the WG makes later changes to the specification text.  This draft
194    will shortly be followed by draft 01 (containing the first round of changes
195    that have already been agreed to on the mailing list). There is no point in
196    reviewing this draft other than to verify that the partitioning has been
197    done correctly.  Roy T. Fielding, Yves Lafon, and Julian Reschke
198    will be the editors after draft 00 is submitted.
199  </t>
200  <t>
201    Discussion of this draft should take place on the HTTPBIS working group
202    mailing list (ietf-http-wg@w3.org). The current issues list is
203    at <eref target="http://www3.tools.ietf.org/wg/httpbis/trac/report/11"/>
204    and related documents (including fancy diffs) can be found at
205    <eref target="http://www3.tools.ietf.org/wg/httpbis/"/>.
206  </t>
207</note>
208</front>
209<middle>
210<section title="Introduction" anchor="introduction">
211<t>
212   This document will define aspects of HTTP related to range requests,
213   partial responses, and the multipart/byteranges media type.  Right now
214   it only includes the extracted relevant sections of
215   <xref target="RFC2616">RFC 2616</xref> without edit.
216</t>
217
218<section title="Requirements" anchor="intro.requirements">
219<t>
220   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
221   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
222   document are to be interpreted as described in <xref target="RFC2119"/>.
223</t>
224<t>
225   An implementation is not compliant if it fails to satisfy one or more
226   of the &MUST; or &REQUIRED; level requirements for the protocols it
227   implements. An implementation that satisfies all the &MUST; or &REQUIRED;
228   level and all the &SHOULD; level requirements for its protocols is said
229   to be "unconditionally compliant"; one that satisfies all the &MUST;
230   level requirements but not all the &SHOULD; level requirements for its
231   protocols is said to be "conditionally compliant."
232</t>
233</section>
234</section>
235
236<section title="Range Units" anchor="range.units">
237<t>
238   HTTP/1.1 allows a client to request that only part (a range of) the
239   response entity be included within the response. HTTP/1.1 uses range
240   units in the Range (<xref target="header.range"/>) and Content-Range (<xref target="header.content-range"/>)
241   header fields. An entity can be broken down into subranges according
242   to various structural units.
243</t>
244<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="range-unit"/><iref primary="true" item="Grammar" subitem="bytes-unit"/><iref primary="true" item="Grammar" subitem="other-range-unit"/>
245   range-unit       = bytes-unit | other-range-unit
246   bytes-unit       = "bytes"
247   other-range-unit = token
248</artwork></figure>
249<t>
250   The only range unit defined by HTTP/1.1 is "bytes". HTTP/1.1
251   implementations &MAY; ignore ranges specified using other units.
252</t>
253<t>
254   HTTP/1.1 has been designed to allow implementations of applications
255   that do not depend on knowledge of ranges.
256</t>
257</section>
258
259<section title="Status Code Definitions">
260<section title="206 Partial Content" anchor="status.206">
261  <iref primary="true" item="206 Partial Content (status code)" x:for-anchor=""/>
262  <iref primary="true" item="Status Codes" subitem="206 Partial Content" x:for-anchor=""/>
263<t>
264   The server has fulfilled the partial GET request for the resource.
265   The request &MUST; have included a Range header field (<xref target="header.range"/>)
266   indicating the desired range, and &MAY; have included an If-Range
267   header field (<xref target="header.if-range"/>) to make the request conditional.
268</t>
269<t>
270   The response &MUST; include the following header fields:
271  <list style="symbols">
272    <t>
273        Either a Content-Range header field (<xref target="header.content-range"/>) indicating
274        the range included with this response, or a multipart/byteranges
275        Content-Type including Content-Range fields for each part. If a
276        Content-Length header field is present in the response, its
277        value &MUST; match the actual number of OCTETs transmitted in the
278        message-body.
279    </t>
280    <t>
281        Date
282    </t>
283    <t>
284        ETag and/or Content-Location, if the header would have been sent
285        in a 200 response to the same request
286    </t>
287    <t>
288        Expires, Cache-Control, and/or Vary, if the field-value might
289        differ from that sent in any previous response for the same
290        variant
291    </t>
292  </list>
293</t>
294<t>
295   If the 206 response is the result of an If-Range request, the response
296   &SHOULD-NOT; include other entity-headers. Otherwise, the response
297   &MUST; include all of the entity-headers that would have been returned
298   with a 200 (OK) response to the same request.
299</t>
300<t>
301   A cache &MUST-NOT; combine a 206 response with other previously cached
302   content if the ETag or Last-Modified headers do not match exactly,
303   see <xref target="combining.byte.ranges" format="counter"/>.
304</t>
305<t>
306   A cache that does not support the Range and Content-Range headers
307   &MUST-NOT; cache 206 (Partial) responses.
308</t>
309</section>
310
311<section title="416 Requested Range Not Satisfiable" anchor="status.416">
312  <iref primary="true" item="416 Requested Range Not Satisfiable (status code)" x:for-anchor=""/>
313  <iref primary="true" item="Status Codes" subitem="416 Requested Range Not Satisfiable" x:for-anchor=""/>
314<t>
315   A server &SHOULD; return a response with this status code if a request
316   included a Range request-header field (<xref target="header.range"/>), and none of
317   the range-specifier values in this field overlap the current extent
318   of the selected resource, and the request did not include an If-Range
319   request-header field. (For byte-ranges, this means that the first-byte-pos
320   of all of the byte-range-spec values were greater than the
321   current length of the selected resource.)
322</t>
323<t>
324   When this status code is returned for a byte-range request, the
325   response &SHOULD; include a Content-Range entity-header field
326   specifying the current length of the selected resource (see <xref target="header.content-range"/>).
327   This response &MUST-NOT; use the multipart/byteranges content-type.
328</t>
329</section>
330</section>
331
332<section title="Combining Byte Ranges" anchor="combining.byte.ranges">
333<t>
334   A response might transfer only a subrange of the bytes of an entity-body,
335   either because the request included one or more Range
336   specifications, or because a connection was broken prematurely. After
337   several such transfers, a cache might have received several ranges of
338   the same entity-body.
339</t>
340<t>
341   If a cache has a stored non-empty set of subranges for an entity, and
342   an incoming response transfers another subrange, the cache &MAY;
343   combine the new subrange with the existing set if both the following
344   conditions are met:
345  <list style="symbols">
346    <t>Both the incoming response and the cache entry have a cache
347        validator.</t>
348    <t>The two cache validators match using the strong comparison
349        function (see &weak-and-strong-validators;).</t>
350  </list>
351</t>
352<t>
353   If either requirement is not met, the cache &MUST; use only the most
354   recent partial response (based on the Date values transmitted with
355   every response, and using the incoming response if these values are
356   equal or missing), and &MUST; discard the other partial information.
357</t>
358</section>
359
360<section title="Header Field Definitions" anchor="header.fields">
361<t>
362   This section defines the syntax and semantics of all standard
363   HTTP/1.1 header fields. For entity-header fields, both sender and
364   recipient refer to either the client or the server, depending on who
365   sends and who receives the entity.
366</t>
367<section title="Accept-Ranges" anchor="header.accept-ranges">
368  <iref primary="true" item="Accept-Ranges header" x:for-anchor=""/>
369  <iref primary="true" item="Headers" subitem="Accept-Ranges" x:for-anchor=""/>
370<t>
371      The Accept-Ranges response-header field allows the server to
372      indicate its acceptance of range requests for a resource:
373</t>
374<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Accept-Ranges"/><iref primary="true" item="Grammar" subitem="acceptable-ranges"/>
375       Accept-Ranges     = "Accept-Ranges" ":" acceptable-ranges
376       acceptable-ranges = 1#range-unit | "none"
377</artwork></figure>
378<t>
379      Origin servers that accept byte-range requests &MAY; send
380</t>
381<figure><artwork type="example">
382       Accept-Ranges: bytes
383</artwork></figure>
384<t>
385      but are not required to do so. Clients &MAY; generate byte-range
386      requests without having received this header for the resource
387      involved. Range units are defined in <xref target="range.units"/>.
388</t>
389<t>
390      Servers that do not accept any kind of range request for a
391      resource &MAY; send
392</t>
393<figure><artwork type="example">
394       Accept-Ranges: none
395</artwork></figure>
396<t>
397      to advise the client not to attempt a range request.
398</t>
399</section>
400
401<section title="Content-Range" anchor="header.content-range">
402  <iref primary="true" item="Content-Range header" x:for-anchor=""/>
403  <iref primary="true" item="Headers" subitem="Content-Range" x:for-anchor=""/>
404<t>
405   The Content-Range entity-header is sent with a partial entity-body to
406   specify where in the full entity-body the partial body should be
407   applied. Range units are defined in <xref target="range.units"/>.
408</t>
409<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Content-Range"/><iref primary="true" item="Grammar" subitem="content-range-spec"/><iref primary="true" item="Grammar" subitem="byte-content-range-spec"/><iref primary="true" item="Grammar" subitem="byte-range-resp-spec"/><iref primary="true" item="Grammar" subitem="instance-length"/>
410    Content-Range = "Content-Range" ":" content-range-spec
411
412    content-range-spec      = byte-content-range-spec
413    byte-content-range-spec = bytes-unit SP
414                              byte-range-resp-spec "/"
415                              ( instance-length | "*" )
416
417    byte-range-resp-spec = (first-byte-pos "-" last-byte-pos)
418                                   | "*"
419    instance-length           = 1*DIGIT
420</artwork></figure>
421<t>
422   The header &SHOULD; indicate the total length of the full entity-body,
423   unless this length is unknown or difficult to determine. The asterisk
424   "*" character means that the instance-length is unknown at the time
425   when the response was generated.
426</t>
427<t>
428   Unlike byte-ranges-specifier values (see <xref target="byte.ranges"/>), a byte-range-resp-spec
429   &MUST; only specify one range, and &MUST; contain
430   absolute byte positions for both the first and last byte of the
431   range.
432</t>
433<t>
434   A byte-content-range-spec with a byte-range-resp-spec whose last-byte-pos
435   value is less than its first-byte-pos value, or whose
436   instance-length value is less than or equal to its last-byte-pos
437   value, is invalid. The recipient of an invalid byte-content-range-spec
438   &MUST; ignore it and any content transferred along with it.
439</t>
440<t>
441   A server sending a response with status code 416 (Requested range not
442   satisfiable) &SHOULD; include a Content-Range field with a byte-range-resp-spec
443   of "*". The instance-length specifies the current length of
444   the selected resource. A response with status code 206 (Partial
445   Content) &MUST-NOT; include a Content-Range field with a byte-range-resp-spec of "*".
446</t>
447<t>
448   Examples of byte-content-range-spec values, assuming that the entity
449   contains a total of 1234 bytes:
450   <list style="symbols">
451      <t>
452        The first 500 bytes:
453<figure><artwork type="text/plain">
454   bytes 0-499/1234
455</artwork></figure>
456      </t>   
457      <t>
458        The second 500 bytes:
459<figure><artwork type="text/plain">
460   bytes 500-999/1234
461</artwork></figure>
462      </t>   
463      <t>
464        All except for the first 500 bytes:
465<figure><artwork type="text/plain">
466   bytes 500-1233/1234
467</artwork></figure>
468      </t>   
469      <t>
470        The last 500 bytes:
471<figure><artwork type="text/plain">
472   bytes 734-1233/1234
473</artwork></figure>
474      </t>   
475   </list>
476</t>
477<t>
478   When an HTTP message includes the content of a single range (for
479   example, a response to a request for a single range, or to a request
480   for a set of ranges that overlap without any holes), this content is
481   transmitted with a Content-Range header, and a Content-Length header
482   showing the number of bytes actually transferred. For example,
483</t>
484<figure><artwork type="example">
485    HTTP/1.1 206 Partial content
486    Date: Wed, 15 Nov 1995 06:25:24 GMT
487    Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
488    Content-Range: bytes 21010-47021/47022
489    Content-Length: 26012
490    Content-Type: image/gif
491</artwork></figure>
492<t>
493   When an HTTP message includes the content of multiple ranges (for
494   example, a response to a request for multiple non-overlapping
495   ranges), these are transmitted as a multipart message. The multipart
496   media type used for this purpose is "multipart/byteranges" as defined
497   in <xref target="internet.media.type.multipart.byteranges"/>. See <xref target="changes.from.rfc.2068"/> for a compatibility issue.
498</t>
499<t>
500   A response to a request for a single range &MUST-NOT; be sent using the
501   multipart/byteranges media type.  A response to a request for
502   multiple ranges, whose result is a single range, &MAY; be sent as a
503   multipart/byteranges media type with one part. A client that cannot
504   decode a multipart/byteranges message &MUST-NOT; ask for multiple
505   byte-ranges in a single request.
506</t>
507<t>
508   When a client requests multiple byte-ranges in one request, the
509   server &SHOULD; return them in the order that they appeared in the
510   request.
511</t>
512<t>
513   If the server ignores a byte-range-spec because it is syntactically
514   invalid, the server &SHOULD; treat the request as if the invalid Range
515   header field did not exist. (Normally, this means return a 200
516   response containing the full entity).
517</t>
518<t>
519   If the server receives a request (other than one including an If-Range
520   request-header field) with an unsatisfiable Range request-header
521   field (that is, all of whose byte-range-spec values have a
522   first-byte-pos value greater than the current length of the selected
523   resource), it &SHOULD; return a response code of 416 (Requested range
524   not satisfiable) (<xref target="status.416"/>).
525  <list><t>
526      <x:h>Note:</x:h> clients cannot depend on servers to send a 416 (Requested
527      range not satisfiable) response instead of a 200 (OK) response for
528      an unsatisfiable Range request-header, since not all servers
529      implement this request-header.
530  </t></list>
531</t>
532</section>
533
534<section title="If-Range" anchor="header.if-range">
535  <iref primary="true" item="If-Range header" x:for-anchor=""/>
536  <iref primary="true" item="Headers" subitem="If-Range" x:for-anchor=""/>
537<t>
538   If a client has a partial copy of an entity in its cache, and wishes
539   to have an up-to-date copy of the entire entity in its cache, it
540   could use the Range request-header with a conditional GET (using
541   either or both of If-Unmodified-Since and If-Match.) However, if the
542   condition fails because the entity has been modified, the client
543   would then have to make a second request to obtain the entire current
544   entity-body.
545</t>
546<t>
547   The If-Range header allows a client to "short-circuit" the second
548   request. Informally, its meaning is `if the entity is unchanged, send
549   me the part(s) that I am missing; otherwise, send me the entire new
550   entity'.
551</t>
552<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="If-Range"/>
553     If-Range = "If-Range" ":" ( entity-tag | HTTP-date )
554</artwork></figure>
555<t>
556   If the client has no entity tag for an entity, but does have a Last-Modified
557   date, it &MAY; use that date in an If-Range header. (The
558   server can distinguish between a valid HTTP-date and any form of
559   entity-tag by examining no more than two characters.) The If-Range
560   header &SHOULD; only be used together with a Range header, and &MUST; be
561   ignored if the request does not include a Range header, or if the
562   server does not support the sub-range operation.
563</t>
564<t>
565   If the entity tag given in the If-Range header matches the current
566   entity tag for the entity, then the server &SHOULD; provide the
567   specified sub-range of the entity using a 206 (Partial content)
568   response. If the entity tag does not match, then the server &SHOULD;
569   return the entire entity using a 200 (OK) response.
570</t>
571</section>
572
573<section title="Range" anchor="header.range">
574  <iref primary="true" item="Range header" x:for-anchor=""/>
575  <iref primary="true" item="Headers" subitem="Range" x:for-anchor=""/>
576
577<section title="Byte Ranges" anchor="byte.ranges">
578<t>
579   Since all HTTP entities are represented in HTTP messages as sequences
580   of bytes, the concept of a byte range is meaningful for any HTTP
581   entity. (However, not all clients and servers need to support byte-range
582   operations.)
583</t>
584<t>
585   Byte range specifications in HTTP apply to the sequence of bytes in
586   the entity-body (not necessarily the same as the message-body).
587</t>
588<t>
589   A byte range operation &MAY; specify a single range of bytes, or a set
590   of ranges within a single entity.
591</t>
592<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="ranges-specifier"/><iref primary="true" item="Grammar" subitem="byte-ranges-specifier"/><iref primary="true" item="Grammar" subitem="byte-range-set"/><iref primary="true" item="Grammar" subitem="byte-range-spec"/><iref primary="true" item="Grammar" subitem="first-byte-pos"/><iref primary="true" item="Grammar" subitem="last-byte-pos"/>
593    ranges-specifier = byte-ranges-specifier
594    byte-ranges-specifier = bytes-unit "=" byte-range-set
595    byte-range-set  = 1#( byte-range-spec | suffix-byte-range-spec )
596    byte-range-spec = first-byte-pos "-" [last-byte-pos]
597    first-byte-pos  = 1*DIGIT
598    last-byte-pos   = 1*DIGIT
599</artwork></figure>
600<t>
601   The first-byte-pos value in a byte-range-spec gives the byte-offset
602   of the first byte in a range. The last-byte-pos value gives the
603   byte-offset of the last byte in the range; that is, the byte
604   positions specified are inclusive. Byte offsets start at zero.
605</t>
606<t>
607   If the last-byte-pos value is present, it &MUST; be greater than or
608   equal to the first-byte-pos in that byte-range-spec, or the byte-range-spec
609   is syntactically invalid. The recipient of a byte-range-set
610   that includes one or more syntactically invalid byte-range-spec
611   values &MUST; ignore the header field that includes that byte-range-set.
612</t>
613<t>
614   If the last-byte-pos value is absent, or if the value is greater than
615   or equal to the current length of the entity-body, last-byte-pos is
616   taken to be equal to one less than the current length of the entity-body
617   in bytes.
618</t>
619<t>
620   By its choice of last-byte-pos, a client can limit the number of
621   bytes retrieved without knowing the size of the entity.
622</t>
623<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="suffix-byte-range-spec"/><iref primary="true" item="Grammar" subitem="suffix-length"/>
624    suffix-byte-range-spec = "-" suffix-length
625    suffix-length = 1*DIGIT
626</artwork></figure>
627<t>
628   A suffix-byte-range-spec is used to specify the suffix of the
629   entity-body, of a length given by the suffix-length value. (That is,
630   this form specifies the last N bytes of an entity-body.) If the
631   entity is shorter than the specified suffix-length, the entire
632   entity-body is used.
633</t>
634<t>
635   If a syntactically valid byte-range-set includes at least one byte-range-spec
636   whose first-byte-pos is less than the current length of
637   the entity-body, or at least one suffix-byte-range-spec with a non-zero
638   suffix-length, then the byte-range-set is satisfiable.
639   Otherwise, the byte-range-set is unsatisfiable. If the byte-range-set
640   is unsatisfiable, the server &SHOULD; return a response with a status
641   of 416 (Requested range not satisfiable). Otherwise, the server
642   &SHOULD; return a response with a status of 206 (Partial Content)
643   containing the satisfiable ranges of the entity-body.
644</t>
645<t>
646   Examples of byte-ranges-specifier values (assuming an entity-body of
647   length 10000):
648  <list style="symbols">
649     <t>The first 500 bytes (byte offsets 0-499, inclusive):  bytes=0-499</t>
650
651     <t>The second 500 bytes (byte offsets 500-999, inclusive):
652        bytes=500-999</t>
653
654     <t>The final 500 bytes (byte offsets 9500-9999, inclusive):
655        bytes=-500</t>
656
657     <t>Or bytes=9500-</t>
658
659     <t>The first and last bytes only (bytes 0 and 9999):  bytes=0-0,-1</t>
660
661     <t>Several legal but not canonical specifications of the second 500
662        bytes (byte offsets 500-999, inclusive):
663        <vspace/>
664         bytes=500-600,601-999<vspace/>
665         bytes=500-700,601-999</t>
666  </list>
667</t>
668</section>
669
670<section title="Range Retrieval Requests" anchor="range.retrieval.requests">
671<t>
672   HTTP retrieval requests using conditional or unconditional GET
673   methods &MAY; request one or more sub-ranges of the entity, instead of
674   the entire entity, using the Range request header, which applies to
675   the entity returned as the result of the request:
676</t>
677<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Range"/>
678   Range = "Range" ":" ranges-specifier
679</artwork></figure>
680<t>
681   A server &MAY; ignore the Range header. However, HTTP/1.1 origin
682   servers and intermediate caches ought to support byte ranges when
683   possible, since Range supports efficient recovery from partially
684   failed transfers, and supports efficient partial retrieval of large
685   entities.
686</t>
687<t>
688   If the server supports the Range header and the specified range or
689   ranges are appropriate for the entity:
690  <list style="symbols">
691     <t>The presence of a Range header in an unconditional GET modifies
692        what is returned if the GET is otherwise successful. In other
693        words, the response carries a status code of 206 (Partial
694        Content) instead of 200 (OK).</t>
695
696     <t>The presence of a Range header in a conditional GET (a request
697        using one or both of If-Modified-Since and If-None-Match, or
698        one or both of If-Unmodified-Since and If-Match) modifies what
699        is returned if the GET is otherwise successful and the
700        condition is true. It does not affect the 304 (Not Modified)
701        response returned if the conditional is false.</t>
702  </list>
703</t>
704<t>
705   In some cases, it might be more appropriate to use the If-Range
706   header (see <xref target="header.if-range"/>) in addition to the Range header.
707</t>
708<t>
709   If a proxy that supports ranges receives a Range request, forwards
710   the request to an inbound server, and receives an entire entity in
711   reply, it &SHOULD; only return the requested range to its client. It
712   &SHOULD; store the entire received response in its cache if that is
713   consistent with its cache allocation policies.
714</t>
715</section>
716</section>
717</section>
718
719<section title="IANA Considerations" anchor="IANA.considerations">
720<t>
721   TBD.
722</t>
723</section>
724
725<section title="Security Considerations" anchor="security.considerations">
726<t>
727   No additional security considerations have been identified beyond
728   those applicable to HTTP in general &messaging;.
729</t>
730</section>
731
732<section title="Acknowledgments" anchor="ack">
733<t>
734   Most of the specification of ranges is based on work originally done
735   by Ari Luotonen and John Franks, with additional input from Steve
736   Zilles.
737</t>
738</section>
739</middle>
740<back>
741<references>
742
743<reference anchor="Part1">
744   <front>
745      <title abbrev="HTTP/1.1">HTTP/1.1, part 1: URIs, Connections, and Message Parsing</title>
746      <author initials="R." surname="Fielding" fullname="Roy T. Fielding" role="editor">
747         <organization abbrev="Day Software">Day Software</organization>
748         <address><email>fielding@gbiv.com</email></address>
749      </author>
750      <author initials="J." surname="Gettys" fullname="Jim Gettys">
751         <organization>One Laptop per Child</organization>
752         <address><email>jg@laptop.org</email></address>
753      </author>
754      <author initials="J." surname="Mogul" fullname="Jeffrey C. Mogul">
755         <organization abbrev="HP">Hewlett-Packard Company</organization>
756         <address><email>JeffMogul@acm.org</email></address>
757      </author>
758      <author initials="H." surname="Frystyk" fullname="Henrik Frystyk Nielsen">
759         <organization abbrev="Microsoft">Microsoft Corporation</organization>
760         <address><email>henrikn@microsoft.com</email></address>
761      </author>
762      <author initials="L." surname="Masinter" fullname="Larry Masinter">
763         <organization abbrev="Adobe Systems">Adobe Systems, Incorporated</organization>
764         <address><email>LMM@acm.org</email></address>
765      </author>
766      <author initials="P." surname="Leach" fullname="Paul J. Leach">
767         <organization abbrev="Microsoft">Microsoft Corporation</organization>
768         <address><email>paulle@microsoft.com</email></address>
769      </author>
770      <author initials="T." surname="Berners-Lee" fullname="Tim Berners-Lee">
771         <organization abbrev="W3C/MIT">World Wide Web Consortium</organization>
772         <address><email>timbl@w3.org</email></address>
773      </author>
774      <author initials="Y." surname="Lafon" fullname="Yves Lafon" role="editor">
775         <organization abbrev="W3C">World Wide Web Consortium</organization>
776         <address><email>ylafon@w3.org</email></address>
777      </author>
778      <author initials="J. F." surname="Reschke" fullname="Julian F. Reschke" role="editor">
779         <organization abbrev="greenbytes">greenbytes GmbH</organization>
780         <address><email>julian.reschke@greenbytes.de</email></address>
781      </author>
782      <date month="&ID-MONTH;" year="&ID-YEAR;"/>
783   </front>
784   <seriesInfo name="Internet-Draft" value="draft-ietf-httpbis-p1-messaging-&ID-VERSION;"/>
785   <x:source href="p1-messaging.xml" basename="p1-messaging"/>
786</reference>
787
788<reference anchor="Part4">
789   <front>
790      <title abbrev="HTTP/1.1">HTTP/1.1, part 4: Conditional Requests</title>
791      <author initials="R." surname="Fielding" fullname="Roy T. Fielding" role="editor">
792         <organization abbrev="Day Software">Day Software</organization>
793         <address><email>fielding@gbiv.com</email></address>
794      </author>
795      <author initials="J." surname="Gettys" fullname="Jim Gettys">
796         <organization>One Laptop per Child</organization>
797         <address><email>jg@laptop.org</email></address>
798      </author>
799      <author initials="J." surname="Mogul" fullname="Jeffrey C. Mogul">
800         <organization abbrev="HP">Hewlett-Packard Company</organization>
801         <address><email>JeffMogul@acm.org</email></address>
802      </author>
803      <author initials="H." surname="Frystyk" fullname="Henrik Frystyk Nielsen">
804         <organization abbrev="Microsoft">Microsoft Corporation</organization>
805         <address><email>henrikn@microsoft.com</email></address>
806      </author>
807      <author initials="L." surname="Masinter" fullname="Larry Masinter">
808         <organization abbrev="Adobe Systems">Adobe Systems, Incorporated</organization>
809         <address><email>LMM@acm.org</email></address>
810      </author>
811      <author initials="P." surname="Leach" fullname="Paul J. Leach">
812         <organization abbrev="Microsoft">Microsoft Corporation</organization>
813         <address><email>paulle@microsoft.com</email></address>
814      </author>
815      <author initials="T." surname="Berners-Lee" fullname="Tim Berners-Lee">
816         <organization abbrev="W3C/MIT">World Wide Web Consortium</organization>
817         <address><email>timbl@w3.org</email></address>
818      </author>
819      <author initials="Y." surname="Lafon" fullname="Yves Lafon" role="editor">
820         <organization abbrev="W3C">World Wide Web Consortium</organization>
821         <address><email>ylafon@w3.org</email></address>
822      </author>
823      <author initials="J. F." surname="Reschke" fullname="Julian F. Reschke" role="editor">
824         <organization abbrev="greenbytes">greenbytes GmbH</organization>
825         <address><email>julian.reschke@greenbytes.de</email></address>
826      </author>
827      <date month="&ID-MONTH;" year="&ID-YEAR;"/>
828   </front>
829   <seriesInfo name="Internet-Draft" value="draft-ietf-httpbis-p4-conditional-&ID-VERSION;"/>
830   <x:source href="p4-conditional.xml" basename="p4-conditional"/>
831</reference>
832
833<reference anchor="RFC2616">
834   <front>
835      <title>Hypertext Transfer Protocol -- HTTP/1.1</title>
836      <author initials="R." surname="Fielding" fullname="R. Fielding">
837         <organization>University of California, Irvine</organization>
838         <address><email>fielding@ics.uci.edu</email></address>
839      </author>
840      <author initials="J." surname="Gettys" fullname="J. Gettys">
841         <organization>W3C</organization>
842         <address><email>jg@w3.org</email></address>
843      </author>
844      <author initials="J." surname="Mogul" fullname="J. Mogul">
845         <organization>Compaq Computer Corporation</organization>
846         <address><email>mogul@wrl.dec.com</email></address>
847      </author>
848      <author initials="H." surname="Frystyk" fullname="H. Frystyk">
849         <organization>MIT Laboratory for Computer Science</organization>
850         <address><email>frystyk@w3.org</email></address>
851      </author>
852      <author initials="L." surname="Masinter" fullname="L. Masinter">
853         <organization>Xerox Corporation</organization>
854         <address><email>masinter@parc.xerox.com</email></address>
855      </author>
856      <author initials="P." surname="Leach" fullname="P. Leach">
857         <organization>Microsoft Corporation</organization>
858         <address><email>paulle@microsoft.com</email></address>
859      </author>
860      <author initials="T." surname="Berners-Lee" fullname="T. Berners-Lee">
861         <organization>W3C</organization>
862         <address><email>timbl@w3.org</email></address>
863      </author>
864      <author initials="Y." surname="Lafon" fullname="Yves Lafon" role="editor">
865         <organization abbrev="W3C">World Wide Web Consortium</organization>
866         <address><email>ylafon@w3.org</email></address>
867      </author>
868      <author initials="J. F." surname="Reschke" fullname="Julian F. Reschke" role="editor">
869         <organization abbrev="greenbytes">greenbytes GmbH</organization>
870         <address><email>julian.reschke@greenbytes.de</email></address>
871      </author>
872      <date month="June" year="1999"/>
873   </front>
874   <seriesInfo name="RFC" value="2616"/>
875</reference>
876
877<reference anchor="RFC2046">
878  <front>
879    <title abbrev="Media Types">Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types</title>
880    <author initials="N." surname="Freed" fullname="Ned Freed">
881      <organization>Innosoft International, Inc.</organization>
882      <address><email>ned@innosoft.com</email></address>
883    </author>
884    <author initials="N." surname="Borenstein" fullname="Nathaniel S. Borenstein">
885      <organization>First Virtual Holdings</organization>
886      <address><email>nsb@nsb.fv.com</email></address>
887    </author>
888    <date month="November" year="1996"/>
889  </front>
890  <seriesInfo name="RFC" value="2046"/>
891</reference>
892
893<reference anchor="RFC2119">
894  <front>
895    <title>Key words for use in RFCs to Indicate Requirement Levels</title>
896    <author initials="S." surname="Bradner" fullname="Scott Bradner">
897      <organization>Harvard University</organization>
898      <address><email>sob@harvard.edu</email></address>
899    </author>
900    <date month="March" year="1997"/>
901  </front>
902  <seriesInfo name="BCP" value="14"/>
903  <seriesInfo name="RFC" value="2119"/>
904</reference>
905
906</references>
907
908<section title="Internet Media Type multipart/byteranges" anchor="internet.media.type.multipart.byteranges">
909<iref item="Media Type" subitem="multipart/byteranges" primary="true"/>
910<iref item="multipart/byteranges Media Type" primary="true"/>
911<t>
912   When an HTTP 206 (Partial Content) response message includes the
913   content of multiple ranges (a response to a request for multiple
914   non-overlapping ranges), these are transmitted as a multipart
915   message-body. The media type for this purpose is called
916   "multipart/byteranges".
917</t><t>
918   The multipart/byteranges media type includes two or more parts, each
919   with its own Content-Type and Content-Range fields. The required
920   boundary parameter specifies the boundary string used to separate
921   each body-part.
922</t>
923<t>
924  <list style="hanging" x:indent="12em">
925    <t hangText="Media Type name:">
926      multipart
927    </t>
928    <t hangText="Media subtype name:">
929      byteranges
930    </t>
931    <t hangText="Required parameters:">
932      boundary
933    </t>
934    <t hangText="Optional parameters:">
935      none
936    </t>
937    <t hangText="Encoding considerations:">
938      only "7bit", "8bit", or "binary" are permitted
939    </t>
940    <t hangText="Security considerations:">
941      none
942    </t>
943  </list>
944</t>
945<figure><preamble>
946   For example:
947</preamble><artwork type="example">
948   HTTP/1.1 206 Partial Content
949   Date: Wed, 15 Nov 1995 06:25:24 GMT
950   Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
951   Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES
952
953   --THIS_STRING_SEPARATES
954   Content-type: application/pdf
955   Content-range: bytes 500-999/8000
956
957   ...the first range...
958   --THIS_STRING_SEPARATES
959   Content-type: application/pdf
960   Content-range: bytes 7000-7999/8000
961
962   ...the second range
963   --THIS_STRING_SEPARATES--
964</artwork></figure>
965<t>
966      Notes:
967  <list style="numbers">
968      <t>Additional CRLFs may precede the first boundary string in the
969         entity.</t>
970
971      <t>Although <xref target="RFC2046"/> permits the boundary string to be
972         quoted, some existing implementations handle a quoted boundary
973         string incorrectly.</t>
974
975      <t>A number of browsers and servers were coded to an early draft
976         of the byteranges specification to use a media type of
977         multipart/x-byteranges<iref item="multipart/x-byteranges Media Type"/><iref item="Media Type" subitem="multipart/x-byteranges"/>, which is almost, but not quite
978         compatible with the version documented in HTTP/1.1.</t>
979  </list>
980</t>
981</section>
982
983<section title="Compatibility with Previous Versions" anchor="compatibility">
984<section title="Changes from RFC 2068" anchor="changes.from.rfc.2068">
985<t>
986   There are situations where a server (especially a proxy) does not
987   know the full length of a response but is capable of serving a
988   byterange request. We therefore need a mechanism to allow byteranges
989   with a content-range not indicating the full length of the message.
990   (<xref target="header.content-range"/>)
991</t>
992<t>
993   Range request responses would become very verbose if all meta-data
994   were always returned; by allowing the server to only send needed
995   headers in a 206 response, this problem can be avoided.
996</t>
997<t>
998   Fix problem with unsatisfiable range requests; there are two cases:
999   syntactic problems, and range doesn't exist in the document. The 416
1000   status code was needed to resolve this ambiguity needed to indicate
1001   an error for a byte range request that falls outside of the actual
1002   contents of a document. (Section <xref target="status.416" format="counter"/>, <xref target="header.content-range" format="counter"/>)
1003</t>
1004</section>
1005
1006<section title="Changes from RFC 2616" anchor="changes.from.rfc.2616">
1007</section>
1008
1009</section>
1010
1011
1012</back>
1013</rfc>
Note: See TracBrowser for help on using the repository browser.