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]