You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by dc...@apache.org on 2012/12/03 14:33:19 UTC
[20/33] Transmogrify Couchbase XML to .rst and support Sphinx
http://git-wip-us.apache.org/repos/asf/couchdb/blob/49d66c4b/share/doc/src/json-structure.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/json-structure.rst b/share/doc/src/json-structure.rst
new file mode 100644
index 0000000..aaba09e
--- /dev/null
+++ b/share/doc/src/json-structure.rst
@@ -0,0 +1,658 @@
+.. 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.
+
+========================
+JSON Structure Reference
+========================
+
+The following appendix provides a quick reference to all the JSON structures
+that you can supply to CouchDB, or get in return to requests.
+
+All Database Documents
+======================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| total_rows | Number of documents in the database/view |
++--------------------------------+---------------------------------------------+
+| offset | Offset where the document list started |
++--------------------------------+---------------------------------------------+
+| update_seq (optional) | Current update sequence for the database |
++--------------------------------+---------------------------------------------+
+| rows [array] | Array of document object |
++--------------------------------+---------------------------------------------+
+
+Bulk Document Response
+======================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| docs [array] | Bulk Docs Returned Documents |
++--------------------------------+---------------------------------------------+
+| id | Document ID |
++--------------------------------+---------------------------------------------+
+| error | Error type |
++--------------------------------+---------------------------------------------+
+| reason | Error string with extended reason |
++--------------------------------+---------------------------------------------+
+
+Bulk Documents
+==============
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| all_or_nothing (optional) | Sets the database commit mode to use |
+| | all-or-nothing semantics |
++--------------------------------+---------------------------------------------+
+| docs [array] | Bulk Documents Document |
++--------------------------------+---------------------------------------------+
+| _id (optional) | Document ID |
++--------------------------------+---------------------------------------------+
+| _rev (optional) | Revision ID (when updating an existing |
+| | document) |
++--------------------------------+---------------------------------------------+
+| _deleted (optional) | Whether the document should be deleted |
++--------------------------------+---------------------------------------------+
+
+Changes information for a database
+==================================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| last_seq | Last change sequence number |
++--------------------------------+---------------------------------------------+
+| results [array] | Changes made to a database |
++--------------------------------+---------------------------------------------+
+| seq | Update sequence number |
++--------------------------------+---------------------------------------------+
+| id | Document ID |
++--------------------------------+---------------------------------------------+
+| changes [array] | List of changes, field-by-field, for this |
+| | document |
++--------------------------------+---------------------------------------------+
+
+CouchDB Document
+================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| _id (optional) | Document ID |
++--------------------------------+---------------------------------------------+
+| _rev (optional) | Revision ID (when updating an existing |
+| | document) |
++--------------------------------+---------------------------------------------+
+
+CouchDB Error Status
+====================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| id | Document ID |
++--------------------------------+---------------------------------------------+
+| error | Error type |
++--------------------------------+---------------------------------------------+
+| reason | Error string with extended reason |
++--------------------------------+---------------------------------------------+
+
+.. _dbinfo_object:
+
+CouchDB database information object
+===================================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| db_name | The name of the database. |
++--------------------------------+---------------------------------------------+
+| committed_update_seq | The number of committed update. |
++--------------------------------+---------------------------------------------+
+| doc_count | A count of the documents in the specified |
+| | database. |
++--------------------------------+---------------------------------------------+
+| doc_del_count | Number of deleted documents |
++--------------------------------+---------------------------------------------+
+| compact_running | Set to true if the database compaction |
+| | routine is operating on this database. |
++--------------------------------+---------------------------------------------+
+| disk_format_version | The version of the physical format used for |
+| | the data when it is stored on disk. |
++--------------------------------+---------------------------------------------+
+| disk_size | Size in bytes of the data as stored on the |
+| | disk. Views indexes are not included in the |
+| | calculation. |
++--------------------------------+---------------------------------------------+
+| instance_start_time | Timestamp of when the database was created, |
+| | expressed in milliseconds since the epoch. |
++--------------------------------+---------------------------------------------+
+| purge_seq | The number of purge operations on the |
+| | database. |
++--------------------------------+---------------------------------------------+
+| update_seq | The current number of updates to the |
+| | database. |
++--------------------------------+---------------------------------------------+
+
+Design Document
+===============
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| _id | Design Document ID |
++--------------------------------+---------------------------------------------+
+| _rev | Design Document Revision |
++--------------------------------+---------------------------------------------+
+| views | View |
++--------------------------------+---------------------------------------------+
+| viewname | View Definition |
++--------------------------------+---------------------------------------------+
+| map | Map Function for View |
++--------------------------------+---------------------------------------------+
+| reduce (optional) | Reduce Function for View |
++--------------------------------+---------------------------------------------+
+
+Design Document Information
+===========================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| name | Name/ID of Design Document |
++--------------------------------+---------------------------------------------+
+| view_index | View Index |
++--------------------------------+---------------------------------------------+
+| compact_running | Indicates whether a compaction routine is |
+| | currently running on the view |
++--------------------------------+---------------------------------------------+
+| disk_size | Size in bytes of the view as stored on disk |
++--------------------------------+---------------------------------------------+
+| language | Language for the defined views |
++--------------------------------+---------------------------------------------+
+| purge_seq | The purge sequence that has been processed |
++--------------------------------+---------------------------------------------+
+| signature | MD5 signature of the views for the design |
+| | document |
++--------------------------------+---------------------------------------------+
+| update_seq | The update sequence of the corresponding |
+| | database that has been indexed |
++--------------------------------+---------------------------------------------+
+| updater_running | Indicates if the view is currently being |
+| | updated |
++--------------------------------+---------------------------------------------+
+| waiting_clients | Number of clients waiting on views from this|
+| | design document |
++--------------------------------+---------------------------------------------+
+| waiting_commit | Indicates if there are outstanding commits |
+| | to the underlying database that need to |
+| | processed |
++--------------------------------+---------------------------------------------+
+
+Design Document spatial index Information
+=========================================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| name | Name/ID of Design Document |
++--------------------------------+---------------------------------------------+
+| spatial_index | View Index |
++--------------------------------+---------------------------------------------+
+| compact_running | Indicates whether a compaction routine is |
+| | currently running on the view |
++--------------------------------+---------------------------------------------+
+| disk_size | Size in bytes of the view as stored on disk |
++--------------------------------+---------------------------------------------+
+| language | Language for the defined views |
++--------------------------------+---------------------------------------------+
+| purge_seq | The purge sequence that has been processed |
++--------------------------------+---------------------------------------------+
+| signature | MD5 signature of the views for the design |
+| | document |
++--------------------------------+---------------------------------------------+
+| update_seq | The update sequence of the corresponding |
+| | database that has been indexed |
++--------------------------------+---------------------------------------------+
+| updater_running | Indicates if the view is currently being |
+| | updated |
++--------------------------------+---------------------------------------------+
+| waiting_clients | Number of clients waiting on views from this|
+| | design document |
++--------------------------------+---------------------------------------------+
+| waiting_commit | Indicates if there are outstanding commits |
+| | to the underlying database that need to |
+| | processed |
++--------------------------------+---------------------------------------------+
+
+Document with Attachments
+=========================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| _id (optional) | Document ID |
++--------------------------------+---------------------------------------------+
+| _rev (optional) | Revision ID (when updating an existing |
+| | document) |
++--------------------------------+---------------------------------------------+
+| _attachments (optional) | Document Attachment |
++--------------------------------+---------------------------------------------+
+| filename | Attachment information |
++--------------------------------+---------------------------------------------+
+| content_type | MIME Content type string |
++--------------------------------+---------------------------------------------+
+| data | File attachment content, Base64 encoded |
++--------------------------------+---------------------------------------------+
+
+List of Active Tasks
+====================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| tasks [array] | Active Task |
++--------------------------------+---------------------------------------------+
+| pid | Process ID |
++--------------------------------+---------------------------------------------+
+| status | Task status message |
++--------------------------------+---------------------------------------------+
+| task | Task name |
++--------------------------------+---------------------------------------------+
+| type | Operation Type |
++--------------------------------+---------------------------------------------+
+
+Replication Settings
+====================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| source | Source database name or URL |
++--------------------------------+---------------------------------------------+
+| target | Target database name or URL |
++--------------------------------+---------------------------------------------+
+| create_target (optional) | Creates the target database |
++--------------------------------+---------------------------------------------+
+| continuous (optional) | Configure the replication to be continuous |
++--------------------------------+---------------------------------------------+
+| cancel (optional) | Cancels the replication |
++--------------------------------+---------------------------------------------+
+| doc_ids (optional) | Array of document IDs to be synchronized |
++--------------------------------+---------------------------------------------+
+| proxy (optional) | Address of a proxy server through which |
+| | replication should occur |
++--------------------------------+---------------------------------------------+
+
+Replication Status
+==================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| ok | Replication status |
++--------------------------------+---------------------------------------------+
+| session_id | Unique session ID |
++--------------------------------+---------------------------------------------+
+| source_last_seq | Last sequence number read from source |
+| | database |
++--------------------------------+---------------------------------------------+
+| history [array] | Replication History |
++--------------------------------+---------------------------------------------+
+| session_id | Session ID for this replication operation |
++--------------------------------+---------------------------------------------+
+| recorded_seq | Last recorded sequence number |
++--------------------------------+---------------------------------------------+
+| docs_read | Number of documents read |
++--------------------------------+---------------------------------------------+
+| docs_written | Number of documents written to target |
++--------------------------------+---------------------------------------------+
+| doc_write_failures | Number of document write failures |
++--------------------------------+---------------------------------------------+
+| start_time | Date/Time replication operation started |
++--------------------------------+---------------------------------------------+
+| start_last_seq | First sequence number in changes stream |
++--------------------------------+---------------------------------------------+
+| end_time | Date/Time replication operation completed |
++--------------------------------+---------------------------------------------+
+| end_last_seq | Last sequence number in changes stream |
++--------------------------------+---------------------------------------------+
+| missing_checked | Number of missing documents checked |
++--------------------------------+---------------------------------------------+
+| missing_found | Number of missing documents found |
++--------------------------------+---------------------------------------------+
+
+.. _request_object:
+
+Request object
+==============
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| body | Request body data as `string`. |
+| | If request method is `GET` method contains |
+| | this field contains ``"undefined"`` value, |
+| | while if `DELETE` or `HEAD` value is ``""`` |
+| | (empty string) |
++--------------------------------+---------------------------------------------+
+| cookie | Cookies `object`. |
++--------------------------------+---------------------------------------------+
+| form | Form data `object`. |
+| | Contains decoded body as key-value pairs if |
+| | `Content-Type` header was |
+| | ``application/x-www-form-urlencoded``. |
++--------------------------------+---------------------------------------------+
+| headers | Request headers `object`. |
++--------------------------------+---------------------------------------------+
+| id | Requested document id `string` if it was |
+| | specified or ``null`` otherwise. |
++--------------------------------+---------------------------------------------+
+| info | :ref:`Database information <dbinfo_object>` |
++--------------------------------+---------------------------------------------+
+| method | Request method as `string` or `array`. |
+| | String value is method is one of: `HEAD`, |
+| | `GET`, `POST`, `PUT`, `DELETE`, `OPTIONS`, |
+| | and `TRACE`, otherwise it will be |
+| | represented as array of char codes. |
++--------------------------------+---------------------------------------------+
+| path | List of requested path sections. |
++--------------------------------+---------------------------------------------+
+| peer | Request source IP address. |
++--------------------------------+---------------------------------------------+
+| query | URL query parameters `object`. |
+| | Note that multiple keys not supported and |
+| | last key value suppress others. |
++--------------------------------+---------------------------------------------+
+| requested_path | List of actual requested path section. |
++--------------------------------+---------------------------------------------+
+| raw_path | Raw requested path `string`. |
++--------------------------------+---------------------------------------------+
+| secObj | :ref:`security_object`. |
++--------------------------------+---------------------------------------------+
+| userCtx | :ref:`userctx_object`. |
++--------------------------------+---------------------------------------------+
+| uuid | Generated UUID by specified algorithm in |
+| | config file. |
++--------------------------------+---------------------------------------------+
+
+.. code-block:: javascript
+
+ {
+ "body": "undefined",
+ "cookie": {
+ "AuthSession": "cm9vdDo1MDZBRjQzRjrfcuikzPRfAn-EA37FmjyfM8G8Lw",
+ "m": "3234"
+ },
+ "form": {},
+ "headers": {
+ "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+ "Accept-Charset": "ISO-8859-1,utf-8;q=0.7,*;q=0.3",
+ "Accept-Encoding": "gzip,deflate,sdch",
+ "Accept-Language": "en-US,en;q=0.8",
+ "Connection": "keep-alive",
+ "Cookie": "m=3234:t|3247:t|6493:t|6967:t|34e2:|18c3:t|2c69:t|5acb:t|ca3:t|c01:t|5e55:t|77cb:t|2a03:t|1d98:t|47ba:t|64b8:t|4a01:t; AuthSession=cm9vdDo1MDZBRjQzRjrfcuikzPRfAn-EA37FmjyfM8G8Lw",
+ "Host": "127.0.0.1:5984",
+ "User-Agent": "Mozilla/5.0 (Windows NT 5.2) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.75 Safari/535.7"
+ },
+ "id": "foo",
+ "info": {
+ "committed_update_seq": 2701412,
+ "compact_running": false,
+ "data_size": 7580843252,
+ "db_name": "mailbox",
+ "disk_format_version": 6,
+ "disk_size": 14325313673,
+ "doc_count": 2262757,
+ "doc_del_count": 560,
+ "instance_start_time": "1347601025628957",
+ "purge_seq": 0,
+ "update_seq": 2701412
+ },
+ "method": "GET",
+ "path": [
+ "mailbox",
+ "_design",
+ "request",
+ "_show",
+ "dump",
+ "foo"
+ ],
+ "peer": "127.0.0.1",
+ "query": {},
+ "raw_path": "/mailbox/_design/request/_show/dump/foo",
+ "requested_path": [
+ "mailbox",
+ "_design",
+ "request",
+ "_show",
+ "dump",
+ "foo"
+ ],
+ "secObj": {
+ "admins": {
+ "names": [
+ "Bob"
+ ],
+ "roles": []
+ },
+ "members": {
+ "names": [
+ "Mike",
+ "Alice"
+ ],
+ "roles": []
+ }
+ },
+ "userCtx": {
+ "db": "mailbox",
+ "name": "Mike",
+ "roles": [
+ "user"
+ ]
+ },
+ "uuid": "3184f9d1ea934e1f81a24c71bde5c168"
+ }
+
+
+.. _response_object:
+
+Response object
+===============
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| code | HTTP status code `number`. |
++--------------------------------+---------------------------------------------+
+| json | JSON encodable `object`. |
+| | Implicitly sets `Content-Type` header as |
+| | ``application/json``. |
++--------------------------------+---------------------------------------------+
+| body | Raw response text `string`. |
+| | Implicitly sets `Content-Type` header as |
+| | ``text/html; charset=utf-8``. |
++--------------------------------+---------------------------------------------+
+| base64 | Base64 encoded `string`. |
+| | Implicitly sets `Content-Type` header as |
+| | ``application/binary``. |
++--------------------------------+---------------------------------------------+
+| headers | Response headers `object`. |
+| | `Content-Type` header from this object |
+| | overrides any implicitly assigned one. |
++--------------------------------+---------------------------------------------+
+| stop | `boolean` signal to stop iteration over |
+| | view result rows (for list functions only) |
++--------------------------------+---------------------------------------------+
+
+.. warning::
+ ``body``, ``base64`` and ``json`` object keys are overlaps each other and
+ the last wins. Since most realizations of key-value objects doesn't preserve
+ key order mixing them may create confusing situation. Try to use only one of
+ them.
+
+.. note::
+ Any custom property makes CouchDB raise internal exception.
+ Also `Response object` could be a simple string value which would be
+ implicitly wrapped into ``{"body": ...}`` object.
+
+
+Returned CouchDB Document with Detailed Revision Info
+=====================================================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| _id (optional) | Document ID |
++--------------------------------+---------------------------------------------+
+| _rev (optional) | Revision ID (when updating an existing |
+| | document) |
++--------------------------------+---------------------------------------------+
+| _revs_info [array] | CouchDB Document Extended Revision Info |
++--------------------------------+---------------------------------------------+
+| rev | Full revision string |
++--------------------------------+---------------------------------------------+
+| status | Status of the revision |
++--------------------------------+---------------------------------------------+
+
+Returned CouchDB Document with Revision Info
+============================================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| _id (optional) | Document ID |
++--------------------------------+---------------------------------------------+
+| _rev (optional) | Revision ID (when updating an existing |
+| | document) |
++--------------------------------+---------------------------------------------+
+| _revisions | CouchDB Document Revisions |
++--------------------------------+---------------------------------------------+
+| ids [array] | Array of valid revision IDs, in reverse |
+| | order (latest first) |
++--------------------------------+---------------------------------------------+
+| start | Prefix number for the latest revision |
++--------------------------------+---------------------------------------------+
+
+Returned Document with Attachments
+==================================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| _id (optional) | Document ID |
++--------------------------------+---------------------------------------------+
+| _rev (optional) | Revision ID (when updating an existing |
+| | document) |
++--------------------------------+---------------------------------------------+
+| _attachments (optional) | Document Attachment |
++--------------------------------+---------------------------------------------+
+| filename | Attachment |
++--------------------------------+---------------------------------------------+
+| stub | Indicates whether the attachment is a stub |
++--------------------------------+---------------------------------------------+
+| content_type | MIME Content type string |
++--------------------------------+---------------------------------------------+
+| length | Length (bytes) of the attachment data |
++--------------------------------+---------------------------------------------+
+| revpos | Revision where this attachment exists |
++--------------------------------+---------------------------------------------+
+
+.. _security_object:
+
+Security Object
+===============
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| admins | Roles/Users with admin privileges |
++--------------------------------+---------------------------------------------+
+| roles [array] | List of roles with parent privilege |
++--------------------------------+---------------------------------------------+
+| users [array] | List of users with parent privilege |
++--------------------------------+---------------------------------------------+
+| readers | Roles/Users with reader privileges |
++--------------------------------+---------------------------------------------+
+| roles [array] | List of roles with parent privilege |
++--------------------------------+---------------------------------------------+
+| users [array] | List of users with parent privilege |
++--------------------------------+---------------------------------------------+
+
+.. code-block:: javascript
+
+ {
+ "admins": {
+ "names": [
+ "Bob"
+ ],
+ "roles": []
+ },
+ "members": {
+ "names": [
+ "Mike",
+ "Alice"
+ ],
+ "roles": []
+ }
+ }
+
+
+.. _userctx_object:
+
+User Context Object
+===================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| db | Database name in context of provided |
+| | operation. |
++--------------------------------+---------------------------------------------+
+| name | User name. |
++--------------------------------+---------------------------------------------+
+| roles | List of user roles. |
++--------------------------------+---------------------------------------------+
+
+.. code-block:: javascript
+
+ {
+ "db": "mailbox",
+ "name": null,
+ "roles": [
+ "_admin"
+ ]
+ }
+
+
+.. _view_head_info_object:
+
+View Head Information
+=====================
+
++--------------------------------+---------------------------------------------+
+| Field | Description |
++================================+=============================================+
+| total_rows | Number of documents in the view |
++--------------------------------+---------------------------------------------+
+| offset | Offset where the document list started |
++--------------------------------+---------------------------------------------+
+
+.. code-block:: javascript
+
+ {
+ "total_rows": 42,
+ "offset": 3
+ }
http://git-wip-us.apache.org/repos/asf/couchdb/blob/49d66c4b/share/doc/src/os-daemons.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/os-daemons.rst b/share/doc/src/os-daemons.rst
new file mode 100644
index 0000000..5ff850c
--- /dev/null
+++ b/share/doc/src/os-daemons.rst
@@ -0,0 +1,50 @@
+.. 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.
+
+OS Daemons
+==========
+
+CouchDB now supports starting external processes. The support is simple
+and enables CouchDB to start each configured OS daemon. If the daemon
+stops at any point, CouchDB will restart it (with protection to ensure
+regularly failing daemons are not repeatedly restarted).
+
+The daemon starting process is one-to-one; for each each configured
+daemon in the configuration file, CouchDB will start exactly one
+instance. If you need to run multiple instances, then you must create
+separate individual configurations. Daemons are configured within the
+``[os_daemons]`` section of your configuration file (``local.ini``). The
+format of each configured daemon is:
+
+.. code-block:: ini
+
+ NAME = PATH ARGS
+
+Where ``NAME`` is an arbitrary (and unique) name to identify the daemon;
+``PATH`` is the full path to the daemon to be executed; ``ARGS`` are any
+required arguments to the daemon.
+
+For example:
+
+.. code-block:: ini
+
+ [os_daemons]
+ basic_responder = /usr/local/bin/responder.js
+
+There is no interactivity between CouchDB and the running process, but
+you can use the OS Daemons service to create new HTTP servers and
+responders and then use the new proxy service to redirect requests and
+output to the CouchDB managed service. For more information on proxying,
+see :ref:`http-proxying`. For further background on the OS Daemon service, see
+`CouchDB Externals API`_.
+
+.. _CouchDB Externals API: http://davispj.com/2010/09/26/new-couchdb-externals-api.html
http://git-wip-us.apache.org/repos/asf/couchdb/blob/49d66c4b/share/doc/src/pretty_urls.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/pretty_urls.rst b/share/doc/src/pretty_urls.rst
new file mode 100644
index 0000000..9f2bdc2
--- /dev/null
+++ b/share/doc/src/pretty_urls.rst
@@ -0,0 +1,136 @@
+.. 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.
+
+.. _pretty_urls:
+
+===========
+Pretty URLs
+===========
+
+CouchDB incorporates a straightforwards URL routing and rewriting engine.
+While it is not as comprehensive as a front-end proxy, it caters for most
+needs out of the box, including using virtual hostnames to map URLs to
+specific databases, and provides more complex use cases through a rewriting
+engine.
+
+This `post
+<http://blog.couchbase.com/what%E2%80%99s-new-apache-couchdb-011-%E2%80%94-part-one-nice-urls-rewrite-rules-and-virtual-hosts>`_ has a detailed example of a combined vhost and rewriter configuration.
+
+Virtual Hosts
+=============
+
+CouchDB, since 0.11.0, can map requests to different locations based on
+the ``Host`` header, even if they arrive on the some inbound IP address.
+
+This allows different virtual hosts on the same machine to map to different
+databases or design documents, etc. The most common use case is to map a
+virtual host to a Rewrite Handler, to provide full control over the
+application's URIs.
+
+To add a virtual host, add a CNAME pointer to the DNS for your domain
+name. For development and testing, it is sufficient to add an entry in
+the hosts file, typically `/etc/hosts`` on Unix-like operating systems:
+
+.. code-block:: bash
+
+ # CouchDB vhost definitions, refer to local.ini for further details
+ 127.0.0.1 sofa.couchdb
+
+Test that this is working:
+
+.. code-block:: bash
+
+ $ ping sofa.couchdb
+ PING sofa.couchdb (127.0.0.1) 56(84) bytes of data.
+ 64 bytes from localhost.localdomain (127.0.0.1): icmp_req=1 ttl=64 time=0.025 ms
+ 64 bytes from localhost.localdomain (127.0.0.1): icmp_req=2 ttl=64 time=0.051 ms
+ ^C
+
+Finally, add an entry to your :ref:`configuration file <configuring>` in the ``[vhosts]``
+section:
+
+.. code-block:: ini
+
+ [vhosts]
+ sofa.couchdb:5984 = /sofa/_design/sofa/_rewrite
+
+If your CouchDB is listening on the default HTTP port, or is sitting
+behind a proxy, then don't specify a port number in the vhost key.
+
+With the above setup, a request to ``http://sofa.couchdb:5984/sweet-o``
+will be mapped to
+``http://127.0.0.1:5984/sofa/_design/sofa/_rewrite/sweet-o``
+
+.. versionadded:: 0.11.0 added `vhosts` functionality
+
+HTTP Rewrite Handler
+====================
+
+Following on from `virtual hosts`_, CouchDB includes a custom URL rewriter.
+All rewriting is done from ``/dbname/_design/ddocname/_rewrite`` by default.
+
+The rewriter is flexible, and can handle methods and custom query formats.
+
+Each rule should be in the ``rewrites`` top-level key of the design doc.
+Example of a complete rule :
+
+.. code-block:: json
+
+ {
+ ....
+ "rewrites": [
+ {
+ "from": "",
+ "to": "index.html",
+ "method": "GET",
+ "query": {}
+ }
+ ]
+ }
+
+
+**from**: is the path rule used to bind current uri to the rule. It
+uses pattern matching for that.
+
+**to**: rule to rewrite an url. It can contain variables depending on
+binding variables discovered during pattern matching and query args
+(url args and from the query member.)
+
+**method**: method to bind the request method to the rule. If method
+is missing, any method will be matched in the rewrite.
+
+**query**: optional query arguments, that may contain dynamic variables,
+by binding keys in the to be used with the matching URL.
+
+``to`` and ``from`` are paths with patterns. The pattern can be strings starting
+with ``:`` or ``*``, for example ``/somepath/:var/*``.
+
+The pattern matching is done by first matching the request method to a
+rule. Then it will try to match the path to one specific rule. If no rule
+match, then a 404 error is displayed.
+
+The path is converted into an erlang list, by regex splitting on ``/``. Each
+variable is converted into an atom. The subsequent pattern matching step is
+done by splitting ``/`` in the request url into a list of atoms. A string
+pattern will match the equivalent token. The ``*`` atom will match any number
+of tokens, but may only be present as the last pattern in the path. If all
+tokens are matched, and all path terms have been consumed, then the overall
+path specification matches.
+
+Once a matching ``from`` rule is found we rewrite the request url using the
+``from``, ``to``, and ``query`` members. Each identified token will be reused
+within the rule, and in the subsequent query if required. The identified
+tokens are matched to the rule and will replace var. If ``*`` is found in
+the rule it will contain any remaining suffix.
+
+The rewriter is re-entrant, and has a configurable recursion limit, set
+by default at 100.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/49d66c4b/share/doc/src/query-servers.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/query-servers.rst b/share/doc/src/query-servers.rst
new file mode 100644
index 0000000..e77abd7
--- /dev/null
+++ b/share/doc/src/query-servers.rst
@@ -0,0 +1,481 @@
+.. 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.
+
+.. default-domain:: js
+
+=============
+Query servers
+=============
+
+.. _queryserver_js:
+
+JavaScript
+==========
+
+.. note:: While every design function has access to all JavaScript objects,
+ the table below describes appropriate usage cases. For example,
+ you may use :func:`emit` in :ref:`listfun`, but :func:`getRow` is not permitted during :ref:`mapfun`.
+
++--------------------------------+---------------------------------------------+
+| JS Function | Reasonable to use in design doc functions |
++================================+=============================================+
+| :func:`emit` | :ref:`mapfun` |
++--------------------------------+---------------------------------------------+
+| :func:`getRow` | :ref:`listfun` |
++--------------------------------+---------------------------------------------+
+| :data:`JSON` | any |
++--------------------------------+---------------------------------------------+
+| :func:`isArray` | any |
++--------------------------------+---------------------------------------------+
+| :func:`log` | any |
++--------------------------------+---------------------------------------------+
+| :func:`provides` | :ref:`showfun`, :ref:`listfun` |
++--------------------------------+---------------------------------------------+
+| :func:`registerType` | :ref:`showfun`, :ref:`listfun` |
++--------------------------------+---------------------------------------------+
+| :func:`require` | every except :ref:`reducefun` |
++--------------------------------+---------------------------------------------+
+| :func:`send` | :ref:`listfun` |
++--------------------------------+---------------------------------------------+
+| :func:`start` | :ref:`listfun` |
++--------------------------------+---------------------------------------------+
+| :func:`sum` | any |
++--------------------------------+---------------------------------------------+
+| :func:`toJSON` | any |
++--------------------------------+---------------------------------------------+
+
+Design functions context
+------------------------
+
+Each design function executes within special context of predefined objects,
+modules and functions:
+
+
+.. function:: emit(key, value)
+
+ Puts `key`-`value` pair into inner stack for further passing to CouchDB
+ when map function is done.
+
+ :param key: View's key.
+ :param value: Associated value with `key`.
+
+ .. code-block:: javascript
+
+ function(doc){
+ emit(doc._id, doc._rev);
+ }
+
+
+.. function:: getRow()
+
+ Extracts next row from the related view result.
+
+ :return: View result row
+ :rtype: object
+
+ .. code-block:: javascript
+
+ function(head, req){
+ send('[');
+ row = getRow();
+ if (row){
+ send(toJSON(row));
+ while(row = getRow()){
+ send(',');
+ send(toJSON(row));
+ }
+ }
+ return ']';
+ }
+
+
+.. data:: JSON
+
+ `JSON2 <https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob;f=share/server/json2.js>`_
+ object.
+
+
+.. function:: isArray(obj)
+
+ Helper to check is provided value `array` or not
+
+ :param obj: Any Javascript value
+ :return: ``true`` is `obj` is `array` typed, ``false`` otherwise.
+ :rtype: boolean
+
+
+.. function:: log(message)
+
+ :param message: Message to log in at CouchDB `INFO` level.
+
+ .. code-block:: javascript
+
+ function(doc){
+ log('Procesing doc ' + doc['_id']);
+ emit(doc['_id'], null);
+ }
+
+ On map function run in CouchDB logs (e.g. at `/var/log/couchdb/couch.log`)
+ you may find next record:
+
+ .. code-block:: text
+
+ [Sat, 03 Nov 2012 17:38:02 GMT] [info] [<0.7543.0>] OS Process #Port<0.3289> Log :: Processing doc 8d300b86622d67953d102165dbe99467
+
+
+.. function:: provides(key, func)
+
+ Registers callable handler for specified MIME key.
+
+ :param key: MIME key previously defined by :func:`registerType`
+ :param func: MIME type handler.
+
+
+.. function:: registerType(key, *mimes)
+
+ Registers list of MIME types by associated `key`.
+
+ :param key: MIME types
+ :param mimes: MIME types enumeration.
+
+ Predefined mappings (`key`-`array`):
+
+ - **all**: ``*/*``
+ - **text**: ``text/plain; charset=utf-8``, ``txt``
+ - **html**: ``text/html; charset=utf-8``
+ - **xhtml**: ``application/xhtml+xml``, ``xhtml``
+ - **xml**: ``application/xml``, ``text/xml``, ``application/x-xml``
+ - **js**: ``text/javascript``, ``application/javascript``,
+ ``application/x-javascript``
+ - **css**: ``text/css``
+ - **ics**: ``text/calendar``
+ - **csv**: ``text/csv``
+ - **rss**: ``application/rss+xml``
+ - **atom**: ``application/atom+xml``
+ - **yaml**: ``application/x-yaml``, ``text/yaml``
+ - **multipart_form**: ``multipart/form-data``
+ - **url_encoded_form**: ``application/x-www-form-urlencoded``
+ - **json**: ``application/json``, ``text/x-json``
+
+
+.. function:: require(path)
+
+ Loads CommonJS module by specified `path`. Path shouldn't starts with slash.
+
+ :param path: CommonJS module path started from design document root.
+ :return: Exported statements.
+
+
+.. function:: send(chunk)
+
+ Sends a single string `chunk` in response.
+
+ :param chunk: Text chunk
+
+ .. code-block:: javascript
+
+ function(head, req){
+ send('Hello,');
+ send(' ');
+ send('Couch');
+ return !
+ }
+
+
+.. function:: start(init_resp)
+
+ Initiates chunked response. As an option, custom
+ :ref:`response <response_object>` object may be sent at this point.
+ For `list`-functions only!
+
+ .. note::
+
+ Only at this point list functions may set response `HTTP code` and
+ `headers`. Also, you need to run this function before :func:`send`,
+ :func:`getRow` or `return` statement or query server will implicitly call
+ this function with empty object (``{}``).
+
+ .. code-block:: javascript
+
+ function(head, req){
+ start({
+ "code": 302,
+ "headers": {
+ "Location": "http://couchdb.apache.org"
+ }
+ });
+ return "Relax!";
+ }
+
+
+.. function:: sum(arr)
+
+ Summarize `arr` items.
+
+ :param arr: Array of numbers.
+ :rtype: number
+
+
+.. function:: toJSON(obj)
+
+ Encodes `obj` to JSON string. Actually is a proxy to ``JSON.stringify``
+ method.
+
+ :param obj: JSON encodable object.
+ :return: JSON string.
+
+
+
+CommonJS Modules
+----------------
+
+`CommonJS Modules <http://wiki.commonjs.org/wiki/Modules/1.1.1>`_ is the one of
+major CouchDB feature introduced in 0.11.0 version that allows to create modular
+design functions without needs to duplicate a lot of same functionality.
+
+Example of CommonJS module that checks user permissions:
+
+.. code-block:: javascript
+
+ function user_context(userctx, secobj){
+ var is_admin = function(){
+ return userctx.indexOf('_admin') != -1;
+ }
+ var is_db_admin = function(){
+ if (is_admin() || !secobj){
+ return true;
+ }
+ if (secobj.admins.names.indexOf(userctx.name) != -1){
+ return true;
+ }
+ for (var idx in userctx.roles){
+ if (secobj.admins.roles.indexOf(userctx.roles[idx]) != -1){
+ return true;
+ }
+ }
+ return false;
+ }
+ var is_db_member = function(){
+ if (is_admin() || is_db_admin() || !secobj){
+ return true;
+ }
+ if (secobj.members.names.indexOf(userctx.name) != -1){
+ return true;
+ }
+ for (var idx in userctx.roles){
+ if (secobj.members.roles.indexOf(userctx.roles[idx]) != -1){
+ return true;
+ }
+ }
+ return false;
+ }
+ var has_all_roles = function(roles){
+ for (var idx in roles){
+ if (userctx.roles.indexOf(roles[idx]) == -1){
+ return false;
+ }
+ }
+ return true;
+ }
+ var has_any_role = function(roles){
+ for (var idx in roles){
+ if (userctx.roles.indexOf(roles[idx]) != -1){
+ return true;
+ }
+ }
+ return false;
+ }
+ return {
+ 'is_admin': is_admin,
+ 'is_db_admin': is_db_admin,
+ 'is_db_member': is_db_member,
+ 'has_all_roles': has_all_roles,
+ 'has_any_role': has_any_role
+ }
+ }
+
+ exports['user'] = user_context
+
+Each module has access to additional global variables:
+
+- **module** (`object`): Contains information about stored module.
+
+ - **id** (`string`): Module id that is actually JSON path in ddoc context.
+ - **current** (`code`): Compiled module code object.
+ - **parent** (`object`): Parent frame.
+ - **exports** (`object`): Export statements.
+
+- **exports** (`object`): Shortcut to ``module.exports`` object.
+
+Lets place module above within design document under `lib/validate` path.
+Now we could use it in our design functions:
+
+.. code-block:: javascript
+
+ function(newdoc, olddoc, userctx, secobj){
+ user = require('lib/validate').user(userctx, secobj);
+ if (user.is_admin()){
+ return true;
+ }
+ if (newdoc.author != olddoc.author){
+ throw({'forbidden': 'unable to update `author` field'});
+ }
+ }
+
+
+.. _queryserver_erlang:
+
+Erlang
+======
+
+.. warning::
+
+ Erlang query server runs out of sandbox feature like JavaScript has to!
+ This means, that Erlang code has full access to your OS, file system and
+ network which may leads to security issues. While Erlang functions are
+ faster than JavaScript ones, you need to be careful with running them,
+ especially if they wasn't written by your own hands.
+
+ Keep in mind: don't trust every code - review it first before running.
+
+
+.. note::
+
+ Due to security restriction, Erlang query server is disabled by default.
+ To enable it you'll need to edit your `local.ini` to include a
+ ``native_query_servers`` section:
+
+ .. code-block:: ini
+
+ [native_query_servers]
+ erlang = {couch_native_process, start_link, []}
+
+ And don't forget to restart CouchDB after that and use ``language: "erlang"``
+ property in your Erlang design documents.
+
+
+.. function:: Emit(Id, Value)
+
+ Emits `key`-`value` pair to view indexer process.
+
+ .. code-block:: erlang
+
+ fun({Doc}) ->
+ <<K,_/binary>> = proplists:get_value(<<"_rev">>, Doc, null),
+ V = proplists:get_value(<<"_id">>, Doc, null),
+ Emit(<<K>>, V)
+ end.
+
+
+.. function:: FoldRows(Fun, Acc)
+
+ Helper to iterate over all rows in list function.
+
+ :param Fun: Function object.
+ :param Acc: Previous returned value by `Fun`.
+
+ .. code-block:: erlang
+
+ fun(Head, {Req}) ->
+ Fun = fun({Row}, Acc) ->
+ Id = couch_util:get_value(<<"id">>, Row),
+ Send(list_to_binary(io_lib:format("Previous doc id: ~p~n", [Acc]))),
+ Send(list_to_binary(io_lib:format("Current doc id: ~p~n", [Id]))),
+ {ok, Id}
+ end,
+ FoldRows(Fun, nil),
+ ""
+ end.
+
+
+.. function:: GetRow()
+
+ Retrieves next row from related view result.
+
+ .. code-block:: erlang
+
+ %% FoldRows background implementation.
+ %% https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob;f=src/couchdb/couch_native_process.erl;hb=HEAD#l368
+ %%
+ foldrows(GetRow, ProcRow, Acc) ->
+ case GetRow() of
+ nil ->
+ {ok, Acc};
+ Row ->
+ case (catch ProcRow(Row, Acc)) of
+ {ok, Acc2} ->
+ foldrows(GetRow, ProcRow, Acc2);
+ {stop, Acc2} ->
+ {ok, Acc2}
+ end
+ end.
+
+.. function:: Log(Msg)
+
+ :param Msg: Message to log in at CouchDB `INFO` level.
+
+ .. code-block:: erlang
+
+ fun({Doc}) ->
+ <<K,_/binary>> = proplists:get_value(<<"_rev">>, Doc, null),
+ V = proplists:get_value(<<"_id">>, Doc, null),
+ Log(lists:flatten(io_lib:format("Hello from ~s doc!", [V]))),
+ Emit(<<K>>, V)
+ end.
+
+ On map function run in CouchDB logs (e.g. at `/var/log/couchdb/couch.log`)
+ you may find next record:
+
+ .. code-block:: text
+
+ [Sun, 04 Nov 2012 11:33:58 GMT] [info] [<0.9144.2>] Hello from 8d300b86622d67953d102165dbe99467 doc!
+
+
+.. function:: Send(Chunk)
+
+ Sends a single string `Chunk` in response.
+
+ .. code-block:: erlang
+
+ fun(Head, {Req}) ->
+ Send("Hello,"),
+ Send(" "),
+ Send("Couch"),
+ "!"
+ end.
+
+ Function above produces next response:
+
+ .. code-block:: text
+
+ Hello, Couch!
+
+
+.. function:: Start(Headers)
+
+ :param Headers: Proplist of :ref:`response object<response_object>`.
+
+ Initialize :ref:`listfun` response. At this point response code and headers
+ may be defined. For example, next function redirect to CouchDB web site:
+
+ .. code-block:: erlang
+
+ fun(Head, {Req}) ->
+ Start({[{<<"code">>, 302},
+ {<<"headers">>, {[
+ {<<"Location">>, <<"http://couchdb.apache.org">>}]
+ }}
+ ]}),
+ "Relax!"
+ end.
+
+
http://git-wip-us.apache.org/repos/asf/couchdb/blob/49d66c4b/share/doc/src/range.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/range.rst b/share/doc/src/range.rst
new file mode 100644
index 0000000..a2f6ed1
--- /dev/null
+++ b/share/doc/src/range.rst
@@ -0,0 +1,72 @@
+.. 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.
+
+HTTP Range Requests
+===================
+
+HTTP allows you to specify byte ranges for requests. This allows the
+implementation of resumable downloads and skippable audio and video
+streams alike. This is available for all attachments inside CouchDB.
+
+This is just a real quick run through how this looks under the hood.
+Usually, you will have larger binary files to serve from CouchDB, like
+MP3s and videos, but to make things a little more obvious, I use a text
+file here (Note that I use the ``application/octet-stream`` Content-Type
+instead of ``text/plain``).
+
+.. code-block:: bash
+
+ shell> cat file.txt
+ My hovercraft is full of eels!
+
+Now let's store this text file as an attachment in CouchDB. First, we
+create a database:
+
+.. code-block:: bash
+
+ shell> curl -X PUT http://127.0.0.1:5984/test
+ {"ok":true}
+
+Then we create a new document and the file attachment in one go:
+
+.. code-block:: bash
+
+ shell> curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \
+ -H "Content-Type: application/octet-stream" -d@file.txt
+ {"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"}
+
+Now we can request the whole file easily:
+
+.. code-block:: bash
+
+ shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt
+ My hovercraft is full of eels!
+
+But say we only want the first 13 bytes:
+
+.. code-block:: bash
+
+ shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt \
+ -H "Range: bytes=0-12"
+ My hovercraft
+
+HTTP supports many ways to specify single and even multiple byte
+ranges. Read all about it in `RFC 2616`_.
+
+.. note::
+ Databases that have been created with CouchDB 1.0.2 or earlier will
+ support range requests in |version|, but they are using a less-optimal
+ algorithm. If you plan to make heavy use of this feature, make sure
+ to compact your database with CouchDB |version| to take advantage of a
+ better algorithm to find byte ranges.
+
+.. _RFC 2616: http://tools.ietf.org/html/rfc2616#section-14.27
http://git-wip-us.apache.org/repos/asf/couchdb/blob/49d66c4b/share/doc/src/release.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/release.rst b/share/doc/src/release.rst
new file mode 100644
index 0000000..c61d8ad
--- /dev/null
+++ b/share/doc/src/release.rst
@@ -0,0 +1,47 @@
+.. 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.
+
+=======================================
+CouchDB Release |version| Feature Guide
+=======================================
+
+Upgrading to CouchDB |version|
+==============================
+
+You can upgrade your existing CouchDB 1.0.x installation to CouchDB |version|
+without any specific steps or migration. When you run CouchDB |version| the
+existing data and index files will be opened and used as normal.
+
+The first time you run a compaction routine on your database within
+CouchDB |version|, the data structure and indexes will be updated to the new
+version of the CouchDB database format that can only be read by CouchDB
+|version| and later. This step is not reversible. Once the data files have
+been updated and migrated to the new version the data files will no
+longer work with a CouchDB 1.0.x release.
+
+.. warning::
+ If you want to retain support for opening the data files in
+ CouchDB 1.0.x you must back up your data files before performing the
+ upgrade and compaction process.
+
+New features in CouchDB |version|
+=================================
+
+.. toctree::
+.. :maxdepth: 2
+..
+.. replicator
+.. ssl
+.. range
+.. proxy
+.. commonjs
+.. other
http://git-wip-us.apache.org/repos/asf/couchdb/blob/49d66c4b/share/doc/src/replication.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/replication.rst b/share/doc/src/replication.rst
new file mode 100644
index 0000000..9245a08
--- /dev/null
+++ b/share/doc/src/replication.rst
@@ -0,0 +1,383 @@
+.. 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.
+
+.. _replication:
+
+Replicator Database
+===================
+
+A database where you ``PUT``/``POST`` documents to trigger replications
+and you ``DELETE`` to cancel ongoing replications. These documents have
+exactly the same content as the JSON objects we used to ``POST`` to
+``_replicate`` (fields ``source``, ``target``, ``create_target``,
+``continuous``, ``doc_ids``, ``filter``, ``query_params``.
+
+Replication documents can have a user defined ``_id``. Design documents
+(and ``_local`` documents) added to the replicator database are ignored.
+
+The default name of this database is ``_replicator``. The name can be
+changed in the ``local.ini`` configuration, section ``[replicator]``,
+parameter ``db``.
+
+Basics
+------
+
+Let's say you PUT the following document into ``_replicator``:
+
+.. code-block:: javascript
+
+ {
+ "_id": "my_rep",
+ "source": "http://myserver.com:5984/foo",
+ "target": "bar",
+ "create_target": true
+ }
+
+In the couch log you'll see 2 entries like these:
+
+.. code-block:: text
+
+ [Thu, 17 Feb 2011 19:43:59 GMT] [info] [<0.291.0>] Document `my_rep` triggered replication `c0ebe9256695ff083347cbf95f93e280+create_target`
+ [Thu, 17 Feb 2011 19:44:37 GMT] [info] [<0.124.0>] Replication `c0ebe9256695ff083347cbf95f93e280+create_target` finished (triggered by document `my_rep`)
+
+As soon as the replication is triggered, the document will be updated by
+CouchDB with 3 new fields:
+
+.. code-block:: javascript
+
+ {
+ "_id": "my_rep",
+ "source": "http://myserver.com:5984/foo",
+ "target": "bar",
+ "create_target": true,
+ "_replication_id": "c0ebe9256695ff083347cbf95f93e280",
+ "_replication_state": "triggered",
+ "_replication_state_time": 1297974122
+ }
+
+Special fields set by the replicator start with the prefix
+``_replication_``.
+
+- ``_replication_id``
+
+ The ID internally assigned to the replication. This is also the ID
+ exposed by ``/_active_tasks``.
+
+- ``_replication_state``
+
+ The current state of the replication.
+
+- ``_replication_state_time``
+
+ A Unix timestamp (number of seconds since 1 Jan 1970) that tells us
+ when the current replication state (marked in ``_replication_state``)
+ was set.
+
+When the replication finishes, it will update the ``_replication_state``
+field (and ``_replication_state_time``) with the value ``completed``, so
+the document will look like:
+
+.. code-block:: javascript
+
+ {
+ "_id": "my_rep",
+ "source": "http://myserver.com:5984/foo",
+ "target": "bar",
+ "create_target": true,
+ "_replication_id": "c0ebe9256695ff083347cbf95f93e280",
+ "_replication_state": "completed",
+ "_replication_state_time": 1297974122
+ }
+
+When an error happens during replication, the ``_replication_state``
+field is set to ``error`` (and ``_replication_state`` gets updated of
+course).
+
+When you PUT/POST a document to the ``_replicator`` database, CouchDB
+will attempt to start the replication up to 10 times (configurable under
+``[replicator]``, parameter ``max_replication_retry_count``). If it
+fails on the first attempt, it waits 5 seconds before doing a second
+attempt. If the second attempt fails, it waits 10 seconds before doing a
+third attempt. If the third attempt fails, it waits 20 seconds before
+doing a fourth attempt (each attempt doubles the previous wait period).
+When an attempt fails, the Couch log will show you something like:
+
+.. code-block:: text
+
+ [error] [<0.149.0>] Error starting replication `67c1bb92010e7abe35d7d629635f18b6+create_target` (document `my_rep_2`): {db_not_found,<<"could not open http://myserver:5986/foo/">>
+
+.. note::
+ The ``_replication_state`` field is only set to ``error`` when all
+ the attempts were unsuccessful.
+
+There are only 3 possible values for the ``_replication_state`` field:
+``triggered``, ``completed`` and ``error``. Continuous replications
+never get their state set to ``completed``.
+
+Documents describing the same replication
+-----------------------------------------
+
+Lets suppose 2 documents are added to the ``_replicator`` database in
+the following order:
+
+.. code-block:: javascript
+
+ {
+ "_id": "doc_A",
+ "source": "http://myserver.com:5984/foo",
+ "target": "bar"
+ }
+
+and
+
+.. code-block:: javascript
+
+ {
+ "_id": "doc_B",
+ "source": "http://myserver.com:5984/foo",
+ "target": "bar"
+ }
+
+Both describe exactly the same replication (only their ``_ids`` differ).
+In this case document ``doc_A`` triggers the replication, getting
+updated by CouchDB with the fields ``_replication_state``,
+``_replication_state_time`` and ``_replication_id``, just like it was
+described before. Document ``doc_B`` however, is only updated with one
+field, the ``_replication_id`` so it will look like this:
+
+.. code-block:: javascript
+
+ {
+ "_id": "doc_B",
+ "source": "http://myserver.com:5984/foo",
+ "target": "bar",
+ "_replication_id": "c0ebe9256695ff083347cbf95f93e280"
+ }
+
+While document ``doc_A`` will look like this:
+
+.. code-block:: javascript
+
+ {
+ "_id": "doc_A",
+ "source": "http://myserver.com:5984/foo",
+ "target": "bar",
+ "_replication_id": "c0ebe9256695ff083347cbf95f93e280",
+ "_replication_state": "triggered",
+ "_replication_state_time": 1297974122
+ }
+
+Note that both document get exactly the same value for the
+``_replication_id`` field. This way you can identify which documents
+refer to the same replication - you can for example define a view which
+maps replication IDs to document IDs.
+
+Canceling replications
+----------------------
+
+To cancel a replication simply ``DELETE`` the document which triggered
+the replication. The Couch log will show you an entry like the
+following:
+
+.. code-block:: text
+
+ [Thu, 17 Feb 2011 20:16:29 GMT] [info] [<0.125.0>] Stopped replication `c0ebe9256695ff083347cbf95f93e280+continuous+create_target` because replication document `doc_A` was deleted
+
+.. note::
+ You need to ``DELETE`` the document that triggered the replication.
+ ``DELETE``-ing another document that describes the same replication
+ but did not trigger it, will not cancel the replication.
+
+Server restart
+--------------
+
+When CouchDB is restarted, it checks its ``_replicator`` database and
+restarts any replication that is described by a document that either has
+its ``_replication_state`` field set to ``triggered`` or it doesn't have
+yet the ``_replication_state`` field set.
+
+.. note::
+ Continuous replications always have a ``_replication_state`` field
+ with the value ``triggered``, therefore they're always restarted
+ when CouchDB is restarted.
+
+Changing the Replicator Database
+--------------------------------
+
+Imagine your replicator database (default name is ``_replicator``) has the
+two following documents that represent pull replications from servers A
+and B:
+
+.. code-block:: javascript
+
+ {
+ "_id": "rep_from_A",
+ "source": "http://aserver.com:5984/foo",
+ "target": "foo_a",
+ "continuous": true,
+ "_replication_id": "c0ebe9256695ff083347cbf95f93e280",
+ "_replication_state": "triggered",
+ "_replication_state_time": 1297971311
+ }
+
+.. code-block:: javascript
+
+ {
+ "_id": "rep_from_B",
+ "source": "http://bserver.com:5984/foo",
+ "target": "foo_b",
+ "continuous": true,
+ "_replication_id": "231bb3cf9d48314eaa8d48a9170570d1",
+ "_replication_state": "triggered",
+ "_replication_state_time": 1297974122
+ }
+
+Now without stopping and restarting CouchDB, you change the name of the
+replicator database to ``another_replicator_db``:
+
+.. code-block:: bash
+
+ $ curl -X PUT http://localhost:5984/_config/replicator/db -d '"another_replicator_db"'
+ "_replicator"
+
+As soon as this is done, both pull replications defined before, are
+stopped. This is explicitly mentioned in CouchDB's log:
+
+.. code-block:: text
+
+ [Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.104.0>] Stopping all ongoing replications because the replicator database was deleted or changed
+ [Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.127.0>] 127.0.0.1 - - PUT /_config/replicator/db 200
+
+Imagine now you add a replication document to the new replicator
+database named ``another_replicator_db``:
+
+.. code-block:: javascript
+
+ {
+ "_id": "rep_from_X",
+ "source": "http://xserver.com:5984/foo",
+ "target": "foo_x",
+ "continuous": true
+ }
+
+From now own you have a single replication going on in your system: a
+pull replication pulling from server X. Now you change back the
+replicator database to the original one ``_replicator``:
+
+::
+
+ $ curl -X PUT http://localhost:5984/_config/replicator/db -d '"_replicator"'
+ "another_replicator_db"
+
+Immediately after this operation, the replication pulling from server X
+will be stopped and the replications defined in the ``_replicator``
+database (pulling from servers A and B) will be resumed.
+
+Changing again the replicator database to ``another_replicator_db`` will
+stop the pull replications pulling from servers A and B, and resume the
+pull replication pulling from server X.
+
+Replicating the replicator database
+-----------------------------------
+
+Imagine you have in server C a replicator database with the two
+following pull replication documents in it:
+
+.. code-block:: javascript
+
+ {
+ "_id": "rep_from_A",
+ "source": "http://aserver.com:5984/foo",
+ "target": "foo_a",
+ "continuous": true,
+ "_replication_id": "c0ebe9256695ff083347cbf95f93e280",
+ "_replication_state": "triggered",
+ "_replication_state_time": 1297971311
+ }
+
+.. code-block:: javascript
+
+ {
+ "_id": "rep_from_B",
+ "source": "http://bserver.com:5984/foo",
+ "target": "foo_b",
+ "continuous": true,
+ "_replication_id": "231bb3cf9d48314eaa8d48a9170570d1",
+ "_replication_state": "triggered",
+ "_replication_state_time": 1297974122
+ }
+
+Now you would like to have the same pull replications going on in server
+D, that is, you would like to have server D pull replicating from
+servers A and B. You have two options:
+
+- Explicitly add two documents to server's D replicator database
+
+- Replicate server's C replicator database into server's D replicator
+ database
+
+Both alternatives accomplish exactly the same goal.
+
+Delegations
+-----------
+
+Replication documents can have a custom ``user_ctx`` property. This
+property defines the user context under which a replication runs. For
+the old way of triggering replications (POSTing to ``/_replicate/``),
+this property was not needed (it didn't exist in fact) - this is because
+at the moment of triggering the replication it has information about the
+authenticated user. With the replicator database, since it's a regular
+database, the information about the authenticated user is only present
+at the moment the replication document is written to the database - the
+replicator database implementation is like a ``_changes`` feed consumer
+(with ``?include_docs=true``) that reacts to what was written to the
+replicator database - in fact this feature could be implemented with an
+external script/program. This implementation detail implies that for non
+admin users, a ``user_ctx`` property, containing the user's name and a
+subset of his/her roles, must be defined in the replication document.
+This is ensured by the document update validation function present in
+the default design document of the replicator database. This validation
+function also ensure that a non admin user can set a user name property
+in the ``user_ctx`` property that doesn't match his/her own name (same
+principle applies for the roles).
+
+For admins, the ``user_ctx`` property is optional, and if it's missing
+it defaults to a user context with name null and an empty list of roles
+- this mean design documents will not be written to local targets. If
+writing design documents to local targets is desired, the a user context
+with the roles ``_admin`` must be set explicitly.
+
+Also, for admins the ``user_ctx`` property can be used to trigger a
+replication on behalf of another user. This is the user context that
+will be passed to local target database document validation functions.
+
+.. note::
+ The ``user_ctx`` property only has effect for local endpoints.
+
+Example delegated replication document:
+
+.. code-block:: javascript
+
+ {
+ "_id": "my_rep",
+ "source": "http://bserver.com:5984/foo",
+ "target": "bar",
+ "continuous": true,
+ "user_ctx": {
+ "name": "joe",
+ "roles": ["erlanger", "researcher"]
+ }
+ }
+
+As stated before, for admins the ``user_ctx`` property is optional, while
+for regular (non admin) users it's mandatory. When the roles property of
+``user_ctx`` is missing, it defaults to the empty list ``[ ]``.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/49d66c4b/share/doc/src/ssl.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/ssl.rst b/share/doc/src/ssl.rst
new file mode 100644
index 0000000..3a546d8
--- /dev/null
+++ b/share/doc/src/ssl.rst
@@ -0,0 +1,109 @@
+.. 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.
+
+Native SSL Support
+==================
+
+CouchDB |version| supports SSL natively. All your secure connection needs can
+now be served without needing to setup and maintain a separate proxy server
+that handles SSL.
+
+SSL setup can be tricky, but the configuration in CouchDB was designed
+to be as easy as possible. All you need is two files; a certificate and
+a private key. If you bought an official SSL certificate from a
+certificate authority, both should be in your possession already.
+
+If you just want to try this out and don't want to pay anything upfront,
+you can create a self-signed certificate. Everything will work the same,
+but clients will get a warning about an insecure certificate.
+
+You will need the OpenSSL command line tool installed. It probably
+already is.
+
+::
+
+ shell> mkdir cert && cd cert
+ shell> openssl genrsa > privkey.pem
+ shell> openssl req -new -x509 -key privkey.pem -out mycert.pem -days 1095
+ shell> ls
+ mycert.pem privkey.pem
+
+Now, you need to edit CouchDB's configuration, either by editing your
+``local.ini`` file or using the ``/_config`` API calls or the
+configuration screen in Futon. Here is what you need to do in
+``local.ini``, you can infer what needs doing in the other places.
+
+Be sure to make these edits. Under ``[daemons]`` you should see:
+
+::
+
+ ; enable SSL support by uncommenting the following line and supply the PEM's below.
+ ; the default ssl port CouchDB listens on is 6984
+ ;httpsd = {couch_httpd, start_link, [https]}
+
+Here uncomment the last line:
+
+::
+
+ httpsd = {couch_httpd, start_link, [https]}
+
+Next, under ``[ssl]`` you will see:
+
+::
+
+ ;cert_file = /full/path/to/server_cert.pem
+ ;key_file = /full/path/to/server_key.pem
+
+Uncomment and adjust the paths so it matches your system's paths:
+
+::
+
+ cert_file = /home/jan/cert/mycert.pem
+ key_file = /home/jan/cert/privkey.pem
+
+For more information please read
+`http://www.openssl.org/docs/HOWTO/certificates.txt`_.
+
+Now start (or restart) CouchDB. You should be able to connect to it
+using HTTPS on port 6984:
+
+::
+
+ shell> curl https://127.0.0.1:6984/
+ curl: (60) SSL certificate problem, verify that the CA cert is OK. Details:
+ error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
+ More details here: http://curl.haxx.se/docs/sslcerts.html
+
+ curl performs SSL certificate verification by default, using a "bundle"
+ of Certificate Authority (CA) public keys (CA certs). If the default
+ bundle file isn't adequate, you can specify an alternate file
+ using the --cacert option.
+ If this HTTPS server uses a certificate signed by a CA represented in
+ the bundle, the certificate verification probably failed due to a
+ problem with the certificate (it might be expired, or the name might
+ not match the domain name in the URL).
+ If you'd like to turn off curl's verification of the certificate, use
+ the -k (or --insecure) option.
+
+Oh no what happened?! — Remember, clients will notify their users that
+your certificate is self signed. ``curl`` is the client in this case and
+it notifies you. Luckily you trust yourself (don't you?) and you can
+specify the ``-k`` option as the message reads:
+
+::
+
+ shell> curl -k https://127.0.0.1:6984/
+ {"couchdb":"Welcome","version":"|version|"}
+
+All done.
+
+.. _`http://www.openssl.org/docs/HOWTO/certificates.txt`: http://www.openssl.org/docs/HOWTO/certificates.txt
http://git-wip-us.apache.org/repos/asf/couchdb/blob/49d66c4b/share/docs/couchdb-manual-1.1/couchdb-api-auth-metasrc.xml
----------------------------------------------------------------------
diff --git a/share/docs/couchdb-manual-1.1/couchdb-api-auth-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-api-auth-metasrc.xml
deleted file mode 100644
index 417500a..0000000
--- a/share/docs/couchdb-manual-1.1/couchdb-api-auth-metasrc.xml
+++ /dev/null
@@ -1,36 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
- 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
-<!ENTITY % every.entities SYSTEM "entities.ent">
-%every.entities;
-]>
-<chapter id="couchdb-api-auth">
-
- <title>CouchDB API Server Authentication Methods</title>
-
- <para>
- The CouchDB Authentication methods provide an interface for
- obtaining session and authorization data.
- </para>
-
- <para>
- A list of the available methods and URL paths are provided below:
- </para>
-
- <para role="meta" id="table-couchdb-api-auth-summary">
- <remark role="title">Authentication API Calls</remark>
-
- <remark role="type" condition="urlapi"/>
-
- <remark role="src" condition="couchdb"/>
-
- <remark role="output" condition="summarytable"/>
-
- <remark role="filter_class" condition="auth"/>
-
- <remark role="version" condition="inherit"/>
-
- <remark role="idprefix" condition="couchdb-api-auth"/>
- </para>
-
-</chapter>