浏览代码

Add 404 for OPTIONS request to troubleshooting section

JC Brand 6 年之前
父节点
当前提交
99bd98004b
共有 3 个文件被更改,包括 40 次插入22 次删除
  1. 1 1
      README.md
  2. 22 21
      docs/source/setup.rst
  3. 17 0
      docs/source/troubleshooting.rst

+ 1 - 1
README.md

@@ -9,7 +9,7 @@
 
 
 You can either use it as a webchat app, or you can integrate it into your own website.
 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.
 is a modern XMPP server.
 
 
 Please support this project via [Patreon](https://www.patreon.com/jcbrand) or [Liberapay](https://liberapay.com/jcbrand)
 Please support this project via [Patreon](https://www.patreon.com/jcbrand) or [Liberapay](https://liberapay.com/jcbrand)

+ 22 - 21
docs/source/setup.rst

@@ -52,14 +52,16 @@ The various components
 An XMPP server
 An XMPP server
 ==============
 ==============
 
 
-*Converse* uses `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
 messaging protocol, and therefore needs to connect to an XMPP/Jabber
 server (Jabber® is an older and more user-friendly synonym for XMPP).
 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
 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.
+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 <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 <https://list.jabber.at>`_
+You can find a list of public XMPP servers/providers on `compliance.conversations.im <http://compliance.conversations.im/>`_
 and a list of servers that you can set up yourself on `xmpp.org <http://xmpp.org/xmpp-software/servers/>`_.
 and a list of servers that you can set up yourself on `xmpp.org <http://xmpp.org/xmpp-software/servers/>`_.
 
 
 .. _`BOSH-section`:
 .. _`BOSH-section`:
@@ -78,7 +80,7 @@ stanzas to be sent over an HTTP connection.
 HTTP connections are stateless and usually shortlived.
 HTTP connections are stateless and usually shortlived.
 XMPP connections on the other hand are stateful and usually last much longer.
 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.
 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
 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
 The Webserver
 =============
 =============
 
 
+.. _CORS:
+
 Overcoming cross-domain request restrictions
 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 <https://xmpp.org/extensions/xep-0363.html>`_)
+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 <https://en.wikipedia.org/wiki/Cross-origin_resource_sharing>`_
-(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 <https://gist.github.com/1095825/6b4517276f26b66b01fa97b0a78c01275fdc6ff2>`_
-which you can use to enable support for XDomainRequest when it is present.
+Alternatively you can use something called `CORS <https://en.wikipedia.org/wiki/Cross-origin_resource_sharing>`__
+(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:
 Examples:
 *********
 *********

+ 17 - 0
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
 This will (usually) reduce the amount of contacts that get rendered in the
 roster, which eases one of the remaining performance bottlenecks.
 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 <https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS#Preflighted_requests_in_CORS>`_
+which is used by the browser to find out whether the endpoint supports
+`Cross-Origin Resource Sharing (CORS) <https://developer.mozilla.org/en-US/docs/Web/HTTP/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.