<abstract>This specification defines how XMPP can be used to transport HTTP communication over peer-to-peer networks.</abstract>
<legal>
<copyright>This XMPP Extension Protocol is copyright (c) 1999 - 2013 by the XMPP Standards Foundation (XSF).</copyright>
<permissions>Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.</permissions>
<warranty>## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##</warranty>
<liability>In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.</liability>
<conformance>
This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <<linkurl='http://www.xmpp.org/extensions/ipr-policy.shtml'>http://www.xmpp.org/extensions/ipr-policy.shtml</link>> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).
Many documents have been written on how to transport XMPP datagrams using HTTP. The motivation behind such solutions has often been to be able to use XMPP in
But up to this point very little has been written about the reverse: How to transport HTTP methods and HTTP responses over an XMPP-based peer-to-peer network.
Here, the motivation is as follows: There are multitudes of applications and APIs written that are based on HTTP over TCP as the basic communication transport protocol.
As these are moving closer and closer to the users, problems arise when the users want to protect their data and services using firewalls. Even though there are methods
today to open up firewalls manually or automatically permit communication with such devices and applications, you still open up the application for everybody. This
rises the need for more advanced security measures which is sometimes difficult to implement using HTTP.
</p>
<p>
The XMPP protocol however does not have the same problems as HTTP in these regards. It's a peer-to-peer protocol naturally allowing communication with applications
and devices behind firewalls. It also includes advanced user authentication and authorization which makes it easier to make sure unauthorized access to private
content is prevented.
</p>
<p>
Furthermore, with the advent of semantic web technologies and its use in web 3.0 and Internet of Things applications, such applications move even more rapidly into
the private spheres of the users, where security and privacy is of paramount importance, it is necessary to use more secure transport protocols than HTTP over TCP.
There are many different types of HTTP-based communication that one would like to be able to transport over XMPP. A non-exhaustive list can include:
</p>
<ul>
<li>Web Content like pages, images, files, etc.</li>
<li>Web Forms.</li>
<li>Web Services (SOAP, REST, etc.)</li>
<li>Semantic Web Resources (RDF, Turtle, etc.)</li>
<li>Federated SPARQL queries (SQL-type query language for the semantic web, or web 3.0)</li>
<li>Streamed multi-media content in UPnP and DLNA networks.</li>
</ul>
<p>
Instead of trying to figure out all possible things transportable over HTTP and make them transportable over XMPP, this document ignores the type of content transported,
and instead focuses on encoding and decoding the original HTTP requests and responses, building an HTTP tunnel over an existing XMPP connection. It would enable
existing applications to work seamlessly over XMPP if browsers and web services supported this extension (like displaying your home control application on your phone
when you are at work), without the need to update the myriad of existing applications. It would also permit federated SPARQL queries in personal networks with the added
benefit of being able to control who can talk to who (or what can talk to what) through established friendship relationships.
</p>
<p>
Previous extensions handling different aspects of XMPP working together with HTTP:
</p>
<ul>
<li>
&xep0070;: This specification handles client authentication of resources, where there are three parties: HTTP Client <-> HTTP Server/XMPP Client <-> XMPP Server.
Here HTTP Client authentication to resources on the HTTP Server is made by a third party, an XMPP Server.
&xep0072;: This specification handles execution of SOAP-based web services specifically. This specification has some benefits regarding to Web Service calls over XMPP,
but is only one example of all types of HTTP-based communication one would desire to transport over XMPP.
&xep0124;: This specification handles XMPP-based communication over HTTP sessions (BOSH), allowing for instance, XMPP communication in java script using the
&xep0131;: While not directly related to HTTP, it is used to transport headers in the form of collections of key-value pairs, exactly as is done in HTTP. The format
for encoding headers into XMP defined by this XEP will be re-used in this XEP.
&xep0147;: This informational specification proposes ways to define XMPP-actions using URL's. This document will propose a different URI scheme for HTTP-based resources
over an XMPP transport.
</li>
</ul>
</section1>
<section1topic='Requirements'anchor='reqs'>
<p>
This document presupposes the server already has a web server (HTTP Server) implementation, and that it hosts content through it, content which can be both
All HTTP communication is done using the <strong>Request</strong>/<strong>Response</strong> paradigm. Each HTTP Request is made sending an <strong>iq</strong>-stanza
containing a <strong>req</strong> element to the server. Each <strong>iq</strong>-stanza sent is of type <strong>set</strong>.
When the server responds, it does so by sending an <strong>iq</strong>-stanza response (type <strong>result</strong>) back to the client containing a <strong>resp</strong>
element. Since responses are asynchronous, and since multiple requests may be active at the same time, responses may be returned in a different order than the in which the
original requests were made.
</p>
<p>
Requests or responses containing data must also consider how this data should be encoded within the XML telegram. Normally in HTTP, content and headers are separated
by a blank line, and the transfer of the content is made in the same stream. Specific HTTP headers are used to define how the content is transferred and encoded within
the stream (Content-Type, Content-Length, Content-Encoding, Content-Transfer-Encoding). This approach is not possible if the response is to be embedded in an XML telegram,
since it can interfere with the encoding of the encompassing XML.
</p>
<p>
To solve this, this document specifies additional data transfer mechanisms that are compatible with the XMPP protocol. The normal HTTP-based content transfer headers will
still be transported, but do not affect the content encoding used in the XMPP transport. The following content encoding methods are available:
Normal text content. The text is encoded as text within XML, using the same encoding used by the XML stream. XML escape characters (<, > and &)
are escaped using the normal &lt;, &gt; and &amp; character escape sequences.
</p>
</dd>
</di>
<di>
<dt>xml</dt>
<dd>
<p>
Xml content embedded in the XML telegram. Note however, that any processing instructions or XML version statements must be avoided, since it may cause
the XML stream to become invalid XML. If this is a problem, normal <strong>text</strong> encoding can be used as an alternative. The advantage of <strong>xml</strong>
instead of <strong>text</strong> or <strong>base64</strong> encodings is when used in conjunction with EXI compression &xep0322;. EXI compression has the ability to
compress XML efficiently. Text will not be compressed, unless response exists in internal string tables. Base-64 encoded data will be compressed so that the 33%
size gain induced by the encoding is recaptured.
</p>
</dd>
</di>
<di>
<dt>base64</dt>
<dd>
<p>
Base-64 encoded binary content. Can be used to easily embed binary content in the telegram.
</p>
</dd>
</di>
<di>
<dt>chunkedBase64</dt>
<dd>
<p>
Chunked Base-64 encoded binary content. The content is not embedded in the telegram. Instead it is sent in chunks, using separate
<strong>chunk</strong> messages to the client. Chunked transport can be used by the server when it doesn't know the size of the final result.
Streaming content, i.e. content of infinite length, must use <strong>ibb</strong> or <strong>jingle</strong> transport types to transfer content.
If the content consists of a file, <strong>sipub</strong> should be used.
</p>
<p>
Chunked encoding is perfect for dynamic responses of moderate sizes, for instance for API method responses. The server does not know when the response
is begun to be generated what the final size will be, but it will be most probably "manageable". Using the chunked transfer mechanism enables the
server to start sending the content, minimizing the need for buffers, and at the same time minimizing the number of messages that needs to be sent,
increasing throughput.
</p>
<p>
The client can limit the maximum chunk size to be used by the server, using the <strong>maxChunkSize</strong> attribute in the request. The chunk
size can be set to a value between 256 and 65536. If not provided in the request, the server chooses an appropriate value. Note that chunks can
be sent containing a smaller amount of bytes than the maximum chunk size provided in the request.
</p>
</dd>
</di>
<di>
<dt>sipub</dt>
<dd>
<p>
The sender might deem the content to be too large for sending embedded in the XMPP telegram. To circumnavigate this, the sender publishes
the content as a file using &xep0137; (Publishing Stream Initiation Requests), instead of embedding the content directly. This might be the case for instance, when
a client requests a video resource, without using a ranged request.
</p>
<p>
This transfer mechanism is of course the logical choice, if the content is already stored in a file on the server, and the size of the file
is sufficiently large to merit the overhead of sipub. Smaller files can simply be returned using the <strong>text</strong>, <strong>xml</strong>
or <strong>base64</strong> mechanisms.
</p>
<p>
The client can disable the use of <strong>sipub</strong> by the server, by including a <strong>sipub='false'</strong> attribute in the request.
<strong>sipub</strong> is enabled by default. On constrained devices with limited support for different XEP's, this can be a way to avoid the
use of technologies not supported by the client.
</p>
</dd>
</di>
<di>
<dt>ibb</dt>
<dd>
<p>
This option may be used to encode indefinite streams, like live audio or video streams (HLS, SHOUTcast, Motion JPeg web cams, etc).
It uses &xep0047; to send the content over an in-band bytestream to the client. This option is not available in requests, only in responses.
</p>
<p>
Streams must not use any of the above mechanisms. Only <strong>ibb</strong> and <strong>jingle</strong> mechanisms can be used. If the content
represents multimedia <strong>jingle</strong> is preferrable, especially if different encodings are available.
</p>
<p>
The client can disable the use of <strong>ibb</strong> by the server, by including a <strong>ibb='false'</strong> attribute in the request.
<strong>ibb</strong> is enabled by default. On constrained devices with limited support for different XEP's, this can be a way to avoid the
use of technologies not supported by the client.
</p>
</dd>
</di>
<di>
<dt>jingle</dt>
<dd>
<p>
For demanding multi-media streams alternative methods to transport streaming rather than embedded into the XMPP stream may be
required. Even though the <strong>ibb</strong> method may be sufficient to stream a low-resolution web cam in the home, or listen to a microphone
or a radio station, it is probably badly suited for high-resolution video streams with multiple video angles and audio channels. If such content is accessed
and streamed, the server can negotiate a different way to stream the content using &xep0166;.
</p>
<p>
The client can disable the use of <strong>ingle</strong> by the server, by including a <strong>jingle='false'</strong> attribute in the request.
<strong>jingle</strong> is enabled by default. On constrained devices with limited support for different XEP's, this can be a way to avoid the
<strong>Note:</strong> Content encoded using <strong>chunkedBase64</strong> encoding method can be terminated, either by the receptor going off-line, or by
sending a <strong>close</strong> command to the sender. The transfer methods <strong>sipub</strong>, <strong>ibb</strong> and <strong>jingle</strong> have
their own mechanisms for aborting content transfer.
The following use cases show how different HTTP methods may work when transported over XMPP. To facilitate the readability in these examples,
simple text or xml results are shown.
</p>
<section3topic='OPTIONS'anchor='OPTIONS'>
<p>
This section shows an example of an OPTIONS method call. OPTIONS is described in <linkurl='http://tools.ietf.org/html/rfc2616#section-9.2'>§9.2 in RFC 2616</link>.
This section shows an example of a GET method call. GET is described in <linkurl='http://tools.ietf.org/html/rfc2616#section-9.3'>§9.3 in RFC 2616</link>.
<strong>Note:</strong> The XMPP/HTTP bridge at the server only transmits headers literally as they are reported, as if it was normal HTTP over TCP
that was used. In the HTTP over XMPP case, connections are not handled in the same way, and so the "Connection: Close" header has no meaning in this
case. For more information about connection handling in the HTTP over XMPP case, see the section on <linkurl='#httpconnections'>Connection Handling</link>.
</p>
</section3>
<section3topic='HEAD'anchor='HEAD'>
<p>
This section shows an example of a HEAD method call. HEAD is described in <linkurl='http://tools.ietf.org/html/rfc2616#section-9.4'>§9.4 in RFC 2616</link>.
This section shows an example of a POST method call. POST is described in <linkurl='http://tools.ietf.org/html/rfc2616#section-9.5'>§9.5 in RFC 2616</link>.
(<?xml version="1.0"?>) at the top of the document, otherwise the resulting XML will be invalid.
</p>
</section3>
<section3topic='PUT'anchor='PUT'>
<p>
This section shows an example of a PUT method call. PUT is described in <linkurl='http://tools.ietf.org/html/rfc2616#section-9.6'>§9.6 in RFC 2616</link>.
This section shows an example of a DELETE method call. DELETE is described in <linkurl='http://tools.ietf.org/html/rfc2616#section-9.7'>§9.7 in RFC 2616</link>.
<text>You're not allowed to change the home page!</text>
</data>
</resp>
</iq>]]>
</example>
</section3>
<section3topic='TRACE'anchor='TRACE'>
<p>
This section shows an example of a TRACE method call. TRACE is described in <linkurl='http://tools.ietf.org/html/rfc2616#section-9.8'>§9.8 in RFC 2616</link>.
or a radio station, it is probably badly suited for high-resolution video streams with multiple video angles and audio channels. If such content is accessed
and streamed, the server can negotiate a different way to stream the content using <linkurl='http://xmpp.org/extensions/xep-0166.html'>XEP 0166: Jingle</link>.
from the http:// scheme to an xmpp:// scheme. All relative URL's within the application, including URL's sent to the XHR object (Ajax) will automatically
be directed to use the HTTP over XMPP transport instead.
</p>
<p>
So, this specification proposes a new transport for HTTP over XMPP, as follows:
</p>
<examplecaption='xmpp:// scheme'>
<![CDATA[
xmpp://Resourceless_JID/PATH]]>
</example>
<p>
Here, the JID to use in the URL, must not include a resource. Only user name, the @ character and the domain. The / separator between the JID
There are many types of streams and streaming protocols. Several of these are based on HTTP or variants simulating HTTP. Examples of such HTTP-based or
<p>If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:http" in response to &xep0030; information requests.</p>
<examplecaption="Service discovery information request">
In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined
in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.
HTTP Headers are serialized to and from XML using the XEP-0131 <linkurl='http://xmpp.org/extensions/xep-0131.html'>Stanza Headers and Internet Metadata</link>.
However, this does not mean that the SHIM feature needs to be published by the client, as defined in §3 in
<linkurl='http://xmpp.org/extensions/xep-0131.html#disco'>XEP-0131</link>, since the headers will be embedded into the HTTP elements.
Also, if there is any conflicts in how to store header values, when it comes to data types, etc., the original format as used by the original
HTTP request must be used, and not the format defined in <linkurl='http://xmpp.org/extensions/xep-0131.html#headers'>Header Definitions</link> or
<linkurl='http://xmpp.org/extensions/xep-0131.html#dates'>A Note About date-Related Headers</link> in XEP-0131.
</p>
<p>
The HTTP over XMPP tunnel is just a tunnel of HTTP over XMPP, it does not know the semantic meaning of headers used in the transport. It does not know
if additional headers added by the myriad of custom applications using HTTP are actually HTTP-compliant. It just acts as a transport, returning the
sime kind of response (being deterministric) as if the original request was made through other means, for example over TCP. It does not add, remove or
change semantic meaning of keys and values, nor change the format of the corresponding values. Such changes will create uncountable problems very difficult
to detect and solve in a general case.
</p>
<p>
This specification differs from XEP-0131 in that this specification the headers are consumed by web servers and web clients (The XMPP client here only
being a "dumb" gateway), while in XEP-0131 the headers are consumed by the XMPP clients themselves, knowing XML and XML formats.
</p>
</section2>
<section2topic='Stanza Sizes'>
<p>
Some XMPP Servers may limit stanza sizes for various reasons. While this may work well for certain applications, like
Instant Messaging and Chat, implementors of HTTP over XMPP need to know that some server have such stanza size
restrictions. Therefore, an implementation should include configurable size limits, so chunking can be used instead
of sending large stanzas. Another limit could be when streaming should be used instead of chunking. This later limit
should be applied in particular on audio and video content.
</p>
<p>
The implementor should also consider to send large content in the form of files using file transfer, and large multi-media
content using Jingle.
</p>
</section2>
<section2topic='Bandwidth Limitations'>
<p>
Some XMPP Servers may also have bandwidth resitrctions enforced. This to limit the possibility of Denial of Service attacks
or similar flooding of messages. Implementors of the HTTP over XMPP extensions must know however, that the bandwidth
limitations for instant messaging and chat may be completely different from that of normal web applications. In chatting,
a 1000 bytes/s limit is in most cases sufficient, while the same limit for even a modest web applications will make the