Network Working Group H. Nielsen
Request for Comments: 2774 P. Leach
Category: Experimental Microsoft
S. Lawrence
Agranat Systems
February 2000
An HTTP Extension Framework
Status of this Memo
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 Notice
Copyright (C) The Internet Society (2000). All Rights Reserved.
IESG Note
This document was originally requested for Proposed Standard status.
However, due to mixed reviews during Last Call and within the HTTP
working group, it is being published as an Experimental document.
This is not necessarily an indication of technical flaws in the
document; rather, there is a more general concern about whether this
document actually represents community consensus regarding the
evolution of HTTP. Additional study and discussion are needed before
this can be determined.
Note also that when HTTP is used as a substrate for other protocols,
it may be necessary or appropriate to use other extension mechanisms
in addition to, or instead of, those defined here. This document
should therefore not be taken as a blueprint for adding extensions to
HTTP, but it defines mechanisms that might be useful in such
circumstances.
Nielsen, et al. Experimental [Page 1]
RFC 2774 An HTTP Extension Framework February 2000
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 ...............................................3
2. Notational Conventions .....................................3
3. Extension Declarations .....................................4
3.1 Header Field Prefixes ...................................5
4. Extension Header Fields ....................................6
4.1 End-to-End Extensions ...................................7
4.2 Hop-by-Hop Extensions ...................................7
4.3 Extension Response Header Fields ........................8
5. Mandatory HTTP Requests ....................................8
5.1 Fulfilling a Mandatory Request .........................10
6. Mandatory HTTP Responses ..................................11
7. 510 Not Extended ..........................................11
8. Publishing an Extension ...................................11
9. Caching Considerations ....................................12
10. Security Considerations ...................................13
11. References ................................................13
12. Acknowledgements ..........................................14
13. Authors' Addresses ........................................14
14. Summary of Protocol Interactions ..........................15
15. Examples ..................................................16
15.1 User Agent to Origin Server ............................16
15.2 User Agent to Origin Server via HTTP/1.1 Proxy .........17
15.3 User Agent to Origin Server via HTTP/1.0 Proxy .........18
Full Copyright Statement ......................................20
Nielsen, et al. Experimental [Page 2]
RFC 2774 An HTTP Extension Framework February 2000
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).
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].
Nielsen, et al. Experimental [Page 3]
RFC 2774 An HTTP Extension Framework February 2000
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.
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.
Nielsen, et al. Experimental [Page 4]
RFC 2774 An HTTP Extension Framework February 2000
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.
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).
Nielsen, et al. Experimental [Page 5]
RFC 2774 An HTTP Extension Framework February 2000
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
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.
Nielsen, et al. Experimental [Page 6]
RFC 2774 An HTTP Extension Framework February 2000
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:
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
Nielsen, et al. Experimental [Page 7]
RFC 2774 An HTTP Extension Framework February 2000
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.
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:
Nielsen, et al. Experimental [Page 8]
RFC 2774 An HTTP Extension Framework February 2000
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
RFC, FYI, BCP