Internet Draft
HTTP Working Group J. Mogul, DECWRL
Internet-Draft 12 September 1997
Expires: 28 March 1998
Format and Example of HTTP/1.1 Requirements Summary
draft-mogul-http-req-sum-00.txt
STATUS OF THIS MEMO
This document is an Internet-Draft. Internet-Drafts are
working documents of the Internet Engineering Task Force
(IETF), its areas, and its working groups. Note that other
groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of
six months and may be updated, replaced, or obsoleted by
other documents at any time. It is inappropriate to use
Internet-Drafts as reference material or to cite them other
than as "work in progress."
To learn the current status of any Internet-Draft, please
check the "1id-abstracts.txt" listing contained in the
Internet-Drafts Shadow Directories on ftp.is.co.za
(Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific
Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US
West Coast).
Distribution of this document is unlimited. Please send
comments to the HTTP working group at
. Discussions of the working
group are archived at
. General
discussions about HTTP and the applications which use HTTP
should take place on the mailing list.
ABSTRACT
RFC1122 [1] introduced a ``Requirements Summary'' format,
to help implementors understand what aspects of a lengthy
specification were mandatory, recommended, or optional.
The HTTP/1.1 specification is similarly lengthy and
complicated; many implementors have asked for guidance in
understanding what they need to do. The latest draft
revision of the HTTP/1.1 specification [2] has a
placeholder section for a ``Requirements Summary'', but
there has been relatively little discussion of the format
and content of this summary in the HTTP working group.
This document proposes a specific format for the summary,
and gives an example summary for one section of the
document.
Mogul [Page 1]
Internet-Draft HTTP requirements summary 12 September 1997 17:27
TABLE OF CONTENTS
1 Introduction 2
2 Categorizing implementations 2
2.1 Introductory material for Requirements Summary 3
3 DRAFT Requirements summary for Section 13: Caching 4
4 Security Considerations 7
5 Acknowledgments 7
6 References 7
7 Author's address 7
1 Introduction
RFC1122 [1] introduced a ``Requirements Summary'' format, to help
implementors understand what aspects of a lengthy specification were
mandatory, recommended, or optional. The HTTP/1.1 specification is
similarly lengthy and complicated; many implementors have asked for
guidance in understanding what they need to do. This is especially
important because there are several kinds of HTTP/1.1 implementations
(including server, proxy, and client, with or without caches). Many
aspects of the specification apply only to a subset of these
implementation categories, which means that someone implementing,
say, an HTTP client must disentangle the client-specific requirements
from the (client-irrrelevant) requirements for servers and proxies.
The latest draft revision of the HTTP/1.1 specification [2] has a
placeholder section for a ``Requirements Summary'' (section 19.9).
but there has been relatively little discussion of the format and
content of this summary in the HTTP working group. What little
discussion has taken place has been mostly positive, but there are
some concerns about how the implementations are categorized.
This document proposes a specific format for the summary, and gives
an example summary for one section of the document.
2 Categorizing implementations
We would like to design the format of the Requirements Summary so
that it is readable even in the plain-ASCII version of the HTTP/1.1
specification, since this is the ``official'' version of an IETF
specification. This places some constraints on the number of columns
in the format, which in turn constrains the number of categories that
can be comfortably included.
Although at first glance, there might appear to be at least six
different implementation categories (server, proxy, client, each with
or without a cache). However, in many sections of the HTTP
specification, caching is irrelevant. For many other features, it is
fairly obvious whether the feature applies to a cache or not.
Mogul [Page 2]
Internet-Draft HTTP requirements summary 12 September 1997 17:27
Therefore, we propose a format where the applicability of a
requirement to an caching implementation is signalled by a footnote,
rather than expanding the number of columns to six.
One possible implementation of this format would be as a spreadsheet,
using a portable representation (such as ``comma separated values'').
The use of a spreadsheet would allow separate editing of the
requirements summary, followed by semi-automatic insertion into the
master copy of the HTTP/1.1 specification. It might also allow
semi-automatic extraction of subset requirements application to
specific kinds of implementations.
2.1 Introductory material for Requirements Summary
[This is repeated more or less verbatim from section 19.9 of [2], for
the benefit of the reader.]
This section summarizes the requirements of the HTTP/1.1
specification. (Requirements are those aspects of the protocol
defined with the words "MUST", "SHOULD", or "MAY.")
This list is not a normative part of the HTTP/1.1 specification, and
if there is any conflict between this listing and another part of the
specification, the statements elsewhere in the specification take
absolute priority.
Requirements are listed in the order that they appear in the the
specification. For each requirement, the list includes
- a very brief summary of the feature; this is meant for
identification purposes only, and must not be used as a
specification of the feature.
- the section of the document in which the feature is
specified.
- A column for each of three categories of implementation
(Server, Proxy, and Client), showing whether the listed
feature is a MUST, SHOULD, or MAY requirement.
- A column for additional footnotes Note that some aspects of
the protocol may be specified in multiple sections in
separated part of the document.
In order to fit into the standard IETF format for ASCII text
documents, some of the column headings, and the requirement keywords,
are abbreviated.
[End of extract from [2].]
Key for column headings:
Srvr = Server
Mogul [Page 3]
Internet-Draft HTTP requirements summary 12 September 1997 17:27
Prox = Proxy
Clnt = Client
Key for requirements keywords:
M = MUST
MN = MUST NOT
S = SHOULD
SN = SHOULD NOT
ok = MAY
na = Not applicable
Some entries are listed as ``MUST NOT'' or ``SHOULD NOT'' even if the
feature summary seems to indicate a ``MUST'' or ``SHOULD''. The
entries reflect the words from the actual spec, rather than the
feature summary. I.e., the feature summary wording is only to help
the reader find the appropriate passage; it is in no way a definitive
description of the requirement!
3 DRAFT Requirements summary for Section 13: Caching
The following table has NOT been carefully proofread; it
probably contains errors. Please do not base an implementation
on this version of the summary!
There is at least one bogus entry that has been inserted into
the following table, to encourage careful proofreading.
For section 13 (Caching), almost all of the requirements that apply
to proxies apply only to caching proxies. A few requirements do also
apply to non-caching proxies; this is noted where applicable.
Notes:
1 Cache rule applies to client-local caches as well as proxy
caches.
2 Rule applies to non-caching proxies.
98 No explicit upper-case conformance requirement stated in [2],
perhaps not actually a conformance requirement.
99 No explicit upper-case conformance requirement stated in [2]
Feature summary Section Srvr Prox Clnt Note
=============== ======= ==== ==== ==== ====
Meets cache correctness rules 1-3 13.1.1 na M M 1
If server unreachable, follow rules 1-3 13.1.1 na S S 1
ditto, or return error/warning 13.1.1 na M M 1
Forward initially-stale response 13.1.1 na S S 1, 2
Don't revalidate initially-stale resp 13.1.1 na SN SN 1
Mogul [Page 4]
Internet-Draft HTTP requirements summary 12 September 1997 17:27
Display warning on received-stale resp 13.1.1 na na ok
Delete MUST-delete warning after reval 13.1.2 na M M 1
Keep MUST-keep warning after reval 13.1.2 na M M 1
Attach Warning to stale response 13.1.5 na M na
Obey client request for freshness 13.1.5 na S na
Revalidate init-stale cached response 13.2.1 na S S 1
Comply with Age calculation algorithm 13.2.3 na M M 1,2,99
Interpret Age rel. to initiation time 13.2.3 na M M 1
max-age overrules Expires 13.2.4 na M M 1, 99
Use heuristic if no Expires or max-age 13.2.4 na ok ok 1
Warn if heuristic & Age > 24 hours 13.2.4 na M M 1, 99
Base heuristic on Last-Mod time 13.2.4 na S S 1
Freshness test based on age 13.2.4 na M M 1, 99
Ignore new response with older Date 13.2.5 na ok ok 1
Use response with most recent Date 13.2.5 na M M 1
Re-revalidate when new resp seems old 13.2.6 na S S 1
Don't expect disambiguation for = Dates 13.2.6 MN na na
Weak comparison for non-subrange reqs 13.3.3 ok ok na
Strong comparison for subrange/non-GET 13.3.3 M M na
Last-modified implicitly weak 13.3.3 M M M 99
Strong etag changes always 13.3.4 M na na
Weak etag changes when 'significant' 13.3.4 S na na
Use etag in conditionals, if available 13.3.4 na M M
Use Last-Modified, if avail & no etag 13.3.4 na S S
ditto, with subrange reqs 13.3.4 na ok ok
Disable use of Last-Mod w/subranges 13.3.4 na na S 99
Use both Last-Mod & etag, if avail 13.3.4 na S S
Use most restrictive validator 13.3.4 na M M 1
Validate only w/etag or Last-Modified 13.3.5 M M M 98
Responses normally cachable 13.4 na ok ok 99
HTTP/1.0 responses not cachable 13.4 na MN MN 1
No validator/expires/max-age ->no cache 13.4 na S S 99
ditto unless unusual situation 13.4 na ok ok 99
Cachable status codes are
200, 203, 206, 300, 301, 410 13.4 na ok ok 99
Cache 206 only if ranges supported 13.4 na MN MN 1
Other status codes w/out explict perm 13.4 na MN MN 1
Don't add or modify Content-Location,
Content-MD5, or Etag 13.5.2 na MN na 2
Don't modify Expires, Content-Length 13.5.2 na MN na 2
Mogul [Page 5]
Internet-Draft HTTP requirements summary 12 September 1997 17:27
Added Expires = Date 13.5.2 na M M 2
Added Content-Length is accurate 13.5.2 na M na 2
If no-transform, don't add
Content-Encoding, Content-Length,
Content-Range, Content-Type 13.5.2 na MN na 2
Add Warning if adding
Content-Encoding, Content-Length,
Content-Range, Content-Type 13.5.2 na M na 2
Combine partial resps 13.5.3 na ok ok 1
Delete 1XX Warnings on revalidate 13.5.3 na M M 1
Keep 2XX Warnings on revalidate 13.5.3 na M M 1
304/206 hdrs update cache entry 13.5.3 na M M 1
End-to-end hdrs update cache entry 13.5.3 na M M 1
Combined subranges: validators match 13.5.4 na M M 1
Combined subranges: strong validators 13.5.4 na M M 1
Otherwise: use most recent partial resp 13.5.4 na M M 1, 99
Use Vary to list selecting req hdrs 13.6 M na na
New req hdrs match Vary on cache use 13.6 na M M 1
Forward non-matching requests 13.6 na M M 1
Forwarded req conditional if have Etag 13.6 na S S 1
Resp updates entry if tags match 13.6 na S S 1
Forward new response 13.6 na M na
Vary * means forward new reqs 13.6 na MN MN 1
Omit Etag on conditional req and
partial cache entry 13.6 na SN SN 1
Delete entry if URI matches
Content-Location on newer resp and
Etags don't match 13.6 na SN SN 1
Provide security for non-shared caches 13.7 S S S 1
Store incomplete response 13.8 na ok ok 1, 99
Incomplete resp. is partial 13.8 na M M 1
Mark all partial resps. as such 13.8 na M M 1
Don't use 200 with partial resp. 13.8 na MN MN 1
Forward 5xx response 13.8 na ok na 2
Treat 5xx like dead server 13.8 na ok na
GET/HEAD: no side effects 13.9 SN na na
PUT,DELETE,POST invalidate entries 13.10 na S S 98
Match host if invalidating by URI 13.10 na M M 1
Write-through all updates 13.11 na M M 1
Use latest response 13.12 na S S 1
History not transparent 13.13 na na SN
Mogul [Page 6]
Internet-Draft HTTP requirements summary 12 September 1997 17:27
Expires no effect on history 13.13 na na ok 98
History can indicate staleness 13.13 na na ok 98
4 Security Considerations
This document only summarizes the specification in [2], it does not
introduce any new features to HTTP. Therefore, there are no security
considerations particular to the requirements summary itself.
5 Acknowledgments
T.B.S.
6 References
1. R. Braden. Requirements for Internet Hosts -- Communication
Layers. RFC 1122, Internet Engineering Task Force, October, 1989.
2. Roy T. Fielding, Henrik Frystyk Nielsen, and Tim Berners-Lee.
Hypertext Transfer Protocol -- HTTP/1.1. Internet-Draft
draft-ietf-http-v11-spec-08.txt, HTTP Working Group, September?,
1997. [As of this writing, this document has not been assigned an
actual Internet-Draft name/number; however, it is available on the
Web at
www.ics.uci.edu/pub/ietf/http/draft-ietf-http-v11-spec-08.txt.gz and
is widely known as ``draft-08''].
7 Author's address
Jeffrey C. Mogul
Western Research Laboratory
Digital Equipment Corporation
250 University Avenue
Palo Alto, California, 94305, USA
Email: mogul@wrl.dec.com
Mogul [Page 7]