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).
This document is also available as a W3C Working Draft. The most recent release is available at /TR/WD-http-pep.
Distribution of this document is unlimited. Please send comments to the HTTP working group at http-wg@cuckoo.hpl.hp.com. Discussions of the working group are archived at http://www.ics.uci.edu/pub/ietf/http/. The editor maintains background information about PEP at /Protocols/PEP/
The contribution of W3 Consortium staff time to the HTTP working group is part of the W3C HTTP Activity.
HTTP is an extensible protocol. PEP is an extension mechanism designed to address the tension between private agreement and public specification and to accomodate extension of HTTP clients and servers by software components.
The PEP mechanism is to associate each extension with a URL, and use a few new header fields to carry the extension identifier and related information from HTTP clients, thru proxies and intermediaries, to servers, and back again.
PEP relies on some HTTP 1.1 features, but is intended to be compatible with all versions of HTTP from 1.1 on, and to be compatible with HTTP/1.0 inasmuch as HTTP 1.1 is compatible with HTTP/1.0.
HTTP is a generic request-response protocol, designed to accomodate a variety of applications, from network information retrieval and searching to file transfer and repository access to query and forms processing.
HTTP is used increasingly in applications that need more facilities than the standard version of the protocol provides, from distributed authoring, collaboration and printing, to various remote procedure call mechanisms.
Many of these applications do not require agreement across the whole Internet about the extended facilities; rather, it suffices:
This document defines PEP, an extension mechanism for HTTP. The PEP design is the result of analyzing a variety of HTTP extensions and extension mechanisms, and the motivation behind them.
PEP relies on some HTTP 1.1 features, but is intended to be compatible with all versions of HTTP from 1.1 on, and to be compatible with HTTP/1.0 inasmuch as HTTP 1.1 is compatible with HTTP/1.0. See section Considerations for Defining Extensions.
PEP is intended to be used as follows:
Editor's note: I have used the term URL throughout this specification, following the popular jargon from the NCSA Mosaic documentation and and the standards track documents RFC1738 and RFC1808. The HTTP 1.1 spec uses URL in some places and URI in others. I don't understand the distinction, and I suspect that none was intended. PEP does not exploit any distinctions between URIs and URLs, and so I would prefer to use only one of the terms.
Note that, at the cost of some extra bytes to spell out the URL in full, the use of a central registry of extension names is avoided.
See Considerations for Defining Extensions for more on defining extensions.
The PEP mechanism is designed to accomodate extension of clients, servers, and proxies by software components as follows:
The agents in an HTTP transaction are a client and a server, which send HTTP messages to each other, with intermediaries between them in some cases. However, semantically, an HTTP trasacion is between a client party (for example, the referent of the From: header field) and a the principle responsible for the publication of a given resource.
The publishing party is basically the one responsible for the service provided at any particular URL, for example, the mapping between the URL and any representation of the resource to which it refers. Exactly who takes this role is beyond the scope this document, but for example, it may be the writer of a document, the server administrator, the organization running the server, or a combination of these.
PEP extensions may be used to extend the end-to-end transaction semantics, or, using the Connection header field (see [HTTP] section 14.10 Connection), they may be used to extend the hop-by-hop transaction semantics. See The Protocol Header Field and Hop-by-hop Extensions (Section 2.2) for details.
PEP extensions often define inessential, non-binding facilities; that is, the transaction can still succeed even if some parties do not participate in the extension. The distinction between binding and non-binding uses of extensions is syntactically evident in requests and responses. See The Protocol Header Field and Binding Extensions Request for details.
The extensions used in a message are declared using the Protocol request/response header field.
The syntax is:
Protocol = "Protocol" ":" 1#extension-decl
| "C-Protocol" ":" 1#extension-decl
extension-decl = "{" extension-id *ext-info "}"
extension-id = URL
ext-info = str | enc | params
params = "{" "params" *bagitem "}"
str = "{" "str" ("req" | "ref" | "opt" ) "}"
enc = "enc"
bag = "{" bagname 1*LWS *bagitem "}"
bagname = token ¦ URL
bagitem = bag ¦ token ¦ quoted-string
URL = 1*<any char except CTLs or space>
Each extension-decl:
Note that, since URLs may contain { and } characters, a space is required after the bagname.
For example:
GET /a-document HTTP/1.1
Host: a.host
Protocol: {http://some.org/an-extension }
HTTP/1.1 200 OK
Protocol: {http://some.org/an-extension }
Vary: Protocol
Content-Type: text/plain
Glad you're using an-extension!
Note the use of the Vary header to notify proxies that responses to GET /a-document depend on the Protocol header fields used in the request. See [HTTP], section 14.43 Vary.
Each extension-decl declares the use of the extension to be one of:
If any of the extension declarations in a request is required, then the request is a binding extension request. See: Binding Extensions Request.
The issue of "relavent agents" is defined in section Hop-by-hop Extensions and summarized in section Summary of Protocol Interactions.
Extensions declared with the Protocol header field are end-to-end extensions. Hop-by-hop extensions are declared with the C-Protocol header field, in conjunction with the Connection header ([HTTP], section 13.5.1 and 14.10).
The relavent agents in a hop-by-hop extension are the agents at the ends of the connection.
The relavent agents in an end-to-end extension are the origin client and server.
Editor's note: Are proxies ever relavent to end-to-end extensions?
A request with {str req} in any of its Protocol header fields is a binding extension request -- the transaction cannot be succeed without consulting and adhering to the relavent extension specification(s).
Because legacy HTTP agents may ignore all protocol header fields, the {str req} is not sufficient to evoke the correct behaviour from HTTP agents.
The method name of all binding extension request must be prefixed by BINDING-. Legacy HTTP agents (i.e. agents implemented without consulting this specification) should respond with 501 (Not Implemented) (see [HTTP] section 5.1.1, Method). Other agents must process the request resulting from removing the BINDING- from the method name and leaving the rest of the request (request URL, version, header fields, body) as is.
NOTE: All method names beginning with BINDING- are reserved for this use.
For example, a client might express the binding rights-management constraints on its request as follows:
BINDING-PUT /a-resource HTTP/1.2
Protocol: {http://some.org/rights-management {str req}
{params {copyright-remains-with-client}
{nonexclusive-right-to-redistribute} }
Host: some.hose
Content-Length: 1203
Content-Type: text/html
<!doctype html ...
The processing of PEP extensions is subject to a number of considerations:
The following table summarizes the outcome in each case:
Editor's note: I need to make a plain-text equivalent of the following table. Until then, please see the HTML version.
| Hop-by-hop | End-to-end | ||||
|---|---|---|---|---|---|
| Optional | Required | Optional | Required | ||
| Proxy | PEP not supported | strip*1 |
501 not implemented |
pass |
501 not implemented |
| Extension not supported | strip |
420 Bad Extensions |
pass |
pass |
|
| Extension supported | extended processing |
extended processing |
extended processing |
extended processing |
|
| Origin Server | PEP not supported | standard processing |
501 not implemented |
standard processing |
501 not implemented |
| Extension not supported | standard processing |
420 |
standard processing |
420 |
|
| Extension supported | extended processing |
extended processing |
extended processing |
extended processing |
|
*1: HTTP/1.0 proxies might not do Connection: processing, so they might pass such extension declarations along.
An extension declaration may use the enc to signal that it is an extension encoding, that is, an extension that involves encoding the body of the message.
For example:
GET /sparse-document HTTP/1.1
Host: a.host
Protocol: {http://some.org/special-encoding enc}
HTTP/1.1 200 OK
Protocol: {http://some.org/special-encoding enc}
Content-Type: application/sparse-data
... sparse data encoded with special-encoding ...
Encodings are applied in the order that they occur in the head of the message. For example:
HTTP/1.1 200 OK
Protocol: {http://some.org/inner-encoding enc}
Protocol: {http://some.org/outer-encoding enc}
Content-Type: text/plain
... text encoded with inner-encoding, then outer-encoding...
While the order of Protocol header fields is guaranteed to be
preserved accross proxy boundaries, the order of Protocol header
fields with respect to Content-Encoding header fields is not ([HTTP] section 4.2 Message Headers); hence the use of
Content-Encoding is prohibited in messages with extension encodings.
Some extensions are used spontaneously by participating agents;
for example, a client may be configured to use and extension, or
a user interface option may trigger the use of an extension.
But in many cases, a server dictates the use of one
or more extensions. In this case, it is useful for the server
to communicate its policies to clients.
The server may notify the client that some resources should
be accessed using one or more extensions with the Protocol-Info entity header field. The
resources are specified by a relative or absolute URL, with an
optional wildcard flag indicating that the notification applies to all
URLs containing the specified URL as a prefix.
The syntax is:
Note that a Protocol-Info with a for parameter
may give information about a different resource from the resource
described by the other header fields in the same message. Nonetheless,
the freshness of the information in the Protocol-Info header
field is the same as the rest of the header fields (which see [HTTP] section 13.2, "Expiration Model").
The notice is strictly advisory. The client should heed the notice
on its next request to the relavent server, unless the delay between
receiving the notice and that next request far exceeds the freshness
of the reply containing the Protocol-Info header.
The strength of the policy for an extension for the resources is one of req, ref, or opt.
For example, consider the case of an HTML form, where the
associated ACTION resource requires a payment extension.
In the response that provides the form, the server may
notify the client about the ACTION resource:
The C-Protocol-Info header field provides hop-by-hop
policies; that is, it allows a server to express policy(ies)
to an agent at the other end of an HTTP connection, rather than
to all parties in an HTTP transaction. Other than scope,
its semantics are the same as the Protocol-Info header
field; the name is distinct so that the Connection
header field can distinguish between hop-by-hop and end-to-end
protocol information notifications.
For example, consider a server whos policy is to access cache usage
statistics from clients that connect to it. In response from a
client, it might advertise its policy as follows:
The next time that client makes a request to this server,
it may provide statistics as follows:
A server policy may require (or refuse) the use of some extensions
in some circumstances. If a request fails to fulfill the
policy, the server should respond with a 420 status code (Bad
Extensions) and specify the policy using the Protocol-Info header
field.
Implementors may note the similarity to the way authentication
challenges are issued with the 401 (Unauthorized) status code.
While the protocol extension definition should be published
at the address of the extension identifier, this is not strictly
necessary. The only absolute requirement is that distinct names
be used for distinct semantics.
For example, one way to achive this is to use an mid:, cid:,
or uuid: URL. The association between the extension identifier
and the specification might be made by distributing a specification
which references the extension identifier. Care must be taken
not to distribute conflicting specifications which reference the
same name.
Even when the web is used to publish extension specifications, care
must be taken that the specification made available at that address
does not change significantly over time. One agent may associate the
identifier with the old semantics, and another might associate it with
the new semantics.
For each aspect of an extension, the interaction with
other aspects of HTTP/1.1 must be fully specified, and the issues
of compatibility should be discussed. For example, any extension
headers which are not strictly entity headers require careful
consideration.
In particular:
The extension definition may be made available in different
representations. For example, a software component that implements
the specification may reside at the same address as a human-readable
specification (distinguished by content negotation).
The human-readable representation serves to document the extension
and encourage deployment, while the software component to allows
clients and servers to be dynamically extended.
The design of some aspects of earlier drafts of this specification
are still pending implementation experience.
An earlier draft of PEP included a mechanism for multi-transaction
negotiation. Implementation experience showed the need to identify
clients across transactions, which the mechanism did not provide.
It is possible, within the design specified here, to do
multi-transaction negotiation within an extension (for example, by
putting information to disambiguate conversation threads in the
params).
Other possibilities under consideration include the use of
state management "cookies" to disambiguate clients, or the use
of an analagous PEP-specific mechanism.
This section got blown away in an editing disaster. If
requested, the editor will attempt to include it in a future
draft.
This draft of PEP is the product of a substantial amount of
investigation and collaboration. Dave Kristol did some of the first
writing on HTTP extension mechanisms. [Kristol95]. Jim Miller and Dave Raggett sketched
out an initial design, which Rohit Khare wrote up in a number of drafts.
Rohit also coined the term "PEP."
This draft is a direct reflection of some implementation work: a
client implementation Henrik Frystyk Nielsen et. al. (see the HTPEP
module in libwww)
and a server implementation by Eui Suk Chung and Anit Chakraborty for
the JEPI project.
Tim Berners-Lee contributed significantly to the requirements
section, and Daniel Dardailler provided extensive review comments.
Dan Connolly Rohit Khare Henrik Frystyk Nielsen6. Extension Policy Information
Protocol-Info = "Protocol-Info" ":" 1#policy-decl
| "C-Protocol-Info" ":" 1#policy-decl
policy-decl = "{" extension-id *policy-info "}"
policy-info = policy-str | params | for
policy-str = "{" "str" ("req" | "ref" | "opt" ) "}"
HTTP/1.1 200 OK
Content-Type: text/html
Protocol-Info: {http://some.org/payment-thingy {for /cgi-bin/buy *} {str req}}
<form action="/cgi-bin/buy">
...
6.1. Hop-by-hop Policies
HTTP/1.1 200 OK
C-Protocol-Info: {http://some.org/provide-stats {for / * }}
Connection: C-Protocol-Info
Content-Type: text/plain
some content
GET /some-resource HTTP/1.1
Host: some.org
C-Protocol: {http://some.org/provide-stats {params {hits 10}}}
Connection: C-Protocol
7. 420: Bad Extensions
8. Considerations for Defining Extensions
8.1. Interaction with Caching, Connections, etc.
8.2. Bootstrapping and Dynamic Loading
9. Security Considerations
10. Future Work
10.1. Mult-Transaction Negotiation
11. Appendix: Considerations for the Design of a PEP Software Component Interface
12. Normative References
13. Bibliography: Informative References
RFC
xxxx. Proposed Standard Approved by the IESG, not yet
assigned an RFC.
14. Acknowledgements
15. Authors Addresses
Architecture Domain Lead, W3 Consortium
MIT Laboratory for Computer Science
545 Technology Square
Cambridge, MA 02139, U.S.A.
Tel: +1 (512) 310 2971
Email: connolly@w3.org
Technical Staff, W3 Consortium
MIT Laboratory for Computer Science
545 Technology Square
Cambridge, MA 02139, U.S.A.
Tel: +1 (617) 253 5884
Fax: +1 (617) 258 5999
Email: khare@w3.org
Technical Staff, W3 Consortium
MIT Laboratory for Computer Science
545 Technology Square
Cambridge, MA 02139, U.S.A.
Tel: +1 (617) 253 8143
Fax: +1 (617) 258 5999
Email: frystyk@w3.org