From 99bd98004b49f5b592204227372c158fba04960a Mon Sep 17 00:00:00 2001 From: JC Brand Date: Mon, 24 Sep 2018 09:52:09 +0200 Subject: [PATCH] Add 404 for OPTIONS request to troubleshooting section --- README.md | 2 +- docs/source/setup.rst | 43 +++++++++++++++++---------------- docs/source/troubleshooting.rst | 17 +++++++++++++ 3 files changed, 40 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 57e74ed9a..e0e6dbcd9 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ You can either use it as a webchat app, or you can integrate it into your own website. -It''s 100% client-side JavaScript, HTML and CSS and the only backend required +It's 100% client-side JavaScript, HTML and CSS and the only backend required is a modern XMPP server. Please support this project via [Patreon](https://www.patreon.com/jcbrand) or [Liberapay](https://liberapay.com/jcbrand) diff --git a/docs/source/setup.rst b/docs/source/setup.rst index 00f150332..33ee5f31f 100644 --- a/docs/source/setup.rst +++ b/docs/source/setup.rst @@ -52,14 +52,16 @@ The various components An XMPP server ============== -*Converse* uses `XMPP `_ as its +Converse uses `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 ``conversejs.org`` but if you want to -have :ref:`session support ` you'll have to set up your own XMPP server. +integrate Converse into your own website and to use your website's +authentication sessions to log in users to the XMPP server (i.e. :ref:`session support `) +then you'll have to set up your own XMPP server. -You can find a list of public XMPP servers/providers on `xmpp.net `_ +You can find a list of public XMPP servers/providers on `compliance.conversations.im `_ and a list of servers that you can set up yourself on `xmpp.org `_. .. _`BOSH-section`: @@ -78,7 +80,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* 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 @@ -127,31 +129,30 @@ configure Converse to connect to a websocket URL. The Webserver ============= +.. _CORS: + Overcoming cross-domain request restrictions -------------------------------------------- -Lets say your domain is *example.org*, but the domain of your connection -manager is *example.com*. +Lets say the domain under which you host Converse is *example.org:80*, +but the domain of your connection manager or the domain of +your HTTP file server (for `XEP-0363 HTTP File Upload `_) +is at a different domain, either a different port like *example.org:5280* or a +different name like *elsehwere.org*. -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). +In cases like this, cross-domain request restrictions of the browser come into +force. For security purposes a browser does not by default allow a website to +make certain types of requests to other domains. -Luckily there is now a standard called -`CORS `_ -(Cross-origin resource sharing), which enables exactly that. -Modern browsers support CORS, but there are problems with Internet Explorer < 10. +One solution is to add a reverse proxy to a webserver such as Nginx or Apache to ensure that +all services you use are hosted under the same domain name and port. -IE 8 and 9 partially support CORS via a proprietary implementation called -XDomainRequest. There is a `Strophe.js plugin `_ -which you can use to enable support for XDomainRequest when it is present. +Alternatively you can use something called `CORS `__ +(Cross-origin resource sharing). -In IE < 8, there is no support for CORS. +By enabling CORS on the non-local domains (e.g. *elsewhere.org*, when +*example.org* is the local domain), you allow the browser to make requests to it. -Instead of using CORS, you can add a reverse proxy in -Apache/Nginx which serves the connection manager under the same domain as your -website. This will remove the need for any cross-domain XHR support. Examples: ********* diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 7c8d2fa95..f1b87a9c0 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -56,3 +56,20 @@ One simple trick to improve performance is to set ``show_only_online_users: true This will (usually) reduce the amount of contacts that get rendered in the roster, which eases one of the remaining performance bottlenecks. +404 response for an OPTIONS request +=================================== + +This often happens when trying to upload a file to the XEP-0363 file server +which is under a different domain or port than the one that's hosting Converse. + +An OPTIONS request usually a so-called +`CORS pre-flight request `_ +which is used by the browser to find out whether the endpoint supports +`Cross-Origin Resource Sharing (CORS) `_. + +If you get a 404 response for such a request, then the endpoint does NOT +support CORS and the browser will prevent requests from being made to it. + +This will prevent you from uploading images to it. + +Take a look at the section ":ref:`CORS`" for more information on how to solve this problem.