Docs: add notes on CORS functionality

5 files changed, 186 insertions, 2 deletions

diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index e06b21af7..3db9689c7 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -58,6 +58,7 @@ html_files = \
     html/_sources/changelog.txt \
     html/_sources/changes.txt \
     html/_sources/commonjs.txt \
+    html/_sources/cors.txt \
     html/_sources/config_reference.txt \
     html/_sources/configuring.txt \
     html/_sources/ddocs.txt \
@@ -109,6 +110,7 @@ html_files = \
     html/changelog.html \
     html/changes.html \
     html/commonjs.html \
+    html/cors.html \
     html/config_reference.html \
     html/configuring.html \
     html/ddocs.html \
@@ -159,6 +161,7 @@ src_files = \
     ../src/changelog.rst \
     ../src/changes.rst \
     ../src/commonjs.rst \
+    ../src/cors.rst \
     ../src/config_reference.rst \
     ../src/configuring.rst \
     ../src/ddocs.rst \
diff --git a/share/doc/src/changelog.rst b/share/doc/src/changelog.rst
index 18c19d40c..55ab00204 100644
--- a/share/doc/src/changelog.rst
+++ b/share/doc/src/changelog.rst
@@ -16,8 +16,6 @@ Apache CouchDB CHANGES
 Version 1.3.0
 -------------
 
-.. note:: This version has not been released yet.
-
 Database core
 ^^^^^^^^^^^^^
 
diff --git a/share/doc/src/config_reference.rst b/share/doc/src/config_reference.rst
index b2e78cf3b..7ae761ab9 100644
--- a/share/doc/src/config_reference.rst
+++ b/share/doc/src/config_reference.rst
@@ -50,6 +50,8 @@ Configuration Groups
 +----------------------------------+-------------------------------------------+
 | uuids                            | UUID generation options                   |
 +----------------------------------+-------------------------------------------+
+| cors                             | Cross Origin Resource Sharing settings    |
++----------------------------------+-------------------------------------------+
 
 attachments Configuration Options
 ---------------------------------
@@ -172,6 +174,8 @@ httpd Configuration Options
 +--------------------------------------+---------------------------------------+
 | vhost_global_handlers                | vhost_global_handlers                 |
 +--------------------------------------+---------------------------------------+
+| enable_cors                          | enables CORS functionality when true  |
++--------------------------------------+---------------------------------------+
 
 httpd_design_handlers Configuration Options
 -------------------------------------------
@@ -286,3 +290,28 @@ uuids Configuration Options
 +======================================+=======================================+
 | algorithm                            | algorithm                             |
 +--------------------------------------+---------------------------------------+
+
+
+cors Configuration Options
+---------------------------
+
++--------------------------------------+---------------------------------------+
+| Option                               | Description                           |
++======================================+=======================================+
+| origins                              | List of origins, separated by a comma |
+|                                      | (protocol, host, optional port)       |
++--------------------------------------+---------------------------------------+
+| methods                              | accepted HTTP methods                 |
++--------------------------------------+---------------------------------------+
+| credentials                          | `true` sends additional header        |
+|                                      | Access-Control-Allow-Credentials=true |
++--------------------------------------+---------------------------------------+
+
+Note that `credentials=true` and `origins=*` are mutually exclusive.
+
+cors vhost Configuration
+------------------------
+
+The same configuration options for `cors` overall may be applied to an
+individual vhost, within a specific section header, for `example.com` the
+appropriate section would be: `[cors:http://example.com]`
diff --git a/share/doc/src/cors.rst b/share/doc/src/cors.rst
new file mode 100644
index 000000000..ff85dd95c
--- /dev/null
+++ b/share/doc/src/cors.rst
@@ -0,0 +1,153 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. _cors:
+
+================
+Introducing CORS
+================
+
+CORS, or "Cross-origin resource sharing" allows a resource such as a web
+page running JavaScript inside a browser, to make AJAX requests
+(XMLHttpRequests) to a different domain, without compromising the security
+of either party.
+
+A typical use case is to have a static website hosted on a CDN make
+requests to another resource, such as a hosted CouchDB instance. This
+avoids needing an intermediary proxy, using JSONP or similar workarounds
+to retrieve and host content.
+
+While CouchDB's integrated HTTP server and support for document attachments
+makes this less of a constraint for pure Couch projects, there are many
+cases where separating the static content from the database access is
+desirable, and CORS makes this very straightforwards indeed.
+
+By supporting CORS functionality, a CouchDB instance can accept direct
+connections to protected DBs and instances, without the browser
+functionality being blocked due to the same origin constraint. CORS is
+widely supported today on over 90% of browsers.
+
+CORS support is provided as experimental functionality in 1.3.0, and as
+such will need to be enabled specifically in CouchDB's configuration.
+
+.. versionadded:: 1.3.0 added CORS support see JIRA :issue:`431`
+
+Features
+========
+
+-  Simple requests for a couchdb instance
+-  Preflight requests for a couchdb instance
+-  Configuration for a specific CouchDB vhost
+-  All origins are excluded by default
+
+Configuration
+=============
+
+Enabling CORS
+-------------
+
+To enable CORS support, you need to set the option
+``enable_cors = true`` in the ``[httpd]`` section of ``local.ini``, and
+``[cors]`` section with ``origins = *``. Note that by default, no
+origins are accepted, you must either use a wildcard or whitelist.
+
+.. code-block:: ini
+
+    [httpd]
+    enable_cors = true
+
+    [cors]
+    origins = *
+
+Passing Credentials
+-------------------
+
+By default, neither authentication headers nor cookies are included
+in requests and responses. To do so requires both setting
+`XmlHttpRequest.withCredentials = true` on the request object in the
+browser, and additionally enabling it within CouchDB.
+
+.. code-block:: ini
+
+    [cors]
+    credentials = true
+
+CouchDB will respond to a credentials-enabled CORS request with an
+additional header, `Access-Control-Allow-Credentials=true`.
+
+Tightening Access
+-----------------
+
+Restricting by Protocol, Host and optional Port
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: ini
+
+    [cors]
+    ; List of origins, separated by a comma (protocol, host, optional port)
+    ; refer to http://tools.ietf.org/html/rfc6454 for specification
+    origins = http://localhost, https://localhost, http://www.number10.gov.uk:80
+
+Restricting Accepted Methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Methods may be further restricted. These apply to all CORS-enabled instances.
+
+.. code-block:: ini
+
+    [cors]
+    ; List of accepted methods, comma-separated
+    ; refer to http://tools.ietf.org/html/rfc2616, rfc2817, rfc5789
+    methods = GET, POST, PUT, DELETE
+
+
+Configuration per vhost
+-----------------------
+
+All the above parameters `origins`, `methods`, `headers`, `credentials`
+may be individually configured per CouchDB vhost. For example, the
+configuration section for `http://example.com/` would be contained in:
+
+.. code-block:: ini
+
+    [cors:http://example.com]
+    credentials = false
+    origins = *
+    methods = GET, PUT, HEAD
+
+Useful References
+-----------------
+
+- Original JIRA `implementation ticket <https://issues.apache.org/jira/browse/COUCHDB-431>`_
+
+Standards and References:
+
+- IETF RFCs relating to methods `rfc2618 <http://tools.ietf.org/html/rfc2616>`_,
+  `rfc2817 <http://tools.ietf.org/html/rfc2817>`_, and
+  `rfc5789 <http://tools.ietf.org/html/rfc5789>`_.
+- IETF RFC for `Web Origins <http://tools.ietf.org/html/rfc6454>`_
+- W3C `CORS standard <http://www.w3.org/TR/cors>`_
+
+Mozilla Developer Network Resources:
+
+- `Same origin policy for URIs <https://developer.mozilla.org/en-US/docs/Same-origin_policy_for_file:_URIs>`_
+- `HTTP Access Control <https://developer.mozilla.org/En/HTTP_access_control>`_
+- `Server-side Access Control <https://developer.mozilla.org/En/Server-Side_Access_Control>`_
+- `Javascript same origin policy <https://developer.mozilla.org/en-US/docs/Same_origin_policy_for_JavaScript>`_
+
+
+Client-side CORS support and usage:
+
+- `CORS browser support matrix <http://caniuse.com/cors>`_
+- `COS tutorial <http://www.html5rocks.com/en/tutorials/cors/>`_
+- `<http://hacks.mozilla.org/2009/07/cross-site-xmlhttprequest-with-cors/>`_
+
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
index ad3a90d17..70d1b9eac 100644
--- a/share/doc/src/index.rst
+++ b/share/doc/src/index.rst
@@ -40,6 +40,7 @@ Contents
     ddocs
     query-servers
     commonjs
+    cors
     errors
     changes
     release