Updated Branches: refs/heads/master 1da677397 -> ef9ac4699
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/master Commit: ef9ac4699b9d68bdf1d5f0ae0169867af593795c Parents: 1da6773 Author: Paul Mietz Egli <[email protected]> Authored: Wed Jul 3 22:28:00 2013 +0400 Committer: Alexander Shorin <[email protected]> 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
