W3C home > Mailing lists > Public > ietf-http-wg-old@w3.org > January to April 1997

Some edits to draft-ietf-http-negotiation-00.txt

From: Koen Holtman <koen@win.tue.nl>
Date: Wed, 26 Feb 1997 10:36:17 +0100 (MET)
Message-Id: <199702260936.KAA00720@wsooti08.win.tue.nl>
To: http-wg@cuckoo.hpl.hp.com
Cc: Koen Holtman <koen@win.tue.nl>

I have made some edits to the TCN draft to resolve the choice
response/Content-Location/Alternates/506 issues.  New sections with
changebars are included below, please check if this resolves the issues.

Note that I have not yet made any other edits, the sections will change
again when I add clarifications and corrections.

Koen.

----snip---

|8.6B TCN
|
|  The TCN response header is used by a server to signal that the
|  resource is transparently negotiated.
|
|      TCN = "TCN" ":" #( response-type | tcn-extension )
|
|      response-type = "list" | "choice" | "adhoc"
|
|      tcn-extension = token [ "=" ( token | quoted-string ) ]
|
|  If the resource is not transparently negotiated, a TCN header must
|  never be included in any response.  If the resource is
|  transparently negotiated, a TCN header, which includes the
|  response-type value of the response, must be included in every
|  response with a 2xx status code or any 3xx status code, except 304.
|  A TCN header may also be included, without a response-type value,
|  in other responses from transparantly negotiated resources.
|
|  Clients should ignore all tcn-extensions they do not understand.


10 Content negotiation responses

   If a request on a transparently negotiated resource yields a
   response with a 2xx status code or any 3xx status code except 304,
   this response must always be either a list response, a choice
   response, or an ad hoc response.  These responses always include
|  the Alternates header bound to the negotiable resource, and a TCN
|  header which specifies their type.  Transparently negotiated
   responses with other status codes may also include an Alternates
|  header.

   After having constructed a list, choice, or ad hoc response, a
   server may process any If-No-Match or If-Range headers in the
   request message and shorten the response to a 304 (Not Modified) or
   206 (Partial Content) response, following the rules in the HTTP/1.1
|  specification [1].  In this case, the entity tag of the shortened
|  response will identify it indirectly as a list, choice, or ad-hoc
   response.


10.1 List response

|  A list response must contain (besides the normal headers required
|  by HTTP) a TCN header which specifies the "list" response-type, the
   Alternates header bound to the negotiable resource, a Vary header
   and (unless it was a HEAD request) an entity body which allows the
   user to manually select the best variant.  It is generated as a
   response to a user agent capable of transparent content negotiation
|  if the server does not, cannot, or is not allowed to choose a
   particular best variant for the request.

   An example of a list response is

     HTTP/1.1 300 Multiple Choices
     Date: Tue, 11 Jun 1996 20:02:21 GMT
|    TCN: list
     Alternates: {"paper.html.en" 0.9 {type text/html} {language en}},
                 {"paper.html.fr" 0.7 {type text/html} {language fr}},
                 {"paper.ps.en"   1.0 {type application/postscript}
                     {language en}}
     Vary: negotiate, accept, accept-language
     ETag: "blah;1234"
     Cache-control: max-age=86400
     Content-Type: text/html
     Content-Length: 227

     <h2>Multiple Choices:</h2>
     <ul>
     <li><a href=paper.html.en>HTML, English version</a>
     <li><a href=paper.html.fr>HTML, French version</a>
     <li><a href=paper.ps.en>Postscript, English version</a>
     </ul>

|     Note: A list response can have any status code, but the 300
|     (Multiple Choices) code is the most appropriate one for HTTP/1.1
|     clients.  Some existing versions of HTTP/1.0 clients are known
|     to silently ignore 300 responses, instead of handling them
|     according to the HTTP/1.0 specification [3].  Servers should
|     therefore be careful in sending 300 responses to non-negotiating
|     HTTP/1.0 user agents, and in making these responses cacheable.
|     The 200 (OK) status code can be used instead.

   The Vary header in the response should ensure correct handling by
   HTTP/1.1 caching proxies not capable of transparent content
   negotiation.  This header can either be

        Vary: *

   or a more elaborate header; see section 10.6.1.

|  Only the origin server may construct list responses.  Depending on
|  the status code, a list response is cacheable unless indicated
   otherwise.

   According to the HTTP/1.1 specification [1], a user agent not
   capable of transparent content negotiation will, when receiving a
   list response, display the entity body included in the response.
   If the response contains a Location header, however, the user agent
   may automatically redirect to this location.

   The handling of list responses by clients supporting transparent
   content negotiation is described in sections 11.1 and 13.
|

10.2 Choice response

   A choice response merges a normal HTTP response from the chosen
|  variant, a TCN header which specifies the "choice" response-type, a
   Content-Location header giving the location of the variant, and the
   Alternates headers bound to the negotiable resource.  Depending on
|  the status code, a choice response is cacheable unless indicated
   otherwise.

   Origin servers and proxy caches must construct choice responses
   with the following algorithm (or any other algorithm which gives
   equal end results for the client).

   In this algorithm, `the current Alternates header' refers to the
   Alternates header containing the variant list which was used to
   choose the best variant, and `the current variant list validator'
   refers to the validator of this list.  Section 10.3 specifies how
   these two items can be obtained by a proxy cache.

   The algorithm consists of four steps.

     1. Construct a HTTP request message on the best variant resource
        by rewriting the request-URI and Host header (if appropriate)
        of the received request message on the negotiable resource.

     2. Generate a valid HTTP response message, but not one with the
        304 (Not Modified) code, for the request message constructed
        in step 1.

        In a proxy cache, the response can be obtained from cache
        memory, or by passing the constructed HTTP request towards the
        origin server.  If the request is passed on, the proxy may
        add, modify, or delete If-None-Match and If-Range headers to
        optimize the transaction with the upstream server.

           Note: the proxy must be careful not to add entity tags of
           non-neighboring variants to the request, as there are no
           global uniqueness requirements for these tags.

|    3. Only in origin servers: check for an origin server
        configuration error. If the HTTP response message generated in
|       step 2 contains a TCN header, then the best variant resource
|       is not a proper end point in the transparent negotiation
        process, and a 506 (Variant Also Negotiates) error response
        message should be generated instead of going to step 4.

     4. Add a number of headers to the HTTP response message generated
        in step 2.

|       a-1. Add a TCN header which specifies the "choice"
|          response-type.

        a. Add a Content-Location header giving the location of the
|          chosen variant.  Delete any Content-Location header which
|          was already present.

               Note: According to the HTTP/1.1 specification [1], if
               the Content-Location header contains a relative URI,
               this URI is relative to the URI in the Content-Base
               header, if present.

        b. If any Vary headers are present in the response message
           from step 2, add, for every Vary header, a Variant-Vary
           header with a copy of the contents of this Vary header.

|       c. Add the current Alternates header.  Delete any
|          Alternates header which was already present.

        d. Add a Vary header to ensure correct handling by HTTP/1.1
           caching proxies not capable of transparent content
           negotiation.  This header can either be

               Vary: *

           or a more elaborate header, see section 10.6.

        e. To ensure compatibility with HTTP/1.0 caching proxies which
           do not recognize the Vary header, an Expires header with a
           date in the past may be added. See section 10.7 for more
           information.

        f. If an ETag header is present in the response message from
           step 2, then extend the entity tag in that header with the
           current variant list validator, as specified in section
           9.2.

        g. Only in proxy caches: set the Age header of the response to

              max( variant_age , alternates_age )

           where variant_age is the age of the variant response
           obtained in step 2, calculated according to the rules in
           the HTTP/1.1 specification [1], and alternates_age is the
           age of the Alternates header added in step c, calculated
           according to the rules in section 10.4.

   Note that a server can shorten the response produced by the above
   algorithm to a 304 (Not Modified) response if an If-None-Match
   header in the original request allows it.  If this is the case, an
   implementation of the above algorithm can avoid the unnecessary
   internal construction of full response message in step 2, it need
   only construct the parts which end up in the final 304 response.  A
   proxy cache which implements this optimization can sometimes
   generate a legal 304 response even if it has not cached the variant
   data itself.

   An example of a choice response is:

     HTTP/1.1 200 OK
     Date: Tue, 11 Jun 1996 20:05:31 GMT
|    TCN: choice
     Content-Type: text/html
     Last-Modified: Mon, 10 Jun 1996 10:01:14 GMT
     Content-Length: 5327
     Cache-control: max-age=604800
     Content-Location: paper.html.en
     Alternates: {"paper.html.en" 0.9 {type text/html} {language en}},
                 {"paper.html.fr" 0.7 {type text/html} {language fr}},
                 {"paper.ps.en"   1.0 {type application/postscript}
                     {language en}}
     Etag: "gonkyyyy;1234"
     Vary: negotiate, accept, accept-language
     Expires: Thu, 01 Jan 1980 00:00:00 GMT

     <title>A paper about ....

   An example of forwarding by a proxy cache: if a proxy receives the
   request

     GET /paper HTTP/1.1
     Host: x.org
     User-Agent: WuxtaWeb/2.4
     Negotiate: 1.0
     Accept: text/html, *
     Accept-Language: en
     If-None-Match: "gonkyyyy;1234", W/"a;b;1234"

   and if it can reuse a cached variant list with the validator
   "1234", taken from a cached response with an age of 8000 seconds,
   to choose paper.html.en as the best variant, then the proxy can
   pass on the request

     GET /paper.html.en HTTP/1.1
     Host: x.org
     User-Agent: WuxtaWeb/2.4
     Negotiate: 1.0
     Accept: text/html, *
     Accept-Language: en
     If-None-Match: "gonkyyyy", W/"a;b"
     Via: 1.1 fred

   to an upstream server.  On receipt of the response

     HTTP/1.1 304 Not Modified
     Date: Tue, 11 Jun 1996 20:05:31 GMT
     Etag: "gonkyyyy"

   from the upstream server, it can return

     HTTP/1.1 304 Not Modified
     Date: Tue, 11 Jun 1996 20:05:31 GMT
|    TCN: choice
     Etag: "gonkyyyy;1234"
     Content-Location: paper.html.en
     Vary: negotiate, accept, accept-language
     Expires: Thu, 01 Jan 1980 00:00:00 GMT
     Via: 1.1 fred
     Age: 8000

   to its own client.


10.3 Ad hoc response

|  An ad hoc response has a TCN header which specifies the "adhoc"
|  response-type.  It must contain the Alternates header bound to the
   negotiable resource, and a Vary header if the response is
   cacheable.  It may be generated by an origin server as a response
   to a non-negotiating user agent, if the server cannot or does not
   want to send a list or choice response.

   The Vary header in the response should ensure correct handling by
   HTTP/1.1 caching proxies not capable of transparent content
   negotiation.  This header can either be

        Vary: *

   or a more elaborate header, see section 10.6.1.  Depending on the
|  status code, an ad hoc response is cacheable unless indicated
   otherwise.

   An example of an ad hoc response is:

     HTTP/1.1 200 OK
     Date: Tue, 11 Jun 1996 20:02:26 GMT
|    TCN: adhoc
     Alternates: {"paper.html.en" 0.9 {type text/html} {language en}},
                 {"paper.html.fr" 0.7 {type text/html} {language fr}},
                 {"paper.ps.en"   1.0 {type application/postscript}
                     {language en}}
     Vary: negotiate, accept, accept-language
     Etag: "gonkzzzz;1234"
     Cache-control: max-age=86400
     Content-Type: text/html
     Content-Length: 227

     <h2>Multiple Choices:</h2>
     <ul>
     <li><a href=paper.html.en>HTML, English version</a>
     <li><a href=paper.html.fr>HTML, French version</a>
     <li><a href=paper.ps.en>Postscript, English version</a>
     </ul>

   Another example is

     HTTP/1.1 302 Moved Temporarily
     Date: Tue, 11 Jun 1996 20:02:28 GMT
|    TCN: adhoc
     Alternates: {"paper.html.en" 0.9 {type text/html} {language en}},
                 {"paper.html.fr" 0.7 {type text/html} {language fr}},
                 {"paper.ps.en"   1.0 {type application/postscript}
                     {language en}}
     Location: paper.html.en
     Content-Type: text/html
     Content-Length: 59

     This document is available <a href=paper.html.en>here</a>.

--snip--
Received on Wednesday, 26 February 1997 01:41:45 EST

This archive was generated by hypermail pre-2.1.9 : Wednesday, 24 September 2003 06:32:30 EDT