Document timeout fix for parsing errors
This commit is contained in:
JC Brand
parent
4cefc7cdf9
commit
b323794fe4
@ -8,19 +8,19 @@
|
||||
Setup and integration
|
||||
=====================
|
||||
|
||||
This page documents what you'll need to do to be able to connect Converse.js with
|
||||
This page documents what you'll need to do to be able to connect Converse with
|
||||
your own XMPP server and to better integrate it into your website.
|
||||
|
||||
At the very least you'll need Converse.js and an :ref:`XMPP server` with
|
||||
At the very least you'll need Converse and an :ref:`XMPP server` with
|
||||
:ref:`websocket-section` or :ref:`BOSH-section` enabled. That's definitely
|
||||
enough to simply demo Converse.js or to do development work on it.
|
||||
enough to simply demo Converse or to do development work on it.
|
||||
|
||||
However, if you want to more fully integrate it into a website or intranet,
|
||||
However, if you want to more fully integrate it into a website
|
||||
then you'll likely need to set up more services and components.
|
||||
|
||||
The diagram below shows a fairly common setup for a website or intranet:
|
||||
|
||||
* Converse.js runs in the web-browser on the user's device.
|
||||
* Converse runs in the web-browser on the user's device.
|
||||
|
||||
* It communicates with the XMPP server via BOSH or websocket which is usually
|
||||
reverse-proxied by a web-server in order to overcome cross-site scripting
|
||||
@ -34,13 +34,12 @@ The diagram below shows a fairly common setup for a website or intranet:
|
||||
the XMPP server is configured to use, so that users can log in with those
|
||||
credentials.
|
||||
|
||||
|
||||
* Usually (but optionally) there is a backend web application which hosts a
|
||||
website in which Converse.js appears.
|
||||
website in which Converse appears.
|
||||
|
||||
.. figure:: images/diagram.png
|
||||
:align: center
|
||||
:alt: A diagram of a possible setup, consisting of Converse.js, a web server, a backend web application, an XMPP server, a user directory such as LDAP and an XMPP server.
|
||||
:alt: A diagram of a possible setup, consisting of Converse, a web server, a backend web application, an XMPP server, a user directory such as LDAP and an XMPP server.
|
||||
|
||||
This diagram shows the various services in a fairly common setup (image generated with `draw.io <https://draw.io>`_).
|
||||
|
||||
@ -53,11 +52,11 @@ The various components
|
||||
An XMPP server
|
||||
==============
|
||||
|
||||
*Converse.js* implements `XMPP <http://xmpp.org/about-xmpp/>`_ as its
|
||||
*Converse* uses `XMPP <http://xmpp.org/about-xmpp/>`_ as its
|
||||
messaging protocol, and therefore needs to connect to an XMPP/Jabber
|
||||
server (Jabber® is an older and more user-friendly synonym for XMPP).
|
||||
|
||||
You can connect to public XMPP servers like ``jabber.org`` but if you want to
|
||||
You can connect to public XMPP servers like ``conversejs.org`` but if you want to
|
||||
have :ref:`session support <session-support>` you'll have to set up your own XMPP server.
|
||||
|
||||
You can find a list of public XMPP servers/providers on `xmpp.net <https://list.jabber.at>`_
|
||||
@ -79,7 +78,7 @@ stanzas to be sent over an HTTP connection.
|
||||
HTTP connections are stateless and usually shortlived.
|
||||
XMPP connections on the other hand are stateful and usually last much longer.
|
||||
|
||||
So to enable a web application like *Converse.js* to communicate with an XMPP
|
||||
So to enable a web application like *Converse* to communicate with an XMPP
|
||||
server, we need a proxy which acts as a bridge between these two protocols.
|
||||
|
||||
This is the job of a BOSH connection manager. BOSH (Bidirectional-streams Over
|
||||
@ -87,7 +86,7 @@ Synchronous HTTP) is a protocol for allowing XMPP communication over HTTP. The
|
||||
protocol is defined in `XEP-0206: XMPP Over BOSH <http://xmpp.org/extensions/xep-0206.html>`_.
|
||||
|
||||
Popular XMPP servers such as `Ejabberd <http://www.ejabberd.im>`_,
|
||||
prosody `(mod_bosh) <http://prosody.im/doc/setting_up_bosh>`_ and
|
||||
Prosody `(mod_bosh) <http://prosody.im/doc/setting_up_bosh>`_ and
|
||||
`OpenFire <http://www.igniterealtime.org/projects/openfire/>`_ all include
|
||||
their own BOSH connection managers (but you usually have to enable them in the
|
||||
configuration).
|
||||
@ -98,14 +97,15 @@ https://conversejs.org does), then you'll need a standalone connection manager.
|
||||
For a standalone manager, see for example `Punjab <https://github.com/twonds/punjab>`_
|
||||
and `node-xmpp-bosh <https://github.com/dhruvbird/node-xmpp-bosh>`_.
|
||||
|
||||
The demo on the `Converse.js homepage <http://conversejs.org>`_ uses a connection
|
||||
The demo on the `Converse homepage <http://conversejs.org>`_ uses a connection
|
||||
manager located at https://conversejs.org/http-bind.
|
||||
|
||||
This connection manager is available for testing purposes only, please don't
|
||||
use it in production.
|
||||
|
||||
Refer to the :ref:`bosh-service-url` configuration setting for information on
|
||||
how to configure Converse.js to connect to a BOSH URL.
|
||||
how to configure Converse to connect to a BOSH URL.
|
||||
|
||||
|
||||
.. _`websocket-section`:
|
||||
|
||||
@ -122,7 +122,7 @@ HTTP. Therefore BOSH, which operates over HTTP, doesn't apply to websockets.
|
||||
does the node-xmpp-bosh connection manager.
|
||||
|
||||
Refer to the :ref:`websocket-url` configuration setting for information on how to
|
||||
configure Converse.js to connect to a websocket URL.
|
||||
configure Converse to connect to a websocket URL.
|
||||
|
||||
The Webserver
|
||||
=============
|
||||
@ -133,7 +133,7 @@ Overcoming cross-domain request restrictions
|
||||
Lets say your domain is *example.org*, but the domain of your connection
|
||||
manager is *example.com*.
|
||||
|
||||
HTTP requests are made by *Converse.js* to the BOSH connection manager via
|
||||
HTTP requests are made by *Converse* to the BOSH connection manager via
|
||||
XmlHttpRequests (XHR). Until recently, it was not possible to make such
|
||||
requests to a different domain than the one currently being served
|
||||
(to prevent XSS attacks).
|
||||
@ -159,7 +159,7 @@ Examples:
|
||||
Assuming your site is accessible on port ``80`` for the domain ``mysite.com``
|
||||
and your connection manager manager is running at ``someothersite.com/http-bind``.
|
||||
|
||||
The *bosh_service_url* value you want to give Converse.js to overcome
|
||||
The *bosh_service_url* value you want to give Converse to overcome
|
||||
the cross-domain restriction is ``mysite.com/http-bind`` and not
|
||||
``someothersite.com/http-bind``.
|
||||
|
||||
@ -192,6 +192,26 @@ Apache
|
||||
</VirtualHost>
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
If you're getting XML parsing errors for your BOSH endpoint, for
|
||||
example::
|
||||
|
||||
XML Parsing Error: mismatched tag. Expected: </hr>.
|
||||
Location: https://example.org/http-bind/
|
||||
Line Number 6, Column 3: bosh-anon:6:3
|
||||
Also ERROR: request id 12.2 error 504 happened
|
||||
|
||||
Then it might be because your webserver and BOSH proxy have the same timeout
|
||||
for BOSH requests. Because the webserver receives the request slightly earlier,
|
||||
it gives up a few microseconds before the XMPP server’s empty result and thus returns a
|
||||
504 error page containing HTML to browser, which then gets parsed as if its
|
||||
XML.
|
||||
|
||||
To fix this, make sure that the webserver's timeout is slightly higher.
|
||||
In Nginx you can do this by adding ``proxy_read_timeout 61;``;
|
||||
|
||||
|
||||
.. _`session-support`:
|
||||
|
||||
Single Session Support
|
||||
@ -215,7 +235,7 @@ authenticated BOSH session with the XMPP server or a standalone `BOSH <http://xm
|
||||
connection manager.
|
||||
|
||||
Once authenticated, it receives RID and SID tokens which need to be passed
|
||||
on to converse.js upon pa. Converse.js will then attach to that same session using
|
||||
on to converse.js upon pa. Converse will then attach to that same session using
|
||||
those tokens.
|
||||
|
||||
It's called "prebind" because you bind to the BOSH session beforehand, and then
|
||||
@ -250,7 +270,7 @@ converse.js can then attach to.
|
||||
A BOSH server acts as a bridge between HTTP, the protocol of the web, and
|
||||
XMPP, the instant messaging protocol.
|
||||
|
||||
Converse.js can only communicate via HTTP (or websocket, in which case BOSH can't be used).
|
||||
Converse can only communicate via HTTP (or websocket, in which case BOSH can't be used).
|
||||
It cannot open TCP sockets to communicate to an XMPP server directly.
|
||||
|
||||
So the BOSH server acts as a middle man, translating our HTTP requests into XMPP stanzas and vice versa.
|
||||
@ -303,7 +323,7 @@ authentication to external services. They are listed in the `Prosody community m
|
||||
page <https://modules.prosody.im/>`_. Other XMPP servers have similar plugin modules.
|
||||
|
||||
If your web-application has access to the same credentials, it can send those
|
||||
credentials to Converse.js so that user's are automatically logged in when the
|
||||
credentials to Converse so that user's are automatically logged in when the
|
||||
page loads.
|
||||
|
||||
This is can be done by setting :ref:`auto_login` to true and configuring the
|
||||
@ -316,7 +336,7 @@ The first option has the drawback that your web-application needs to know the
|
||||
XMPP credentials of your users and that they need to be stored in the clear.
|
||||
|
||||
The second option has that same drawback and it also needs to pass those
|
||||
credentials to Converse.js.
|
||||
credentials to Converse.
|
||||
|
||||
To avoid these drawbacks, you can instead let your backend web application
|
||||
generate temporary authentication tokens which are then sent to the XMPP server
|
||||
|
||||
@ -1 +1 @@
|
||||
zc.buildout==2.11.4
|
||||
zc.buildout==2.12.1
|
||||
|
||||
Loading…
Reference in New Issue
Block a user