Ignore:
Timestamp:
30/12/12 08:25:02 (10 years ago)
Author:
fielding@…
Message:

(editorial) rewrite definition of Vary; partly addresses #419

Location:
draft-ietf-httpbis/latest
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • draft-ietf-httpbis/latest/p2-semantics.html

    r2067 r2068  
    449449  }
    450450  @bottom-center {
    451        content: "Expires July 2, 2013";
     451       content: "Expires July 3, 2013";
    452452  }
    453453  @bottom-right {
    … …  
    495495      <meta name="dct.creator" content="Reschke, J. F.">
    496496      <meta name="dct.identifier" content="urn:ietf:id:draft-ietf-httpbis-p2-semantics-latest">
    497       <meta name="dct.issued" scheme="ISO8601" content="2012-12-29">
     497      <meta name="dct.issued" scheme="ISO8601" content="2012-12-30">
    498498      <meta name="dct.replaces" content="urn:ietf:rfc:2616">
    499499      <meta name="dct.abstract" content="The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypertext information systems. This document defines the semantics of HTTP/1.1 messages, as expressed by request methods, request header fields, response status codes, and response header fields, along with the payload of messages (metadata and body content) and mechanisms for content negotiation.">
    … …  
    523523            <tr>
    524524               <td class="left">Intended status: Standards Track</td>
    525                <td class="right">December 29, 2012</td>
     525               <td class="right">December 30, 2012</td>
    526526            </tr>
    527527            <tr>
    528                <td class="left">Expires: July 2, 2013</td>
     528               <td class="left">Expires: July 3, 2013</td>
    529529               <td class="right"></td>
    530530            </tr>
    … …  
    554554         in progress”.
    555555      </p>
    556       <p>This Internet-Draft will expire on July 2, 2013.</p>
     556      <p>This Internet-Draft will expire on July 3, 2013.</p>
    557557      <h1><a id="rfc.copyrightnotice" href="#rfc.copyrightnotice">Copyright Notice</a></h1>
    558558      <p>Copyright © 2012 IETF Trust and the persons identified as the document authors. All rights reserved.</p>
    … …  
    29452945  Retry-After: 120
    29462946</pre><p id="rfc.section.7.1.3.p.8">In the latter example, the delay is 2 minutes.</p>
     2947      <div id="rfc.iref.s.7"></div>
    29472948      <h2 id="rfc.section.7.2"><a href="#rfc.section.7.2">7.2</a>&nbsp;<a id="selected.representation" href="#selected.representation">Selected Representation Header Fields</a></h2>
    2948       <p id="rfc.section.7.2.p.1"><span id="rfc.iref.s.7"></span> We use the term "<dfn>selected representation</dfn>" to refer to the the current representation of the <a href="#resources" class="smpl">target resource</a> that would have been selected in a successful response if the same request had used the method GET and excluded any conditional
     2949      <p id="rfc.section.7.2.p.1">We use the term "<dfn>selected representation</dfn>" to refer to the the current representation of the <a href="#resources" class="smpl">target resource</a> that would have been selected in a successful response if the same request had used the method GET and excluded any conditional
    29492950         request header fields.
    29502951      </p>
    … …  
    29792980      <div id="rfc.iref.v.1"></div>
    29802981      <h3 id="rfc.section.7.2.1"><a href="#rfc.section.7.2.1">7.2.1</a>&nbsp;<a id="header.vary" href="#header.vary">Vary</a></h3>
    2981       <p id="rfc.section.7.2.1.p.1">The "Vary" header field conveys the set of header fields that were used to select the representation.</p>
    2982       <p id="rfc.section.7.2.1.p.2">Caches use this information as part of determining whether a stored response can be used to satisfy a given request (<a href="p6-cache.html#caching.negotiated.responses" title="Using Negotiated Responses">Section 4.3</a> of <a href="#Part6" id="rfc.xref.Part6.14"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>).
    2983       </p>
    2984       <p id="rfc.section.7.2.1.p.3">In uncacheable or stale responses, the Vary field value advises the user agent about the criteria that were used to select
    2985          the representation.
     2982      <p id="rfc.section.7.2.1.p.1">The "Vary" header field describes what parts of a request message, aside from the method and request target, might influence
     2983         the origin server's process for selecting and representing the response. The value consists of either a single asterisk ("*")
     2984         or a list of header field names (case-insensitive).
    29862985      </p>
    29872986      <div id="rfc.figure.u.57"></div><pre class="inline"><span id="rfc.iref.g.59"></span>  <a href="#header.vary" class="smpl">Vary</a> = "*" / 1#<a href="#imported.abnf" class="smpl">field-name</a>
    2988 </pre><p id="rfc.section.7.2.1.p.5">The set of header fields named by the Vary field value is known as the selecting header fields.</p>
    2989       <p id="rfc.section.7.2.1.p.6">A server <em class="bcp14">SHOULD</em> include a Vary header field with any cacheable response that is subject to proactive negotiation. Doing so allows a cache
    2990          to properly interpret future requests on that resource and informs the user agent about the presence of negotiation on that
    2991          resource. A server <em class="bcp14">MAY</em> include a Vary header field with a non-cacheable response that is subject to proactive negotiation, since this might provide
    2992          the user agent with useful information about the dimensions over which the response varies at the time of the response.
    2993       </p>
    2994       <p id="rfc.section.7.2.1.p.7">A Vary field value of "*" signals that unspecified parameters not limited to the header fields (e.g., the network address
    2995          of the client), play a role in the selection of the response representation; therefore, a cache cannot determine whether this
    2996          response is appropriate. A proxy <em class="bcp14">MUST NOT</em> generate the "*" value.
    2997       </p>
    2998       <p id="rfc.section.7.2.1.p.8">The field-names given are not limited to the set of standard header fields defined by this specification. Field names are
    2999          case-insensitive.
     2987</pre><p id="rfc.section.7.2.1.p.3">A Vary field value of "*" signals that anything about the request might play a role in selecting the response representation,
     2988         possibly including elements outside the message syntax (e.g., the client's network address), and thus a recipient will not
     2989         be able to determine whether this response is appropriate for a later request without forwarding the request to the origin
     2990         server. A proxy <em class="bcp14">MUST NOT</em> generate a Vary field with a "*" value.
     2991      </p>
     2992      <p id="rfc.section.7.2.1.p.4">A Vary field value consisting of a comma-separated list of names indicates that the named request header fields, known as
     2993         the selecting header fields, might have a role in selecting the representation. The potential selecting header fields are
     2994         not limited to those defined by this specification.
     2995      </p>
     2996      <p id="rfc.section.7.2.1.p.5">An origin server might send Vary with a list of fields for two purposes: </p>
     2997      <ol>
     2998         <li>
     2999            <p>To inform cache recipients that they <em class="bcp14">MUST NOT</em> use this response to satisfy a later request unless the later request has the same values for the listed fields as the original
     3000               request (<a href="p6-cache.html#caching.negotiated.responses" title="Using Negotiated Responses">Section 4.3</a> of <a href="#Part6" id="rfc.xref.Part6.14"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). In other words, Vary expands the cache key required to match a new request to the stored cache entry.
     3001            </p>
     3002         </li>
     3003         <li>
     3004            <p>To inform user agent recipients that this response is subject to content negotiation (<a href="#request.conneg" title="Content Negotiation">Section&nbsp;5.3</a>) and that a different representation might be sent in a subsequent request if additional parameters are provided in the listed
     3005               header fields (<a href="#proactive.negotiation" class="smpl">proactive negotiation</a>).
     3006            </p>
     3007         </li>
     3008      </ol>
     3009      <p id="rfc.section.7.2.1.p.6">Unless it has been deliberately configured to prevent cache transparency, an origin server <em class="bcp14">SHOULD</em> send a Vary header field in a cacheable response that is subject to proactive negotiation.
     3010      </p>
     3011      <div id="rfc.figure.u.58"></div>
     3012      <p>For example, a response that contains</p><pre class="text">  Vary: accept-encoding, accept-language
     3013</pre><p>indicates that the origin server might have used the request's <a href="#header.accept-encoding" class="smpl">Accept-Encoding</a> and <a href="#header.accept-language" class="smpl">Accept-Language</a> fields (or lack thereof) as determining factors while choosing this <a href="#selected.representation" class="smpl">selected representation</a>.
    30003014      </p>
    30013015      <h2 id="rfc.section.7.3"><a href="#rfc.section.7.3">7.3</a>&nbsp;<a id="response.auth" href="#response.auth">Authentication Challenges</a></h2>
    … …  
    30543068      <p id="rfc.section.7.4.1.p.1">The "Allow" header field lists the set of methods advertised as supported by the <a href="#resources" class="smpl">target resource</a>. The purpose of this field is strictly to inform the recipient of valid request methods associated with the resource.
    30553069      </p>
    3056       <div id="rfc.figure.u.58"></div><pre class="inline"><span id="rfc.iref.g.60"></span>  <a href="#header.allow" class="smpl">Allow</a> = #<a href="#method.overview" class="smpl">method</a>
     3070      <div id="rfc.figure.u.59"></div><pre class="inline"><span id="rfc.iref.g.60"></span>  <a href="#header.allow" class="smpl">Allow</a> = #<a href="#method.overview" class="smpl">method</a>
    30573071</pre><p id="rfc.section.7.4.1.p.3">Example of use:</p>
    3058       <div id="rfc.figure.u.59"></div><pre class="text">  Allow: GET, HEAD, PUT
     3072      <div id="rfc.figure.u.60"></div><pre class="text">  Allow: GET, HEAD, PUT
    30593073</pre><p id="rfc.section.7.4.1.p.5">The actual set of allowed methods is defined by the origin server at the time of each request.</p>
    30603074      <p id="rfc.section.7.4.1.p.6">A proxy <em class="bcp14">MUST NOT</em> modify the Allow header field — it does not need to understand all the methods specified in order to handle them according
    … …  
    30673081         to avoid particular server limitations, and for analytics regarding server or operating system use. An origin server <em class="bcp14">MAY</em> generate a Server field in its responses.
    30683082      </p>
    3069       <div id="rfc.figure.u.60"></div><pre class="inline"><span id="rfc.iref.g.61"></span>  <a href="#header.server" class="smpl">Server</a> = <a href="#header.user-agent" class="smpl">product</a> *( <a href="#imported.abnf" class="smpl">RWS</a> ( <a href="#header.user-agent" class="smpl">product</a> / <a href="#imported.abnf" class="smpl">comment</a> ) )
     3083      <div id="rfc.figure.u.61"></div><pre class="inline"><span id="rfc.iref.g.61"></span>  <a href="#header.server" class="smpl">Server</a> = <a href="#header.user-agent" class="smpl">product</a> *( <a href="#imported.abnf" class="smpl">RWS</a> ( <a href="#header.user-agent" class="smpl">product</a> / <a href="#imported.abnf" class="smpl">comment</a> ) )
    30703084</pre><p id="rfc.section.7.4.2.p.3">The Server field-value consists of one or more product identifiers, each followed by zero or more comments (<a href="p1-messaging.html#header.fields" title="Header Fields">Section 3.2</a> of <a href="#Part1" id="rfc.xref.Part1.29"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>), which together identify the origin server software and its significant subproducts. By convention, the product identifiers
    30713085         are listed in order of their significance for identifying the origin server software. Each product identifier consists of
    … …  
    30733087      </p>
    30743088      <p id="rfc.section.7.4.2.p.4">Example:</p>
    3075       <div id="rfc.figure.u.61"></div><pre class="text">  Server: CERN/3.0 libwww/2.17
     3089      <div id="rfc.figure.u.62"></div><pre class="text">  Server: CERN/3.0 libwww/2.17
    30763090</pre><p id="rfc.section.7.4.2.p.6">An origin server <em class="bcp14">SHOULD NOT</em> generate a Server field containing needlessly fine-grained detail and <em class="bcp14">SHOULD</em> limit the addition of subproducts by third parties. Overly long and detailed Server field values increase response latency
    30773091         and potentially reveal internal implementation details that might make it (slightly) easier for attackers to find and exploit
    … …  
    34643478         these:
    34653479      </p>
    3466       <div id="rfc.figure.u.62"></div><pre class="text">  Example-URI-Field: "http://example.com/a.html,foo",
     3480      <div id="rfc.figure.u.63"></div><pre class="text">  Example-URI-Field: "http://example.com/a.html,foo",
    34673481                     "http://without-a-comma.example.com/"
    34683482  Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005"
    … …  
    40314045         MIME environments.
    40324046      </p>
    4033       <div id="rfc.figure.u.63"></div><pre class="inline"><span id="rfc.iref.g.62"></span>  <a href="#mime-version" class="smpl">MIME-Version</a> = 1*<a href="#imported.abnf" class="smpl">DIGIT</a> "." 1*<a href="#imported.abnf" class="smpl">DIGIT</a>
     4047      <div id="rfc.figure.u.64"></div><pre class="inline"><span id="rfc.iref.g.62"></span>  <a href="#mime-version" class="smpl">MIME-Version</a> = 1*<a href="#imported.abnf" class="smpl">DIGIT</a> "." 1*<a href="#imported.abnf" class="smpl">DIGIT</a>
    40344048</pre><p id="rfc.section.A.1.p.3">MIME version "1.0" is the default for use in HTTP/1.1. However, HTTP/1.1 message parsing and semantics are defined by this
    40354049         document and not the MIME specification.
    … …  
    41744188      <p id="rfc.section.D.p.2">The rules below are defined in <a href="#Part1" id="rfc.xref.Part1.45"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>:
    41754189      </p>
    4176       <div id="rfc.figure.u.64"></div><pre class="inline">  <a href="#imported.abnf" class="smpl">BWS</a>           = &lt;BWS, defined in <a href="#Part1" id="rfc.xref.Part1.46"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>, <a href="p1-messaging.html#whitespace" title="Whitespace">Section 3.2.3</a>&gt;
     4190      <div id="rfc.figure.u.65"></div><pre class="inline">  <a href="#imported.abnf" class="smpl">BWS</a>           = &lt;BWS, defined in <a href="#Part1" id="rfc.xref.Part1.46"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>, <a href="p1-messaging.html#whitespace" title="Whitespace">Section 3.2.3</a>&gt;
    41774191  <a href="#imported.abnf" class="smpl">OWS</a>           = &lt;OWS, defined in <a href="#Part1" id="rfc.xref.Part1.47"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>, <a href="p1-messaging.html#whitespace" title="Whitespace">Section 3.2.3</a>&gt;
    41784192  <a href="#imported.abnf" class="smpl">RWS</a>           = &lt;RWS, defined in <a href="#Part1" id="rfc.xref.Part1.48"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>, <a href="p1-messaging.html#whitespace" title="Whitespace">Section 3.2.3</a>&gt;
    … …  
    41864200  <a href="#imported.abnf" class="smpl">word</a>          = &lt;word, defined in <a href="#Part1" id="rfc.xref.Part1.56"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>, <a href="p1-messaging.html#field.components" title="Field value components">Section 3.2.6</a>&gt;
    41874201</pre><h1 id="rfc.section.E"><a href="#rfc.section.E">E.</a>&nbsp;<a id="collected.abnf" href="#collected.abnf">Collected ABNF</a></h1>
    4188       <div id="rfc.figure.u.65"></div> <pre class="inline"><a href="#header.accept" class="smpl">Accept</a> = [ ( "," / ( media-range [ accept-params ] ) ) *( OWS "," [
     4202      <div id="rfc.figure.u.66"></div> <pre class="inline"><a href="#header.accept" class="smpl">Accept</a> = [ ( "," / ( media-range [ accept-params ] ) ) *( OWS "," [
    41894203 OWS ( media-range [ accept-params ] ) ] ) ]
    41904204<a href="#header.accept-charset" class="smpl">Accept-Charset</a> = *( "," OWS ) ( ( charset / "*" ) [ weight ] ) *( OWS

  • draft-ietf-httpbis/latest/p2-semantics.xml

    r2067 r2068  
    37833783
    37843784<section title="Selected Representation Header Fields" anchor="selected.representation">
    3785 <t><iref primary="true" item="selected representation"/>
     3785   <iref primary="true" item="selected representation"/>
     3786   <x:anchor-alias value="selected representation"/>
     3787<t>
    37863788   We use the term "<x:dfn>selected representation</x:dfn>" to refer to the
    37873789   the current representation of the <x:ref>target resource</x:ref> that would have been
    … …  
    38093811   <x:anchor-alias value="Vary"/>
    38103812<t>
    3811    The "Vary" header field conveys the set of header fields
    3812    that were used to select the representation.
    3813 </t>
    3814 <t>
    3815    Caches use this information as part of determining whether a stored
    3816    response can be used to satisfy a given request (&caching-neg-resp;).
    3817 </t>
    3818 <t>
    3819    In uncacheable or stale responses, the Vary field value advises the user
    3820    agent about the criteria that were used to select the representation.
     3813   The "Vary" header field describes what parts of a request message, aside
     3814   from the method and request target, might influence the origin server's
     3815   process for selecting and representing the response. The value consists of
     3816   either a single asterisk ("*") or a list of header field names
     3817   (case-insensitive).
    38213818</t>
    38223819<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Vary"/>
    … …  
    38243821</artwork></figure>
    38253822<t>
    3826    The set of header fields named by the Vary field value is known as the
    3827    selecting header fields.
    3828 </t>
    3829 <t>
    3830    A server &SHOULD; include a Vary header field with any cacheable response
    3831    that is subject to proactive negotiation. Doing so allows a cache to
    3832    properly interpret future requests on that resource and informs the user
    3833    agent about the presence of negotiation on that resource. A server &MAY;
    3834    include a Vary header field with a non-cacheable response that is subject
    3835    to proactive negotiation, since this might provide the user agent with
    3836    useful information about the dimensions over which the response varies at
    3837    the time of the response.
    3838 </t>
    3839 <t>
    3840    A Vary field value of "*" signals that unspecified parameters not limited
    3841    to the header fields (e.g., the network address of the client), play a
    3842    role in the selection of the response representation; therefore, a cache
    3843    cannot determine whether this response is appropriate. A proxy &MUST-NOT;
    3844    generate the "*" value.
    3845 </t>
    3846 <t>
    3847    The field-names given are not limited to the set of standard header
    3848    fields defined by this specification. Field names are case-insensitive.
    3849 </t>
     3823   A Vary field value of "*" signals that anything about the request might
     3824   play a role in selecting the response representation, possibly including
     3825   elements outside the message syntax (e.g., the client's network address),
     3826   and thus a recipient will not be able to determine whether this response is
     3827   appropriate for a later request without forwarding the request to the
     3828   origin server. A proxy &MUST-NOT; generate a Vary field with a "*" value.
     3829</t>
     3830<t>
     3831   A Vary field value consisting of a comma-separated list of names indicates
     3832   that the named request header fields, known as the selecting header fields,
     3833   might have a role in selecting the representation. The potential selecting
     3834   header fields are not limited to those defined by this specification.
     3835</t>
     3836<t>
     3837   An origin server might send Vary with a list of fields for two purposes:
     3838   <list style="numbers">
     3839      <x:lt>
     3840        <t>
     3841           To inform cache recipients that they &MUST-NOT; use this response
     3842           to satisfy a later request unless the later request has the
     3843           same values for the listed fields as the original request
     3844           (&caching-neg-resp;). In other words, Vary expands the cache key
     3845           required to match a new request to the stored cache entry.
     3846        </t>
     3847      </x:lt>
     3848      <x:lt>
     3849        <t>
     3850           To inform user agent recipients that this response is subject to
     3851           content negotiation (<xref target="request.conneg"/>) and that a
     3852           different representation might be sent in a subsequent request if
     3853           additional parameters are provided in the listed header fields
     3854           (<x:ref>proactive negotiation</x:ref>).
     3855        </t>
     3856      </x:lt>
     3857   </list>
     3858</t>
     3859<t>
     3860   Unless it has been deliberately configured to prevent cache transparency,
     3861   an origin server &SHOULD; send a Vary header field in a cacheable
     3862   response that is subject to proactive negotiation.
     3863</t>
     3864<figure><preamble>For example, a response that contains</preamble><artwork type="example">
     3865  Vary: accept-encoding, accept-language
     3866</artwork><postamble>indicates that the origin server might have used the
     3867   request's <x:ref>Accept-Encoding</x:ref> and <x:ref>Accept-Language</x:ref>
     3868   fields (or lack thereof) as determining factors while choosing this
     3869   <x:ref>selected representation</x:ref>.</postamble></figure>
    38503870</section>
    38513871</section>
Note: See TracChangeset for help on using the changeset viewer.