You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by dj...@apache.org on 2013/05/20 18:27:03 UTC
[2/6] git commit: updated refs/heads/1.3.x to b03809c
docs: fold section on CORS into configuration chapter
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/3c0287cc
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/3c0287cc
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/3c0287cc
Branch: refs/heads/1.3.x
Commit: 3c0287cc95e5f7d27ab1445ad494f380eae57b56
Parents: 866c8eb
Author: Dirkjan Ochtman <dj...@apache.org>
Authored: Mon May 20 18:10:48 2013 +0200
Committer: Dirkjan Ochtman <dj...@apache.org>
Committed: Mon May 20 18:10:48 2013 +0200
----------------------------------------------------------------------
share/doc/build/Makefile.am | 3 -
share/doc/src/configuring.rst | 139 ++++++++++++++++++++++++++++++++
share/doc/src/cors.rst | 153 ------------------------------------
share/doc/src/index.rst | 1 -
4 files changed, 139 insertions(+), 157 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/3c0287cc/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index ee5a4eb..fc2524a 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -57,7 +57,6 @@ 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 \
@@ -103,7 +102,6 @@ html_files = \
html/changelog.html \
html/changes.html \
html/commonjs.html \
- html/cors.html \
html/config_reference.html \
html/configuring.html \
html/ddocs.html \
@@ -148,7 +146,6 @@ src_files = \
../src/changelog.rst \
../src/changes.rst \
../src/commonjs.rst \
- ../src/cors.rst \
../src/config_reference.rst \
../src/configuring.rst \
../src/ddocs.rst \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/3c0287cc/share/doc/src/configuring.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/configuring.rst b/share/doc/src/configuring.rst
index 138bce9..245e29a 100644
--- a/share/doc/src/configuring.rst
+++ b/share/doc/src/configuring.rst
@@ -467,3 +467,142 @@ such as Lucene:
request URL to be interpreted as ``http://couchdb:5984/media``. Care
should be taken to ensure that both requested URLs and destination
URLs are able to cope.
+
+.. _cors:
+
+Cross-Origin Resource Sharing
+=============================
+
+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/>`_
http://git-wip-us.apache.org/repos/asf/couchdb/blob/3c0287cc/share/doc/src/cors.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/cors.rst b/share/doc/src/cors.rst
deleted file mode 100644
index ff85dd9..0000000
--- a/share/doc/src/cors.rst
+++ /dev/null
@@ -1,153 +0,0 @@
-.. 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/>`_
-
http://git-wip-us.apache.org/repos/asf/couchdb/blob/3c0287cc/share/doc/src/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
index 43ec938..b1c6feb 100644
--- a/share/doc/src/index.rst
+++ b/share/doc/src/index.rst
@@ -35,7 +35,6 @@ Contents
ddocs
query-servers
commonjs
- cors
errors
changes
release