Bidirectional Web Transfer Protocol — BWTP/1.0
Status of this Memo
This document is under development.
This document is an alternative proposal for the transport protocol for the WebSocket API from HTML 5.
This document is heavily based on RFC2616 and borrows structure, ideas and text from that document.
Copyright Notice
Copyright (c) 2009 the Authors and Contributors
Abstract
The Bidirectional Web Transfer Protocol (HTTP) is an application-level protocol that can be used to upgrade an RFC2616 HTTP connection to a bidirectional channel capable of exchanging messages.
Table of Contents
|
Table of Contents
|
1 Introduction
1.1 Purpose
The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypermedia information systems. HTTP has been in use by the World-Wide Web global information initiative since 1990, but it is intrinsically a request/response protocol and cannot well service the growing use-case for data to be pushed from a server to a client.
The Bidirectional Web Transfer Protocol (BWTP) is an application-level protocol that can be used to upgrade a HTTP/1.1 connection to be able to exchange bidirectional MIME-like messages, containing meta information about the data transferred.
Messages are passed in a format similar to that used by HTTP/1.1 as defined by RFC2616. It is intended that implementations of HTTP clients, servers and intermediaries will be able to be minimally updated in order to support BWTP.
1.2 Requirements
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 [34].
An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements for the protocols it implements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements for its protocols is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements for its protocols is said to be "conditionally compliant."
1.3 Terminology
This specification uses a number of terms to refer to the roles played by participants in, and objects of, the HTTP or BWTP communication.
- connection
- A transport layer virtual circuit established between two programs for the purpose of communication.
- message
- The basic unit of BWTP communication, consisting of a structured sequence of octets matching the syntax defined in section 4 and transmitted via the connection.
- request
- An HTTP request message, as defined in section 5 of RFC 2616.
- response
- An HTTP response message, as defined in section 6 of RFC 2616.
- resource
- A network data object or service that can be identified by a URI, as defined in section 3.2. Resources may be available in multiple representations (e.g. multiple languages, data formats, size, and resolutions) or vary in other ways.
- client
- A program that establishes connections for the purpose of sending requests.
- user agent
- The client which initiates a connection. These are often browsers, editors, spiders (web-traversing robots), or other end user tools.
- server
- An application program that accepts connections. Any given program may be capable of being both a client and a server; our use of these terms refers only to the role being performed by the program for a particular connection, rather than to the program's capabilities in general. Likewise, any server may act as an origin server, proxy, gateway, or tunnel, switching behavior based on the nature of each message.
- origin server
- The server on which a given resource resides or is to be created.
- proxy
- An intermediary program which acts as both a server and a client for the purpose of making requests on behalf of other clients. Requests are serviced internally or by passing them on, with possible translation, to other servers. A proxy MUST implement both the client and server requirements of this specification. A "transparent proxy" is a proxy that does not modify the request or response beyond what is required for proxy authentication and identification. A "non-transparent proxy" is a proxy that modifies the request or response in order to provide some added service to the user agent, such as group annotation services, media type transformation, protocol reduction, or anonymity filtering. Except where either transparent or non-transparent behavior is explicitly stated, the HTTP proxy requirements apply to both types of proxies.
- gateway
- A server which acts as an intermediary for some other server. Unlike a proxy, a gateway receives requests as if it were the origin server for the requested resource; the requesting client may not be aware that it is communicating with a gateway.
- tunnel
- An intermediary program which is acting as a blind relay between two connections. Once active, a tunnel is not considered a party to the HTTP communication, though the tunnel may have been initiated by an HTTP request. The tunnel ceases to exist when both ends of the relayed connections are closed.
- upstream/downstream
- Upstream and downstream describe the flow of a message: all messages flow from upstream to downstream.
- inbound/outbound
- Inbound and outbound refer to the request and response paths for messages: "inbound" means "travelling toward the origin server", and "outbound" means "travelling toward the user agent"
1.4 Overall Operation
The BWTP protocol is an HTTP upgrade protocol. A client makes an HTTP upgrade request to the server in order to establish a BWTP connection. After a successful upgrade, the BWTP connection implements two independent and asynchronous streams of MIME-like messages, one inbound and one outbound.
The upgrade request and response may define meta data defaults for all messages on a BWTP connection, such as content-type, character-set, content-encoding, Location and Origin. Individual messages my override any or all of these defaults as well as provide additional meta-data that does not have defaults.
The following diagram shows how the user agent (UA) initiates the BWTP connection by sending an upgrade request (an HTTP request) to the origin server (O), over a connection (v):
UA -------------------v------------------- O
upgrade request ---------------------->
<----------------- 101 upgrade response
inbound messages --------------------->
<-------------------- outbound messages
Following the upgrade request-response, both server and client can immediately start to send each other messages. The inbound and outbound message streams are independent and asynchronous (messages do not have responses).
A more complicated situation occurs when one or more intermediaries are present in the request/response chain. There are three common forms of intermediary: proxy, gateway, and tunnel. A proxy is a forwarding agent, receiving a message for a URI in its absolute form, rewriting all or part of the message, and forwarding the reformatted request toward the server identified by the URI. A gateway is a receiving agent, acting as a layer above some other server(s) and, if necessary, translating the requests to the underlying server's protocol. A tunnel acts as a relay point between two connections without changing the messages; tunnels are used when the communication needs to pass through an intermediary (such as a firewall) even when the intermediary cannot understand the contents of the messages.
UA -----v----- A -----v----- B -----v----- C -----v----- O
upgrade request ------------------------------------>
<------------------------------- 101 upgrade response
inbound messages ----------------------------------->
<---------------------------------- outbound messages
The figure above shows three intermediaries (A, B, and C) between the user agent and origin server. All intermediaries must accept the initial upgrade request and pass it onwards towards the origin server. If any intermediary does not understand the upgrade request, the BWTP connection will not be established.
A message that travels the whole chain will pass through four separate connections.
This distinction is important because some BWTP communication options may apply only to the connection with the nearest, non-tunnel neighbour, only to the end-points of the chain, or to all connections along the chain.
Although the diagram is linear, each participant may be engaged in multiple, simultaneous communications. For example, B may be receiving requests from many clients other than A, and/or forwarding requests to servers other than C, at the same time that it is handling A's request.
Any party to the communication which is not acting as a tunnel may inject messages into either the inbound or outbound stream.
The following illustrates if B has injects both an inbound and an outbound message:
UA -----v----- A -----v----- B -----v----- C -----v----- O
upgrade request ------------------------------------>
<------------------------------- 101 upgrade response
inbound messages ----------------------------------->
<---------------------------------- outbound messages
<-------outbound message--|--inbound message ------->
inbound messages ----------------------------------->
<---------------------------------- outbound messages
BWTP communication usually takes place over TCP/IP connections. The default port is TCP 80 [19], but other ports can be used. This does not preclude BWTP from being implemented on top of any other protocol on the Internet, or on other networks. BWTP only presumes a HTTP connection can be established over a reliable transport; any protocol that provides such guarantees can be used.
2 Notational Conventions and Generic Grammar
2.1 Augmented BNF
All of the mechanisms specified in this document are described in both prose and an augmented Backus-Naur Form (BNF) as defined by section 2.1 of RFC 2616.
Implementers will need to be familiar with the notation in order to understand this specification.
2.2 Basic Rules
The Basic Rules as defined by section 2.2 of RFC 2616 are used throughout this specification to describe basic parsing constructs. The US-ASCII coded character set is defined by ANSI X3.4-1986 [21].
3 Protocol Parameters
3.1 BWTP Version
BWTP uses a "<major>.<minor>" numbering scheme to indicate versions of the protocol. The protocol versioning policy is intended to allow the sender to indicate the format of a message and its capacity for understanding further BWTP communication, rather than the features obtained via that communication. No change is made to the version number for the addition of message components which do not affect communication behavior or which only add to extensible field values. The <minor> number is incremented when the changes made to the protocol add features which do not change the general message parsing algorithm, but which may add to the message semantics and imply additional capabilities of the sender. The <major> number is incremented when the format of a message within the protocol is changed. See RFC 2145 [36] for a fuller explanation.
All messages on a BWTP connection will be of the same version that is negotiated with the upgrade request and response that establishes the BWTP connection:
BWTP-Version = "BWTP" "/" 1*DIGIT "." 1*DIGIT
Note that the major and minor numbers MUST be treated as separate integers and that each MAY be incremented higher than a single digit. Thus, BWTP/2.4 is a lower version than BWTP/2.13, which in turn is lower than BWTP/12.3. Leading zeros MUST be ignored by recipients and MUST NOT be sent.
The BWTP version of a connection is the highest BWTP version for which all intermediaries and the agent and origin server can handle.
3.2 Uniform Resource Identifiers
URIs as defined by 3.2 of RFC2616 are used to identify BWTP resources.
3.4 Character Sets
BWTP uses the same definition of the term "character set" as that described in section 3.4 of RFC2616.
3.4.1 Missing Charset
If not otherwise specified, a character set of UTF-8 may be assumed.
3.5 Content Codings
The content codings defined by section 3.5 of RFC2616 and registered with the Internet Assigned Numbers Authority (IANA) MAY be applied to a BWTP message.
3.6 Transfer Codings
HTTP-like transfer codings MUST NOT be applied to BWTP connections or messages. Specifically the chunked transfer encoding is not supported by BWTP; Range limited messages should be sent in situations where chunked transfer is desirable.
3.7 Media Types
HTTP uses Internet Media Types [17] in the Content-Type header field in order to provide open and extensible data typing and type negotiation. The media-type is defined in section 3.7 of RFC2616 as:
media-type = type "/" subtype *( ";" parameter )
type = token
subtype = token
3.12 Range Units
BWTP allows a message to carry only a part of an identified resource. BWTP uses range units in the Content-Range header field. A range-unit is defined in section 3.12 of RFC2616 as:
range-unit = bytes-unit | other-range-unit
bytes-unit = "bytes"
other-range-unit = token
An entity can be broken down into subranges according to various structural units.
The only range unit defined by BWTP/1.0 is "bytes". BWTP/1.0 implementations MAY ignore ranges specified using other units. BWTP/1.0 has been designed to allow implementations of applications that do not depend on knowledge of ranges.
4 BWTP Message
4.1 Message Types
BWTP messages consist of inbound messages from client to server and outbound message from the server to client:
BWTP-message = Inbound-message | Outbound-message ; BWTP/1.0 messages
4.2 Generic Messages
Inbound and Outbound messages use the generic message format of RFC 822 [9] for transferring entities (the payload of the message). Both types of message consist of a start-line, zero or more header fields (also known as "headers"), an empty line (i.e., a line with nothing preceding the CRLF) indicating the end of the header fields, and possibly a message-body.
generic-message = start-line
*(message-header CRLF)
CRLF
[ message-body ]
[ *CRLF ]
start-line = "BWTP" SP message-address SP content-length
content-length = 1*DIGIT
In the interest of robustness, servers and clients SHOULD ignore any empty line(s) received where a start-line is expected.
4.3 Message Address
The message address identifies a server resource to which (inbound) or from which (outbound) a message is sent. A message address has a message URI and it may have an optional fragment list used for multiplexing multiple message streams.
message-address = message-URI [ "#" fragment-list ]
message-URI = "*" ; the connection default resource
| absoluteURI
| abs_path
fragment-list = fragment *( "," fragment )
fragment = token
4.3.1 Message URI
A message URI may be an absoluteURI or an abs_path as defined by "Uniform Resource Identifiers (URI): Generic Syntax and Semantics," RFC 2396, or "*" to indicate the messages uses the default message-URI for the connection or virtual connection.
4.3.2 Fragments and Virtual Connections.
A fragment is specified in a coma separated list of tokens after a "#" in the message address. Fragments are used to multiplex multiple channels of messages over a single BWTP connection. Messages with the same fragment make up a virtual connection. A fragment name of "*" is used for a message that applies to all fragment. A messages without a fragment an explicit fragment form distinct virtual connection to messages with with fragment.
Default headers and connection headers be apply to the virtual connection.
A virtual connection is established by any party sending a message with the fragment ID of the channel. If random fragment IDs are assigned to newly created channels, in order to avoid the same ID being selected simultaneously, it is recommended that clients should terminate the token with an even digit and servers should terminate the token with and odd digit.
When using virtual connections a client, server or intermediary SHOULD break large messages into multiple range messages so that a single virtual channel will not unfairly use a connection.
4.4 Message Headers
BWTP header fields follow the same generic format as that given in Section 3.1 of RFC 822 [9]. Each header field consists of a name followed by a colon (":") and the field value. Field names are case-insensitive. The field value MAY be preceded by any amount of LWS, though a single SP is preferred. Header fields can be extended over multiple lines by preceding each extra line with at least one SP or HT. Applications ought to follow "common form", where one is known or indicated, when generating HTTP constructs, since there might exist some implementations that fail to accept anything beyond the common forms.
message-header = field-name ":" [ field-value ]
field-name = token
field-value = *( field-content | LWS )
field-content = <the OCTETs making up the field-value
and consisting of either *TEXT or combinations
of token, separators, and quoted-string>
The field-content does not include any leading or trailing LWS: linear white space occurring before the first non-whitespace character of the field-value or after the last non-whitespace character of the field-value. Such leading or trailing LWS MAY be removed without changing the semantics of the field value. Any LWS that occurs between field-content MAY be replaced with a single SP before interpreting the field value or forwarding the message downstream.
The order in which header fields with differing field names are received is not significant.
Multiple message-header fields with the same field-name MAY be present in a message if and only if the entire field-value for that header field is defined as a comma-separated list [i.e., #(values)]. It MUST be possible to combine the multiple header fields into one "field-name: field-value" pair, without changing the semantics of the message, by appending each subsequent field-value to the first, each separated by a comma. The order in which header fields with the same field-name are received is therefore significant to the interpretation of the combined field value, and thus a proxy MUST NOT change the order of these field values when a message is forwarded.
4.4.1 General Header Fields
There are a few header fields which have general applicability for both inbound and outbound messages, but which do not apply to the entity being transferred. These header fields apply only to the message being transmitted.
general-header = "Connection"
| "Date"
| "Request-Method"
| "Response-Status"
| "Via"
| bwtp-default
bwtp-default = "BWTP-" token
General-header field names can be extended reliably only in combination with a change in the protocol version. However, new or experimental header fields may be given the semantics of general header fields if all parties in the communication recognize them to be general-header fields. Unrecognized header fields are treated as entity-header fields.
4.5.2 Default Header Fields
A bwtp-default header is a default header that applies to all subsequent messages on the connection, as if the messages contained the header stripped of the leading "BWTP-". A default header does not apply the message that it is in.
If the message setting the default header has a fragment, then the default only applies to other messages with the same fragment. If the fragment of the message setting the default header is "*", then the default applies to all fragments currently defined and all future fragments created.
Default headers may be overridden by a specified header in a message or by a new default header.
4.5 Message Length
The message body length is determined by the content-length specified in the message start-line.
4.6 Message Body
The presence of a message-body in a request is signalled by a non zero content-length in the message start-line. If a Content-Length field is included in the message-headers, it is ignored.
The message body is defined as
message-body = *OCTET
4.7 Message Examples
A minimal message with default destination and content-type is
BWTP * 12
Hello World!
A message with URI, fragment, content-type and a content range
BWTP /greeting#1 5
Content-Range: bytes 1-5/12
Hello
An empty message with a Connection header that applies to all fragments:
BWTP *#* 0
Connection: closing
5 Inbound Message
An inbound message from a client to a server is a generic message with the restriction of the included headers to be either general, inbound or entity headers:
Inbound-message = "BWTP" SP message-address SP content-length
*(( general-header | inbound-header | entity-header ) CRLF)
CRLF
[ message-body ]
[ CRLF ]
5.1 Inbound Message Address
The inbound message-Address is a message-URI with an optional fragment list. It identifies the resource on the origin server to which the message is destined. A message-address of "*" means that the message was sent to default URI on the default virtual connection. A message-address of "*#*" means that the message was sent to the default URI on all virtual connections.
The inbound message-Address is a message-URI with an optional fragment list. It identifies the resource on the origin server to which the message is destined. A message-address of "*" means that the default URI of the default virtual connection. A message-address of "*#*" means all virtual connections for the default URI.
If the abs_path form is used for the inbound message URI, then the host of the resource is defined either by a Host header in the message or a Host header in the original upgrade request.
The inbound message URI is not used by proxies to route messages. A message, even with an absolute URI or Host header that specifies a different origin server will be delivered to the origin server identified in the original upgrade request.
If the message-URI is encoded using the "% HEX HEX" encoding [42], the origin server MUST decode the Request-URI in order to properly interpret the request.
5.3 Inbound Header Fields
The inbound-header fields allow the client to pass additional information about the message, and about the client itself, to the server. These fields act as message modifiers, with semantics equivalent to the parameters on a programming language method invocation.
inbound-header = Authorization
| Host
| Origin
inbound-header field names can be extended reliably only in combination with a change in the protocol version. However, new or experimental header fields MAY be given the semantics of request- header fields if all parties in the communication recognize them to be request-header fields. Unrecognized header fields are treated as entity-header fields.
5.4 Inbound Message Examples
A minimal inbound message with default destination and content-type is
BWTP * 12
Hello World!
An inbound message with default destination and content-type and a content range
BWTP * 5
Content-Range: bytes 1-5/12
Hello
An inbound message that explicitly identifies a destination, content type and content encoding is
BWTP /destination/path 12
Content-Type: text/plain;charset=utf-8
Hello World!
An empty message with a Connection header for a specific fragment:
BWTP *#123 0
Connection: closing
6 Outbound Message
An outbound message from a server to a client is a generic message with the restriction of the included headers to be either general, outbound or entity headers:
Outbound-message = "BWTP" SP message-address SP content-length
*(( general-header | outbound-header | entity-header ) CRLF)
CRLF
[ message-body ]
[ CRLF ]
6.1 Outbound Message address
The outbound message-address is a message-URI with an optional fragment list. It identifies the resource on the origin server from which the message has been sent. A message-address of "*" means that the message was sent from default URI on the default virtual connection. A message-address of "*#*" means that the message was sent by the default URI on all virtual connections.
If the abs_path form is used for the outbound message URI, then the host of the resource is defined either by a Host header in the message or a Host header in the original upgrade request.
The outbound message address is not used by proxies to route messages. All outbound messages on a connection will be delivered to the user agent that initialized the connection.
If the message-URI is encoded using the "% HEX HEX" encoding [42], the user agent MUST decode the message-URI in order to properly interpret the message.
6.2 Outbound Header Fields
The outbound-header fields allow the server to pass additional information about the message. These header fields give information about the server and about further access to the resource identified by the Message-URI.
outbound-header = Access-Control-Allow-Origin
| Set-Cookie
Outbound header field names can be extended reliably only in combination with a change in the protocol version. However, new or experimental header fields MAY be given the semantics of response- header fields if all parties in the communication recognize them to be response-header fields. Unrecognized header fields are treated as entity-header fields.
6.3 Outbound Message Examples
A minimal outbound message with default source and content-type is
BWTP * 12
Hello World!
An outbound message with default destination and content-type and a content range
BWTP * 5
Content-Range: bytes 1-5/12
Hello
An outbound message that explicitly identifies a source, content type, content encoding and Origin is
BWTP /destination/path 12
Content-Type: text/plain;charset=utf-8
Origin: www.acme.com
Hello World!
An empty message with a Connection header:
BWTP * 0
Connection: close
7 Entity
In this section, both sender and recipient refer to either the client or the server, depending on who sends and who receives the message.
7.1 Entity Header Fields
Entity-header fields define meta-data about the entity-body or, if no body is present, about the resource identified by the request. Some of this meta-data is OPTIONAL; some might be REQUIRED by portions of this specification.
entity-header = Content-Encoding
| Content-Language
| Content-Location
| Content-MD5
| Content-Range
| Content-Type
| Transfer-Encoding
| extension-header
extension-header = message-header
The extension-header mechanism allows additional entity-header fields to be defined without changing the protocol, but these fields cannot be assumed to be recognizable by the recipient. Unrecognized header fields SHOULD be ignored by the recipient and MUST be forwarded by transparent proxies.
8 Connections
8.1 Negotiation
8.1.1 Upgrade Request
A BWTP connection is initiated by a client issuing an upgrade request, which is a valid HTTP/1.1 GET request with an Upgrade header field set to the desired BWTP-Version:
BWTP-Upgrade-Request = "GET" SP URI SP "HTTP/1.1" CRLF
*(message-header CRLF)
"Upgrade" ":" BWTP-Version
*(message-header CRLF)
CRLF
[ message-body ]
Since Upgrade is only for the immediate connection, the Upgrade Request SHOULD also contain a Connection header with "Upgrade" in its values.
The default values for all inbound messages on the resulting BWTP connection are taken from:
- The default message-URI is the URI of the upgrade request.
- The default host is the host given either in an absolute URI or in a Host header.
- Any header field with a name starting with "BWTP-" is used as a default field of all inbound BWTP messages, with the leading "BWTP-" stripped from the name.
Here is an example of an Upgrade Request:
GET /path HTTP/1.1
Host: host.com:80
Upgrade: BWTP/1.0
Connection: Upgrade
Origin: the.origin.com
Authorization: BASIC amd73ksosh3hj210sd3d0dk1
BWTP-Content-Type: text/plain;charset=utf-8
This request, if accepted, has the following inbound messages defaults:
message-URI /path
host host.com
port 80
Content-Type text/plain;charset=utf-8
If an intermediary in the HTTP connection accept the upgrade, they MUST forward the Upgrade header in their requests towards the origin server.
8.1.2 Upgrade Response
When an origin server receives an Upgrade request and the resource specified by the URI accepts the upgrade, then acceptance is indicated by sending an Upgrade Response:
BWTP-Upgrade-Response = "HTTP/1.1" SP 101 SP "Bidirectional Web Transfer Protocol" CRLF
*(message-header CRLF)
"Upgrade" ":" BWTP-Version
*(message-header CRLF)
CRLF
The default values for all outbound messages on the resulting BWTP connection are taken from:
- The default message-URI is the URI of the upgrade request.
- The default host is the host given either in an absolute URI or in a Host header of the upgrade request.
- Any header field in the response with a name starting with "BWTP-" is used as a default field of all outbound BWTP messages, with the leading "BWTP-" stripped from the name.
Here is an example of an Upgrade Response:
HTTP/1.1 101 Bidirectional Web Transfer Protocol
BWTP-Content-Origin: the.origin.com
BWTP-Content-Type: text/plain;charset=utf-8
This request, if sent in response to the prior Upgrade Request example, has the following outbound messages defaults:
message-URI /path
host host.com
port 80
Content-Type text/plain;charset=utf-8
Content-Origin the.origin.com
8.2 Flow Control
BWTP/1.1 servers SHOULD maintain connections and use TCP's flow control mechanisms to resolve temporary overloads, rather than terminating connections with the expectation that clients will retry. The latter technique can exacerbate network congestion.
8.3 Closing Connections
8.3.1 Spontaneous Connection close
Either the client or server or any intermediary MAY at any time close the BWTP. Message delivery is not guaranteed if a spontaneous close is performed. Clients, servers and intermediaries SHOULD use orderly connection close if guaranteed delivery is required.
8.3.2 Orderly Connection close
Either the client or server or any intermediary MAY initiate an orderly close of a BWTP connection by sending a message with a "Connection" header field with a value of "closing".
After sending such a message, the connection can continue to be used normally until a message is received with a "Connection" header field with a value of "close".
When a client or server receives a message with a "Connection" header field with a value of "close" or "closing", it should immediately flush any pending or queued messages for the connection and the last message sent should have a "Connection" header field with a value of "close".
After sending message with a "Connection" header field with a value of "close", client or server or any intermediary MUST NOT send any more messages on that connect, but messages SHOULD continue to be received and processed until a message is received that also contains a Connection Close header.
Once the connection close header has been both received and sent, the connection may be closed.
If the orderly close is initiated by an intermediary, then it should send a connection closing message on both it's inbound and outbound connections. An intermediary that receives a connection close or closing header MUST always pass on that header either in the message received or in a new injected message.
A connection close or closing header may be sent on any valid BWTP message. If no message is queued or available to carry a close header, then an empty BWTP message may be sent.
BWTP *#* 0
Connection: close
A connection closing or close message applies to the virtual connection indicated by the fragment of the message address. A BWTP connection that is carrying virtual connections is closed once all known virtual connections are closed.
8.4 Proxy Connections
TODO - work out how this should work. I think the proxy should first be given the chance to accept the normal upgrade request. If it does it just becomes an intermediary as defined in this document. If it does not accept the upgrade, then we can have a fallback to a CONNECT tunnel to bypass the proxy.
11 Access Authentication
HTTP provides several OPTIONAL challenge-response authentication mechanisms which can be used by a server to challenge a client request and by a client to provide authentication information. The general framework for access authentication, and the specification of "basic" and "digest" authentication, are specified in "HTTP Authentication: Basic and Digest Access Authentication" [43]. This specification adopts the definitions of "challenge" and "credentials" from that specification.
14 Header Field Definitions
14.x Access-Control-Allow-Origin
An outbound message may have one Access-Control-Allow-Origin header, with the following syntax:
access-control-allow-origin-header = "Access-Control-Allow-Origin" ":" origin-value
origin-value = origin
| "*"
origin = token
The origin values specifies a URI that may access the resource. The client (browser) MUST enforce that only code downloded from the origin may access the contents of the message or be notified of the arrival of the message.
The origin may be specified "*" as a wildcard, thereby allowing any origin to access the resource.
14.x Authorization
14.x Connection
The Connection general-header field allows the sender to specify options that are desired for that particular connection. Unlike the corresponding HTTP Connection general-header, the BWTP connection field SHOULD be communicated by proxies over further connections.
The Connection header has the following grammar:
Connection = "Connection" ":" 1#(connection-token)
connection-token = "close" | "closing" | token
14.x Content-Encoding
The Content-Encoding entity-header field is used as a modifier to the media-type. When present, its value indicates what additional content codings have been applied to the message body, and thus what decoding mechanisms must be applied in order to obtain the media-type referenced by the Content-Type header field. Content-Encoding is primarily used to allow a message to be compressed without losing the identity of its underlying media type.
Content-Encoding = "Content-Encoding" ":" 1#content-coding
Content codings are defined in section 3.5 of RFC2616 . An example of its use is
Content-Encoding: gzip
If the content-encoding of an entity is not "identity", then the message MUST include a Content-Encoding entity-header that lists the non-identity content-coding(s) used.
If multiple encodings have been applied to an entity, the content codings MUST be listed in the order in which they were applied. Additional information about the encoding parameters MAY be provided by other entity-header fields not defined by this specification (eg for cryptography or digital signatures).
14.x Content-Language
The Content-Language entity-header field describes the natural language(s) of the intended audience for the enclosed entity. Note that this might not be equivalent to all the languages used within the entity-body.
Content-Language = "Content-Language" ":" 1#language-tag
The use and definition of the Content-Language value is as defined in section 14.12 of RFC 2616.
14.x Content-Location
The Content-Location entity-header field MAY be used to supply a resource location for the entity enclosed in the message when that entity is accessible from a location separate from a BWTP message.
Content-Location = "Content-Location" ":" absoluteURI
The value of Content-Location value MUST be an absolute URI.
14.x Content-MD5
The Content-MD5 entity-header field, as defined in RFC 1864 [23], is an MD5 digest of the entity-body for the purpose of providing an end-to-end message integrity check (MIC) of the entity-body. (Note: a MIC is good for detecting accidental modification of the entity-body in transit, but is not proof against malicious attacks.)
Content-MD5 = "Content-MD5" ":" md5-digest
md5-digest = <base64 of 128 bit MD5 digest as per RFC 1864>
The Content-MD5 header field MAY be generated by a server or client to function as an integrity check of the entity-body. Any recipient of the entity-body, including gateways and proxies, MAY check that the digest value in this header field matches that of the entity-body as received.
The generation of the Content-MD5 value is as defined in section 14.15 of RFC 2616.
14.x Content-Range
The Content-Range entity-header is sent with a message to indicate that it carries only a single partial entity-body.
Content-Range = "Content-Range" ":" content-range-spec
content-range-spec = byte-content-range-spec
byte-content-range-spec = bytes-unit SP
byte-range-resp-spec "/"
( instance-length | "*" )
byte-range-resp-spec = (first-byte-pos "-" last-byte-pos)
| "*"
instance-length = 1*DIGIT
The header SHOULD indicate the total length of the full entity-body, unless this length is unknown or difficult to determine. The asterisk "*" character means that the instance-length is unknown at the time when the message was generated. The content length of the BWTP message should be the number of bytes actually transferred and not the length of the full entity-body.
It is at the descresion of the message sender if content ranges will be used to break a large entity into multiple messages. It is at the descressoin of the message receiver if multiple parts are kept until all are receieve, partially process or discarded.
Range units are defined in section 3.12 of RFC2616. Examples of byte-content-range-spec values, assuming that the entity contains a total of 1234 bytes:
The first 500 bytes:
bytes 0-499/1234
The second 500 bytes:
bytes 500-999/1234
All except for the first 500 bytes:
bytes 500-1233/1234
The last 500 bytes:
bytes 734-1233/1234
14.x Content-Type
The Content-Type entity-header field indicates the media type of the entity-body sent.
Content-Type = "Content-Type" ":" media-type
Media types are defined in section 3.7 of RFC2616. An example of the field is
Content-Type: text/html; charset=ISO-8859-4
14.x Host
14.x Origin
An inbound message may have one Origin header with the following syntax:
origin-header = "Origin" ":" origin
origin = token
The origin is a URI indicating the server from which the message initiated. It does not include any path information, but only the server name.
14.x Request-Method
When carrying HTTP requests over a BWTP connection (see appendix A), the Request-Method header may be used to carry the request method.
14.x Response-Status
When carrying HTTP responses over a BWTP connection (see appendix A), the Response-Status header may be used to carry the response status code.
14.x Set-Cookie
TBD.
14.x Transfer-Encoding
The Transfer-Encoding general-header field indicates what (if any) type of transformation has been applied to the message body in order to safely transfer it between the sender and the recipient. This differs from the content-coding in that the transfer-coding is a property of the transport, not of the entity.
Transfer-Encoding = "Transfer-Encoding" ":" 1#transfer-coding
BWTP Transfer-codings are distinct from RFC2616 Trasnfer-codings, in that the "chunked" encoding is not supported. Otherwise, transfer codings are as defined in section 3.6 of RFC2616.
15 Security Considerations
Origins???
16 Acknowledgements
17 References
18 Authors' Addresses
Giants with large shoulders
Greg Wilkins <moc.editbew|wgerg#moc.editbew|wgerg>
Pieter Hintjens <moc.xitami|hp#moc.xitami|hp>
19 Appendices
Appendix A. Carrying HTTP request reponses
A client server pair with an open BWTP connection may use that connection to carry HTTP request and responses, so that an additional connection is not
needed for a mix of BWTP and HTTP traffic. HTTP requests carried over BWTP may be either from client to server or server to client, but the interpretation
of the request URI on a client is entirely undefined.
HTTP Requests
A HTTP request carried by a BTWP connection is a BWTP message with a Request-Method field containing the request method. The request URI is the
message-uri of the BTWP message. Thus the following HTTP request:
GET /index.html HTTP/1.1
Host: somehost.org
User-Agent: exploring-monkey/1.0
may be sent over BTWP as:
BWTP /index.html 0
Request-Method: GET
User-Agent: exploring-monkey/1.0
HTTP Responses
A HTTP response carried by a BTWP connection is a BWTP message with a Response-status field containing the HTTP response status. Thus the following HTTP
response:
HTTP/1.1 200 OK
Content-Type: text/plain
Transfer-encoding: chunked
12;
Hello World
0;
may be sent over BTWP as:
BWTP * 12
Response-Status: 200 OK
Content-Type: text/plain
Hello World
A response must be sent on the same BWTP virtual connection as the request was received on. Within a BWTP virtual connection, normal HTTP ordering of
responses with respect to requests must be maintained. There is no ordering dependency between responses sent to requests received on different BWTP
virtual connections.
Appendix B. Mapping to the WebSocket API.
HTML5 defines the WebSocket javascript API for two-way communication with a remote host from a web browser. The API is defined as:
interface WebSocket {
readonly attribute DOMString URL;
// ready state
const unsigned short CONNECTING = 0;
const unsigned short OPEN = 1;
const unsigned short CLOSED = 2;
readonly attribute long readyState;
// networking
attribute Function onopen;
attribute Function onmessage;
attribute Function onclose;
void send(in DOMString data);
void close();
};
A BWTP connection may be used to carry a single or multiple WebSockets between a client and a host. It is recommended that only a single BWTP connection be used between a client and a given host/port.
Single/Initial WebSocket per connection
A client may map the WebSocket API to a BWTP connection as follows:
- On creation of a WebSocket, a new HTTP connection is opened to the host identified in the URL contructor (or to a configured proxy) and a request to UPGRADE to BWTP is sent. The upgrade request MUST set the BWTP-Content-Type header to "text/plain;charset=utf-8".
- On a successful response to the UPGRADE request, the WebSocket API onopen function is called.
- The WebSocket API send(in DOMSTring data) method will send a BWTP message to the default message address and content type with the data as the message body.
- When a BWTP message is received for the default message address and with the default content-type, the WebSocket API onmessage function is called.
- When a message is sent or received with a Connection: closed header, the WebSocket API onclose function is called.
Multiple WebSockets per connection
If a client initiates multiple WebSockets to the same host (either from the same frame or from different frames in the same browser), the client SHOULD use an existing BWTP connection by using a virtual connection:
- On creation of a WebSocket to a host/port which already has an open BWTP connection, the client will allocate a random fragment ID and send an UPGRADE request using the HTTP over BWTP
(see Appendix A) over the virtual connection for the fragment ID.
- The server will respond the the UPGRADE request on the virtual connection and the WebSocket API onopen function is called.
- The WebSocket API send(in DOMSTring data) method will send a BWTP message to the default message address with the virtual connection fragment ID.
- When a BWTP message is received for the virtual connection fragment ID, the WebSocket API onmessage function is called.
- When a message is sent or received with the virtual connection fragment ID and a Connection: closed header, the WebSocket API onclose function is called.
Appendix C. Examples
Simple connection
This example shows the initial handshake and a simple message in either direction.
> GET /path HTTP/1.1
> Host: host.com:80
> Upgrade: BWTP/1.0
> Connection: Upgrade
> BWTP-Origin: the.origin.com
> BWTP-Content-Type: text/plain;charset=utf-8
< HTTP/1.1 101 Bidirectional Web Transfer Protocol
< BWTP-Access-Control-Allow-Origin: the.origin.com
< BWTP-Content-Type: text/plain;charset=utf-8
> BWTP * 12
>
> Hello World!
< BWTP * 11
<
< Hello User!
Destinations and JSON messages
This session shows how a simple chat room might work, using JSON messages.
> GET /chat HTTP/1.1
> Host: host.com:80
> Upgrade: BWTP/1.0
> Connection: Upgrade
> BWTP-Origin: the.origin.com
> BWTP-Content-Type: text/x-json
< HTTP/1.1 101 Bidirectional Web Transfer Protocol
< BWTP-Access-Control-Allow-Origin: the.origin.com
< BWTP-Content-Type: text/x-json
> BWTP /room1 45
>
> {user:'user1', msg:'Hello everyone in room1'}
< BWTP /room1 39
<
< {user:'user2', msg:'Welcome to room 1'}
> BWTP /room1 31
>
> {user:'user1': msg:'Thank you'}
Content types
This session shows how different content types can be used per message.
> GET /path HTTP/1.1
> Host: host.com:80
> Upgrade: BWTP/1.0
> Connection: Upgrade
> BWTP-Origin: the.origin.com
> BWTP-Content-Type: text/plain;charset=utf-8
< HTTP/1.1 101 Bidirectional Web Transfer Protocol
< BWTP-Access-Control-Allow-Origin: the.origin.com
< BWTP-Content-Type: text/plain;charset=utf-8
> BWTP * 20
> Content-Type: text/html
>
> <b>Hello in HTML</b>
< BWTP * 33
< Content-Type: text/xml
<
< <response>Hello in XML</response>
Appendix D. Key differences with HTTP/1.1
BWTP is heavily influenced by HTTP/1.1 and the BWTP specification draws significantly from RFC2616. The key differences with HTTP/1.1 are:
- Whereas a client can directly establish an HTTP connection, it establishes a BWTP connection by upgrading from HTTP;
- Whereas every HTTP request has one response, BWTP messages have no responses;
- Whereas HTTP establishes an asymmetric client-server dialog, BWTP establishes a symmetric peer-to-peer dialog;
- Whereas HTTP requests have methods, and HTTP responses have statuses, BWTP messages have neither;
- Whereas HTTP requests and responses are fully self-describing, BWTP messages may rely on meta-data established at the start of the BWTP connection;
- Whereas HTTP content lengths are encoded as headers, BWTP content lengths are specified on the message start line;
- Whereas HTTP provides mechanisms for caching (conditional retrieval), BWTP does not allow for caching of messages;
- Whereas HTTP expects a connection to close after any request-response pair, BWTP defines an orderly close handshake sequence.
20 Index
Please see the PostScript version of this RFC for the INDEX.
21. Full Copyright Statement
Copyright (c) 2009 the Authors and Contributors
This Specification is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This Specification is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, see <http://www.gnu.org/licenses>.
