Chapril/xmpp.chapril.org-conversejs
Chapril/xmpp.chapril.org-conversejs
24
0
Fork 0
Code Issues Pull Requests Projects Releases Activity

Add more documentation around file sharing and CORS

Browse Source
This commit is contained in:
JC Brand 2018-11-10 21:59:57 +01:00
parent 9d0cfe8f43
commit 1c38863bfd
4 changed files with 99 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
docs/source/features.rst
View File

@ -2,22 +2,32 @@
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/features.rst">Edit me on GitHub</a></div>
.. _`features`:
========
Features
========
Open chats via URL
==================
File sharing (`XEP-0363 HTTP File Upload <https://xmpp.org/extensions/xep-0363.html>`_)
=======================================================================================
From version 3.3.0, converse.js now has the ability to open chats (private or
groupchat) based on the URL fragment.
Converse supports file sharing by first uploading the file to a file server and
then sending the file's URL to the recipient.
A room (aka groupchat) can be opened with a URL fragment such as `#converse/room?jid=room@domain`
and a private chat with a URL fragment such as
`#converse/chat?jid=user@domain`.
The file server that is used is configured by the XMPP server admin, and is not
something that Converse has any control over.
XEP-0384 OMEMO Encryption
=========================
Often when people report file sharing not working, it's because the file server
is not configured to allow file uploads from other domains.
The file server needs to be configured for `Cross-Origin resource sharing <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`_
(known by the acronym CORS). Specifically, it needs to add a
``Access-Control-Allow-Origin`` header which includes the domain hosting
Converse.
End to end message encryption (`XEP-0384 OMEMO <https://xmpp.org/extensions/xep-0363.html>`_)
=============================================================================================
Converse supports OMEMO encryption based on the
`Signal Protocol <https://github.com/signalapp/libsignal-protocol-javascript>`_.
@ -83,6 +93,18 @@ articles:
* `What's wrong with webcrypto? <https://tonyarcieri.com/whats-wrong-with-webcrypto>`_
* `Heartbleed and JavaScript crypto <https://tankredhase.com/2014/04/13/heartbleed-and-javascript-crypto/>`_
Open chats via URL
==================
From version 3.3.0, converse.js now has the ability to open chats (private or
groupchat) based on the URL fragment.
A room (aka groupchat) can be opened with a URL fragment such as `#converse/room?jid=room@domain`
and a private chat with a URL fragment such as
`#converse/chat?jid=user@domain`.
Notifications
=============

42
docs/source/quickstart.rst
View File

@ -20,10 +20,11 @@ The latest versions of these files are available at these URLs:
* https://cdn.conversejs.org/dist/converse.min.js
* https://cdn.conversejs.org/css/converse.min.css
It's however recommended that you load a specific version of Converse, to avoid
breakage when a new version is released and the above URLs load new resources.
If you are integrating Converse into an existing website or app, then we recommend
that you load a specific version of Converse. Otherwise your website or app
might break when a new backwards-incompatible version of Converse is released.
To load a specific version of Converse you can put the version in the URL, like so:
To load a specific version of Converse you can put the version in the URL:
* https://cdn.conversejs.org/4.0.4/dist/converse.min.js
* https://cdn.conversejs.org/4.0.4/css/converse.min.css
@ -33,28 +34,19 @@ via the *script* and *link* tags:
.. code-block:: html
<link rel="stylesheet" type="text/css" media="screen" href="https://cdn.conversejs.org/css/converse.min.css">
<script src="https://cdn.conversejs.org/dist/converse.min.js" charset="utf-8"></script>
.. note:: Instead of always loading the latest version of Converse via the
CDN, it's generally better to load a specific version (preferably the
latest one), to avoid breakage when new backwards-incompatible versions are
released.
<link rel="stylesheet" type="text/css" media="screen" href="https://cdn.conversejs.org/4.0.4/css/converse.min.css">
<script src="https://cdn.conversejs.org/4.0.4/dist/converse.min.js" charset="utf-8"></script>
Option 2: Building the files yourself
-------------------------------------
Instead of using the CDN, you can also create your own builds and host them
yourself.
Instead of using the CDN, you can also create your own builds and host them yourself.
Have a look at the :ref:`creating_builds` section on how to create your own
builds.
Have a look at the :ref:`creating_builds` section on how to create your own builds.
Long story short, you should be able to do it by running `make dist`, but you
might need to install some development libraries on your system first
(e.g. gcc, libffi-dev and ruby-dev).
In short, you should be able to do it by running ``make dist`` inside a
checkout of the `Converse repo <http://github.com/conversejs/converse.js/>`_.
Besides including the ``converse.min.js`` and ``converse.min.css`` files,
you'll also need to make sure that the ``webfonts`` directory is available in
@ -64,8 +56,8 @@ the same location as ``converse.min.css``.
Initializing Converse
---------------------
You'll then need to initialize Converse with configuration settings relevant to your requirements.
Refer to the :ref:`configuration-settings` section for info on all the available configuration settings.
You'll need to initialize Converse with configuration settings relevant to your requirements.
Take a look at the :ref:`configuration-settings` section for info on all the available settings.
To quickly get started, you can put the following JavaScript code at the
bottom of your page (after the closing *</body>* element)::
@ -78,7 +70,7 @@ bottom of your page (after the closing *</body>* element)::
</script>
The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the
Converse repository may serve as a nice usable example.
Converse repository serves as a nice, usable example.
Fullscreen version
------------------
@ -103,15 +95,19 @@ For example::
Where to go from here?
======================
Have a look at the various :ref:`features <features>` that Converse provides, for some of
them you might have to do more setup work, like configuring an XMPP server or
webserver.
You might want to implement some kind of persistent single-session solution for
your website, where users authenticate once in your website and are then
automatically logged in to the XMPP server as well. For more info on how this
can be achieved, read: :ref:`session-support`.
Perhaps you want to create your own custom build of Converse? Then head over
to the :doc:`builds` section, or more generally the :doc:`development`
to the :doc:`builds` section, or more generally the :doc:`development <development>`
documentation.
Do you want to know how to theme Converse? Then read the :doc:`theming`
Do you want to know how to theme Converse? Then read the :doc:`theming <theming>`
documentation.

35
docs/source/setup.rst
View File

@ -129,31 +129,36 @@ configure Converse to connect to a websocket URL.
The Webserver
=============
.. _CORS:
Overcoming cross-domain request restrictions
--------------------------------------------
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*.
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
In such a situation the same-origin security policy of the browser comes into force.
For security purposes a browser does not by default allow a website to
make certain types of requests to other domains.
One solution is to add a reverse proxy to a webserver such as Nginx or Apache to ensure that
There are two ways in which you can solve this problem.
.. _CORS:
1. Cross-Origin Resource Sharing (CORS)
---------------------------------------
CORS is a technique for overcoming browser restrictions related to the
`same-origin security policy <https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy>`_.
CORS is enabled by adding an ``Access-Control-Allow-Origin`` header. Where this
is configured depends on what webserver is used for your file upload server.
2. Reverse-proxy
----------------
Another possible 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.
Alternatively you can use something called `CORS <https://en.wikipedia.org/wiki/Cross-origin_resource_sharing>`__
(Cross-origin resource sharing).
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.
Examples:
*********

36
docs/source/troubleshooting.rst
View File

@ -56,13 +56,30 @@ 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
===================================
File upload is not working
==========================
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.
One of the most common causes for file upload not working is a lack of CORS
support by the file server to which the file should be uploaded.
An OPTIONS request usually a so-called
CORS stands for `Cross-Origin Resource Sharing (CORS) <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`_
and is a technique for overcoming browser restrictions related to the
`same-origin security policy <https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy>`_.
For example, if the domain under which you host Converse is *example.org*,
but the domain of your of your HTTP file server (for `XEP-0363 HTTP File Upload <https://xmpp.org/extensions/xep-0363.html>`_)
is *upload.example.org*, then the HTTP file server needs to enable CORS.
If you're not sure what the domain of the HTTP file server is, take a look at
the console of your browser's developer tools.
You might see an error like this one::
Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://example.de:5443/...
You might also see a 404 HTTP response for an OPTIONS request in the `Network Tab` of your browser's developer tools.
An OPTIONS request is 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>`_.
@ -70,6 +87,11 @@ which is used by the browser to find out whether the endpoint supports
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.
This will prevent you from uploading files to it.
How you solve a CORS-related issue depends on your particular setup, specifically it depends on
what you're using as the HTTP file server.
CORS is enabled by adding an ``Access-Control-Allow-Origin`` header, so you'll
have to configure your file server to add this header.
Take a look at the section ":ref:`CORS`" for more information on how to solve this problem.