You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by ja...@apache.org on 2012/12/06 12:34:40 UTC
[8/50] [abbrv] Transmogrify Couchbase XML to .rst and support Sphinx
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7f66e6f4/share/doc/src/api/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/misc.rst b/share/doc/src/api/misc.rst
new file mode 100644
index 0000000..f9562ae
--- /dev/null
+++ b/share/doc/src/api/misc.rst
@@ -0,0 +1,805 @@
+.. 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.
+
+.. _api-misc:
+
+=====================
+Miscellaneous Methods
+=====================
+
+The CouchDB Miscellaneous interface provides the basic interface to a
+CouchDB server for obtaining CouchDB information and getting and setting
+configuration information.
+
+A list of the available methods and URL paths are provided below:
+
++--------+-------------------------+-------------------------------------------+
+| Method | Path | Description |
++========+=========================+===========================================+
+| GET | / | Get the welcome message and version |
+| | | information |
++--------+-------------------------+-------------------------------------------+
+| GET | /_active_tasks | Obtain a list of the tasks running in the|
+| | | server |
++--------+-------------------------+-------------------------------------------+
+| GET | /_all_dbs | Get a list of all the DBs |
++--------+-------------------------+-------------------------------------------+
+| GET | /_log | Return the server log file |
++--------+-------------------------+-------------------------------------------+
+| POST | /_replicate | Set or cancel replication |
++--------+-------------------------+-------------------------------------------+
+| POST | /_restart | Restart the server |
++--------+-------------------------+-------------------------------------------+
+| GET | /_stats | Return server statistics |
++--------+-------------------------+-------------------------------------------+
+| GET | /_utils | CouchDB administration interface (Futon) |
++--------+-------------------------+-------------------------------------------+
+| GET | /_uuids | Get generated UUIDs from the server |
++--------+-------------------------+-------------------------------------------+
+| GET | /favicon.ico | Get the site icon |
++--------+-------------------------+-------------------------------------------+
+
+``GET /``
+=========
+
+* **Method**: ``GET /``
+* **Request**: None
+* **Response**: Welcome message and version
+* **Admin Privileges Required**: no
+* **Return Codes**:
+
+ * **200**:
+ Request completed successfully.
+
+Accessing the root of a CouchDB instance returns meta information about
+the instance. The response is a JSON structure containing information
+about the server, including a welcome message and the version of the
+server.
+
+.. code-block:: javascript
+
+ {
+ "couchdb" : "Welcome",
+ "version" : "1.0.1"
+ }
+
+.. _active-tasks:
+
+``GET /_active_tasks``
+======================
+
+* **Method**: ``GET /_active_tasks``
+* **Request**: None
+* **Response**: List of running tasks, including the task type, name, status
+ and process ID
+* **Admin Privileges Required**: yes
+* **Return Codes**:
+
+ * **200**:
+ Request completed successfully.
+
+You can obtain a list of active tasks by using the ``/_active_tasks``
+URL. The result is a JSON array of the currently running tasks, with
+each task being described with a single object. For example:
+
+.. code-block:: javascript
+
+ [
+ {
+ "pid" : "<0.11599.0>",
+ "status" : "Copied 0 of 18369 changes (0%)",
+ "task" : "recipes",
+ "type" : "Database Compaction"
+ }
+ ]
+
+The returned structure includes the following fields for each task:
+
+* **tasks** [array]: Active Task
+
+ * **pid**:Process ID
+ * **status**: Task status message
+ * **task**: Task name
+ * **type**: Operation Type
+
+For operation type, valid values include:
+
+- ``Database Compaction``
+
+- ``Replication``
+
+- ``View Group Compaction``
+
+- ``View Group Indexer``
+
+``GET /_all_dbs``
+=================
+
+* **Method**: ``GET /_all_dbs``
+* **Request**: None
+* **Response**: JSON list of DBs
+* **Admin Privileges Required**: no
+* **Return Codes**:
+
+ * **200**:
+ Request completed successfully.
+
+Returns a list of all the databases in the CouchDB instance. For
+example:
+
+.. code-block:: http
+
+ GET http://couchdb:5984/_all_dbs
+ Accept: application/json
+
+The return is a JSON array:
+
+.. code-block:: javascript
+
+ [
+ "_users",
+ "contacts",
+ "docs",
+ "invoices",
+ "locations"
+ ]
+
+``GET /_log``
+=============
+
+* **Method**: ``GET /_log``
+* **Request**: None
+* **Response**: Log content
+* **Admin Privileges Required**: yes
+* **Query Arguments**:
+
+ * **Argument**: bytes
+
+ * **Description**: Bytes to be returned
+ * **Optional**: yes
+ * **Type**: numeric
+ * **Default**: 1000
+
+ * **Argument**: offset
+
+ * **Description**: Offset in bytes where the log tail should be started
+ * **Optional**: yes
+ * **Type**: numeric
+ * **Default**: 0
+
+* **Return Codes**:
+
+ * **200**:
+ Request completed successfully.
+
+Gets the CouchDB log, equivalent to accessing the local log file of the
+corresponding CouchDB instance.
+
+When you request the log, the response is returned as plain (UTF-8)
+text, with an HTTP ``Content-type`` header as ``text/plain``.
+
+For example, the request:
+
+.. code-block:: http
+
+ GET http://couchdb:5984/_log
+ Accept: */*
+
+The raw text is returned:
+
+.. code-block:: text
+
+ [Wed, 27 Oct 2010 10:49:42 GMT] [info] [<0.23338.2>] 192.168.0.2 - - 'PUT' /authdb 401
+ [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /recipes/FishStew 200
+ [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /_session 200
+ [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.24199.2>] 192.168.0.116 - - 'GET' / 200
+ [Wed, 27 Oct 2010 13:03:38 GMT] [info] [<0.24207.2>] 192.168.0.116 - - 'GET' /_log?offset=5 200
+
+If you want to pick out specific parts of the log information you can
+use the ``bytes`` argument, which specifies the number of bytes to be
+returned, and ``offset``, which specifies where the reading of the log
+should start, counted back from the end. For example, if you use the
+following request:
+
+.. code-block:: http
+
+ GET /_log?bytes=500&offset=2000
+
+Reading of the log will start at 2000 bytes from the end of the log, and
+500 bytes will be shown.
+
+.. _replicate:
+
+``POST /_replicate``
+====================
+
+.. todo:: POST /_replicate :: what response is?
+
+* **Method**: ``POST /_replicate``
+* **Request**: Replication specification
+* **Response**: TBD
+* **Admin Privileges Required**: yes
+* **Query Arguments**:
+
+ * **Argument**: bytes
+
+ * **Description**: Bytes to be returned
+ * **Optional**: yes
+ * **Type**: numeric
+ * **Default**: 1000
+
+ * **Argument**: offset
+
+ * **Description**: Offset in bytes where the log tail should be started
+ * **Optional**: yes
+ * **Type**: numeric
+ * **Default**: 0
+
+* **Return Codes**:
+
+ * **200**:
+ Replication request successfully completed
+ * **202**:
+ Continuous replication request has been accepted
+ * **404**:
+ Either the source or target DB is not found
+ * **500**:
+ JSON specification was invalid
+
+Request, configure, or stop, a replication operation.
+
+The specification of the replication request is controlled through the
+JSON content of the request. The JSON should be an object with the
+fields defining the source, target and other options. The fields of the
+JSON request are shown in the table below:
+
+* **cancel (optional)**: Cancels the replication
+* **continuous (optional)**: Configure the replication to be continuous
+* **create_target (optional)**: Creates the target database
+* **doc_ids (optional)**: Array of document IDs to be synchronized
+* **proxy (optional)**: Address of a proxy server through which replication
+ should occur
+* **source**: Source database name or URL
+* **target**: Target database name or URL
+
+Replication Operation
+---------------------
+
+The aim of the replication is that at the end of the process, all active
+documents on the source database are also in the destination database
+and all documents that were deleted in the source databases are also
+deleted (if they exist) on the destination database.
+
+Replication can be described as either push or pull replication:
+
+- *Pull replication* is where the ``source`` is the remote CouchDB
+ instance, and the ``destination`` is the local database.
+
+ Pull replication is the most useful solution to use if your source
+ database has a permanent IP address, and your destination (local)
+ database may have a dynamically assigned IP address (for example,
+ through DHCP). This is particularly important if you are replicating
+ to a mobile or other device from a central server.
+
+- *Push replication* is where the ``source`` is a local database, and
+ ``destination`` is a remote database.
+
+Specifying the Source and Target Database
+-----------------------------------------
+
+You must use the URL specification of the CouchDB database if you want
+to perform replication in either of the following two situations:
+
+- Replication with a remote database (i.e. another instance of CouchDB
+ on the same host, or a different host)
+
+- Replication with a database that requires authentication
+
+For example, to request replication between a database local to the
+CouchDB instance to which you send the request, and a remote database
+you might use the following request:
+
+.. code-block:: http
+
+ POST http://couchdb:5984/_replicate
+ Content-Type: application/json
+ Accept: application/json
+
+ {
+ "source" : "recipes",
+ "target" : "http://coucdb-remote:5984/recipes",
+ }
+
+
+In all cases, the requested databases in the ``source`` and ``target``
+specification must exist. If they do not, an error will be returned
+within the JSON object:
+
+.. code-block:: javascript
+
+ {
+ "error" : "db_not_found"
+ "reason" : "could not open http://couchdb-remote:5984/ol1ka/",
+ }
+
+You can create the target database (providing your user credentials
+allow it) by adding the ``create_target`` field to the request object:
+
+.. code-block:: http
+
+ POST http://couchdb:5984/_replicate
+ Content-Type: application/json
+ Accept: application/json
+
+ {
+ "create_target" : true
+ "source" : "recipes",
+ "target" : "http://couchdb-remote:5984/recipes",
+ }
+
+The ``create_target`` field is not destructive. If the database already
+exists, the replication proceeds as normal.
+
+Single Replication
+------------------
+
+You can request replication of a database so that the two databases can
+be synchronized. By default, the replication process occurs one time and
+synchronizes the two databases together. For example, you can request a
+single synchronization between two databases by supplying the ``source``
+and ``target`` fields within the request JSON content.
+
+.. code-block:: http
+
+ POST http://couchdb:5984/_replicate
+ Content-Type: application/json
+ Accept: application/json
+
+ {
+ "source" : "recipes",
+ "target" : "recipes-snapshot",
+ }
+
+In the above example, the databases ``recipes`` and ``recipes-snapshot``
+will be synchronized. These databases are local to the CouchDB instance
+where the request was made. The response will be a JSON structure
+containing the success (or failure) of the synchronization process, and
+statistics about the process:
+
+.. code-block:: javascript
+
+ {
+ "ok" : true,
+ "history" : [
+ {
+ "docs_read" : 1000,
+ "session_id" : "52c2370f5027043d286daca4de247db0",
+ "recorded_seq" : 1000,
+ "end_last_seq" : 1000,
+ "doc_write_failures" : 0,
+ "start_time" : "Thu, 28 Oct 2010 10:24:13 GMT",
+ "start_last_seq" : 0,
+ "end_time" : "Thu, 28 Oct 2010 10:24:14 GMT",
+ "missing_checked" : 0,
+ "docs_written" : 1000,
+ "missing_found" : 1000
+ }
+ ],
+ "session_id" : "52c2370f5027043d286daca4de247db0",
+ "source_last_seq" : 1000
+ }
+
+The structure defines the replication status, as described in the table
+below:
+
+* **history [array]**: Replication History
+
+ * **doc_write_failures**: Number of document write failures
+ * **docs_read**: Number of documents read
+ * **docs_written**: Number of documents written to target
+ * **end_last_seq**: Last sequence number in changes stream
+ * **end_time**: Date/Time replication operation completed
+ * **missing_checked**: Number of missing documents checked
+ * **missing_found**: Number of missing documents found
+ * **recorded_seq**: Last recorded sequence number
+ * **session_id**: Session ID for this replication operation
+ * **start_last_seq**: First sequence number in changes stream
+ * **start_time**: Date/Time replication operation started
+
+* **ok**: Replication status
+* **session_id**: Unique session ID
+* **source_last_seq**: Last sequence number read from source database
+
+Continuous Replication
+----------------------
+
+Synchronization of a database with the previously noted methods happens
+only once, at the time the replicate request is made. To have the target
+database permanently replicated from the source, you must set the
+``continuous`` field of the JSON object within the request to true.
+
+With continuous replication changes in the source database are
+replicated to the target database in perpetuity until you specifically
+request that replication ceases.
+
+.. code-block:: http
+
+ POST http://couchdb:5984/_replicate
+ Content-Type: application/json
+ Accept: application/json
+
+ {
+ "continuous" : true
+ "source" : "recipes",
+ "target" : "http://couchdb-remote:5984/recipes",
+ }
+
+Changes will be replicated between the two databases as long as a
+network connection is available between the two instances.
+
+.. note::
+ Two keep two databases synchronized with each other, you need to set
+ replication in both directions; that is, you must replicate from
+ ``databasea`` to ``databaseb``, and separately from ``databaseb`` to
+ ``databasea``.
+
+Canceling Continuous Replication
+--------------------------------
+
+You can cancel continuous replication by adding the ``cancel`` field to
+the JSON request object and setting the value to true. Note that the
+structure of the request must be identical to the original for the
+cancellation request to be honoured. For example, if you requested
+continuous replication, the cancellation request must also contain the
+``continuous`` field.
+
+For example, the replication request:
+
+.. code-block:: http
+
+ POST http://couchdb:5984/_replicate
+ Content-Type: application/json
+ Accept: application/json
+
+ {
+ "source" : "recipes",
+ "target" : "http://couchdb-remote:5984/recipes",
+ "create_target" : true,
+ "continuous" : true
+ }
+
+Must be canceled using the request:
+
+.. code-block:: http
+
+ POST http://couchdb:5984/_replicate
+ Content-Type: application/json
+ Accept: application/json
+
+ {
+ "cancel" : true,
+ "continuous" : true
+ "create_target" : true,
+ "source" : "recipes",
+ "target" : "http://couchdb-remote:5984/recipes",
+ }
+
+Requesting cancellation of a replication that does not exist results in
+a 404 error.
+
+``POST /_restart``
+==================
+
+* **Method**: ``POST /_restart``
+* **Request**: None
+* **Response**: JSON status message
+* **Admin Privileges Required**: yes
+* **HTTP Headers**:
+
+ * **Header**: ``Content-Type``
+
+ * **Description**: Request content type
+ * **Optional**: no
+ * **Value**: :mimetype:`application/json`
+
+* **Return Codes**:
+
+ * **200**:
+ Replication request successfully completed
+
+Restarts the CouchDB instance. You must be authenticated as a user with
+administration privileges for this to work.
+
+For example:
+
+.. code-block:: http
+
+ POST http://admin:password@couchdb:5984/_restart
+
+The return value (if the server has not already restarted) is a JSON
+status object indicating that the request has been received:
+
+.. code-block:: javascript
+
+ {
+ "ok" : true,
+ }
+
+If the server has already restarted, the header may be returned, but no
+actual data is contained in the response.
+
+``GET /_stats``
+===============
+
+* **Method**: ``GET /_stats``
+* **Request**: None
+* **Response**: Server statistics
+* **Admin Privileges Required**: no
+* **Return Codes**:
+
+ * **200**:
+ Request completed successfully.
+
+The ``_stats`` method returns a JSON object containing the statistics
+for the running server. The object is structured with top-level sections
+collating the statistics for a range of entries, with each individual
+statistic being easily identified, and the content of each statistic is
+self-describing. For example, the request time statistics, within the
+``couchdb`` section are structured as follows:
+
+.. code-block:: javascript
+
+ {
+ "couchdb" : {
+ ...
+ "request_time" : {
+ "stddev" : "27.509",
+ "min" : "0.333333333333333",
+ "max" : "152",
+ "current" : "400.976",
+ "mean" : "10.837",
+ "sum" : "400.976",
+ "description" : "length of a request inside CouchDB without MochiWeb"
+ },
+ ...
+ }
+ }
+
+
+The fields provide the current, minimum and maximum, and a collection of
+statistical means and quantities. The quantity in each case is not
+defined, but the descriptions below provide
+
+The statistics are divided into the following top-level sections:
+
+- ``couchdb``: Describes statistics specific to the internals of CouchDB.
+
+ +-------------------------+-------------------------------------------------------+----------------+
+ | Statistic ID | Description | Unit |
+ +=========================+=======================================================+================+
+ | ``auth_cache_hits`` | Number of authentication cache hits | number |
+ +-------------------------+-------------------------------------------------------+----------------+
+ | ``auth_cache_misses`` | Number of authentication cache misses | number |
+ +-------------------------+-------------------------------------------------------+----------------+
+ | ``database_reads`` | Number of times a document was read from a database | number |
+ +-------------------------+-------------------------------------------------------+----------------+
+ | ``database_writes`` | Number of times a database was changed | number |
+ +-------------------------+-------------------------------------------------------+----------------+
+ | ``open_databases`` | Number of open databases | number |
+ +-------------------------+-------------------------------------------------------+----------------+
+ | ``open_os_files`` | Number of file descriptors CouchDB has open | number |
+ +-------------------------+-------------------------------------------------------+----------------+
+ | ``request_time`` | Length of a request inside CouchDB without MochiWeb | milliseconds |
+ +-------------------------+-------------------------------------------------------+----------------+
+
+- ``httpd_request_methods``
+
+ +----------------+----------------------------------+----------+
+ | Statistic ID | Description | Unit |
+ +================+==================================+==========+
+ | ``COPY`` | Number of HTTP COPY requests | number |
+ +----------------+----------------------------------+----------+
+ | ``DELETE`` | Number of HTTP DELETE requests | number |
+ +----------------+----------------------------------+----------+
+ | ``GET`` | Number of HTTP GET requests | number |
+ +----------------+----------------------------------+----------+
+ | ``HEAD`` | Number of HTTP HEAD requests | number |
+ +----------------+----------------------------------+----------+
+ | ``POST`` | Number of HTTP POST requests | number |
+ +----------------+----------------------------------+----------+
+ | ``PUT`` | Number of HTTP PUT requests | number |
+ +----------------+----------------------------------+----------+
+
+- ``httpd_status_codes``
+
+ +----------------+------------------------------------------------------+----------+
+ | Statistic ID | Description | Unit |
+ +================+======================================================+==========+
+ | ``200`` | Number of HTTP 200 OK responses | number |
+ +----------------+------------------------------------------------------+----------+
+ | ``201`` | Number of HTTP 201 Created responses | number |
+ +----------------+------------------------------------------------------+----------+
+ | ``202`` | Number of HTTP 202 Accepted responses | number |
+ +----------------+------------------------------------------------------+----------+
+ | ``301`` | Number of HTTP 301 Moved Permanently responses | number |
+ +----------------+------------------------------------------------------+----------+
+ | ``304`` | Number of HTTP 304 Not Modified responses | number |
+ +----------------+------------------------------------------------------+----------+
+ | ``400`` | Number of HTTP 400 Bad Request responses | number |
+ +----------------+------------------------------------------------------+----------+
+ | ``401`` | Number of HTTP 401 Unauthorized responses | number |
+ +----------------+------------------------------------------------------+----------+
+ | ``403`` | Number of HTTP 403 Forbidden responses | number |
+ +----------------+------------------------------------------------------+----------+
+ | ``404`` | Number of HTTP 404 Not Found responses | number |
+ +----------------+------------------------------------------------------+----------+
+ | ``405`` | Number of HTTP 405 Method Not Allowed responses | number |
+ +----------------+------------------------------------------------------+----------+
+ | ``409`` | Number of HTTP 409 Conflict responses | number |
+ +----------------+------------------------------------------------------+----------+
+ | ``412`` | Number of HTTP 412 Precondition Failed responses | number |
+ +----------------+------------------------------------------------------+----------+
+ | ``500`` | Number of HTTP 500 Internal Server Error responses | number |
+ +----------------+------------------------------------------------------+----------+
+
+- ``httpd``
+
+ +----------------------------------+----------------------------------------------+----------+
+ | Statistic ID | Description | Unit |
+ +==================================+==============================================+==========+
+ | ``bulk_requests`` | Number of bulk requests | number |
+ +----------------------------------+----------------------------------------------+----------+
+ | ``clients_requesting_changes`` | Number of clients for continuous _changes | number |
+ +----------------------------------+----------------------------------------------+----------+
+ | ``requests`` | Number of HTTP requests | number |
+ +----------------------------------+----------------------------------------------+----------+
+ | ``temporary_view_reads`` | Number of temporary view reads | number |
+ +----------------------------------+----------------------------------------------+----------+
+ | ``view_reads`` | Number of view reads | number |
+ +----------------------------------+----------------------------------------------+----------+
+
+You can also access individual statistics by quoting the statistics
+sections and statistic ID as part of the URL path. For example, to get
+the ``request_time`` statistics, you can use:
+
+.. code-block:: http
+
+ GET /_stats/couchdb/request_time
+
+This returns an entire statistics object, as with the full request, but
+containing only the request individual statistic. Hence, the returned
+structure is as follows:
+
+.. code-block:: javascript
+
+ {
+ "couchdb" : {
+ "request_time" : {
+ "stddev" : 7454.305,
+ "min" : 1,
+ "max" : 34185,
+ "current" : 34697.803,
+ "mean" : 1652.276,
+ "sum" : 34697.803,
+ "description" : "length of a request inside CouchDB without MochiWeb"
+ }
+ }
+ }
+
+
+``GET /_utils``
+===============
+
+* **Method**: ``GET /_utils``
+* **Request**: None
+* **Response**: Administration interface
+* **Admin Privileges Required**: no
+
+Accesses the built-in Futon administration interface for CouchDB.
+
+``GET /_uuids``
+===============
+
+* **Method**: ``GET /_uuids``
+* **Request**: None
+* **Response**: List of UUIDs
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: count
+
+ * **Description**: Number of UUIDs to return
+ * **Optional**: yes
+ * **Type**: numeric
+
+* **Return Codes**:
+
+ * **200**:
+ Request completed successfully.
+
+Requests one or more Universally Unique Identifiers (UUIDs) from the
+CouchDB instance. The response is a JSON object providing a list of
+UUIDs. For example:
+
+.. code-block:: javascript
+
+ {
+ "uuids" : [
+ "7e4b5a14b22ec1cf8e58b9cdd0000da3"
+ ]
+ }
+
+You can use the ``count`` argument to specify the number of UUIDs to be
+returned. For example:
+
+.. code-block:: http
+
+ GET http://couchdb:5984/_uuids?count=5
+
+Returns:
+
+.. code-block:: javascript
+
+ {
+ "uuids" : [
+ "c9df0cdf4442f993fc5570225b405a80",
+ "c9df0cdf4442f993fc5570225b405bd2",
+ "c9df0cdf4442f993fc5570225b405e42",
+ "c9df0cdf4442f993fc5570225b4061a0",
+ "c9df0cdf4442f993fc5570225b406a20"
+ ]
+ }
+
+The UUID type is determined by the UUID type setting in the CouchDB
+configuration. See :ref:`api-put-config`.
+
+For example, changing the UUID type to ``random``:
+
+.. code-block:: http
+
+ PUT http://couchdb:5984/_config/uuids/algorithm
+ Content-Type: application/json
+ Accept: */*
+
+ "random"
+
+When obtaining a list of UUIDs:
+
+.. code-block:: javascript
+
+ {
+ "uuids" : [
+ "031aad7b469956cf2826fcb2a9260492",
+ "6ec875e15e6b385120938df18ee8e496",
+ "cff9e881516483911aa2f0e98949092d",
+ "b89d37509d39dd712546f9510d4a9271",
+ "2e0dbf7f6c4ad716f21938a016e4e59f"
+ ]
+ }
+
+``GET /favicon.ico``
+====================
+
+* **Method**: ``GET /favicon.ico``
+* **Request**: None
+* **Response**: Binary content for the `favicon.ico` site icon
+* **Admin Privileges Required**: no
+* **Return Codes**:
+
+ * **200**:
+ Request completed successfully.
+ * **404**:
+ The requested content could not be found. The returned content will include
+ further information, as a JSON object, if available.
+
+Returns the site icon. The return ``Content-Type`` header is
+:mimetype:`image/x-icon`, and the content stream is the image data.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7f66e6f4/share/doc/src/api/reference.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/reference.rst b/share/doc/src/api/reference.rst
new file mode 100644
index 0000000..fce650a
--- /dev/null
+++ b/share/doc/src/api/reference.rst
@@ -0,0 +1,28 @@
+.. 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.
+
+API Reference
+=============
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ configuration
+ authn
+ database
+ documents
+ design
+ misc
+ local
+ dbmaint
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7f66e6f4/share/doc/src/changelog.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/changelog.rst b/share/doc/src/changelog.rst
new file mode 100644
index 0000000..18c19d4
--- /dev/null
+++ b/share/doc/src/changelog.rst
@@ -0,0 +1,1175 @@
+.. 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.
+
+Apache CouchDB CHANGES
+======================
+
+Version 1.3.0
+-------------
+
+.. note:: This version has not been released yet.
+
+Database core
+^^^^^^^^^^^^^
+
+* :issue:`1512`: Validate bind address before assignment. :commit:`09ead8a0`
+* Restore ``max_document_size`` protection. :commit:`bf1eb135`
+
+Documentation
+^^^^^^^^^^^^^
+
+* :issue:`1523`: Import CouchBase documentation and convert them into
+ `Sphinx docs <http://sphinx.pocoo.org/>`_
+
+Futon
+^^^^^
+
+* :issue:`1470`: Futon raises popup on attempt to navigate to missed/deleted
+ document. :commit:`5da40eef`
+* :issue:`1383`: Futon view editor won't allow you to save original view after
+ saving a revision. :commit:`ce48342`
+* :issue:`627`: Support all timezones. :commit:`b1a049bb`
+* :issue:`509`: Added view request duration to Futon. :commit:`2d2c7d1e`
+* :issue:`1473`, :issue:`1472`: Disable buttons for actions that the user
+ doesn't have permissions to. :commit:`7156254d`
+
+HTTP Interface
+^^^^^^^^^^^^^^^^^
+
+* :issue:`1537`: Include user name in show/list `ETags`. :commit:`ac320479`
+* :issue:`1511`: CouchDB checks `roles` field for `_users` database documents
+ with more care. :commit:`41205000`
+* :issue:`1502`: Allow users to delete own _users doc. :commit:`f0d6f19bc8`
+* :issue:`1501`: :ref:`Changes feed <changes>` now can take special parameter
+ ``since=now`` to emit changes since current point of time. :commit:`3bbb2612`
+* :issue:`1442`: No longer rewrites the `X-CouchDB-Requested-Path` during
+ recursive calls to the rewriter. :commit:`56744f2f`
+* :issue:`1441`: Limit recursion depth in the URL rewriter.
+ Defaults to a maximum of 100 invocations but is configurable.
+ :commit:`d076976c`
+* :issue:`1381`: Add jquery.couch support for Windows 8 Metro apps.
+ :commit:`dfc5d37c`
+* :issue:`1337`: Use MD5 for attachment ETag header value. :commit:`6d912c9f`
+* :issue:`1321`: Variables in rewrite rules breaks OAuth authentication.
+ :commit:`c307ba95`
+* :issue:`1285`: Allow configuration of vendor and modules version in CouchDB
+ welcome message. :commit:`3c24a94d`
+* :issue:`1277`: Better query parameter support and code clarity:
+ :commit:`7e3c69ba`
+
+ * Responses to documents created/modified via form data `POST` to /db/doc or
+ copied with `COPY` should now include `Location` header.
+ * Form data POST to /db/doc now includes an `ETag` response header.
+ * ``?batch=ok`` is now supported for `COPY` and `POST` /db/doc updates.
+ * ``?new_edits=false`` is now supported for more operations.
+
+* :issue:`1210`: Files starting with underscore can be attached and updated now.
+ :commit:`05858792`
+* :issue:`1097`: Allow `OPTIONS` request to shows and lists functions.
+ :commit:`9f53704a`
+* :issue:`1026`: Database names are encoded with respect of special characters
+ in the rewriter now. :commit:`272d6415`
+* :issue:`986`: Added Server-Sent Events protocol to db changes API.
+ See http://www.w3.org/TR/eventsource/ for details. :commit:`093d2aa6`
+* :issue:`887`: Fix ``bytes`` and ``offset`` parameters semantic for `_log`
+ resource (`explanation <https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blobdiff;f=src/couchdb/couch_log.erl;h=1b05f4db2;hp=0befe7aab;hb=ad700014;hpb=7809f3ca>`_)
+ :commit:`ad700014`
+* :issue:`764`, :issue:`514`, :issue:`430`: Fix sending HTTP headers from
+ ``_list`` function, :commit:`2a74f88375`
+* Send a 202 response for `_restart`. :commit:`b213e16f`
+* Make password hashing synchronous when using the /_config/admins API.
+ :commit:`08071a80`
+* Fix `_session` for IE7.
+* Return ``X-Couch-Id`` header if doc is created, :commit:`98515bf0b9`
+* Allow any 2xx code to indicate success, :commit:`0d50103cfd`
+* Restore 400 error for empty PUT, :commit:`2057b895`
+* Add support to serve single file with CouchDB, :commit:`2774531ff2`
+* Support auth cookies with ``:`` characters, :commit:`d9566c831d`
+
+Log System
+^^^^^^^^^^
+
+* :issue:`1380`: Minor fixes for logrotate support.
+* Improve file I/O error logging and handling, :commit:`4b6475da`
+* Module Level Logging, :commit:`b58f069167`
+* Log 5xx responses at error level, :commit:`e896b0b7`
+* Log problems opening database at ERROR level except for auto-created
+ system dbs, :commit:`41667642f7`
+
+Replicator
+^^^^^^^^^^
+
+* :issue:`1557`: Upgrade some code to use BIFs bring good improvements for
+ replication.
+* :issue:`1363`: Fix rarely occurred, but still race condition in changes feed
+ if a quick burst of changes happens while replication is starting the
+ replication can go stale. :commit:`573a7bb9`
+* :issue:`1323`: Replicator now acts as standalone application.
+ :commit:`f913ca6e`
+* :issue:`1259`: Stabilize replication id, :commit:`c6252d6d7f`
+* :issue:`1248`: `HTTP 500` error now doesn't occurs when replicating with
+ ``?doc_ids=null``. :commit:`bea76dbf`
+
+Security
+^^^^^^^^
+
+* :issue:`1060`: Passwords are now hashed using the PBKDF2 algorithm with a
+ configurable work factor. :commit:`7d418134`
+
+Source Repository
+^^^^^^^^^^^^^^^^^
+
+* The source repository was migrated from `SVN`_ to `Git`_.
+
+.. _SVN: https://svn.apache.org/repos/asf/couchdb
+.. _Git: https://git-wip-us.apache.org/repos/asf/couchdb.git
+
+Storage System
+^^^^^^^^^^^^^^
+
+* Fixed unnecessary conflict when deleting and creating a
+ document in the same batch.
+
+Test Suite
+^^^^^^^^^^
+
+* :issue:`1563`: Ensures urlPrefix is set in all ajax requests.
+ :commit:`07a6af222`
+* :issue:`1389`: Improved tracebacks printed by the JS CLI tests.
+* :issue:`1339`: Use shell trap to catch dying beam processes during test runs.
+ :commit:`2921c78`
+* :issue:`1338`: Start CouchDB with ``port=0``. While CouchDB might be already
+ running on the default port 5984, port number 0 let the TCP stack figure out a
+ free port to run. :commit:`127cbe3`
+* :issue:`1321`: Moved the JS test suite to the CLI.
+* Improved the reliability of a number of tests.
+* Fix race condition for test running on faster hardware.
+
+URL Rewriter & Vhosts
+^^^^^^^^^^^^^^^^^^^^^
+
+* :issue:`1026`: Database name is encoded during rewriting
+ (allowing embedded /'s, etc). :commit:`272d6415`
+
+UUID Algorithms
+^^^^^^^^^^^^^^^
+
+* :issue:`1373`: Added the utc_id algorithm :commit:`5ab712a2`
+
+Query and View Server
+^^^^^^^^^^^^^^^^^^^^^
+
+* :issue:`1491`: Clenaup view tables. :commit:`c37204b7`
+* :issue:`1483`: Update handlers requires valid doc ids. :commit:`72ea7e38`
+* :issue:`1445`: CouchDB tries no more to delete view file if it couldn't open
+ it, even if the error is `emfile`.
+* :issue:`1444`: Fix missed_named_view error that occurs on existed design
+ documents and views. :commit:`b59ac98b`
+* :issue:`1372`: `_stats` builtin reduce function no longer produces error for
+ empty view result.
+* :issue:`1334`: Speedup in the communication with external view servers.
+ :commit:`a851c6e5`
+* :issue:`410`: More graceful error handling for JavaScript validate_doc_update
+ functions.
+* :issue:`111`: Improve the errors reported by the javascript view server
+ to provide a more friendly error report when something goes wrong.
+ :commit:`0c619ed`
+* Deprecate E4X support, :commit:`cdfdda2314`
+
+Windows
+^^^^^^^
+
+* :issue:`1482`: Use correct linker flang to build `snappy_nif.dll` on Windows.
+ :commit:`a6eaf9f1`
+* Allows building cleanly on Windows without cURL, :commit:`fb670f5712`
+
+
+Version 1.2.0
+-------------
+
+Authentication
+^^^^^^^^^^^^^^
+
+* Fix use of OAuth with VHosts and URL rewriting.
+* OAuth secrets can now be stored in the users system database
+ as an alternative to key value pairs in the .ini configuration.
+ By default this is disabled (secrets are stored in the .ini)
+ but can be enabled via the .ini configuration key `use_users_db`
+ in the `couch_httpd_oauth` section.
+* Documents in the _users database are no longer publicly
+ readable.
+* Confidential information in the _replication database is no
+ longer publicly readable.
+* Password hashes are now calculated by CouchDB. Clients are no
+ longer required to do this manually.
+* Cookies used for authentication can be made persistent by enabling
+ the .ini configuration key `allow_persistent_cookies` in the
+ `couch_httpd_auth` section.
+
+Build System
+^^^^^^^^^^^^
+
+* cURL is no longer required to build CouchDB as it is only
+ used by the command line JS test runner. If cURL is available
+ when building CouchJS you can enable the HTTP bindings by
+ passing -H on the command line.
+* Temporarily made `make check` pass with R15B. A more thorough
+ fix is in the works (:issue:`1424`).
+* Fixed --with-js-include and --with-js-lib options.
+* Added --with-js-lib-name option.
+
+Futon
+^^^^^
+
+* The `Status` screen (active tasks) now displays two new task status
+ fields: `Started on` and `Updated on`.
+* Futon remembers view code every time it is saved, allowing to save an
+ edit that amounts to a revert.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Added a native JSON parser.
+* The _active_tasks API now offers more granular fields. Each
+ task type is now able to expose different properties.
+* Added built-in changes feed filter `_view`.
+* Fixes to the `_changes` feed heartbeat option which caused
+ heartbeats to be missed when used with a filter. This caused
+ timeouts of continuous pull replications with a filter.
+* Properly restart the SSL socket on configuration changes.
+
+Replicator
+^^^^^^^^^^
+
+* A new replicator implementation. It offers more performance and
+ configuration options.
+* Passing non-string values to query_params is now a 400 bad
+ request. This is to reduce the surprise that all parameters
+ are converted to strings internally.
+* Added optional field `since_seq` to replication objects/documents.
+ It allows to bootstrap a replication from a specific source sequence
+ number.
+* Simpler replication cancellation. In addition to the current method,
+ replications can now be canceled by specifying the replication ID
+ instead of the original replication object/document.
+
+Storage System
+^^^^^^^^^^^^^^
+
+* Added optional database and view index file compression (using Google's
+ snappy or zlib's deflate). This feature is enabled by default, but it
+ can be disabled by adapting local.ini accordingly. The on-disk format
+ is upgraded on compaction and new DB/view creation to support this.
+* Several performance improvements, most notably regarding database writes
+ and view indexing.
+* Computation of the size of the latest MVCC snapshot data and all its
+ supporting metadata, both for database and view index files. This
+ information is exposed as the `data_size` attribute in the database and
+ view group information URIs.
+* The size of the buffers used for database and view compaction is now
+ configurable.
+* Added support for automatic database and view compaction. This feature
+ is disabled by default, but it can be enabled via the .ini configuration.
+* Performance improvements for the built-in changes feed filters `_doc_ids`
+ and `_design'.
+
+View Server
+^^^^^^^^^^^
+
+* Add CoffeeScript (http://coffeescript.org/) as a first class view server
+ language.
+* Fixed old index file descriptor leaks after a view cleanup.
+* The requested_path property keeps the pre-rewrite path even when no VHost
+ configuration is matched.
+* Fixed incorrect reduce query results when using pagination parameters.
+* Made icu_driver work with Erlang R15B and later.
+
+OAuth
+^^^^^
+
+* Updated bundled erlang_oauth library to the latest version.
+
+
+Version 1.1.1
+-------------
+
+* Support SpiderMonkey 1.8.5
+* Add configurable maximum to the number of bytes returned by _log.
+* Allow CommonJS modules to be an empty string.
+* Bump minimum Erlang version to R13B02.
+* Do not run deleted validate_doc_update functions.
+* ETags for views include current sequence if include_docs=true.
+* Fix bug where duplicates can appear in _changes feed.
+* Fix bug where update handlers break after conflict resolution.
+* Fix bug with _replicator where include "filter" could crash couch.
+* Fix crashes when compacting large views.
+* Fix file descriptor leak in _log
+* Fix missing revisions in _changes?style=all_docs.
+* Improve handling of compaction at max_dbs_open limit.
+* JSONP responses now send "text/javascript" for Content-Type.
+* Link to ICU 4.2 on Windows.
+* Permit forward slashes in path to update functions.
+* Reap couchjs processes that hit reduce_overflow error.
+* Status code can be specified in update handlers.
+* Support provides() in show functions.
+* _view_cleanup when ddoc has no views now removes all index files.
+* max_replication_retry_count now supports "infinity".
+* Fix replication crash when source database has a document with empty ID.
+* Fix deadlock when assigning couchjs processes to serve requests.
+* Fixes to the document multipart PUT API.
+* Fixes regarding file descriptor leaks for databases with views.
+
+
+Version 1.1.0
+-------------
+
+.. note:: All CHANGES for 1.0.2 and 1.0.3 also apply to 1.1.0.
+
+Externals
+^^^^^^^^^
+
+* Added OS Process module to manage daemons outside of CouchDB.
+* Added HTTP Proxy handler for more scalable externals.
+
+Futon
+^^^^^
+
+* Added a "change password"-feature to Futon.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Native SSL support.
+* Added support for HTTP range requests for attachments.
+* Added built-in filters for `_changes`: `_doc_ids` and `_design`.
+* Added configuration option for TCP_NODELAY aka "Nagle".
+* Allow POSTing arguments to `_changes`.
+* Allow `keys` parameter for GET requests to views.
+* Allow wildcards in vhosts definitions.
+* More granular ETag support for views.
+* More flexible URL rewriter.
+* Added support for recognizing "Q values" and media parameters in
+ HTTP Accept headers.
+* Validate doc ids that come from a PUT to a URL.
+
+Replicator
+^^^^^^^^^^
+
+* Added `_replicator` database to manage replications.
+* Fixed issues when an endpoint is a remote database accessible via SSL.
+* Added support for continuous by-doc-IDs replication.
+* Fix issue where revision info was omitted when replicating attachments.
+* Integrity of attachment replication is now verified by MD5.
+
+Storage System
+^^^^^^^^^^^^^^
+
+* Multiple micro-optimizations when reading data.
+
+URL Rewriter & Vhosts
+^^^^^^^^^^^^^^^^^^^^^
+
+* Fix for variable substituion
+
+View Server
+^^^^^^^^^^^
+
+* Added CommonJS support to map functions.
+* Added `stale=update_after` query option that triggers a view update after
+ returning a `stale=ok` response.
+* Warn about empty result caused by `startkey` and `endkey` limiting.
+* Built-in reduce function `_sum` now accepts lists of integers as input.
+* Added view query aliases start_key, end_key, start_key_doc_id and
+ end_key_doc_id.
+
+
+Version 1.0.3
+-------------
+
+General
+^^^^^^^
+
+* Fixed compatibility issues with Erlang R14B02.
+
+Etap Test Suite
+^^^^^^^^^^^^^^^
+
+* Etap tests no longer require use of port 5984. They now use a randomly
+ selected port so they won't clash with a running CouchDB.
+
+Futon
+^^^^^
+
+* Made compatible with jQuery 1.5.x.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Fix bug that allows invalid UTF-8 after valid escapes.
+* The query parameter `include_docs` now honors the parameter `conflicts`.
+ This applies to queries against map views, _all_docs and _changes.
+* Added support for inclusive_end with reduce views.
+
+Replicator
+^^^^^^^^^^
+
+* Enabled replication over IPv6.
+* Fixed for crashes in continuous and filtered changes feeds.
+* Fixed error when restarting replications in OTP R14B02.
+* Upgrade ibrowse to version 2.2.0.
+* Fixed bug when using a filter and a limit of 1.
+
+Security
+^^^^^^^^
+
+* Fixed OAuth signature computation in OTP R14B02.
+* Handle passwords with : in them.
+
+Storage System
+^^^^^^^^^^^^^^
+
+* More performant queries against _changes and _all_docs when using the
+ `include_docs` parameter.
+
+Windows
+^^^^^^^
+
+* Windows builds now require ICU >= 4.4.0 and Erlang >= R14B03. See
+ :issue:`1152`, and :issue:`963` + OTP-9139 for more information.
+
+
+Version 1.0.2
+-------------
+
+Futon
+^^^^^
+
+* Make test suite work with Safari and Chrome.
+* Fixed animated progress spinner.
+* Fix raw view document link due to overzealous URI encoding.
+* Spell javascript correctly in loadScript(uri).
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Allow reduce=false parameter in map-only views.
+* Fix parsing of Accept headers.
+* Fix for multipart GET APIs when an attachment was created during a
+ local-local replication. See :issue:`1022` for details.
+
+Log System
+^^^^^^^^^^
+
+* Reduce lengthy stack traces.
+* Allow logging of native <xml> types.
+
+Replicator
+^^^^^^^^^^
+
+* Updated ibrowse library to 2.1.2 fixing numerous replication issues.
+* Make sure that the replicator respects HTTP settings defined in the config.
+* Fix error when the ibrowse connection closes unexpectedly.
+* Fix authenticated replication (with HTTP basic auth) of design documents
+ with attachments.
+* Various fixes to make replication more resilient for edge-cases.
+
+Storage System
+^^^^^^^^^^^^^^
+
+* Fix leaking file handles after compacting databases and views.
+* Fix databases forgetting their validation function after compaction.
+* Fix occasional timeout errors after successfully compacting large databases.
+* Fix ocassional error when writing to a database that has just been compacted.
+* Fix occasional timeout errors on systems with slow or heavily loaded IO.
+* Fix for OOME when compactions include documents with many conflicts.
+* Fix for missing attachment compression when MIME types included parameters.
+* Preserve purge metadata during compaction to avoid spurious view rebuilds.
+* Fix spurious conflicts introduced when uploading an attachment after
+ a doc has been in a conflict. See :issue:`902` for details.
+* Fix for frequently edited documents in multi-master deployments being
+ duplicated in _changes and _all_docs. See :issue:`968` for details on how
+ to repair.
+* Significantly higher read and write throughput against database and
+ view index files.
+
+View Server
+^^^^^^^^^^^
+
+* Don't trigger view updates when requesting `_design/doc/_info`.
+* Fix for circular references in CommonJS requires.
+* Made isArray() function available to functions executed in the query server.
+* Documents are now sealed before being passed to map functions.
+* Force view compaction failure when duplicated document data exists. When
+ this error is seen in the logs users should rebuild their views from
+ scratch to fix the issue. See :issue:`999` for details.
+
+
+Version 1.0.1
+-------------
+
+Authentication
+^^^^^^^^^^^^^^
+
+* Enable basic-auth popup when required to access the server, to prevent
+ people from getting locked out.
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Included additional source files for distribution.
+
+Futon
+^^^^^
+
+* User interface element for querying stale (cached) views.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Expose `committed_update_seq` for monitoring purposes.
+* Show fields saved along with _deleted=true. Allows for auditing of deletes.
+* More robust Accept-header detection.
+
+Replicator
+^^^^^^^^^^
+
+* Added support for replication via an HTTP/HTTPS proxy.
+* Fix pull replication of attachments from 0.11 to 1.0.x.
+* Make the _changes feed work with non-integer seqnums.
+
+Storage System
+^^^^^^^^^^^^^^
+
+* Fix data corruption bug :issue:`844`. Please see
+ http://couchdb.apache.org/notice/1.0.1.html for details.
+
+
+Version 1.0.0
+-------------
+
+Security
+^^^^^^^^
+
+* Added authentication caching, to avoid repeated opening and closing of the
+ users database for each request requiring authentication.
+
+Storage System
+^^^^^^^^^^^^^^
+
+* Small optimization for reordering result lists.
+* More efficient header commits.
+* Use O_APPEND to save lseeks.
+* Faster implementation of pread_iolist(). Further improves performance on
+ concurrent reads.
+
+View Server
+^^^^^^^^^^^
+
+* Faster default view collation.
+* Added option to include update_seq in view responses.
+
+
+Version 0.11.2
+--------------
+
+Authentication
+^^^^^^^^^^^^^^
+
+* User documents can now be deleted by admins or the user.
+
+Futon
+^^^^^
+
+* Add some Futon files that were missing from the Makefile.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Better error messages on invalid URL requests.
+
+Replicator
+^^^^^^^^^^
+
+* Fix bug when pushing design docs by non-admins, which was hanging the
+ replicator for no good reason.
+* Fix bug when pulling design documents from a source that requires
+ basic-auth.
+
+Security
+^^^^^^^^
+
+* Avoid potential DOS attack by guarding all creation of atoms.
+
+
+Version 0.11.1
+--------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Output of `couchdb --help` has been improved.
+* Fixed compatibility with the Erlang R14 series.
+* Fixed warnings on Linux builds.
+* Fixed build error when aclocal needs to be called during the build.
+* Require ICU 4.3.1.
+* Fixed compatibility with Solaris.
+
+Configuration System
+^^^^^^^^^^^^^^^^^^^^
+
+* Fixed timeout with large .ini files.
+
+Futon
+^^^^^
+
+* Use "expando links" for over-long document values in Futon.
+* Added continuous replication option.
+* Added option to replicating test results anonymously to a community
+ CouchDB instance.
+* Allow creation and deletion of config entries.
+* Fixed display issues with doc ids that have escaped characters.
+* Fixed various UI issues.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Mask passwords in active tasks and logging.
+* Update mochijson2 to allow output of BigNums not in float form.
+* Added support for X-HTTP-METHOD-OVERRIDE.
+* Better error message for database names.
+* Disable jsonp by default.
+* Accept gzip encoded standalone attachments.
+* Made max_concurrent_connections configurable.
+* Made changes API more robust.
+* Send newly generated document rev to callers of an update function.
+
+JavaScript Clients
+^^^^^^^^^^^^^^^^^^
+
+* Added tests for couch.js and jquery.couch.js
+* Added changes handler to jquery.couch.js.
+* Added cache busting to jquery.couch.js if the user agent is msie.
+* Added support for multi-document-fetch (via _all_docs) to jquery.couch.js.
+* Added attachment versioning to jquery.couch.js.
+* Added option to control ensure_full_commit to jquery.couch.js.
+* Added list functionality to jquery.couch.js.
+* Fixed issues where bulkSave() wasn't sending a POST body.
+
+Log System
+^^^^^^^^^^
+
+* Log HEAD requests as HEAD, not GET.
+* Keep massive JSON blobs out of the error log.
+* Fixed a timeout issue.
+
+Replication System
+^^^^^^^^^^^^^^^^^^
+
+* Refactored various internal APIs related to attachment streaming.
+* Fixed hanging replication.
+* Fixed keepalive issue.
+
+Security
+^^^^^^^^
+
+* Added authentication redirect URL to log in clients.
+* Fixed query parameter encoding issue in oauth.js.
+* Made authentication timeout configurable.
+* Temporary views are now admin-only resources.
+
+Storage System
+^^^^^^^^^^^^^^
+
+* Don't require a revpos for attachment stubs.
+* Added checking to ensure when a revpos is sent with an attachment stub,
+ it's correct.
+* Make file deletions async to avoid pauses during compaction and db
+ deletion.
+* Fixed for wrong offset when writing headers and converting them to blocks,
+ only triggered when header is larger than 4k.
+* Preserve _revs_limit and instance_start_time after compaction.
+
+Test Suite
+^^^^^^^^^^
+
+* Made the test suite overall more reliable.
+
+View Server
+^^^^^^^^^^^
+
+* Provide a UUID to update functions (and all other functions) that they can
+ use to create new docs.
+* Upgrade CommonJS modules support to 1.1.1.
+* Fixed erlang filter funs and normalize filter fun API.
+* Fixed hang in view shutdown.
+
+URL Rewriter & Vhosts
+^^^^^^^^^^^^^^^^^^^^^
+
+* Allow more complex keys in rewriter.
+* Allow global rewrites so system defaults are available in vhosts.
+* Allow isolation of databases with vhosts.
+* Fix issue with passing variables to query parameters.
+
+
+Version 0.11.0
+--------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Updated and improved source documentation.
+* Fixed distribution preparation for building on Mac OS X.
+* Added support for building a Windows installer as part of 'make dist'.
+* Bug fix for building couch.app's module list.
+* ETap tests are now run during make distcheck. This included a number of
+ updates to the build system to properly support VPATH builds.
+* Gavin McDonald setup a build-bot instance. More info can be found at
+ http://ci.apache.org/buildbot.html
+
+Futon
+^^^^^
+
+* Added a button for view compaction.
+* JSON strings are now displayed as-is in the document view, without the
+ escaping of new-lines and quotes. That dramatically improves readability of
+ multi-line strings.
+* Same goes for editing of JSON string values. When a change to a field value is
+ submitted, and the value is not valid JSON it is assumed to be a string. This
+ improves editing of multi-line strings a lot.
+* Hitting tab in textareas no longer moves focus to the next form field, but
+ simply inserts a tab character at the current caret position.
+* Fixed some font declarations.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Provide Content-MD5 header support for attachments.
+* Added URL Rewriter handler.
+* Added virtual host handling.
+
+Replication
+^^^^^^^^^^^
+
+* Added option to implicitly create replication target databases.
+* Avoid leaking file descriptors on automatic replication restarts.
+* Added option to replicate a list of documents by id.
+* Allow continuous replication to be cancelled.
+
+Runtime Statistics
+^^^^^^^^^^^^^^^^^^
+
+* Statistics are now calculated for a moving window instead of non-overlapping
+ timeframes.
+* Fixed a problem with statistics timers and system sleep.
+* Moved statistic names to a term file in the priv directory.
+
+Security
+^^^^^^^^
+
+* Fixed CVE-2010-0009: Apache CouchDB Timing Attack Vulnerability.
+* Added default cookie-authentication and users database.
+* Added Futon user interface for user signup and login.
+* Added per-database reader access control lists.
+* Added per-database security object for configuration data in validation
+ functions.
+* Added proxy authentication handler
+
+Storage System
+^^^^^^^^^^^^^^
+
+* Adds batching of multiple updating requests, to improve throughput with many
+ writers. Removed the now redundant couch_batch_save module.
+* Adds configurable compression of attachments.
+
+View Server
+^^^^^^^^^^^
+
+* Added optional 'raw' binary collation for faster view builds where Unicode
+ collation is not important.
+* Improved view index build time by reducing ICU collation callouts.
+* Improved view information objects.
+* Bug fix for partial updates during view builds.
+* Move query server to a design-doc based protocol.
+* Use json2.js for JSON serialization for compatiblity with native JSON.
+* Major refactoring of couchjs to lay the groundwork for disabling cURL
+ support. The new HTTP interaction acts like a synchronous XHR. Example usage
+ of the new system is in the JavaScript CLI test runner.
+
+
+
+
+Version 0.10.1
+--------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Test suite now works with the distcheck target.
+
+Replicator
+^^^^^^^^^^
+
+* Stability enhancements regarding redirects, timeouts, OAuth.
+
+Query Server
+^^^^^^^^^^^^
+
+* Avoid process leaks
+* Allow list and view to span languages
+
+Stats
+^^^^^
+
+* Eliminate new process flood on system wake
+
+
+Version 0.10.0
+--------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Changed `couchdb` script configuration options.
+* Added default.d and local.d configuration directories to load sequence.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Added optional cookie-based authentication handler.
+* Added optional two-legged OAuth authentication handler.
+
+Storage Format
+^^^^^^^^^^^^^^
+
+* Add move headers with checksums to the end of database files for extra robust
+ storage and faster storage.
+
+View Server
+^^^^^^^^^^^
+
+* Added native Erlang views for high-performance applications.
+
+
+Version 0.9.2
+-------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Remove branch callbacks to allow building couchjs against newer versions of
+ Spidermonkey.
+
+Replication
+^^^^^^^^^^^
+
+* Fix replication with 0.10 servers initiated by an 0.9 server (:issue:`559`).
+
+
+Version 0.9.1
+-------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* PID file directory is now created by the SysV/BSD daemon scripts.
+* Fixed the environment variables shown by the configure script.
+* Fixed the build instructions shown by the configure script.
+* Updated ownership and permission advice in `README` for better security.
+
+Configuration and stats system
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Corrected missing configuration file error message.
+* Fixed incorrect recording of request time.
+
+Database Core
+^^^^^^^^^^^^^
+
+* Document validation for underscore prefixed variables.
+* Made attachment storage less sparse.
+* Fixed problems when a database with delayed commits pending is considered
+ idle, and subject to losing changes when shutdown. (:issue:`334`)
+
+External Handlers
+^^^^^^^^^^^^^^^^^
+
+* Fix POST requests.
+
+Futon
+^^^^^
+
+* Redirect when loading a deleted view URI from the cookie.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Attachment requests respect the "rev" query-string parameter.
+
+JavaScript View Server
+^^^^^^^^^^^^^^^^^^^^^^
+
+* Useful JavaScript Error messages.
+
+Replication
+^^^^^^^^^^^
+
+* Added support for Unicode characters transmitted as UTF-16 surrogate pairs.
+* URL-encode attachment names when necessary.
+* Pull specific revisions of an attachment, instead of just the latest one.
+* Work around a rare chunk-merging problem in ibrowse.
+* Work with documents containing Unicode characters outside the Basic
+ Multilingual Plane.
+
+
+Version 0.9.0
+-------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* The `couchdb` script now supports system chainable configuration files.
+* The Mac OS X daemon script now redirects STDOUT and STDERR like SysV/BSD.
+* The build and system integration have been improved for portability.
+* Added COUCHDB_OPTIONS to etc/default/couchdb file.
+* Remove COUCHDB_INI_FILE and COUCHDB_PID_FILE from etc/default/couchdb file.
+* Updated `configure.ac` to manually link `libm` for portability.
+* Updated `configure.ac` to extended default library paths.
+* Removed inets configuration files.
+* Added command line test runner.
+* Created dev target for make.
+
+Configuration and stats system
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Separate default and local configuration files.
+* HTTP interface for configuration changes.
+* Statistics framework with HTTP query API.
+
+Database Core
+^^^^^^^^^^^^^
+
+* Faster B-tree implementation.
+* Changed internal JSON term format.
+* Improvements to Erlang VM interactions under heavy load.
+* User context and administrator role.
+* Update validations with design document validation functions.
+* Document purge functionality.
+* Ref-counting for database file handles.
+
+Design Document Resource Paths
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Added httpd_design_handlers config section.
+* Moved _view to httpd_design_handlers.
+* Added ability to render documents as non-JSON content-types with _show and
+ _list functions, which are also httpd_design_handlers.
+
+Futon Utility Client
+^^^^^^^^^^^^^^^^^^^^
+
+* Added pagination to the database listing page.
+* Implemented attachment uploading from the document page.
+* Added page that shows the current configuration, and allows modification of
+ option values.
+* Added a JSON "source view" for document display.
+* JSON data in view rows is now syntax highlighted.
+* Removed the use of an iframe for better integration with browser history and
+ bookmarking.
+* Full database listing in the sidebar has been replaced by a short list of
+ recent databases.
+* The view editor now allows selection of the view language if there is more
+ than one configured.
+* Added links to go to the raw view or document URI.
+* Added status page to display currently running tasks in CouchDB.
+* JavaScript test suite split into multiple files.
+* Pagination for reduce views.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Added client side UUIDs for idempotent document creation
+* HTTP COPY for documents
+* Streaming of chunked attachment PUTs to disk
+* Remove negative count feature
+* Add include_docs option for view queries
+* Add multi-key view post for views
+* Query parameter validation
+* Use stale=ok to request potentially cached view index
+* External query handler module for full-text or other indexers.
+* Etags for attachments, views, shows and lists
+* Show and list functions for rendering documents and views as developer
+ controlled content-types.
+* Attachment names may use slashes to allow uploading of nested directories
+ (useful for static web hosting).
+* Option for a view to run over design documents.
+* Added newline to JSON responses. Closes bike-shed.
+
+Replication
+^^^^^^^^^^^
+
+* Using ibrowse.
+* Checkpoint replications so failures are less expensive.
+* Automatically retry of failed replications.
+* Stream attachments in pull-replication.
+
+
+Version 0.8.1-incubating
+------------------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* The `couchdb` script no longer uses `awk` for configuration checks as this
+ was causing portability problems.
+* Updated `sudo` example in `README` to use the `-i` option, this fixes
+ problems when invoking from a directory the `couchdb` user cannot access.
+
+Database Core
+^^^^^^^^^^^^^
+
+* Fix for replication problems where the write queues can get backed up if the
+ writes aren't happening fast enough to keep up with the reads. For a large
+ replication, this can exhaust memory and crash, or slow down the machine
+ dramatically. The fix keeps only one document in the write queue at a time.
+* Fix for databases sometimes incorrectly reporting that they contain 0
+ documents after compaction.
+* CouchDB now uses ibrowse instead of inets for its internal HTTP client
+ implementation. This means better replication stability.
+
+Futon
+^^^^^
+
+* The view selector dropdown should now work in Opera and Internet Explorer
+ even when it includes optgroups for design documents. (:issue:`81`)
+
+JavaScript View Server
+^^^^^^^^^^^^^^^^^^^^^^
+
+* Sealing of documents has been disabled due to an incompatibility with
+ SpiderMonkey 1.9.
+* Improve error handling for undefined values emitted by map functions.
+ (:issue:`83`)
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Fix for chunked responses where chunks were always being split into multiple
+ TCP packets, which caused problems with the test suite under Safari, and in
+ some other cases.
+* Fix for an invalid JSON response body being returned for some kinds of
+ views. (:issue:`84`)
+* Fix for connections not getting closed after rejecting a chunked request.
+ (:issue:`55`)
+* CouchDB can now be bound to IPv6 addresses.
+* The HTTP `Server` header now contains the versions of CouchDB and Erlang.
+
+
+Version 0.8.0-incubating
+------------------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* CouchDB can automatically respawn following a server crash.
+* Database server no longer refuses to start with a stale PID file.
+* System logrotate configuration provided.
+* Improved handling of ICU shared libraries.
+* The `couchdb` script now automatically enables SMP support in Erlang.
+* The `couchdb` and `couchjs` scripts have been improved for portability.
+* The build and system integration have been improved for portability.
+
+Database Core
+^^^^^^^^^^^^^
+
+* The view engine has been completely decoupled from the storage engine. Index
+ data is now stored in separate files, and the format of the main database
+ file has changed.
+* Databases can now be compacted to reclaim space used for deleted documents
+ and old document revisions.
+* Support for incremental map/reduce views has been added.
+* To support map/reduce, the structure of design documents has changed. View
+ values are now JSON objects containing at least a `map` member, and
+ optionally a `reduce` member.
+* View servers are now identified by name (for example `javascript`) instead of
+ by media type.
+* Automatically generated document IDs are now based on proper UUID generation
+ using the crypto module.
+* The field `content-type` in the JSON representation of attachments has been
+ renamed to `content_type` (underscore).
+
+Futon
+^^^^^
+
+* When adding a field to a document, Futon now just adds a field with an
+ autogenerated name instead of prompting for the name with a dialog. The name
+ is automatically put into edit mode so that it can be changed immediately.
+* Fields are now sorted alphabetically by name when a document is displayed.
+* Futon can be used to create and update permanent views.
+* The maximum number of rows to display per page on the database page can now
+ be adjusted.
+* Futon now uses the XMLHTTPRequest API asynchronously to communicate with the
+ CouchDB HTTP server, so that most operations no longer block the browser.
+* View results sorting can now be switched between ascending and descending by
+ clicking on the `Key` column header.
+* Fixed a bug where documents that contained a `@` character could not be
+ viewed. (:issue:`12`)
+* The database page now provides a `Compact` button to trigger database
+ compaction. (:issue:`38`)
+* Fixed portential double encoding of document IDs and other URI segments in
+ many instances. (:issue:`39`)
+* Improved display of attachments.
+* The JavaScript Shell has been removed due to unresolved licensing issues.
+
+JavaScript View Server
+^^^^^^^^^^^^^^^^^^^^^^
+
+* SpiderMonkey is no longer included with CouchDB, but rather treated as a
+ normal external dependency. A simple C program (`_couchjs`) is provided that
+ links against an existing SpiderMonkey installation and uses the interpreter
+ embedding API.
+* View functions using the default JavaScript view server can now do logging
+ using the global `log(message)` function. Log messages are directed into the
+ CouchDB log at `INFO` level. (:issue:`59`)
+* The global `map(key, value)` function made available to view code has been
+ renamed to `emit(key, value)`.
+* Fixed handling of exceptions raised by view functions.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* CouchDB now uses MochiWeb instead of inets for the HTTP server
+ implementation. Among other things, this means that the extra configuration
+ files needed for inets (such as `couch_httpd.conf`) are no longer used.
+* The HTTP interface now completely supports the `HEAD` method. (:issue:`3`)
+* Improved compliance of `Etag` handling with the HTTP specification.
+ (:issue:`13`)
+* Etags are no longer included in responses to document `GET` requests that
+ include query string parameters causing the JSON response to change without
+ the revision or the URI having changed.
+* The bulk document update API has changed slightly on both the request and the
+ response side. In addition, bulk updates are now atomic.
+* CouchDB now uses `TCP_NODELAY` to fix performance problems with persistent
+ connections on some platforms due to nagling.
+* Including a `?descending=false` query string parameter in requests to views
+ no longer raises an error.
+* Requests to unknown top-level reserved URLs (anything with a leading
+ underscore) now return a `unknown_private_path` error instead of the
+ confusing `illegal_database_name`.
+* The Temporary view handling now expects a JSON request body, where the JSON
+ is an object with at least a `map` member, and optional `reduce` and
+ `language` members.
+* Temporary views no longer determine the view server based on the Content-Type
+ header of the `POST` request, but rather by looking for a `language` member
+ in the JSON body of the request.
+* The status code of responses to `DELETE` requests is now 200 to reflect that
+ that the deletion is performed synchronously.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7f66e6f4/share/doc/src/changes.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/changes.rst b/share/doc/src/changes.rst
new file mode 100644
index 0000000..0d98c86
--- /dev/null
+++ b/share/doc/src/changes.rst
@@ -0,0 +1,214 @@
+.. 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.
+
+.. _changes:
+
+============
+Changes Feed
+============
+
+Polling
+=======
+
+A list of changes made to documents in the database, in the order they were
+made, can be obtained from the database's ``_changes`` resource. You can query
+the ``_changes`` resource by issuing a ``GET`` request with the following
+(optional) parameters:
+
++--------------+----------------------------------------------+---------------+--------------+
+| Parameter | Value | Default Value | Notes |
++==============+==============================================+===============+==============+
+| since | seqnum / now | 0 | \(1) |
++--------------+----------------------------------------------+---------------+--------------+
+| limit | maxsequences | none | \(2) |
++--------------+----------------------------------------------+---------------+--------------+
+| descending | boolean | false | \(3) |
++--------------+----------------------------------------------+---------------+--------------+
+| feed | normal / longpoll / continuous / eventsource | normal | \(4) |
++--------------+----------------------------------------------+---------------+--------------+
+| heartbeat | milliseconds | 60000 | \(5) |
++--------------+----------------------------------------------+---------------+--------------+
+| timeout | milliseconds | 60000 | \(6) |
++--------------+----------------------------------------------+---------------+--------------+
+| filter | designdoc/filtername / _view | none | \(7) |
++--------------+----------------------------------------------+---------------+--------------+
+| include_docs | boolean | false | \(8) |
++--------------+----------------------------------------------+---------------+--------------+
+| style | all_docs / main_only | main_only | \(9) |
++--------------+----------------------------------------------+---------------+--------------+
+| view | designdoc/filtername | none | \(10) |
++--------------+----------------------------------------------+---------------+--------------+
+
+Notes:
+
+(1) Start the results from the change immediately after the given sequence
+ number.
+
+(2) Limit number of result rows to the specified value (note that using 0 here
+ has the same effect as 1).
+
+(3) Return the change results in descending sequence order (most recent change
+ first)
+
+(4) Select the type of feed.
+
+(5) Period in milliseconds after which an empty line is sent in the results.
+ Only applicable for `longpoll` or `continuous` feeds. Overrides any timeout
+ to keep the feed alive indefinitely.
+
+(6) Maximum period in milliseconds to wait for a change before the response is
+ sent, even if there are no results. Only applicable for `longpoll` or
+ `continuous` feeds. Note that 60000 is also the default maximum timeout to
+ prevent undetected dead connections.
+
+ You can change the default maximum timeout in your ini-configuration:
+
+ .. code-block:: ini
+
+ [httpd]
+ changes_timeout=#millisecs
+
+(7) Reference to a :ref:`filter function <filterfun>` from a design document
+ that will filter whole stream emitting only filtered events.
+ See the `section in the book`_ for more information.
+
+(8) Include the associated document with each result. If there are conflicts,
+ only the winning revision is returned.
+
+(9) Specifies how many revisions are returned in the changes array.
+ The default, `main_only`, will only return the current "winning" revision;
+ `all_docs` will return all leaf revisions (including conflicts and deleted
+ former conflicts.)
+
+(10) Allows to use view functions as filters. It requires to set ``filter``
+ special value `_view` to enable this feature. Documents counted as "passed"
+ for view filter in case if map function emits at least one record for them.
+
+.. versionchanged:: 0.11.0 added ``include_docs`` parameter
+.. versionchanged:: 1.2.0 added ``view`` parameter and special value `_view`
+ for ``filter`` one
+.. versionchanged:: 1.3.0 ``since`` parameter could take `now` value to start
+ listen changes since current seq number.
+.. versionchanged:: 1.3.0 ``eventsource`` feed type added.
+
+By default all changes are immediately returned as a JSON object::
+
+ GET /somedatabase/_changes HTTP/1.1
+
+.. code-block:: javascript
+
+ {"results":[
+ {"seq":1,"id":"fresh","changes":[{"rev":"1-967a00dff5e02add41819138abb3284d"}]},
+ {"seq":3,"id":"updated","changes":[{"rev":"2-7051cbe5c8faecd085a3fa619e6e6337"}]},
+ {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
+ ],
+ "last_seq":5}
+
+``results`` is the list of changes in sequential order. New and changed
+documents only differ in the value of the rev; deleted documents include the
+``"deleted": true`` attribute. (In the ``style=all_docs mode``, deleted applies
+only to the current/winning revision. The other revisions listed might be
+deleted even if there is no deleted property; you have to ``GET`` them
+individually to make sure.)
+
+``last_seq`` is the sequence number of the last update returned. (Currently it
+will always be the same as the seq of the last item in results.)
+
+Sending a ``since`` param in the query string skips all changes up to and
+including the given sequence number::
+
+ GET /somedatabase/_changes?since=3 HTTP/1.1
+
+.. code-block:: javascript
+
+ {"results":[
+ {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
+ ],
+ "last_seq":5}
+
+Long Polling
+============
+
+The `longpoll` feed (probably most useful used from a browser) is a more
+efficient form of polling that waits for a change to occur before the response
+is sent. `longpoll` avoids the need to frequently poll CouchDB to discover
+nothing has changed!
+
+The response is basically the same JSON as is sent for the normal feed.
+
+A timeout limits the maximum length of time the connection is open. If there
+are no changes before the timeout expires the response's results will be an
+empty list.
+
+Continuous
+==========
+
+Polling the CouchDB server is not a good thing to do. Setting up new HTTP
+connections just to tell the client that nothing happened puts unnecessary
+strain on CouchDB.
+
+A continuous feed stays open and connected to the database until explicitly
+closed and changes are sent to the client as they happen, i.e. in near
+real-time.
+
+The continuous feed's response is a little different than the other feed types
+to simplify the job of the client - each line of the response is either empty
+or a JSON object representing a single change, as found in the normal feed's
+results.
+
+.. code-block:: text
+
+ GET /somedatabase/_changes?feed=continuous HTTP/1.1
+
+.. code-block:: javascript
+
+ {"seq":1,"id":"fresh","changes":[{"rev":"1-967a00dff5e02add41819138abb3284d"}]}
+ {"seq":3,"id":"updated","changes":[{"rev":"2-7051cbe5c8faecd085a3fa619e6e6337"}]}
+ {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
+ ... tum tee tum ...
+ {"seq":6,"id":"updated","changes":[{"rev":"3-825cb35de44c433bfb2df415563a19de"}]}
+
+Obviously, `... tum tee tum ...` does not appear in the actual response, but
+represents a long pause before the change with seq 6 occurred.
+
+.. _section in the book: http://books.couchdb.org/relax/reference/change-notifications
+
+Event Source
+============
+
+The `eventsource` feed provides push notifications that can be consumed in
+the form of DOM events in the browser. Refer to theW3C specification for
+`W3 eventsource specification`_ for further details.
+
+.. code-block:: text
+
+ GET /somedatabase/_changes?feed=eventsource HTTP/1.1
+
+.. code-block:: javascript
+
+ // define the event handling function
+ if (window.EventSource) {
+ var source = new EventSource(
+ "/somedatabase/_changes?feed=eventsource");
+ var results = [];
+ var sourceListener = function(e) {
+ var data = JSON.parse(e.data);
+ results.push(data);
+ };
+
+ // start listening for events
+ source.addEventListener('message', sourceListener , false);
+
+ // stop listening for events
+ source.removeEventListener('message', sourceListener , false);
+
+.. _W3 eventsource specification: http://www.w3.org/TR/eventsource/
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7f66e6f4/share/doc/src/commonjs.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/commonjs.rst b/share/doc/src/commonjs.rst
new file mode 100644
index 0000000..49ccaa6
--- /dev/null
+++ b/share/doc/src/commonjs.rst
@@ -0,0 +1,56 @@
+.. 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.
+
+.. _commonjs:
+
+CommonJS support for map functions
+==================================
+
+CommonJS support allows you to use `CommonJS notation <http://commonjs.org/specs>`_
+inside map and reduce functions, but only of libraries that are stored
+inside the views part of the design doc.
+
+So you could continue to access CommonJS code in design\_doc.foo, from
+your list functions etc, but we'd add the ability to require CommonJS
+modules within map and reduce, but only from ``design_doc.views.lib``.
+
+There's no worry here about namespace collisions, as Couch just plucks
+``views.*.map`` and ``views.*.reduce`` out of the design doc. So you
+could have a view called ``lib`` if you wanted, and still have CommonJS
+stored in ``views.lib.sha1`` and ``views.lib.stemmer`` if you wanted.
+
+The implementation is simplified by enforcing that CommonJS modules to
+be used in map functions be stored in views.lib.
+
+A sample design doc (taken from the test suite in Futon) is below:
+
+.. code-block:: javascript
+
+ {
+ "views" : {
+ "lib" : {
+ "baz" : "exports.baz = 'bam';",
+ "foo" : {
+ "zoom" : "exports.zoom = 'yeah';",
+ "boom" : "exports.boom = 'ok';",
+ "foo" : "exports.foo = 'bar';"
+ }
+ },
+ "commonjs" : {
+ "map" : "function(doc) { emit(null, require('views/lib/foo/boom').boom)}"
+ }
+ },
+ "_id" : "_design/test"
+ }
+
+The ``require()`` statement is relative to the design document, but
+anything loaded form outside of ``views/lib`` will fail.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7f66e6f4/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
new file mode 100644
index 0000000..26974fc
--- /dev/null
+++ b/share/doc/src/conf.py
@@ -0,0 +1,88 @@
+## 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.
+
+import sys, os
+
+extensions = ["sphinx.ext.todo", "sphinx.ext.extlinks"]
+
+source_suffix = ".rst"
+
+master_doc = "index"
+
+nitpicky = True
+
+version = "1.3"
+
+release = "1.3.0"
+
+project = u"Apache CouchDB"
+
+copyright = u"2012, The Apache Software Foundation"
+
+highlight_language = "json"
+
+pygments_style = "sphinx"
+
+html_theme = "default"
+
+templates_path = ["../templates"]
+
+html_static_path = ["../static"]
+
+html_title = "Apache CouchDB " + version + " Manual"
+
+html_style = "rtd.css"
+
+html_logo = "../images/logo.png"
+
+html_favicon = "../images/favicon.ico"
+
+html_sidebars= {
+ "**": [
+ "searchbox.html",
+ "localtoc.html",
+ "relations.html",
+ "utilities.html",
+ "help.html",
+ ]
+}
+
+text_newlines = "native"
+
+latex_documents = [(
+ "index",
+ "CouchDB.tex",
+ project,
+ "",
+ "manual",
+ True
+)]
+
+latex_elements = {
+ "papersize":"a4paper"
+}
+
+texinfo_documents = [(
+ "index",
+ "CouchDB",
+ project,
+ "",
+ "CouchDB",
+ "The Apache CouchDB database",
+ "Databases",
+ True
+)]
+
+extlinks = {
+ 'issue': ('https://issues.apache.org/jira/browse/COUCHDB-%s', 'COUCHDB-'),
+ 'commit': ('https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=commit;h=%s', '#')
+}