[2/7] git commit: updated refs/heads/1846-dev-server-improvements to 98a4a1b

[ga...@apache.org]

Expanded description of the validate_doc_update function


Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/ef9ac469
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/ef9ac469
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/ef9ac469

Branch: refs/heads/1846-dev-server-improvements
Commit: ef9ac4699b9d68bdf1d5f0ae0169867af593795c
Parents: 1da6773
Author: Paul Mietz Egli <pa...@obscure.com>
Authored: Wed Jul 3 22:28:00 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Wed Jul 3 22:28:00 2013 +0400

----------------------------------------------------------------------
 share/doc/src/ddocs.rst | 39 +++++++++++++++++++++++++++++++++------
 1 file changed, 33 insertions(+), 6 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/couchdb/blob/ef9ac469/share/doc/src/ddocs.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/ddocs.rst b/share/doc/src/ddocs.rst
index ada5b0d..0bb2c9d 100644
--- a/share/doc/src/ddocs.rst
+++ b/share/doc/src/ddocs.rst
@@ -575,14 +575,41 @@ Validate document update functions
    :param secObj: :ref:`security_object`
 
    :throws: ``forbidden`` error to gracefully prevent document storing.
+   :throws: ``unauthorized`` error to prevent storage and allow the user to
+            re-auth.
+
+A design document may contain a function named `validate_doc_update`
+which can be used to prevent invalid or unauthorized document update requests
+from being stored.  The function is passed the new document from the update
+request, the current document stored in the database, a :ref:`userctx_object`
+containing information about the user writing the document (if present), and
+a :ref:`security_object` with lists of database security roles.
+
+Validation functions typically examine the structure of the new document to
+ensure that required fields are present and to verify that the requesting user
+should be allowed to make changes to the document properties.  For example,
+an application may require that a user must be authenticated in order to create
+a new document or that specific document fields be present when a document
+is updated. The validation function can abort the pending document write
+by throwing one of two error objects:
 
-To perform validate operations on document saving there is a special design
-function type called `validate_doc_update`.
+.. code-block:: javascript
 
-Instead of thousands words take a look at the next example of validate
-function - this function is used in ``_design/_auth`` ddoc from `_users`
-database to control users documents required field set and modification
-permissions:
+  // user is not authorized to make the change but may re-authenticate
+  throw({ unauthorized: 'Error message here.' });
+  
+  // change is not allowed
+  throw({ forbidden: 'Error message here.' });
+
+Document validation is optional, and each design document in the database may
+have at most one validation function.  When a write request is received for
+a given database, the validation function in each design document in that
+database is called in an unspecified order.  If any of the validation functions
+throw an error, the write will not succeed.
+
+**Example**: The ``_design/_auth`` ddoc from `_users` database uses a validation
+function to ensure that documents contain some required fields and are only
+modified by a user with the ``_admin`` role:
 
 .. code-block:: javascript