[Couchdb Wiki] Update of "CORS" by DaveCottlehuber

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for change notification.

The "CORS" page has been changed by DaveCottlehuber:
http://wiki.apache.org/couchdb/CORS

Comment:
getting started on documenting it

New page:
<<Include(EditTheWiki)>>

WARNING!! This page is a temporary gathering spot for CORS documentation while the [[https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=shortlog;h=refs/heads/431-feature_cors|git branch]] is in development. It will get merged back into the cors branch when sufficiently clean, and will use the sphinx support being worked on in the [[https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=shortlog;h=refs/heads/docs|docs branch]].

<<TableOfContents(2)>>

= Introducing CORS =

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 [[http://caniuse.com/cors|widely supported]] today on over 90% of browsers.

 * dev list [[http://markmail.org/message/wzdge2nb3xkaqzlk|announcement]] from @benoitc
 * JIRA [[https://issues.apache.org/jira/browse/COUCHDB-431]]

== CORS References ==

 * [[http://www.w3.org/TR/cors/#preflight-request]]
 * [[http://hacks.mozilla.org/2009/07/cross-site-xmlhttprequest-with-cors/]]
 * [[https://developer.mozilla.org/En/HTTP_access_control]]
 * [[https://developer.mozilla.org/En/Server-Side_Access_Control]]

== Client-side CORS support and usage ==

 * [[http://caniuse.com/cors]]
 * [[http://www.html5rocks.com/en/tutorials/cors/]]
 * [[http://www.kendoui.com/blogs/teamblog/posts/11-10-03/using_cors_with_all_modern_browsers.aspx]]

= Features =

 * simple requests for a couchdb instance
 * preflight requests for a couchdb instance
 * configuration for a specific CouchDB vhost
 * all origins are matched 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}}}. Note that by default, all origins will be accepted.

== Tightening Access ==

To configure defaults cors settings you need to create the [cors] section in the local.ini file:

{{{
[cors]
credentials = false
;;; List of origins separated by a comma
; origins =
;;; List of accepted headers separated by a comma
; headers =
; List of accepted methods
; methods =
}}}

To set the options for a vhosts you will need to create a section with the vhost name prefixed by "cors:" . Ex for the vhost example.com:


{{{
; Configuration for a vhost
;[cors:example.com]
; credentials = false
; List of origins separated by a comma
;origins =
; List of accepted headers separated by a comma
; headers =
; List of accepted methods
; methods =
}}}