From a82f6c2d76abd41983a1b92026a0a5be0d6d76c7 Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Tue, 20 Jan 2015 14:10:33 -0800 Subject: [PATCH] Docs tweaks and changelog for #1237, fix #1236 --- docs/changelog.rst | 3 +++ docs/plugins/web.rst | 28 +++++++++++++++------------- 2 files changed, 18 insertions(+), 13 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index 2827b1404..374f48b46 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -13,6 +13,9 @@ Features: * :doc:`/plugins/lastgenre`: Add *comedy*, *humor*, and *stand-up* as well as a longer list of classical music genre tags to the built-in whitelist and canonicalization tree. :bug:`1206` :bug:`1239` :bug:`1240` +* :doc:`/plugins/web`: Add support for *cross-origin resource sharing* for + more flexible in-browser clients. Thanks to Andre Miller. :bug:`1236` + :bug:`1237` Fixes: diff --git a/docs/plugins/web.rst b/docs/plugins/web.rst index 66b7f110b..70ed37274 100644 --- a/docs/plugins/web.rst +++ b/docs/plugins/web.rst @@ -62,7 +62,7 @@ configuration file. The available options are: Default: Bind to 127.0.0.1. - **port**: The server port. Default: 8337. -- **cors**: The CORS origin. See below. +- **cors**: The CORS allowed origin (see :ref:`web-cors`, below). Default: CORS is disabled. Implementation @@ -86,26 +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) +.. _web-cors: + +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 ``web`` plugin's API can be used as a backend for an in-browser client. By +default, browsers will only allow access from clients running on the same +server as the API. (You will get an arcane error about ``XMLHttpRequest`` +otherwise.) A technology called `CORS`_ lets you relax this restriction. -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. +If you want to use an in-browser client hosted elsewhere (or running from +a different server on your machine), set the ``cors`` configuration option to +the "origin" (protocol, host, and optional port number) where the client is +served. Or set it to ``'*'`` to enable access from all origins. Note that +there are security implications if you set the origin to ``'*'``, so please +research this before using it. For example:: web: host: 0.0.0.0 - cors: 'http://webserver' + cors: 'http://example.com' JSON API