From cf64cd2f8f157edd5d8bd1d1a1823e145d65fe76 Mon Sep 17 00:00:00 2001
From: Peter Saint-Andre Applications, restricted either by their runtime environments or by firewalls that permit only Web browsing, often find that arbitrary TCP connections (see &rfc0793;) cannot be established. BOSH, the protocol described in this document, may be used as a "drop-in" alternative to a bi-directional TCP connection. It is a mature fully-featured protocol that has been in use for many years with many open source and commercial implementations. It overcomes common communication constraints by employing fully-compliant "cookie-free" BOSH can transport any data efficiently and with minimal latency in both directions. For applications that require both "push" and "pull" communications, BOSH is significantly more bandwidth-efficient and responsive than most other bi-directional HTTP-based transport protocols (e.g. &xep0025;) and techniques now commonly known as AJAX. Certain applications often find that arbitrary TCP connections (see &rfc0793;) cannot be established (e.g., applications that are restricted either by their runtime environments or by firewalls permitting only Web browsing). BOSH, the protocol described in this document, may be used as a "drop-in" alternative to a bidirectional TCP connection. It is a mature, fully-featured protocol that has been in use for many years with many open source and commercial implementations. It overcomes common communication constraints by employing fully-compliant "cookie-free" BOSH can transport any data efficiently and with minimal latency in both directions. For applications that require both "push" and "pull" communications, BOSH is significantly more bandwidth-efficient and responsive than most other bidirectional HTTP-based transport protocols (e.g. &xep0025;) and techniques now commonly known as AJAX. BOSH achieves this efficiency and low-latency by avoiding polling without resorting to chunked HTTP responses (i.e. without using the technique which is now commonly known as "Comet"). The protocol employs multiple synchronous HTTP request/response pairs. This technique allows it to pass through even those proxies that buffer partial HTTP responses before forwarding the full responses only once they are available. Note: Although the XML being transported in the examples herein is XMPP, this transport is not part of XMPP. In fact, from its conception the intention of the primary author was that it could be used to implement any bidirectional XML stream transporting a mixture of elements qualified by namespaces defined by different protocols (e.g., both XMPP and JSON). This mix is necessary since some connection managers may not support Multiple Streams and constrained clients often have no access to HTTP Pipelining (which limits them to one BOSH session at a time). BOSH connection managers are generally not required to understand anything about the XML content that they transport beyond perhaps ensuring that each XML stanza is qualified by the correct namespace. &xep0206; documents some XMPP-specific extensions of this protocol that were formerly included in this document. Note: Although the XML being transported in the examples herein is XMPP (see &rfc3920;), this transport is not part of XMPP. In fact, from its conception the intention of the primary author was that it could be used to implement any bidirectional XML stream transporting a mixture of elements qualified by namespaces defined by different protocols (e.g., both XMPP and JSON). This mix is necessary since some connection managers may not support Multiple Streams and constrained clients often have no access to HTTP Pipelining (which limits them to one BOSH session at a time). BOSH connection managers are generally not required to understand anything about the XML content that they transport beyond perhaps ensuring that each XML stanza is qualified by the correct namespace. &xep0206; documents some XMPP-specific extensions of this protocol that were formerly included in this document. Note: This document inherits terminology regarding the Hypertext Transport Protocol from RFC 1945 and RFC 2616. The following design requirements reflect the need to offer performance as close as possible to a standard TCP connection. This document assumes that most implementations will utilize a specialized "connection manager" to handle HTTP connections rather than the usual TCP connections. Effectively, such a connection manager will be a specialized HTTP server that translates between the HTTP requests and responses defined herein and the data streams (or API) implemented by the &server; or &server;s with which it communicates, thus enabling an HTTP client to connect to a &server;. We can illustrate this graphically as follows: This document assumes that most implementations will utilize a specialized "connection manager" to handle HTTP connections rather than the usual TCP connections. Effectively, such a connection manager will be a specialized HTTP server that translates between the HTTP requests and responses defined herein and the data streams (or API) implemented by the server or servers with which it communicates, thus enabling an HTTP client to connect to a server. We can illustrate this graphically as follows: BOSH addresses communications between an HTTP client and the connection manager only. It does not address communications between the connection manager and the &server;, since such communications are implementation-specific (e.g., the &server; may natively support this HTTP binding, in which case the connection manager will be a logical entity rather than a physical entity; alternatively the connection manager may be an independant translating proxy such that the &server; may believe it is talking directly to the client over TCP; or the connection manager and the &server; may use a component protocol or an API defined by the &server; implementation). BOSH addresses communications between an HTTP client and the connection manager only. It does not address communications between the connection manager and the server, since such communications are implementation-specific (e.g., the server may natively support this HTTP binding, in which case the connection manager will be a logical entity rather than a physical entity; alternatively the connection manager may be an independant translating proxy such that the server may believe it is talking directly to the client over TCP; or the connection manager and the server may use a component protocol or an API defined by the server implementation). Furthermore, no aspect of this protocol limits its use to client-to-server communications. It could be used for server-to-server or component-to-server communications as well. However, this document focuses exclusively on use of the transport by clients that cannot maintain arbitrary persistent TCP connections with a server. We assume that servers and components are under no such restrictions and thus would use TCP. All information is encoded in the body of standard HTTP POST requests and responses. Each HTTP body contains a single <body/> wrapper which encapsulates the XML elements being transferred (see <body/> Wrapper Element). Clients SHOULD send all HTTP requests over a single persistent HTTP/1.1 connection using HTTP Pipelining. However, a client MAY deliver its POST requests in any way permited by RFC 1945 or RFC 2616. For examples, constrained clients can be expected to open more than one persistent connection instead of using Pipelining, or in some cases to open a new HTTP/1.0 connection to send each request. However, clients and connection managers SHOULD NOT use Chunked Transfer Coding, since intermediaries may buffer each partial HTTP request or response and only forward the full request or reponse once it is available. Clients SHOULD send all HTTP requests over a single persistent HTTP/1.1 connection using HTTP Pipelining. However, a client MAY deliver its POST requests in any way permited by RFC 1945 or RFC 2616. For example, constrained clients can be expected to open more than one persistent connection instead of using Pipelining, or in some cases to open a new HTTP/1.0 connection to send each request. However, clients and connection managers SHOULD NOT use Chunked Transfer Coding, since intermediaries may buffer each partial HTTP request or response and only forward the full request or reponse once it is available. Clients MAY include an HTTP Accept-Encoding header in any request. If the connection manager receives a request with an Accept-Encoding header, it MAY include an HTTP Content-Encoding header in the response (indicating one of the encodings specified in the request) and compress the response body accordingly. Requests and responses MAY include HTTP headers not specified herein. The receiver SHOULD ignore any such headers. Each BOSH session MAY share the HTTP connection(s) it uses with other HTTP traffic, including other BOSH sessions and HTTP requests and responses completely unrelated to this protocol (e.g., web page downloads). However, the responses to requests that are not part of the session sent over the same connection using HTTP pipelining (or queued to be sent over the same connection) may be delayed if they were sent while a request that is part of the session is being held (since the connection manager MUST send its responses in the same order that the requests were received, and the connection manager typically delays its responses). Note: Clients that only support Polling Sessions MAY prevent the connection manager from waiting by setting 'wait' or 'hold' to "0". However, polling is NOT RECOMMENDED since the associated increase in bandwidth consumption and the decrease in responsiveness are both typically one or two orders of magnitude! A connection manager MAY be configured to enable sessions with more than one &server; in different domains. When requesting a session with such a 'proxy' connection manager, a client SHOULD include a 'route' attribute that specifies the protocol, hostname, and port of the &server; with which it wants to communicate, formatted as "proto:host:port" (e.g., "xmpp:jabber.org:9999"). A client MAY include a 'from' attribute to enable the connection manager to forward its identity to the &server;. A connection manager MAY be configured to enable sessions with more than one server in different domains. When requesting a session with such a 'proxy' connection manager, a client SHOULD include a 'route' attribute that specifies the protocol, hostname, and port of the server with which it wants to communicate, formatted as "proto:host:port" (e.g., "xmpp:jabber.org:9999"). A client MAY include a 'from' attribute to enable the connection manager to forward its identity to the server. A client MAY include an 'ack' attribute (set to "1") to indicate that it will be using acknowledgements throughout the session and that the absence of an 'ack' attribute in any request is meaningful (see Acknowledgements). A client MAY include a 'secure' attribute to specify that communications between the connection manager and the &server; must be "secure". (Note: The 'secure' attribute is of type xs:boolean (see &w3xmlschema2;) and the default value is "false". &BOOLEANNOTE;) If a connection manager receives a session request with the 'secure' attribute set to "true" or "1", then it MUST respond to the client with a remote-connection-failed error as soon as it determines that it cannot communicate in a secure way with the &server;. A connection manager SHOULD consider communications with the &server; to be "secure" if they are encrypted using SSL or TLS with verified certificates, or if it is running on the same physical machine as the &server;. A connection manager MAY consider communications over a "private" network to be secure, even without SSL or TLS; however, a network SHOULD be considered "private" only if the administrator of the connection manager is sure that unknown individuals or processes do not have access to the network (i.e., individuals or processes who do not have access to either the connection manager or the &server;). The connection manager SHOULD try to establish a secure connection with the &server; even if the client does not specifically require it. A client MAY include a 'secure' attribute to specify that communications between the connection manager and the server must be "secure". (Note: The 'secure' attribute is of type xs:boolean (see &w3xmlschema2;) and the default value is "false". &BOOLEANNOTE;) If a connection manager receives a session request with the 'secure' attribute set to "true" or "1", then it MUST respond to the client with a remote-connection-failed error as soon as it determines that it cannot communicate in a secure way with the server. A connection manager SHOULD consider communications with the server to be "secure" if they are encrypted using SSL or TLS with verified certificates, or if it is running on the same physical machine as the server. A connection manager MAY consider communications over a "private" network to be secure, even without SSL or TLS; however, a network SHOULD be considered "private" only if the administrator of the connection manager is sure that unknown individuals or processes do not have access to the network (i.e., individuals or processes who do not have access to either the connection manager or the server). The connection manager SHOULD try to establish a secure connection with the server even if the client does not specifically require it. Some clients are constrained to only accept HTTP responses with specific Content-Types (e.g., "text/html"). The <body/> element of the first request MAY possess a 'content' attribute. This specifies the value of the HTTP Content-Type header that MUST appear in all the connection manager's responses during the session. If the client request does not possess a 'content' attribute, then the HTTP Content-Type header of responses MUST be "text/xml; charset=utf-8".
-
If the connection manager supports session pausing (see Inactivity) then it SHOULD advertise that to the client by including a 'maxpause' attribute in the session creation response element. The value of the attribute indicates the maximum length of a temporary session pause (in seconds) that a client MAY request.
For both requests and responses, the <body/> element and its content SHOULD be UTF-8 encoded. If the HTTP Content-Type header of a request/response specifies a character encoding other than UTF-8, then the connection manager MAY convert between UTF-8 and the other character encoding. However, even in this case, it is OPTIONAL for the connection manager to convert between encodings. The connection manager MAY inform the client which encodings it can convert by setting the optional 'charsets' attribute in the session creation response element to a space-separated list of encodings.
As soon as the connection manager has established a connection to the &server; and discovered its identity, it MAY forward the identity to the client by including a 'from' attribute in a response, either in its session creation response, or (if it has not received the identity from the &server; by that time) in any subsequent response to the client. If it established a secure connection to the &server; (as defined in Initiating a BOSH Session), then in the same response the connection manager SHOULD also include the 'secure' attribute set to "true" or "1".
+As soon as the connection manager has established a connection to the server and discovered its identity, it MAY forward the identity to the client by including a 'from' attribute in a response, either in its session creation response, or (if it has not received the identity from the server by that time) in any subsequent response to the client. If it established a secure connection to the server (as defined in Initiating a BOSH Session), then in the same response the connection manager SHOULD also include the 'secure' attribute set to "true" or "1".