From 5cf869e0f8d3a4809827baaeffc300a1bd11d214 Mon Sep 17 00:00:00 2001 From: Andre Miller Date: Tue, 20 Jan 2015 20:52:24 +0200 Subject: [PATCH] Updated web documentation for CORS --- docs/plugins/web.rst | 34 ++++++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) diff --git a/docs/plugins/web.rst b/docs/plugins/web.rst index 63c679e2b..66b7f110b 100644 --- a/docs/plugins/web.rst +++ b/docs/plugins/web.rst @@ -20,6 +20,12 @@ flask``. .. _Flask: http://flask.pocoo.org/ +If you require `CORS`_ (Cross-origin resource sharing), then you also +need `flask-cors`_. This can be installed by running ``pip install flask-cors``. + +.. _flask-cors: https://github.com/CoryDolphin/flask-cors +.. _CORS: http://en.wikipedia.org/wiki/Cross-origin_resource_sharing + Finally, enable the ``web`` plugin in your configuration (see :ref:`using-plugins`). @@ -52,10 +58,12 @@ Configuration To configure the plugin, make a ``web:`` section in your configuration file. The available options are: -- **host**: The server hostname. - Default: Bind to all interfaces. +- **host**: The server hostname. Set this to 0.0.0.0 to bind to all interfaces. + Default: Bind to 127.0.0.1. - **port**: The server port. Default: 8337. +- **cors**: The CORS origin. See below. + Default: CORS is disabled. Implementation -------------- @@ -78,6 +86,28 @@ for unsupported formats/browsers. There are a number of options for this: .. _html5media: http://html5media.info/ .. _MediaElement.js: http://mediaelementjs.com/ +Cross-origin resource sharing (CORS) +------------------------------------ + +This is only required if you intend to access the API from a browser using JavaScript and +the JavaScript is not hosted by the beets web server. + +The browser will check if the resources the JavaScript is trying to access is coming from the +same source as the the Script and give an error similar to the following: + +``XMLHttpRequest cannot load http://beets:8337/item/xx. No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://webserver' is therefore not allowed access.`` + +To prevent this, `CORS`_ is used. To enable CORS, set the ``cors`` configuration option to the origin +of your JavaScript or set it to ``'*'`` to enable access from all origins. Note that there are +security implications if you set the origin to ``'*'``, please research this before enabling it. + +For example:: + + web: + host: 0.0.0.0 + cors: 'http://webserver' + + JSON API --------