Subject: Re: NEW ISSUE: 13.1.2's Definition of 1xx Warn-Codes

From: Mark Nottingham <[email-masked]>
Date: Tue, 10 Jun 2008 23:58:03 +1000

Digging up an older thread, I had a look at the Warning sections (now  
in p6). Here's a straw-man rewrite (there are a number of changes, but  
very little text that's genuinely new);

---8<---
3.2.  Warnings

    Whenever a cache returns a response that is neither first-hand nor
    "fresh enough" (in the sense of condition 2 in Section 3.1), it MUST
    attach a warning to that effect, using a Warning general-header.   
The
    Warning header and the warnings defined by this specification are
    described in Section 16.6.

16.6.  Warning

    The Warning general-header field is used to carry additional
    information about the status or transformation of a message which
    might not be reflected in the message.  This information is  
typically
    used to warn about a possible lack of semantic transparency from
    caching operations or transformations applied to the entity body of
    the message.

    Warnings MAY be used for other purposes, both cache-related and
    otherwise.  The use of a warning, rather than an error status code,
    distinguish these responses from true failures.

    Warning headers can in general be applied to any message, however
    some warn-codes are specific to caches and can only be
    applied to response messages.

      Warning    = "Warning" ":" 1#warning-value

      warning-value = warn-code SP warn-agent SP warn-text
                                            [SP warn-date]

      warn-code  = 3DIGIT
      warn-agent = ( uri-host [ ":" port ] ) | pseudonym
                      ; the name or pseudonym of the server adding
                      ; the Warning header, for use in debugging
      warn-text  = quoted-string
      warn-date  = DQUOTE HTTP-date DQUOTE

    Multiple warnings MAY be attached to a response (either by the  
origin
    server or by a cache), including multiple warnings with the same  
code
    number.  For example, a server might provide the same warning with
    texts in both English and Basque.

    When this occurs, the user
    agent ought to inform the user of as many of them as possible, in  
the
    order that they appear in the response.  If it is not possible to
    inform the user of all of the warnings, the user agent SHOULD follow
    these heuristics:

    o  Warnings that appear early in the response take priority over
       those appearing later in the response.

    o  Warnings in the user's preferred character set take priority over
       warnings in other character sets but with identical warn-codes  
and
       warn-agents.

    Systems that generate multiple Warning headers SHOULD order them  
with
    this user agent behavior in mind. New Warning headers SHOULD be  
added
    after any existing Warning headers.

    Warnings are assigned three digit warn-codes.  The first digit
    indicates whether the Warning is required to be deleted from a
    stored cache entry after validation:

    1xx  Warnings that describe the freshness or revalidation status of
       the response, and so MUST be deleted by caches after validation.

    2xx  Warnings that describe some aspect of the entity body or entity
       headers that is not rectified by a revalidation (for example, a
       lossy compression of the entity bodies) and which MUST NOT be
       deleted by caches after validation, unless a full response is
       returned, in which case they MUST be.

    The warn-text SHOULD be in a natural language and character set that
    is most likely to be intelligible to the human user receiving the
    response.  This decision MAY be based on any available knowledge,
    such as the location of the cache or user, the Accept-Language field
    in a request, the Content-Language field in a response, etc.  The
    default language is English and the default character set is ISO-
    8859-1 ([ISO-8859-1]).

    If a character set other than ISO-8859-1 is used, it MUST be encoded
    in the warn-text using the method described in [RFC2047].

    If an implementation sends a message with one or more Warning  
headers
    to a receiver whose version is HTTP/1.0 or lower, then the sender  
MUST
    include in each warning-value a warn-date that matches the Date  
header
    in the message.

    If an implementation receives a message with a warning-value that
    includes a warn-date, and that warn-date is different from the Date
    value in the response, then that warning-value MUST be deleted from
    the message before storing, forwarding, or using it.  (This prevents
    bad consequences of naive caching of Warning header fields.)  If all
    of the warning-values are deleted for this reason, the Warning  
header
    MUST be deleted as well.

    The following warn-codes are defined by this specification, each  
with a
    recommended warn-text in English, and a description of its meaning.

    110 Response is stale

       MUST be included whenever the returned response is stale.

    111 Revalidation failed

       MUST be included if a cache returns a stale response because an
       attempt to validate the response failed, due to an inability to
       reach the server.

    112 Disconnected operation

       SHOULD be included if the cache is intentionally disconnected  
from
       the rest of the network for a period of time.

    113 Heuristic expiration

       MUST be included if the cache heuristically chose a freshness
       lifetime greater than 24 hours and the response's age is greater
       than 24 hours.

    199 Miscellaneous warning

       The warning text MAY include arbitrary information to be  
presented
       to a human user, or logged.  A system receiving this warning MUST
       NOT take any automated action, besides presenting the warning to
       the user.

    214 Transformation applied

       MUST be added by an intermediate cache or proxy if it applies any
       transformation changing the content-coding (as specified in the
       Content-Encoding header) or media-type (as specified in the
       Content-Type header) of the response, or the entity-body of the
       response, unless this Warning code already appears in the
       response.

    299 Miscellaneous persistent warning

       The warning text MAY include arbitrary information to be  
presented
       to a human user, or logged.  A system receiving this warning MUST
       NOT take any automated action.
--->8---

On 03/01/2007, at 8:23 AM, Larry Masinter wrote:

>> The modified proposal (after discussion) is ...
>> "A cache MUST NOT generate 1xx warn-codes for any messages
>> except cache entries, and MUST NOT generate 1xx warn-codes
>> for a cache entry except in response to a validation attempt
>> for that entry. 1xx warn-codes MUST NOT be generated in
>> Request messages."
>
> I think this rewrite is worse than the text it
> proposes to replace, as far as being misleading.
> The text is part of a description of the differences
> between 1xx warnings and 2xx warnings, and the
> 'right' rewrite is to make the descriptions more
> parallel.
>
> The actual conditions for when a 1xx warning
> may be generated (and MUST NOT) be generated
> are contained in section 13.1.1.
>
> Probably the right thing to do is to tighten up the
> language in 13.1.1 so that it is clearly normative,
> and then chanage the 3.1.2 Warnings section so that
> it doesn't attempt to summarize them more succinctly
> than they can be. I'd suggest:
>
>   1xx  Warnings that describe the freshness or revalidation status of
>     the response. These warnings are generally deleted after
>     successful validation (the rules for when a cache MUST or
>     MUST NOT include or delete a warning response are in section  
> 13.1.1.)
>
>   2xx  Warnings that describe some aspect of the entity body or entity
>     headers that is not rectified by a revalidation (for example, a
>     lossy compression of the entity bodies). 2xx MUST NOT be
>     deleted after a successful revalidation.
>
>

--
Mark Nottingham     http://www.mnot.net/