An HTTP Extension Framework

This memo defines an Experimental Protocol for the Internet community. It does not specify an Internet standard of any kind. Discussion and suggestions for improvement are requested. Distribution of this memo is unlimited.¶

Copyright © The Internet Society (2000). All Rights Reserved.¶

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.¶

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: ¶

• extending a single HTTP message;
• introducing new encodings;
• initiating HTTP-derived protocols for new applications; to...
• switching to protocols which, once initiated, run independent of the original protocol stack.

The proposal is intended to be used as follows: ¶

• 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).
• 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).
• 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).¶

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.¶

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.¶

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¶

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.¶

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).¶

An ultimate recipient conforming to this specification receiving a mandatory request MUST process the request by performing the following actions in the order listed below: ¶

1. Identify all mandatory extension declarations (both hop-by-hop and end-to-end); the server MAY ignore optional declarations without affecting the result of processing the HTTP message;
2. Examine all extensions identified in 1) and determine if they are supported for this message. If not, respond with a 510 (Not Extended) status-code (see Section 7);
3. If 2) did not result in a 510 (Not Extended) status code, then process the request according to the semantics of the extensions and of the existing HTTP method name as defined in HTTP/1.1 [5] or later versions of HTTP. The HTTP method name can be obtained by ignoring the "M-" method name prefix.
4. If the evaluation in 3) was successful and the mandatory request fulfilled, the server MUST respond as defined in Section 5.1. A server MUST NOT fulfill a request without understanding and obeying all mandatory extension declaration(s) in a request.

A proxy that does not act as the ultimate recipient of a mandatory extension declaration MUST NOT remove the extension declaration or the "M-" method name prefix when forwarding the message (see Section 5.1 for how to detect when a mandatory extension has been fulfilled).¶

A server receiving an HTTP/1.0 (or earlier versions of HTTP) message that includes a Connection header MUST, for each connection-token in this field, remove and ignore any header field(s) from the message with the same name as the connection-token.¶

A server receiving a mandatory request including the "M-" method name prefix without any mandatory extension declarations to follow MUST return a 510 (Not Extended) response.¶

The "M-" prefix is reserved by this proposal and MUST NOT be used by other HTTP extensions.¶

A server MUST NOT include mandatory extension declarations in an HTTP response unless it is responding to a mandatory HTTP request whose definition allowed for the mandatory response or the server has some a priori knowledge that the recipient can handle the extended response. A server MAY include optional extension declarations in any HTTP response (see Section 4).¶

If a client is the ultimate recipient of a mandatory HTTP response containing mandatory extension declarations that either the client does not understand or does not want to use, then it SHOULD discard the complete response as if it were a 500 (Internal Server Error) response.¶

The policy for accessing the resource has not been met in the request. The server should send back all the information necessary for the client to issue an extended request. It is outside the scope of this specification to specify how the extensions inform the client.¶

If the 510 response contains information about extensions that were not present in the initial request then the client MAY repeat the request if it has reason to believe it can fulfill the extension policy by modifying the request according to the information provided in the 510 response. Otherwise the client MAY present any entity included in the 510 response to the user, since that entity may include relevant diagnostic information.¶

While the protocol extension definition should be published at the address of the extension identifier, this specification does not require it. The only absolute requirement is that extension identifiers MUST be globally unique identifiers, and that distinct names be used for distinct semantics.¶

Likewise, applications are not required to attempt resolving extension identifiers included in an extension declaration. The only absolute requirement is that an application MUST NOT claim conformance with an extension that it does not recognize (regardless of whether it has tried to resolve the extension identifier or not). This document does not provide any policy for how long or how often an application may attempt to resolve an extension identifier.¶

The association between the extension identifier and the specification might be made by distributing a specification, which references the extension identifier.¶

It is strongly recommended that the integrity and persistence of the extension identifier be maintained and kept unquestioned throughout the lifetime of the extension. Care should be taken not to distribute conflicting specifications that reference the same name. Even when an extension specification is made available at the address of the URI, care must be taken that the specification made available at that address does not change over time. One agent may associate the identifier with the old semantics, while another might associate it with the new semantics.¶

The extension definition may be made available in different representations ranging from ¶

• a human-readable specification defining the extension semantics (see for example [7]),
• downloadable code which implements the semantics defined by the extension,
• a formal interface description provided by the extension, to
• a machine-readable specification defining the extension semantics.

For example, a software component that implements the specification may reside at the same address as a human-readable specification (distinguished by content negotiation). The human-readable representation serves to document the extension and encourage deployment, while the software component would allow clients and servers to be dynamically extended.¶

Use of extensions using the syntax defined by this document may have additional implications on the cachability of HTTP response messages other than the ones described in Section 5.1.¶

The originator of an extended message should be able to determine from the semantics of the extension whether or not the extension's presence impacts the caching constraints of the response message. If an extension does require tighter constraints on the cachebility of the response, the originator MUST include the appropriate combination of cache header fields (Cache-Control, Vary, Expires) corresponding to the required level of constraints of the extended semantics.¶

Dynamic installation of extension facilities as described in the introduction involves software written by one party (the provider of the implementation) to be executed under the authority of another (the party operating the host software). This opens the host party to a variety of "Trojan horse" attacks by the provider, or a malicious third party that forges implementations under a provider's name. See, for example RFC2046 [4], section 4.5.2 for a discussion of these risks.¶

Roy Fielding, Rohit Khare, Yaron Y. Goland, and Koen Holtman, deserve special recognition for their efforts in commenting in all phases of this specification. Also thanks to Josh Cohen, Ross Patterson, Jim Gettys, Larry Masinter, and to the people involved in PEP [9].¶

The contribution of World Wide Web Consortium (W3C) staff is part of the W3C HTTP Activity (see "http://www.w3.org/Protocols/Activity").¶

The following tables summarize the outcome of strength and scope rules of the mandatory proposal of compliant and non-compliant HTTP proxies and origin servers. The summary is intended as a guide and index to the text, but is necessarily cryptic and incomplete. This summary should never be used or referenced separately from the complete specification.¶

Table 1: Origin Server

       Scope            Hop-by-hop                End-to-end

     Strength      Optional     Required    Optional     Required
                    (may)        (must)       (may)       (must)

   Mandatory     Standard    501 (Not     Standard     501 (Not
   unsupported   processing  Implemented) processing   Implemented)

   Extension     Standard    510 (Not     Standard     510 (Not
   unsupported   processing  Extended)    processing   Extended)
   Extension     Extended    Extended     Extended     Extended
   supported     processing  processing   processing   processing

Table 2: Proxy Server

       Scope            Hop-by-hop                End-to-end

     Strength      Optional     Required    Optional     Required
                    (may)        (must)       (may)       (must)

   Mandatory     Strip       501 (Not     Forward      501 (Not
   unsupported   extension   Implemented) extension    Implemented)
                             or tunnel                 or tunnel

   Extension     Strip       510 (Not     Forward      Forward
   unsupported   extension   Extended)    extension    extension

   Extension     Extended    Extended     Extended     Extended
   supported     processing  processing   processing,  processing,
                 and strip   and strip    may strip    may strip

The following examples show various scenarios using mandatory in HTTP/1.1 requests and responses. Information not essential for illustrating the examples is left out (referred to as "...")¶

Copyright © The Internet Society (2000). All Rights Reserved.¶

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.¶

The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns.¶

This document and the information contained herein is provided on an “AS IS” basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.¶

The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification can be obtained from the IETF Secretariat.¶

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director.¶

Funding for the RFC Editor function is currently provided by the Internet Society.¶