Skip to content

Commit

Permalink
Obsolete Warning
Browse files Browse the repository at this point in the history 
Fixes #139.
  • Loading branch information
@mnot
mnot committed Oct 15, 2018
1 parent 2a4052e commit 478edff
Showing 1 changed file with 29 additions and 290 deletions.
319 changes: 29 additions & 290 deletions draft-ietf-httpbis-cache-latest.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -431,17 +431,10 @@
the cache complies with the client requirements in <xref target="combining.byte.ranges"/>.
</t>
<t>
When combining the new response with one or more stored responses, a
cache &MUST;:
<list style="symbols">
<t>delete any <x:ref>Warning</x:ref> header fields in the stored response
with warn-code 1xx (see <xref target="header.warning" />);</t>
<t>retain any <x:ref>Warning</x:ref> header fields in the stored response
with warn-code 2xx; and,</t>
<t>use other header fields provided in the new response, aside
from <x:ref>Content-Range</x:ref>, to replace all instances of the
corresponding header fields in the stored response.</t>
</list>
When combining the new response with one or more stored responses, a cache
&MUST; use the header fields provided in the new response, aside from
<x:ref>Content-Range</x:ref>, to replace all instances of the
corresponding header fields in the stored response.
</t>
</section>

Expand Down Expand Up @@ -722,12 +715,6 @@
expiration value that is no more than some fraction of the interval since
that time. A typical setting of this fraction might be 10%.
</t>
<t>
When a heuristic is used to calculate freshness lifetime, a cache &SHOULD;
generate a <x:ref>Warning</x:ref> header field with a 113 warn-code (see
<xref target="warn.113"/>) in the response if its current_age is more than
24 hours and such a warning is not already present.
</t>
<aside>
<t>
&Note; <xref target="RFC2616" x:fmt="of" x:sec="13.9"/> prohibited caches
Expand Down Expand Up @@ -846,18 +833,6 @@
path) or doing so is explicitly allowed (e.g., by the max-stale request
directive; see <xref target="cache-request-directive" />).
</t>
<t>
A cache &SHOULD; generate a <x:ref>Warning</x:ref> header field with the
110 warn-code (see <xref target="warn.110"/>) in stale responses.
Likewise, a cache &SHOULD; generate a 112 warn-code (see
<xref target="warn.112"/>) in stale responses if the cache is disconnected.
</t>
<t>
A cache &SHOULD-NOT; generate a new <x:ref>Warning</x:ref> header field
when forwarding a response that does not have an <x:ref>Age</x:ref> header
field, even if the response is already stale. A cache need not validate
a response that merely became stale in transit.
</t>
</section>
</section>

Expand Down Expand Up @@ -1044,16 +1019,10 @@
</list>
</t>
<t>
For each stored response identified for update, the cache &MUST;:
<list style="symbols">
<t>delete any <x:ref>Warning</x:ref> header fields in the stored response
with warn-code 1xx (see <xref target="header.warning" />);</t>
<t>retain any <x:ref>Warning</x:ref> header fields in the stored response
with warn-code 2xx; and,</t>
<t>use other header fields provided in the <x:ref>304 (Not Modified)</x:ref>
response to replace all instances of the corresponding header
fields in the stored response.</t>
</list>
For each stored response identified for update, the cache &MUST; use the
header fields provided in the <x:ref>304 (Not Modified)</x:ref> response
to replace all instances of the corresponding header fields in the stored
response.
</t>
</section>

Expand Down Expand Up @@ -1084,18 +1053,11 @@
</t>
<t>
If a cache updates a stored response with the metadata provided in a HEAD
response, the cache &MUST;:
<list style="symbols">
<t>delete any <x:ref>Warning</x:ref> header fields in the stored response
with warn-code 1xx (see <xref target="header.warning" />);</t>
<t>retain any <x:ref>Warning</x:ref> header fields in the stored response
with warn-code 2xx; and,</t>
<t>use other header fields provided in the HEAD response to replace all
instances of the corresponding header fields in the stored response
and append new header fields to the stored response's header section
unless otherwise restricted by the <x:ref>Cache-Control</x:ref>
header field.</t>
</list>
response, the cache &MUST; use the header fields provided in the HEAD
response to replace all instances of the corresponding header fields in
the stored response and append new header fields to the stored response's
header section unless otherwise restricted by the
<x:ref>Cache-Control</x:ref> header field.
</t>
</section>
</section>
Expand Down Expand Up @@ -1184,7 +1146,7 @@
</c>
<c>Warning</c>
<c>http</c>
<c>standard</c>
<c>obsoleted</c>
<c>
<xref target="header.warning"/>
</c>
Expand Down Expand Up @@ -1867,238 +1829,13 @@ Pragma: no-cache
<section title="Warning" anchor="header.warning">
<iref item="Warning header field" primary="true" x:for-anchor="" />
<x:anchor-alias value="Warning"/>
<x:anchor-alias value="warning-value"/>
<x:anchor-alias value="warn-agent"/>
<x:anchor-alias value="warn-code"/>
<x:anchor-alias value="warn-date"/>
<x:anchor-alias value="warn-text"/>
<t>
The "Warning" header field is used to carry additional information
The "Warning" header field was used to carry additional information
about the status or transformation of a message that might not be reflected
in the status code. This information is typically used to warn about possible
incorrectness introduced by caching operations or transformations applied
to the payload of the message.
in the status code. This specification obsoletes it, as it is not widely
generated or surfaced to users. The information it carried can be gleaned
from examining other header fields, such as <x:ref>Age</x:ref>.
</t>
<t>
Warnings can be used for other purposes, both cache-related and otherwise.
The use of a warning, rather than an error status code, distinguishes these
responses from true failures.
</t>
<t>
Warning header fields can in general be applied to any message, however some
warn-codes are specific to caches and can only be applied to response
messages.
</t>
<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Warning"/><iref primary="true" item="Grammar" subitem="warning-value"/><iref primary="true" item="Grammar" subitem="warn-code"/><iref primary="true" item="Grammar" subitem="warn-agent"/><iref primary="true" item="Grammar" subitem="warn-text"/><iref primary="true" item="Grammar" subitem="warn-date"/>
<x:ref>Warning</x:ref> = 1#<x:ref>warning-value</x:ref>

<x:ref>warning-value</x:ref> = <x:ref>warn-code</x:ref> <x:ref>SP</x:ref> <x:ref>warn-agent</x:ref> <x:ref>SP</x:ref> <x:ref>warn-text</x:ref>
[ <x:ref>SP</x:ref> <x:ref>warn-date</x:ref> ]

<x:ref>warn-code</x:ref> = 3<x:ref>DIGIT</x:ref>
<x:ref>warn-agent</x:ref> = ( <x:ref>uri-host</x:ref> [ ":" <x:ref>port</x:ref> ] ) / <x:ref>pseudonym</x:ref>
; the name or pseudonym of the server adding
; the Warning header field, for use in debugging
; a single "-" is recommended when agent unknown
<x:ref>warn-text</x:ref> = <x:ref>quoted-string</x:ref>
<x:ref>warn-date</x:ref> = <x:ref>DQUOTE</x:ref> <x:ref>HTTP-date</x:ref> <x:ref>DQUOTE</x:ref>
</artwork></figure>
<t>
Multiple warnings can be generated in a response (either by the origin
server or by a cache), including multiple warnings with the same warn-code
number that only differ in warn-text.
</t>
<t>
A user agent that receives one or more Warning header fields &SHOULD;
inform the user of as many of them as possible, in the order that they
appear in the response. Senders that generate multiple Warning header
fields are encouraged to order them with this user agent behavior in mind.
A sender that generates new Warning header fields &MUST; append them after
any existing Warning header fields.
</t>
<t>
Warnings are assigned three digit warn-codes. The first digit indicates
whether the Warning is required to be deleted from a stored response after
validation:
<list style="symbols">
<t>1xx warn-codes describe the freshness or validation status of the
response, and so they &MUST; be deleted by a cache after validation. They can
only be generated by a cache when validating a cached entry, and
&MUST-NOT; be generated in any other situation.</t>
<t>2xx warn-codes describe some aspect of the representation that is not
rectified by a validation (for example, a lossy compression of the
representation) and they &MUST-NOT; be deleted by a cache after validation,
unless a full response is sent, in which case they &MUST; be.</t>
</list>
</t>
<t>
If a sender generates one or more 1xx warn-codes in a message to be
sent to a recipient known to implement only HTTP/1.0, the sender &MUST;
include in each corresponding warning-value a warn-date that matches the
<x:ref>Date</x:ref> header field in the message. For example:
</t>
<figure><artwork type="message/http; msgtype=&#34;response&#34;" x:indent-with=" ">
HTTP/1.1 200 OK
Date: Sat, 25 Aug 2012 23:34:45 GMT
Warning: 112 - "network down" "Sat, 25 Aug 2012 23:34:45 GMT"

</artwork></figure>
<t>
Warnings have accompanying warn-text that describes the error, e.g., for
logging. It is advisory only, and its content does not affect interpretation
of the warn-code.
</t>
<t>
If a recipient that uses, evaluates, or displays Warning header fields
receives a warn-date that is different from the <x:ref>Date</x:ref> value
in the same message, the recipient &MUST; exclude the warning-value
containing that warn-date before storing, forwarding, or using the message.
This allows recipients to exclude warning-values that were improperly
retained after a cache validation.
If all of the warning-values are excluded, the recipient &MUST; exclude
the Warning header field as well.
</t>
<t>
The following warn-codes are defined by this specification, each with a
recommended warn-text in English, and a description of its meaning.
The procedure for defining additional warn codes is described in
<xref target="warn.code.registry"/>.
</t>
<?BEGININC build/draft-ietf-httpbis-cache-latest.iana-warn-codes ?>
<!--AUTOGENERATED FROM extract-warn-code-defs.xslt, do not edit manually-->
<texttable align="left"
suppress-title="true"
anchor="iana.warn.code.registration.table">
<ttcol>Warn Code</ttcol>
<ttcol>Short Description</ttcol>
<ttcol>Reference</ttcol>
<c>110</c>
<c>Response is Stale</c>
<c>
<xref target="warn.110"/>
</c>
<c>111</c>
<c>Revalidation Failed</c>
<c>
<xref target="warn.111"/>
</c>
<c>112</c>
<c>Disconnected Operation</c>
<c>
<xref target="warn.112"/>
</c>
<c>113</c>
<c>Heuristic Expiration</c>
<c>
<xref target="warn.113"/>
</c>
<c>199</c>
<c>Miscellaneous Warning</c>
<c>
<xref target="warn.199"/>
</c>
<c>214</c>
<c>Transformation Applied</c>
<c>
<xref target="warn.214"/>
</c>
<c>299</c>
<c>Miscellaneous Persistent Warning</c>
<c>
<xref target="warn.299"/>
</c>
</texttable>
<!--(END)-->

<?ENDINC build/draft-ietf-httpbis-cache-latest.iana-warn-codes ?>

<section title='Warning: 110 - "Response is Stale"' anchor="warn.110">
<iref primary="true" item="110 (warn-code)" x:for-anchor=""/>
<iref primary="true" item="Response is Stale (warn-text)" x:for-anchor=""/>
<t>
A cache &SHOULD; generate this whenever the sent response is stale.
</t>
</section>

<section title='Warning: 111 - "Revalidation Failed"' anchor="warn.111">
<iref primary="true" item="111 (warn-code)" x:for-anchor=""/>
<iref primary="true" item="Revalidation Failed (warn-text)" x:for-anchor=""/>
<t>
A cache &SHOULD; generate this when sending a stale response because an
attempt to validate the response failed, due to an inability to reach
the server.
</t>
</section>

<section title='Warning: 112 - "Disconnected Operation"' anchor="warn.112">
<iref primary="true" item="112 (warn-code)" x:for-anchor=""/>
<iref primary="true" item="Disconnected Operation (warn-text)" x:for-anchor=""/>
<t>
A cache &SHOULD; generate this if it is intentionally disconnected from
the rest of the network for a period of time.
</t>
</section>

<section title='Warning: 113 - "Heuristic Expiration"' anchor="warn.113">
<iref primary="true" item="113 (warn-code)" x:for-anchor=""/>
<iref primary="true" item="Heuristic Expiration (warn-text)" x:for-anchor=""/>
<t>
A cache &SHOULD; generate this if it heuristically chose a freshness
lifetime greater than 24 hours and the response's age is greater than 24
hours.
</t>
</section>

<section title='Warning: 199 - "Miscellaneous Warning"' anchor="warn.199">
<iref primary="true" item="199 (warn-code)" x:for-anchor=""/>
<iref primary="true" item="Miscellaneous Warning (warn-text)" x:for-anchor=""/>
<t>
The warning text can 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.
</t>
</section>

<section title='Warning: 214 - "Transformation Applied"' anchor="warn.214">
<iref primary="true" item="214 (warn-code)" x:for-anchor=""/>
<iref primary="true" item="Transformation Applied (warn-text)" x:for-anchor=""/>
<t>
This Warning code &MUST; be added by a proxy if it applies any transformation to the
representation, such as changing the content-coding, media-type, or
modifying the representation data, unless this Warning code already appears
in the response.
</t>
</section>

<section title='Warning: 299 - "Miscellaneous Persistent Warning"' anchor="warn.299">
<iref primary="true" item="299 (warn-code)" x:for-anchor=""/>
<iref primary="true" item="Miscellaneous Persistent Warning (warn-text)" x:for-anchor=""/>
<t>
The warning text can include arbitrary information to be presented to
a human user or logged. A system receiving this warning &MUST-NOT; take
any automated action.
</t>
</section>

<section title="Warn Code Registry" anchor="warn.code.registry">
<t>
The "Hypertext Transfer Protocol (HTTP) Warn Codes" registry defines the namespace for warn codes.
It has been created and is now maintained at
<eref target="https://www.iana.org/assignments/http-warn-codes"/>.
</t>
<t>
A registration &MUST; include the following fields:
<list style="symbols">
<t>Warn Code (3 digits)</t>
<t>Short Description</t>
<t>Pointer to specification text</t>
</list>
</t>
<t>
Values to be added to this namespace require IETF Review (see <xref
target="RFC8126" x:fmt="," x:sec="4.8"/>).
</t>
</section>
</section>
</section>

Expand Down Expand Up @@ -2194,13 +1931,12 @@ Warning: 112 - "network down" "Sat, 25 Aug 2012 23:34:45 GMT"
</t>
</section>

<section title="Warn Code Registration" anchor="warn.code.registration">
<section title="Warn Code Registry" anchor="warn.code.registration">
<t>
Please update the "Hypertext Transfer Protocol (HTTP) Warn Codes" registry
at <eref target="https://www.iana.org/assignments/http-warn-codes"/>
with the registration procedure of <xref target="warn.code.registry"/>
and the warn code values summarized in the table of
<xref target="header.warning"/>.
Please add a note to the "Hypertext Transfer Protocol (HTTP) Warn Codes"
registry at <eref
target="https://www.iana.org/assignments/http-warn-codes"/> to the effect
that Warning is obsoleted.
</t>
</section>
</section>
Expand Down Expand Up @@ -2483,9 +2219,12 @@ Warning: 112 - "network down" "Sat, 25 Aug 2012 23:34:45 GMT"
<?ENDINC build/draft-ietf-httpbis-cache-latest.abnf-appendix ?>

<section title="Changes from RFC 7234" anchor="changes.from.rfc.7234">
<t>
None yet.
</t>
<ul>
<t>The Warning response header was obsoleted. Much of the information
supported by Warning could be gleaned by examining the response), and the
remaining warn-codes -- although potentially useful -- were entirely
advisory, and in practice were not added by caches or intermediaries.</t>
</ul>
</section>

<section title="Change Log" anchor="change.log" removeInRFC="true">
Expand Down

0 comments on commit 478edff

Please sign in to comment.