CDRIVER-5721 document bson_validate_with_error_and_offset() (#1769)

* document bson_validate_with_error_and_offset
* move bson_validate_flags_t docs to a standalone page
* update libbson.inv
* opts_templates: fix missing copyright header in mongoc-opts-private.h
* build/generate-opts.py

Author: Micah Scott @ MongoDB

build/generate-opts.py

@@ -115,7 +115,7 @@ def __init__(self, items, **defaults):
 validate_option = ('validate', {
     'type': 'bson_validate_flags_t',
     'convert': '_mongoc_convert_validate_flags',
-    'help': 'Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t <bson_validate_with_error>`. Set to ``false`` to skip client-side validation of the provided BSON documents.'
+    'help': 'Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t`. Set to ``false`` to skip client-side validation of the provided BSON documents.'
 })
 
 collation_option = ('collation', {

build/opts_templates/mongoc-opts-private.h.template

@@ -1,3 +1,19 @@
+/*
+ * Copyright 2009-present MongoDB, Inc.
+ *
+ * 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.
+ */
+
 #include "mongoc-prelude.h"
 
 #ifndef MONGOC_OPTS_H

src/libbson/doc/api.rst

@@ -19,6 +19,7 @@ API Reference
   bson_subtype_t
   bson_type_t
   bson_unichar_t
+  bson_validate_flags_t
   bson_value_t
   bson_visitor_t
   bson_writer_t

src/libbson/doc/bson_t.rst

@@ -225,6 +225,7 @@ BSON document contains duplicate keys.
     bson_steal
     bson_validate
     bson_validate_with_error
+    bson_validate_with_error_and_offset
 
 Example
 -------

src/libbson/doc/bson_validate.rst

@@ -15,24 +15,26 @@ Parameters
 ----------
 
 * ``bson``: A :symbol:`bson_t`.
-* ``flags``: A bitwise-or of all desired :symbol:`bson_validate_flags_t <bson_validate_with_error>`.
-* ``offset``: A location for the offset within ``bson`` where the error occurred.
+* ``flags``: A bitwise-or of all desired :symbol:`bson_validate_flags_t`.
+* ``offset``: Optional location where the error offset will be written.
 
 Description
 -----------
 
 Validates a BSON document by walking through the document and inspecting the keys and values for valid content.
 
-You can modify how the validation occurs through the use of the ``flags`` parameter, see :symbol:`bson_validate_with_error()` for details.
+You can modify how the validation occurs through the use of the ``flags`` parameter, see :symbol:`bson_validate_flags_t` for details.
 
 Returns
 -------
 
-Returns true if ``bson`` is valid; otherwise false and ``offset`` is set to the byte offset where the error was detected.
+If ``bson`` passes the requested validations, returns true.
+Otherwise, returns false and if ``offset`` is non-`NULL` it will be written with the byte offset in the document where an error was detected.
+
+To get more information about the specific validation failure, use :symbol:`bson_validate_with_error_and_offset()` instead.
 
 .. seealso::
 
-  | :symbol:`bson_validate_with_error()`.
+  | :symbol:`bson_validate_with_error()`, :symbol:`bson_validate_with_error_and_offset()`.
 
   | :symbol:`bson_visitor_t` can be used for custom validation, :ref:`example_custom_validation`.
-

src/libbson/doc/bson_validate_flags_t.rst

@@ -0,0 +1,48 @@
+:man_page: bson_validate_flags_t
+
+bson_validate_flags_t
+=====================
+
+Document validation options
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  #include <bson/bson-types.h>
+
+  typedef enum {
+    BSON_VALIDATE_NONE = 0,
+    BSON_VALIDATE_UTF8 = (1 << 0),
+    BSON_VALIDATE_DOLLAR_KEYS = (1 << 1),
+    BSON_VALIDATE_DOT_KEYS = (1 << 2),
+    BSON_VALIDATE_UTF8_ALLOW_NULL = (1 << 3),
+    BSON_VALIDATE_EMPTY_KEYS = (1 << 4),
+  } bson_validate_flags_t;
+
+Description
+-----------
+
+``bson_validate_flags_t`` is a set of binary flags which may be combined to specify a level of BSON document validation.
+
+A value of ``0``, ``false``, or ``BSON_VALIDATE_NONE`` equivalently requests the minimum applicable level of validation.
+
+In the context of validation APIs :symbol:`bson_validate()`, :symbol:`bson_validate_with_error()`, and :symbol:`bson_validate_with_error_and_offset()` the minimum validation still guarantees that a document can be successfully traversed by :symbol:`bson_iter_visit_all()`.
+
+Higher level APIs using this type may have different minimum validation levels. For example, ``libmongoc`` functions that take ``bson_validate_flags_t`` use ``0`` to mean the document contents are not visited and malformed headers will not be detected by the client.
+
+Each defined flag aside from ``BSON_VALIDATE_NONE`` describes an optional validation feature that may be enabled, alone or in combination with other features:
+
+* ``BSON_VALIDATE_NONE`` Minimum level of validation; in ``libbson``, validates element headers.
+* ``BSON_VALIDATE_UTF8`` All keys and string values are checked for invalid UTF-8.
+* ``BSON_VALIDATE_UTF8_ALLOW_NULL`` String values are allowed to have embedded NULL bytes.
+* ``BSON_VALIDATE_DOLLAR_KEYS`` Prohibit keys that start with ``$`` outside of a "DBRef" subdocument.
+* ``BSON_VALIDATE_DOT_KEYS`` Prohibit keys that contain ``.`` anywhere in the string.
+* ``BSON_VALIDATE_EMPTY_KEYS`` Prohibit zero-length keys.
+
+.. seealso::
+
+  | :symbol:`bson_validate()`, :symbol:`bson_validate_with_error()`, :symbol:`bson_validate_with_error_and_offset()`.
+
+  | :symbol:`bson_visitor_t` can be used for custom validation, :ref:`example_custom_validation`.

src/libbson/doc/bson_validate_with_error.rst

@@ -8,15 +8,6 @@ Synopsis
 
 .. code-block:: c
 
-  typedef enum {
-     BSON_VALIDATE_NONE = 0,
-     BSON_VALIDATE_UTF8 = (1 << 0),
-     BSON_VALIDATE_DOLLAR_KEYS = (1 << 1),
-     BSON_VALIDATE_DOT_KEYS = (1 << 2),
-     BSON_VALIDATE_UTF8_ALLOW_NULL = (1 << 3),
-     BSON_VALIDATE_EMPTY_KEYS = (1 << 4),
-  } bson_validate_flags_t;
-
   bool
   bson_validate_with_error (const bson_t *bson,
                             bson_validate_flags_t flags,
@@ -26,33 +17,28 @@ Parameters
 ----------
 
 * ``bson``: A :symbol:`bson_t`.
-* ``flags``: A bitwise-or of all desired validation flags.
+* ``flags``: A bitwise-or of all desired :symbol:`bson_validate_flags_t`.
 * ``error``: Optional :symbol:`bson_error_t`.
 
 Description
 -----------
 
 Validates a BSON document by walking through the document and inspecting the keys and values for valid content.
 
-You can modify how the validation occurs through the use of the ``flags`` parameter. A description of their effect is below.
-
-* ``BSON_VALIDATE_NONE`` Basic validation of BSON length and structure.
-* ``BSON_VALIDATE_UTF8`` All keys and string values are checked for invalid UTF-8.
-* ``BSON_VALIDATE_UTF8_ALLOW_NULL`` String values are allowed to have embedded NULL bytes.
-* ``BSON_VALIDATE_DOLLAR_KEYS`` Prohibit keys that start with ``$`` outside of a "DBRef" subdocument.
-* ``BSON_VALIDATE_DOT_KEYS`` Prohibit keys that contain ``.`` anywhere in the string.
-* ``BSON_VALIDATE_EMPTY_KEYS`` Prohibit zero-length keys.
+You can modify how the validation occurs through the use of the ``flags`` parameter, see :symbol:`bson_validate_flags_t` for details.
 
 Returns
 -------
 
-Returns true if ``bson`` is valid; otherwise false and ``error`` is filled out.
+If ``bson`` passes the requested validations, returns true.
+Otherwise, returns false and if ``error`` is non-`NULL` it will be filled out with details.
 
 The :symbol:`bson_error_t` domain is set to ``BSON_ERROR_INVALID``. Its code is set to one of the ``bson_validate_flags_t`` flags indicating which validation failed; for example, if a key contains invalid UTF-8, then the code is set to ``BSON_VALIDATE_UTF8``, but if the basic structure of the BSON document is corrupt, the code is set to ``BSON_VALIDATE_NONE``. The error message is filled out, and gives more detail if possible.
 
+To get the specific location of the error, use :symbol:`bson_validate_with_error_and_offset()` instead.
+
 .. seealso::
 
-  | :symbol:`bson_validate()`.
+  | :symbol:`bson_validate()`, :symbol:`bson_validate_with_error_and_offset()`.
 
   | :symbol:`bson_visitor_t` can be used for custom validation, :ref:`example_custom_validation`.
-

src/libbson/doc/bson_validate_with_error_and_offset.rst

@@ -0,0 +1,44 @@
+:man_page: bson_validate_with_error_and_offset
+
+bson_validate_with_error_and_offset()
+=====================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  bool
+  bson_validate_with_error_and_offset (const bson_t *bson,
+                                       bson_validate_flags_t flags,
+                                       size_t *offset,
+                                       bson_error_t *error)
+
+Parameters
+----------
+
+* ``bson``: A :symbol:`bson_t`.
+* ``flags``: A bitwise-or of all desired :symbol:`bson_validate_flags_t`.
+* ``offset``: Optional location where the error offset will be written.
+* ``error``: Optional :symbol:`bson_error_t`.
+
+Description
+-----------
+
+Validates a BSON document by walking through the document and inspecting the keys and values for valid content.
+
+You can modify how the validation occurs through the use of the ``flags`` parameter, see :symbol:`bson_validate_flags_t` for details.
+
+Returns
+-------
+
+If ``bson`` passes the requested validations, returns true.
+Otherwise, returns false and writes each non-`NULL` output parameter: ``offset`` with the byte offset of the detected error and ``error`` with the details.
+
+The :symbol:`bson_error_t` domain is set to ``BSON_ERROR_INVALID``. Its code is set to one of the ``bson_validate_flags_t`` flags indicating which validation failed; for example, if a key contains invalid UTF-8, then the code is set to ``BSON_VALIDATE_UTF8``, but if the basic structure of the BSON document is corrupt, the code is set to ``BSON_VALIDATE_NONE``. The error message is filled out, and gives more detail if possible.
+
+.. seealso::
+
+  | :symbol:`bson_validate()`, :symbol:`bson_validate_with_error()`.
+
+  | :symbol:`bson_visitor_t` can be used for custom validation, :ref:`example_custom_validation`.

src/libmongoc/doc/includes/bulk-insert-opts.txt

@@ -5,4 +5,4 @@
 
 ``opts`` may be NULL or a BSON document with additional command options:
 
-* ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t <bson_validate_with_error>`. Set to ``false`` to skip client-side validation of the provided BSON documents.
+* ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t`. Set to ``false`` to skip client-side validation of the provided BSON documents.

src/libmongoc/doc/includes/bulk-replace-one-opts.txt

@@ -5,7 +5,7 @@
 
 ``opts`` may be NULL or a BSON document with additional command options:
 
-* ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t <bson_validate_with_error>`. Set to ``false`` to skip client-side validation of the provided BSON documents.
+* ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t`. Set to ``false`` to skip client-side validation of the provided BSON documents.
 * ``collation``: Configure textual comparisons. See `Setting Collation Order <setting_collation_order_>`_, and `the MongoDB Manual entry on Collation <https://www.mongodb.com/docs/manual/reference/collation/>`_. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``hint``: A document or string that specifies the index to use to support the query predicate.
 * ``upsert``: If true, insert a document if none match ``selector``.

src/libmongoc/doc/includes/bulk-update-many-opts.txt

@@ -5,7 +5,7 @@
 
 ``opts`` may be NULL or a BSON document with additional command options:
 
-* ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t <bson_validate_with_error>`. Set to ``false`` to skip client-side validation of the provided BSON documents.
+* ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t`. Set to ``false`` to skip client-side validation of the provided BSON documents.
 * ``collation``: Configure textual comparisons. See `Setting Collation Order <setting_collation_order_>`_, and `the MongoDB Manual entry on Collation <https://www.mongodb.com/docs/manual/reference/collation/>`_. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``hint``: A document or string that specifies the index to use to support the query predicate.
 * ``upsert``: If true, insert a document if none match ``selector``.

src/libmongoc/doc/includes/bulk-update-one-opts.txt

@@ -5,7 +5,7 @@
 
 ``opts`` may be NULL or a BSON document with additional command options:
 
-* ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t <bson_validate_with_error>`. Set to ``false`` to skip client-side validation of the provided BSON documents.
+* ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t`. Set to ``false`` to skip client-side validation of the provided BSON documents.
 * ``collation``: Configure textual comparisons. See `Setting Collation Order <setting_collation_order_>`_, and `the MongoDB Manual entry on Collation <https://www.mongodb.com/docs/manual/reference/collation/>`_. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``hint``: A document or string that specifies the index to use to support the query predicate.
 * ``upsert``: If true, insert a document if none match ``selector``.

src/libmongoc/doc/includes/delete-many-opts.txt

@@ -7,7 +7,7 @@
 
 * ``writeConcern``: Construct a :symbol:`mongoc_write_concern_t` and use :symbol:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :symbol:`mongoc_client_write_command_with_opts`.
 * ``sessionId``: First, construct a :symbol:`mongoc_client_session_t` with :symbol:`mongoc_client_start_session`. You can begin a transaction with :symbol:`mongoc_client_session_start_transaction`, optionally with a :symbol:`mongoc_transaction_opt_t` that overrides the options inherited from |opts-source|, and use :symbol:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :symbol:`mongoc_client_session_t`.
-* ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t <bson_validate_with_error>`. Set to ``false`` to skip client-side validation of the provided BSON documents.
+* ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t`. Set to ``false`` to skip client-side validation of the provided BSON documents.
 * ``comment``: A :symbol:`bson_value_t` specifying the comment to attach to this command. The comment will appear in log messages, profiler output, and currentOp output. Requires MongoDB 4.4 or later.
 * ``collation``: Configure textual comparisons. See `Setting Collation Order <setting_collation_order_>`_, and `the MongoDB Manual entry on Collation <https://www.mongodb.com/docs/manual/reference/collation/>`_. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``hint``: A document or string that specifies the index to use to support the query predicate.

src/libmongoc/doc/includes/delete-one-opts.txt

@@ -7,7 +7,7 @@
 
 * ``writeConcern``: Construct a :symbol:`mongoc_write_concern_t` and use :symbol:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :symbol:`mongoc_client_write_command_with_opts`.
 * ``sessionId``: First, construct a :symbol:`mongoc_client_session_t` with :symbol:`mongoc_client_start_session`. You can begin a transaction with :symbol:`mongoc_client_session_start_transaction`, optionally with a :symbol:`mongoc_transaction_opt_t` that overrides the options inherited from |opts-source|, and use :symbol:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :symbol:`mongoc_client_session_t`.
-* ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t <bson_validate_with_error>`. Set to ``false`` to skip client-side validation of the provided BSON documents.
+* ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t`. Set to ``false`` to skip client-side validation of the provided BSON documents.
 * ``comment``: A :symbol:`bson_value_t` specifying the comment to attach to this command. The comment will appear in log messages, profiler output, and currentOp output. Requires MongoDB 4.4 or later.
 * ``collation``: Configure textual comparisons. See `Setting Collation Order <setting_collation_order_>`_, and `the MongoDB Manual entry on Collation <https://www.mongodb.com/docs/manual/reference/collation/>`_. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``hint``: A document or string that specifies the index to use to support the query predicate.

src/libmongoc/doc/includes/insert-many-opts.txt

@@ -7,7 +7,7 @@
 
 * ``writeConcern``: Construct a :symbol:`mongoc_write_concern_t` and use :symbol:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :symbol:`mongoc_client_write_command_with_opts`.
 * ``sessionId``: First, construct a :symbol:`mongoc_client_session_t` with :symbol:`mongoc_client_start_session`. You can begin a transaction with :symbol:`mongoc_client_session_start_transaction`, optionally with a :symbol:`mongoc_transaction_opt_t` that overrides the options inherited from |opts-source|, and use :symbol:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :symbol:`mongoc_client_session_t`.
-* ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t <bson_validate_with_error>`. Set to ``false`` to skip client-side validation of the provided BSON documents.
+* ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t`. Set to ``false`` to skip client-side validation of the provided BSON documents.
 * ``comment``: A :symbol:`bson_value_t` specifying the comment to attach to this command. The comment will appear in log messages, profiler output, and currentOp output. Requires MongoDB 4.4 or later.
 * ``ordered``: set to ``false`` to attempt to insert all documents, continuing after errors.
 * ``bypassDocumentValidation``: Set to ``true`` to skip server-side schema validation of the provided BSON documents.

src/libmongoc/doc/includes/insert-one-opts.txt

@@ -7,6 +7,6 @@
 
 * ``writeConcern``: Construct a :symbol:`mongoc_write_concern_t` and use :symbol:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :symbol:`mongoc_client_write_command_with_opts`.
 * ``sessionId``: First, construct a :symbol:`mongoc_client_session_t` with :symbol:`mongoc_client_start_session`. You can begin a transaction with :symbol:`mongoc_client_session_start_transaction`, optionally with a :symbol:`mongoc_transaction_opt_t` that overrides the options inherited from |opts-source|, and use :symbol:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :symbol:`mongoc_client_session_t`.
-* ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t <bson_validate_with_error>`. Set to ``false`` to skip client-side validation of the provided BSON documents.
+* ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t`. Set to ``false`` to skip client-side validation of the provided BSON documents.
 * ``comment``: A :symbol:`bson_value_t` specifying the comment to attach to this command. The comment will appear in log messages, profiler output, and currentOp output. Requires MongoDB 4.4 or later.
 * ``bypassDocumentValidation``: Set to ``true`` to skip server-side schema validation of the provided BSON documents.