Ignore:
Timestamp:
20/01/13 01:58:48 (8 years ago)
Author:
fielding@…
Message:

Cleanup on aisle p5. Addresses #405

Don't refer to Range Units as Range Specifiers;
move requirements on unknown ranges to the header field definitions.
Disentangle the Content-Range ABNF so that it correctly distinguishes between
the three different forms in use and does not allow them to be mixed.
Use the new ABNF alternatives to simplify the prose.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p5-range.xml

    r2134 r2135  
    184184  <x:anchor-alias value="other-range-unit"/>
    185185  <x:anchor-alias value="range-unit"/>
    186 <t>
    187    HTTP/1.1 allows a client to request that only part (a range) of the
    188    representation be included within the response. HTTP/1.1 uses range
    189    units in the <x:ref>Range</x:ref> (<xref target="header.range"/>) and
     186  <x:anchor-alias value="range unit"/>
     187<t>
     188   A representation can be partitioned into subranges according to various
     189   structural units, depending on the structure inherent in the
     190   representation's media type. Such a <x:dfn>range unit</x:dfn> can be used
     191   in the <x:ref>Range</x:ref> (<xref target="header.range"/>) and
    190192   <x:ref>Content-Range</x:ref> (<xref target="header.content-range"/>)
    191    header fields. A representation can be broken down into subranges according
    192    to various structural units.
     193   header fields to delineate the parts of a representation that are
     194   either requested or transferred, respectively.
    193195</t>
    194196<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"/>
     
    198200</artwork></figure>
    199201<t>
    200   HTTP/1.1 has been designed to allow implementations of applications
    201   that do not depend on knowledge of ranges. The only range unit defined
    202   by HTTP/1.1 is "bytes". Additional specifiers can be defined as described
    203   in <xref target="range.specifier.registry"/>.
    204 </t>
    205 <t>
    206   If a range unit is not understood in a request, a server &MUST; ignore
    207   the whole <x:ref>Range</x:ref> header field (<xref target="header.range"/>).
    208   If a range unit is not understood in a response, an intermediary
    209   &SHOULD; pass the response to the client; a client &MUST; fail.
    210 </t>
    211 
    212 <section title="Range Specifier Registry" anchor="range.specifier.registry">
    213 <t>
    214    The HTTP Range Specifier Registry defines the name space for the range
    215    specifier names.
     202  The only range unit defined by HTTP/1.1 is "bytes"
     203  (<xref target="byte.ranges"/>). Additional units can be defined as described
     204  in <xref target="range.unit.registry"/>.
     205</t>
     206
     207<section title="Range Unit Registry" anchor="range.unit.registry">
     208<t>
     209   The HTTP Range Unit Registry defines the name space for the range
     210   unit names and refers to their corresponding specifications.
    216211</t>
    217212<t>
     
    469464<section title="Content-Range" anchor="header.content-range">
    470465  <iref primary="true" item="Content-Range header field" x:for-anchor=""/>
    471   <x:anchor-alias value="byte-content-range-spec"/>
    472   <x:anchor-alias value="byte-range-resp-spec"/>
    473466  <x:anchor-alias value="Content-Range"/>
    474   <x:anchor-alias value="instance-length"/>
    475   <x:anchor-alias value="other-content-range-spec"/>
    476   <x:anchor-alias value="other-range-resp-spec"/>
     467  <x:anchor-alias value="byte-content-range"/>
     468  <x:anchor-alias value="byte-range-resp"/>
     469  <x:anchor-alias value="byte-range"/>
     470  <x:anchor-alias value="unsatisfied-range"/>
     471  <x:anchor-alias value="complete-length"/>
     472  <x:anchor-alias value="other-content-range"/>
     473  <x:anchor-alias value="other-range-resp"/>
    477474<t>
    478475   The "Content-Range" header field is sent with a partial representation to
     
    480477   applied.
    481478</t>
     479<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Content-Range"/><iref primary="true" item="Grammar" subitem="byte-content-range"/><iref primary="true" item="Grammar" subitem="byte-range-resp"/><iref primary="true" item="Grammar" subitem="byte-range"/><iref primary="true" item="Grammar" subitem="unsatisfied-range"/><iref primary="true" item="Grammar" subitem="other-content-range"/><iref primary="true" item="Grammar" subitem="other-range-resp"/><iref primary="true" item="Grammar" subitem="complete-length"/>
     480  <x:ref>Content-Range</x:ref>       = <x:ref>byte-content-range</x:ref>
     481                      / <x:ref>other-content-range</x:ref>
     482                         
     483  <x:ref>byte-content-range</x:ref>  = <x:ref>bytes-unit</x:ref> <x:ref>SP</x:ref>
     484                        ( <x:ref>byte-range-resp</x:ref> "/" <x:ref>unsatisfied-range</x:ref> )
     485
     486  <x:ref>byte-range-resp</x:ref>     = <x:ref>byte-range</x:ref> "/" ( <x:ref>complete-length</x:ref> / "*" )
     487  <x:ref>byte-range</x:ref>          = <x:ref>first-byte-pos</x:ref> "-" <x:ref>last-byte-pos</x:ref>
     488  <x:ref>unsatisfied-range</x:ref>   = "*/" <x:ref>complete-length</x:ref>
     489                         
     490  <x:ref>complete-length</x:ref>     = 1*<x:ref>DIGIT</x:ref>
     491 
     492  <x:ref>other-content-range</x:ref> = <x:ref>other-range-unit</x:ref> <x:ref>SP</x:ref> <x:ref>other-range-resp</x:ref>
     493  <x:ref>other-range-resp</x:ref>    = *<x:ref>CHAR</x:ref>
     494</artwork></figure>
    482495<t>   
    483    Range units are defined in <xref target="range.units"/>.
    484 </t>
    485 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Content-Range"/><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"/>
    486   <x:ref>Content-Range</x:ref>           = <x:ref>byte-content-range-spec</x:ref>
    487                           / <x:ref>other-content-range-spec</x:ref>
    488                          
    489   <x:ref>byte-content-range-spec</x:ref> = <x:ref>bytes-unit</x:ref> <x:ref>SP</x:ref>
    490                             <x:ref>byte-range-resp-spec</x:ref> "/"
    491                             ( <x:ref>instance-length</x:ref> / "*" )
    492  
    493   <x:ref>byte-range-resp-spec</x:ref>    = (<x:ref>first-byte-pos</x:ref> "-" <x:ref>last-byte-pos</x:ref>)
    494                           / "*"
    495                          
    496   <x:ref>instance-length</x:ref>         = 1*<x:ref>DIGIT</x:ref>
    497  
    498   <x:ref>other-content-range-spec</x:ref> = <x:ref>other-range-unit</x:ref> <x:ref>SP</x:ref>
    499                              <x:ref>other-range-resp-spec</x:ref>
    500   <x:ref>other-range-resp-spec</x:ref>    = *<x:ref>CHAR</x:ref>
    501 </artwork></figure>
    502 <t>
    503    The header field &SHOULD; indicate the total length of the full representation,
    504    unless this length is unknown or difficult to determine. The asterisk
    505    "*" character means that the instance-length is unknown at the time
    506    when the response was generated.
    507 </t>
    508 <t>
    509    Unlike byte-ranges-specifier values (see <xref target="byte.ranges"/>), a byte-range-resp-spec
    510    &MUST; only specify one range, and &MUST; contain
    511    absolute byte positions for both the first and last byte of the
    512    range.
    513 </t>
    514 <t>
    515    A byte-content-range-spec with a byte-range-resp-spec whose last-byte-pos
    516    value is less than its first-byte-pos value, or whose
    517    instance-length value is less than or equal to its last-byte-pos
    518    value, is invalid. The recipient of an invalid byte-content-range-spec
    519    &MUST; ignore it and any content transferred along with it.
    520 </t>
    521 <t>
    522    In the case of a byte range request: a server sending a response with
    523    status code <x:ref>416 (Range Not Satisfiable)</x:ref> &SHOULD; send a
    524    Content-Range field with a byte-range-resp-spec of "*".
    525    The instance-length specifies the current length of the selected resource.
    526    A server &MUST-NOT; generate a a Content-Range field with a
    527    byte-range-resp-spec of "*" in a <x:ref>206 (Partial Content)</x:ref>
    528    response.
    529 </t>
    530 <t>
    531   The "Content-Range" header field has no meaning for status codes that do not
    532   explicitly describe its semantic. Currently, only status codes
    533   <x:ref>206 (Partial Content)</x:ref> and <x:ref>416 (Range Not Satisfiable)</x:ref> describe
    534   the meaning of this header field.
    535 </t>
    536 <t>
    537    Examples of byte-content-range-spec values, assuming that the representation
     496   Range units are defined in <xref target="range.units"/>. A recipient of a
     497   <x:ref>206 (Partial Content)</x:ref> response containing a
     498   <x:ref>Content-Range</x:ref> header field with a <x:ref>range unit</x:ref>
     499   that the recipient does not understand &MUST-NOT; attempt to recombine it
     500   with a stored representation. A proxy that receives such a message
     501   &SHOULD; forward it downstream.
     502</t>
     503<t>
     504   For byte ranges, a sender &SHOULD; indicate the complete length of the
     505   representation from which the range has been extracted unless the complete
     506   length is unknown or difficult to determine. An asterisk character ("*") in
     507   place of the complete-length indicates that the representation length was
     508   unknown when the header field was generated.
     509</t>
     510<t>
     511   A Content-Range field value with a <x:ref>byte-range-resp</x:ref> that has
     512   a <x:ref>last-byte-pos</x:ref> value less than its
     513   <x:ref>first-byte-pos</x:ref> value, or a <x:ref>complete-length</x:ref>
     514   value less than or equal to its <x:ref>last-byte-pos</x:ref> value, is
     515   invalid. The recipient of an invalid <x:ref>Content-Range</x:ref> &MUST-NOT;
     516   attempt to recombine the received content with a stored representation.
     517</t>
     518<t>
     519   A server generating a <x:ref>206 (Partial Content)</x:ref> response to a
     520   byte range request &MUST; send, in each body-part of a multipart response
     521   or in the header block of a single part response, a Content-Range header
     522   field containing a <x:ref>byte-range-resp</x:ref> value that reflects the
     523   corresponding range being sent. The following example would apply
     524   when the complete length of the selected representation is known by the
     525   sender to be 1234 bytes:
     526</t>
     527<figure><artwork type="example">
     528  Content-Range: bytes 42-1233/1234
     529</artwork></figure>
     530<t>
     531   or this second example would apply when the complete length is unknown:
     532</t>
     533<figure><artwork type="example">
     534  Content-Range: bytes 42-1233/*
     535</artwork></figure>
     536<t>
     537   A server generating a <x:ref>416 (Range Not Satisfiable)</x:ref> response
     538   to a byte range request &SHOULD; send a Content-Range header field with an
     539   <x:ref>unsatisfied-range</x:ref> value, as in the following example:
     540</t>
     541<figure><artwork type="example">
     542  Content-Range: bytes */1234
     543</artwork></figure>
     544<t>
     545   The complete-length in a 416 response indicates the current length of the
     546   selected representation, which will be known by the server generating the
     547   response because that is how it determined the range to be unsatisfiable.
     548</t>
     549<t>
     550   The "Content-Range" header field has no meaning for status codes that do
     551   not explicitly describe its semantic. For this specification, only the
     552   <x:ref>206 (Partial Content)</x:ref> and
     553   <x:ref>416 (Range Not Satisfiable)</x:ref> status codes describe a meaning
     554   for Content-Range.
     555</t>
     556<t>
     557   More examples of Content-Range values, assuming that the representation
    538558   contains a total of 1234 bytes:
    539559   <list style="symbols">
     
    541561        The first 500 bytes:
    542562<figure><artwork type="example" x:indent-with="   ">
    543   bytes 0-499/1234
     563  Content-Range: bytes 0-499/1234
    544564</artwork></figure>
    545565      </t>   
     
    547567        The second 500 bytes:
    548568<figure><artwork type="example" x:indent-with="   ">
    549   bytes 500-999/1234
     569  Content-Range: bytes 500-999/1234
    550570</artwork></figure>
    551571      </t>   
     
    553573        All except for the first 500 bytes:
    554574<figure><artwork type="example" x:indent-with="   ">
    555   bytes 500-1233/1234
     575  Content-Range: bytes 500-1233/1234
    556576</artwork></figure>
    557577      </t>   
     
    559579        The last 500 bytes:
    560580<figure><artwork type="example" x:indent-with="   ">
    561   bytes 734-1233/1234
     581  Content-Range: bytes 734-1233/1234
    562582</artwork></figure>
    563583      </t>   
     
    766786   retrieval of large representations. A server &MUST; ignore a Range header
    767787   field received with a request method other than GET.
     788</t>
     789<t>
     790   An origin server &MUST; ignore a <x:ref>Range</x:ref> header field that
     791   contains a range unit it does not understand. A proxy &MAY; either discard
     792   a <x:ref>Range</x:ref> header field that contains a range unit it does not
     793   understand or pass it to the next inbound server when forwarding the
     794   request.
    768795</t>
    769796<t>
     
    868895<t>
    869896  The registration procedure for HTTP Range Specifiers is defined by
    870   <xref target="range.specifier.registry"/> of this document.
     897  <xref target="range.unit.registry"/> of this document.
    871898</t>
    872899<t>
     
    13151342<t>
    13161343  This specification introduces a Range Specifier Registry.
    1317   (<xref target="range.specifier.registry"/>)
     1344  (<xref target="range.unit.registry"/>)
    13181345</t>
    13191346</section>
     
    13681395<x:ref>Accept-Ranges</x:ref> = acceptable-ranges
    13691396
    1370 <x:ref>Content-Range</x:ref> = byte-content-range-spec / other-content-range-spec
     1397<x:ref>Content-Range</x:ref> = byte-content-range / other-content-range
    13711398
    13721399<x:ref>HTTP-date</x:ref> = &lt;HTTP-date, defined in [Part2], Section 7.1.1.1&gt;
     
    13811408 range-unit ] ) ) / "none"
    13821409
    1383 <x:ref>byte-content-range-spec</x:ref> = bytes-unit SP byte-range-resp-spec "/" (
    1384  instance-length / "*" )
    1385 <x:ref>byte-range-resp-spec</x:ref> = ( first-byte-pos "-" last-byte-pos ) / "*"
     1410<x:ref>byte-content-range</x:ref> = bytes-unit SP ( byte-range-resp "/"
     1411 unsatisfied-range )
     1412<x:ref>byte-range</x:ref> = first-byte-pos "-" last-byte-pos
     1413<x:ref>byte-range-resp</x:ref> = byte-range "/" ( complete-length / "*" )
    13861414<x:ref>byte-range-set</x:ref> = *( "," OWS ) ( byte-range-spec /
    13871415 suffix-byte-range-spec ) *( OWS "," [ OWS ( byte-range-spec /
     
    13911419<x:ref>bytes-unit</x:ref> = "bytes"
    13921420
     1421<x:ref>complete-length</x:ref> = 1*DIGIT
     1422
    13931423<x:ref>entity-tag</x:ref> = &lt;entity-tag, defined in [Part4], Section 2.3&gt;
    13941424
    13951425<x:ref>first-byte-pos</x:ref> = 1*DIGIT
    13961426
    1397 <x:ref>instance-length</x:ref> = 1*DIGIT
    1398 
    13991427<x:ref>last-byte-pos</x:ref> = 1*DIGIT
    14001428
    1401 <x:ref>other-content-range-spec</x:ref> = other-range-unit SP other-range-resp-spec
    1402 <x:ref>other-range-resp-spec</x:ref> = *CHAR
     1429<x:ref>other-content-range</x:ref> = other-range-unit SP other-range-resp
     1430<x:ref>other-range-resp</x:ref> = *CHAR
    14031431<x:ref>other-range-set</x:ref> = 1*CHAR
    14041432<x:ref>other-range-unit</x:ref> = token
     
    14111439
    14121440<x:ref>token</x:ref> = &lt;token, defined in [Part1], Section 3.2.6&gt;
     1441
     1442<x:ref>unsatisfied-range</x:ref> = "*/" complete-length
    14131443</artwork>
    14141444</figure>
Note: See TracChangeset for help on using the changeset viewer.