Return-Path: X-Original-To: apmail-couchdb-commits-archive@www.apache.org Delivered-To: apmail-couchdb-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 1B8ACDEDA for ; Thu, 6 Dec 2012 11:35:19 +0000 (UTC) Received: (qmail 18323 invoked by uid 500); 6 Dec 2012 11:35:02 -0000 Delivered-To: apmail-couchdb-commits-archive@couchdb.apache.org Received: (qmail 16863 invoked by uid 500); 6 Dec 2012 11:34:59 -0000 Mailing-List: contact commits-help@couchdb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 14167 invoked by uid 99); 6 Dec 2012 11:34:41 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 06 Dec 2012 11:34:41 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id DCD6A8196E6; Thu, 6 Dec 2012 11:34:40 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: jan@apache.org To: commits@couchdb.apache.org X-Mailer: ASF-Git Admin Mailer Subject: [10/50] [abbrv] Transmogrify Couchbase XML to .rst and support Sphinx Message-Id: <20121206113440.DCD6A8196E6@tyr.zones.apache.org> Date: Thu, 6 Dec 2012 11:34:40 +0000 (UTC) http://git-wip-us.apache.org/repos/asf/couchdb/blob/7f66e6f4/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 ` | ++--------------------------------+---------------------------------------------+ +| 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/7f66e6f4/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/7f66e6f4/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 +`_ 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 ` 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/7f66e6f4/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 `_ + 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 ` 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 `_ 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}) -> + <> = proplists:get_value(<<"_rev">>, Doc, null), + V = proplists:get_value(<<"_id">>, Doc, null), + Emit(<>, 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}) -> + <> = 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(<>, 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`. + + 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/7f66e6f4/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/7f66e6f4/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/7f66e6f4/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/7f66e6f4/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/7f66e6f4/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 @@ - - -%every.entities; -]> - - - CouchDB API Server Authentication Methods - - - The CouchDB Authentication methods provide an interface for - obtaining session and authorization data. - - - - A list of the available methods and URL paths are provided below: - - - - Authentication API Calls - - - - - - - - - - - - - - -