The official documentation has moved to http://docs.couchdb.org — The transition is not 100% complete, but http://docs.couchdb.org should be seen as having the latest info. In some cases, the wiki still has some more or older info on certain topics inside CouchDB.

You need to be added to the ContributorsGroup to edit the wiki. But don't worry! Just email any Mailing List or grab us on IRC and let us know your user name.

Note: CORS is supported only in CouchDB 1.3.x branches or releases, and at present is experimental support. This means that:

functionality is disabled by default
support or API may change in subsequent releases

WARNING!! This page is a temporary gathering spot for CORS documentation while the 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 docs branch.

Contents

Introducing CORS
Features
Configuration
Testing Your Implementation
Reference Material
1. CORS References
2. Client-side CORS support and usage

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 widely supported today on over 90% of browsers.

dev list announcement from @benoitc
JIRA https://issues.apache.org/jira/browse/COUCHDB-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.

[httpd]
enable_cors = true

[cors]
origins = *

Tightening Access

Restricting by Protocol, Host and optional Port

[cors]
; List of origins, separated by a comma (protocol, host, port)
; refer to http://tools.ietf.org/html/rfc6454 for specification
origins = http://home.muse.net.nz:8000, https://localhost, http://www.number10.gov.uk:80

Restricting Accepted Methods

[cors]
; List of accepted methods, comma-separated
; refer to http://tools.ietf.org/html/rfc2616, rfc2817, rfc5789
methods = GET, POST, PUT, DELETE

Restricting Accepted Headers

[cors]
; List of accepted headers separated by a comma
headers = TODO

Securing at the VHOST level

TODO

To set the options for a vhost, 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 =

Credentials

TODO

Testing Your Implementation

The following snippet was lifted from html5rocks CORS tutorial:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Testing CORS</title>
    <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.8.2/jquery.min.js"></script>
    <meta author="http://www.html5rocks.com/en/tutorials/cors/#toc-adding-cors-support-to-the-server">
    <meta license="Apache 2.0">
    <script>
      
      // Create the XHR object.
      function createCORSRequest(method, url) {
        var xhr = new XMLHttpRequest();
        if ("withCredentials" in xhr) {
          // XHR for Chrome/Firefox/Opera/Safari.
          xhr.open(method, url, true);
        } else if (typeof XDomainRequest != "undefined") {
          // XDomainRequest for IE.
          xhr = new XDomainRequest();
          xhr.open(method, url);
        } else {
          // CORS not supported.
          xhr = null;
        }
        return xhr;
      }

      // Make the actual CORS request.
      function makeCorsRequest(uri) {
        console.log("got uri: " + uri);
        var xhr = createCORSRequest('GET', uri);
        if (!xhr) {
          alert('CORS not supported');
          return;
        }

        // Response handlers.
        xhr.onload = function() {
          console.log('Response from CORS request to ' + uri + ': ' + xhr.responseText);
        };

        xhr.onerror = function() {
          console.log('Woops, there was an error making the request to ' + uri + '.');
        };

        xhr.send();
      }
      
      $(document).ready(function() {
        makeCorsRequest('http://my.couchdb.org:5984/');
        });
  </script>
  </head>
  <body>
  </body>
</html>

Reference Material

This image is from the excellent html5rocks CORS tutorial.

CORS References

Client-side CORS support and usage

http://caniuse.com/cors covers browser support
http://www.html5rocks.com/en/tutorials/cors/ has a nice example
http://www.kendoui.com/blogs/teamblog/posts/11-10-03/using_cors_with_all_modern_browsers.aspx

Note that at least IE >= 8 does not support pre-flight.