HTTP/1.1 200 OK Date: Mon, 08 Apr 2002 23:59:39 GMT Server: Apache/1.3.20 (Unix) Last-Modified: Fri, 14 Aug 1998 13:07:00 GMT ETag: "2e99af-7843-35d43674" Accept-Ranges: bytes Content-Length: 30787 Connection: close Content-Type: text/plain INTERNET-DRAFT Mandatory H. Frystyk Nielsen, W3C draft-frystyk-http-extensions-00 P. Leach, Microsoft Scott Lawrence, Agranat Systems Expires: February 07, 1999 Friday, August 07, 1998 HTTP Extension Framework for Mandatory and Optional Extensions Status of this Document 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), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). Distribution of this document is unlimited. Please send comments to the mailing list. This list is archived at "http://lists.w3.org/Archives/Public/ietf-http-ext/". The contribution of World Wide Web Consortium (W3C) staff is part of the W3C HTTP Activity (see "http://www.w3.org/Protocols/Activity"). Abstract HTTP is used increasingly in applications that need more facilities than the standard version of the protocol provides, ranging from distributed authoring, collaboration, and printing, to various remote procedure call mechanisms. This document proposes the use of a mandatory extension mechanism designed to address the tension between private agreement and public specification and to accommodate extension of applications such as HTTP clients, servers, and proxies. The proposal associates each extension with a URI[2], and use a few new RFC 822[1] style header fields to carry the extension identifier and related information between the parties involved in an extended transaction. Table of Contents 1. Introduction.....................................................2 2. Notational Conventions...........................................3 Frystyk et al [Page 1] INTERNET-DRAFT Mandatory Friday, August 07, 1998 3. Extension Declarations...........................................3 3.1 Header Field Prefixes.........................................4 4. Extension Header Fields..........................................4 4.1 End-to-End Extensions.........................................5 4.2 Hop-by-Hop Extensions.........................................5 5. Mandatory HTTP Requests..........................................6 6. Mandatory HTTP Responses.........................................7 7. 102 Extended.....................................................7 8. 510 Not Extended.................................................8 9. Publishing an Extension..........................................8 10. Security Considerations.........................................9 11. References......................................................9 12. Acknowledgements...............................................10 13. Authors Addresses..............................................10 14. Summary of Protocol Interactions...............................11 15. Examples.......................................................11 15.1 Client Requests Server to use an Extension..................12 15.2 Server proposes the use of an Extension.....................12 1. Introduction The mandatory proposal is designed to accommodate dynamic extension of HTTP clients and servers by software components; and to address the tension between private agreement and public specification. The kind of extensions capable of being introduced range from: o extending a single HTTP message; o introducing new encodings; o initiating HTTP-derived protocols for new applications; to... o switching to protocols which, once initiated, run independent of the original protocol stack. The proposal is intended to be used as follows: o Some party designs and specifies an extension; the party assigns the extension an identifier, which is a URI, and makes one or more representations of the extension available at that address (see section 9). o An HTTP client, server, or proxy that implements the Mandatory extension mechanism (hereafter called an agent) declares the use of the extension by referencing its URI in an extension declaration in an HTTP message (see section 3). o The ultimate recipient of the extension declaration which can be the origin server, the user agent, or any intermediary in the request/response chain can based on the extension declaration deduce how to properly interpret the extended message. The proposal uses features in HTTP/1.1 but is compatible with both HTTP/1.0 and HTTP/1.1 applications in such a way that extended applications can coexist with existing HTTP applications. Frystyk, et al [Page 2] INTERNET-DRAFT Mandatory Friday, August 07, 1998 By providing a more robust framework for describing extensions, this proposal supersedes several existing extension mechanisms like the HTTP/1.1 Expect and Upgrade header fields as well as avoids existing problems with non-compliant CGI scripts handling unknown HTTP methods. 2. Notational Conventions This specification uses the same notational conventions and basic parsing constructs as RFC 2068[7]. In particular the BNF constructs "token", "quoted-string", "field-name", and "URI" in this document are to be interpreted as described in RFC 2068[7]. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119[9]. This proposal does not rely on particular features defined in URLs [3] that cannot potentially be expressed using URNs (see section 9). Therefore, the more generic term URI[2] is used throughout the specification. 3. Extension Declarations An extension declaration can be used to indicate that an extension has been applied to a message and possibly to reserve a part of the header namespace identified by a header field prefix (see 3.1). This specification does not define any ramifications of applying an extension to a message nor whether two extensions can or cannot logically coexist within the same message. It is strictly a framework for describing which extensions have been applied and what the ultimate recipient either must or may do in order to properly interpret any extension declarations within that message. The grammar for an extension declaration is as follows: ext-decl = <"> URI <"> ";" namespace [ ext-params ] ext-params = *( ext-extension ) namespace = "ns" "=" header-prefix header-prefix = 2*DIGIT "-" ext-extension = ";" token [ "=" ( token | quoted-string ) ] An extension is identified by a URI. Extension identifier URIs can be either relative or absolute. Relative extension identifiers MUST specify header-fields defined in an IETF RFC (see RFC 1808[4]). Examples of extension declarations are "Content-FooBar" "New-Registered-Header" "http://www.temporary.com/extension"; ns=33- Frystyk, et al [Page 3] INTERNET-DRAFT Mandatory Friday, August 07, 1998 An extension declaration can be extended through the use of one or more ext-extension parameters. Unrecognized ext-extension parameters SHOULD be ignored and MUST NOT be removed by proxies when forwarding the extension declaration. 3.1 Header Field Prefixes The header-prefix are dynamically generated header field prefix strings that can be used to indicate that all header fields in the message matching the header-prefix value using string prefix-matching are introduced by this extension instance. This allows an extension instance to dynamically reserve a subspace of the header space in a protocol message in order to prevent header field name clashes. Linear white space (LWS) MUST NOT be used between the digits and the "-". The format of the prefix using a combination of digits and the dash "-" guarantees that no extension declaration can reserve the whole header field name space. Prefixes are primarily intended to avoid header field name conflicts and to allow multiple instances of a single extension using its own header fields to be applied to the same message without conflicting with each other. Agents SHOULD NOT reuse header-prefix values in the same message unless explicitly allowed by the extension (see section 4.1 for a discussion of the ultimate recipient of an extension declaration). Examples of header-prefix values are 1234- 546- 234345653- Old applications may introduce header fields independent of this extension mechanism, potentially conflicting with header fields introduced by the prefix mechanism. In order to minimize this risk, prefixes MUST contain at least 2 digits. 4. Extension Header Fields This proposal introduces two types of extension declaration strength: mandatory and optional, and two types of extension declaration scope: hop-by-hop and end-to-end (see section 4.1 and 4.2). A mandatory extension declaration indicates that the ultimate recipient MUST consult and adhere to the rules given by the extension when processing the message or report an error (see section 5 and 8). Frystyk, et al [Page 4] INTERNET-DRAFT Mandatory Friday, August 07, 1998 An optional extension declaration indicates that the ultimate recipient of the extension MAY consult and adhere to the rules given by the extension when processing the message, or ignore the extension declaration completely. An agent may not be able to distinguish whether the ultimate recipient does not understand an extension referred to by an optional extension or simply ignores the extension declaration. The combination of the declaration strength and scope defines a 2x2 matrix which is distinguished by four new general HTTP header fields: Man, Opt, C-Man, and C-Opt. (See section 4.1 and 4.2, and appendix 14 for a table of interactions with origin servers and proxies.) The header fields are general header fields as they describe which extensions actually are applied to an HTTP message. Optional declarations MAY be applied to any HTTP message without any change to existing HTTP semantics. Mandatory declarations MUST be applied to a request message as described in section 5 and to a response message as described in section 6. 4.1 End-to-End Extensions End-to-end declarations MUST be transmitted to the ultimate recipient of the declaration. The Man and the Opt general header fields are end- to-end header fields and are defined as follows: mandatory = "Man" ":" 1#ext-decl optional = "Opt" ":" 1#ext-decl For example HTTP/1.1 200 OK Content-Length: 421 Opt: "http://www.digest.org/Digest"; ns=55- 55-digest: "snfksjgor2tsajkt52" ... If a proxy is the ultimate recipient of a mandatory end-to-end extension declaration then it MUST handle that extension declaration as described in section 5. The proxy SHOULD remove all parts of the extension declaration from the message before forwarding it. 4.2 Hop-by-Hop Extensions Hop-by-hop extension declarations are meaningful only for a single transport-level connection. The C-Man and the C-Opt general header field are hop-by-hop header fields and MUST NOT be communicated by proxies over further connections. The two headers have the following grammar: c-mandatory = "C-Man" ":" 1#ext-decl c-optional = "C-Opt" ":" 1#ext-decl Frystyk, et al [Page 5] INTERNET-DRAFT Mandatory Friday, August 07, 1998 For example GET / HTTP/1.1 Host: some.host C-Man: "http://www.digest.org/ProxyAuth"; Credentials="g5gj262jdw@4df" Connection: C-Man In HTTP/1.1, the C-Man and the C-Opt header field MUST be protected by a Connection header. That is, the header fields are to be included as Connection header directives (see section [7], section 14.10). An agent MUST NOT send the C-Man or the C-Opt header field to an HTTP/1.0 proxy as it does not obey the HTTP/1.1 rules for parsing the Connection header field (see [7]). 5. Mandatory HTTP Requests An HTTP request is called a mandatory request if it includes at least one mandatory extension declaration (using the Man or the C-Man header fields). The method name of a mandatory request MUST be prefixed by "M-". For example, a client might express the binding rights- management constraints in an HTTP PUT request as follows: M-PUT /a-resource HTTP/1.1 Man: "http://www.copyright.org/rights-management"; ns=43- 43-copyright: http://www.copyright.org/COPYRIGHT.html 43-contributions: http://www.copyright.org/PATCHES.html Host: www.w3.org Content-Length: 1203 Content-Type: text/html