INTERNET-DRAFT HTTP Extensions H. Frystyk Nielsen, W3C draft-frystyk-http-extensions-03 P. Leach, Microsoft Scott Lawrence, Agranat Systems Expires: Sep 15, 1999 Mon, Mar 15, 1999 HTTP Extension Framework Status of this Document This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. General information about this document is linked from "http://www.w3.org/Protocols/HTTP/ietf-http-ext/". Send comments to the mailing list. This list is archived at "http://lists.w3.org/Archives/Public/ietf-http-ext/". Abstract A wide range of applications have proposed various extensions of the HTTP protocol. Current efforts span an enormous range, including distributed authoring, collaboration, printing, and remote procedure call mechanisms. These HTTP extensions are not coordinated, since there has been no standard framework for defining extensions and thus, separation of concerns. This document describes a generic extension mechanism for HTTP, which is designed to address the tension between private agreement and public specification and to accommodate extension of applications using HTTP clients, servers, and proxies. The proposal associates each extension with a globally unique identifier, and uses HTTP header fields to carry the extension identifier and related information between the parties involved in the extended communication. Table of Contents 1. Introduction ...............................................2 2. Notational Conventions .....................................3 Frystyk et al [Page 1] INTERNET-DRAFT HTTP Extensions Mon, Mar 15, 1999 3. Extension Declarations .....................................3 3.1 Header Field Prefixes ...................................4 4. Extension Header Fields ....................................6 4.1 End-to-End Extensions ...................................6 4.2 Hop-by-Hop Extensions ...................................7 4.3 Extension Response Header Fields ........................7 5. Mandatory HTTP Requests ....................................8 5.1 Fulfilling a Mandatory Request ..........................9 6. Mandatory HTTP Responses ..................................10 7. 510 Not Extended ..........................................11 8. Publishing an Extension ...................................11 9. Caching Considerations ....................................12 10. Security Considerations ...................................13 11. References ................................................13 12. Acknowledgements ..........................................13 13. Authors Addresses .........................................14 14. Summary of Protocol Interactions ..........................14 15. Examples ..................................................15 15.1 User Agent to Origin Server ............................15 15.2 User Agent to Origin Server via HTTP/1.1 Proxy .........16 15.3 User Agent to Origin Server via HTTP/1.0 Proxy .........17 1. Introduction This proposal is designed to address the tension between private agreement and public specification; and to accommodate dynamic extension of HTTP clients and servers by software components. 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 a globally unique URI, and makes one or more representations of the extension available at that address (see section 8). Frystyk, et al [Page 2] INTERNET-DRAFT HTTP Extensions Mon, Mar 15, 1999 o An HTTP client or server that implements this 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 HTTP application which the extension declaration is intended for (hereafter called the ultimate recipient) can deduce how to properly interpret the extended message based on the extension declaration. The proposal uses features in HTTP/1.1 but is compatible with HTTP/1.0 applications in such a way that extended applications can coexist with existing HTTP applications. Applications implementing this proposal MUST be based on HTTP/1.1 (or later versions of HTTP). 2. Notational Conventions This specification uses the same notational conventions and basic parsing constructs as RFC 2068 [5]. In particular the BNF constructs "token", "quoted-string", "Request-Line", "field-name", and "absoluteURI" in this document are to be interpreted as described in RFC 2068 [5]. 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 [6]. This proposal does not rely on particular features defined in URLs [8] that cannot potentially be expressed using URNs (see section 8). Therefore, the more generic term URI [8] 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 section defines the extension declaration itself; section 4 defines a set of header fields using the extension declaration. 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 simply 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. Frystyk, et al [Page 3] INTERNET-DRAFT HTTP Extensions Mon, Mar 15, 1999 The grammar for an extension declaration is as follows: ext-decl = <"> ( absoluteURI | field-name ) <"> [ namespace ] [ decl-extensions ] namespace = ";" "ns" "=" header-prefix header-prefix = 2*DIGIT decl-extensions = *( decl-ext ) decl-ext = ";" token [ "=" ( token | quoted-string ) ] An extension is identified by an absolute, globally unique URI or a field-name. A field-name MUST specify a header field uniquely defined in an IETF Standards Track RFC [3]. A URI can unambiguously be distinguished from a field-name by the presence of a colon (":"). The support for header field names as extension identifiers provides a transition strategy from decentralized extensions to extensions defined by IETF Standards Track RFCs until a mapping between the globally unique URI space and features defined in IETF Standards Track RFCs has been defined according to the guidelines described in section 8. Examples of extension declarations are "http://www.company.com/extension"; ns=11 "Range" An agent MAY use the decl-extensions mechanism to include optional extension declaration parameters but cannot assume these parameters to be recognized by the recipient. An agent MUST NOT use decl-extensions to pass extension instance data, which MAY be passed using header field prefix values (see section 3.1). Unrecognized decl-ext parameters SHOULD be ignored and MUST NOT be removed by proxies when forwarding the extension declaration. 3.1 Header Field Prefixes The header-prefix is a dynamically generated string. All header fields in the message that match this string, using string prefix-matching, belong to that extension declaration. Header field prefixes allow an extension declaration to dynamically reserve a subspace of the header space in a protocol message in order to prevent header field name clashes and to allow multiple declarations using the same extension to be applied to the same message without conflicting. Frystyk, et al [Page 4] INTERNET-DRAFT HTTP Extensions Mon, Mar 15, 1999 Header fields using a header-prefix are of the form: prefixed-header = prefix-match field-name prefix-match = header-prefix "-" Linear white space (LWS) MUST NOT be used between the header-prefix and the dash ("-") or between the prefix-match and the field-name. The string prefix matching algorithm is applied to the prefix-match string. 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. The header-prefix mechanism was preferred over other solutions for exchanging extension instance parameters because it is header based and therefore allows for easy integration of new extensions with existing HTTP features. Agents MUST 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). Clients SHOULD be as consistent as possible when generating header- prefix values as this facilitates use of the Vary header field in responses that vary as a function of the request extension declaration(s) (see [5], section 13.6). Servers including prefixed-header header fields in a Vary header field value MUST also include the corresponding extension declaration field- name as part of that value. For example, if a response depends on the value of the 16-use-transform header field defined by an optional extension declaration in the request, the Vary header field in the response could look like this: Vary: Opt, 16-use-transform Note, that header-prefix consistency is no substitute for including an extension declaration in the message: header fields with header-prefix values not defined by an extension declaration in the same message are not defined by this specification. Examples of header-prefix values are Frystyk, et al [Page 5] INTERNET-DRAFT HTTP Extensions Mon, Mar 15, 1999 12 15 23 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 reporting an error (see section 5 and 7). 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 sections 4.1 and 4.2; also see appendix 14, which has 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 if appropriate (see section 5 for how to apply mandatory extension declarations to requests and section 6 for how to apply them to responses). 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: Frystyk, et al [Page 6] INTERNET-DRAFT HTTP Extensions Mon, Mar 15, 1999 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=15 15-digest: "snfksjgor2tsajkt52" ... The ultimate recipient of a mandatory end-to-end extension declaration MUST handle that extension declaration as described in section 5 and 6. 4.2 Hop-by-Hop Extensions Hop-by-hop extension declarations are meaningful only for a single HTTP connection. In HTTP/1.1, C-Man, C-Opt, and all header fields with matching header-prefix values defined by C-Man and C-Opt MUST be protected by a Connection header field. That is, these header fields are to be included as Connection header field directives (see [5], section 14.10). The two header fields have the following grammar: c-mandatory = "C-Man" ":" 1#ext-decl c-optional = "C-Opt" ":" 1#ext-decl For example M-GET / HTTP/1.1 Host: some.host C-Man: "http://www.digest.org/ProxyAuth"; ns=14 14-Credentials="g5gj262jdw@4df" Connection: C-Man, 14-Credentials The ultimate recipient of a mandatory hop-by-hop extension declaration MUST handle that extension declaration as described in section 5 and 6. 4.3 Extension Response Header Fields Two extension response header fields are used to indicate that a request containing mandatory extension declarations has been fulfilled by the ultimate recipient as described in section 5.1. The extension response header fields are exclusively intended to serve as extension acknowledgements, and can not carry any other information. Frystyk, et al [Page 7] INTERNET-DRAFT HTTP Extensions Mon, Mar 15, 1999 The Ext header field is used to indicate that all end-to-end mandatory extension declarations in the request were fulfilled: ext = "Ext" ":" The C-Ext response header field is used to indicate that all hop-by- hop mandatory extension declarations in the request were fulfilled. c-ext = "C-Ext" ":" In HTTP/1.1, the C-Ext header fields MUST be protected by a Connection header (see [5], section 14.10). The Ext and the C-Ext header fields are not mutually exclusive; they can both occur within the same message as described in section 5.1. 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=16 16-copyright: http://www.copyright.org/COPYRIGHT.html 16-contributions: http://www.copyright.org/PATCHES.html Host: www.w3.org Content-Length: 1203 Content-Type: text/html