CDRIVER-5700 deprecate bson_as_json and bson_array_as_json (#1776)

* deprecate `bson_as_json` and `bson_array_as_json`
* add `bson_as_legacy_extended_json` and `bson_array_as_legacy_extended_json` as non-deprecated alternatives
* remove use of deprecated calls
* document libbson's Legacy Extended JSON

Author: kevinAlbs

.evergreen/scripts/compile-libmongocrypt.sh

@@ -10,12 +10,11 @@ compile_libmongocrypt() {
   # `.evergreen/scripts/kms-divergence-check.sh` to ensure that there is no
   # divergence in the copied files.
 
-  # TODO: once 1.12.0 is released (containing MONGOCRYPT-599) replace the following with:
+  # TODO: once 1.12.0 is released (containing de69cc91e1574e8861cd0ceb4bb866cc02a53d6b) replace the following with:
   # git clone -q --depth=1 https://github.com/mongodb/libmongocrypt --branch 1.12.0 || return
   {
     git clone -q https://github.com/mongodb/libmongocrypt || return
-    # Check out commit containing MONGOCRYPT-599
-    git -C libmongocrypt checkout 7aeaec4ae1369c7d3c5b3aea6f1da35c5e9478b0
+    git -C libmongocrypt checkout de69cc91e1574e8861cd0ceb4bb866cc02a53d6b
   }
 
   declare -a crypt_cmake_flags=(

src/libbson/CMakeLists.txt

@@ -295,6 +295,7 @@ if (ENABLE_EXAMPLES)
    add_example (json-to-bson examples/json-to-bson.c)
    add_example (bson-check-depth examples/bson-check-depth.c)
    add_example (creating examples/creating.c)
+   add_example (extended-json examples/extended-json.c)
 endif () # ENABLE_EXAMPLES
 
 

src/libbson/NEWS

@@ -7,6 +7,7 @@ Deprecated:
   * Compiling with `BSON_MEMCHECK` defined is deprecated.
   * `bson_in_range_*` and `bson_cmp_*` functions.
   * `bson_atomic_*` and `bson_thrd_yield` functions.
+  * `bson_as_json` and `bson_array_as_json` are deprecated due to producing non-portable Legacy Extended JSON. Prefer Canonical Extended JSON or Relaxed Extended JSON for portability. To continue using Legacy Extended JSON, use `bson_as_legacy_extended_json` and `bson_array_as_legacy_extended_json`.
 
 libbson 1.28.1
 ==============

src/libbson/doc/api.rst

@@ -26,3 +26,4 @@ API Reference
   bson_get_monotonic_time
   bson_memory
   version
+  legacy_extended_json

src/libbson/doc/bson_array_as_canonical_extended_json.rst

@@ -20,7 +20,9 @@ Parameters
 Description
 -----------
 
-The :symbol:`bson_array_as_canonical_extended_json()` encodes ``bson`` as a UTF-8 string in the canonical `MongoDB Extended JSON format`_, except the outermost element is encoded as a JSON array, rather than a JSON document.
+:symbol:`bson_array_as_canonical_extended_json()` encodes ``bson`` as a UTF-8 string in Canonical Extended JSON.
+The outermost element is encoded as a JSON array (``[ ... ]``), rather than a JSON document (``{ ... }``).
+See `MongoDB Extended JSON format`_ for a description of Extended JSON formats.
 
 The caller is responsible for freeing the resulting UTF-8 encoded string by calling :symbol:`bson_free()` with the result.
 
@@ -36,31 +38,11 @@ Upon failure, NULL is returned.
 Example
 -------
 
-.. code-block:: c
-
-  #include <bson/bson.h>
-
-  int main ()
-  {
-     bson_t bson;
-     char *str;
-
-     bson_init (&bson);
-     /* BSON array is a normal BSON document with integer values for the keys,
-      * starting with 0 and continuing sequentially
-      */
-     BSON_APPEND_INT32 (&bson, "0", 1);
-     BSON_APPEND_UTF8 (&bson, "1", "bar");
-
-     str = bson_array_as_canonical_extended_json (&bson, NULL);
-     /* Prints
-      * [ { "$numberInt" : 1 }, "bar" ]
-      */
-     printf ("%s\n", str);
-     bson_free (str);
-
-     bson_destroy (&bson);
-  }
+.. literalinclude:: ../examples/extended-json.c
+   :language: c
+   :start-after: // bson_array_as_canonical_extended_json ... begin
+   :end-before: // bson_array_as_canonical_extended_json ... end
+   :dedent: 6
 
 
 .. only:: html

src/libbson/doc/bson_array_as_json.rst

@@ -3,13 +3,18 @@
 bson_array_as_json()
 ====================
 
+.. warning::
+   .. deprecated:: 1.29.0
+
+      This function is deprecated and should not be used in new code.
+
 Synopsis
 --------
 
 .. code-block:: c
 
   char *
-  bson_array_as_json (const bson_t *bson, size_t *length);
+  bson_array_as_json (const bson_t *bson, size_t *length) BSON_GNUC_DEPRECATED_FOR (bson_array_as_legacy_extended_json);
 
 Parameters
 ----------
@@ -20,14 +25,12 @@ Parameters
 Description
 -----------
 
-The :symbol:`bson_array_as_json()` function shall encode ``bson`` as a UTF-8
-string using libbson's legacy JSON format, except the outermost element is
-encoded as a JSON array, rather than a JSON document. This function is
-superseded by :symbol:`bson_array_as_canonical_extended_json()` and
-:symbol:`bson_array_as_relaxed_extended_json()`, which use the same 
-`MongoDB Extended JSON format`_ as all other MongoDB drivers.
-The caller is responsible for freeing the resulting UTF-8 encoded string by
-calling :symbol:`bson_free()` with the result.
+:symbol:`bson_array_as_json()` encodes ``bson`` as a UTF-8 string using :doc:`libbson's Legacy Extended JSON <legacy_extended_json>`.
+The outermost element is encoded as a JSON array (``[ ... ]``), rather than a JSON document (``{ ... }``).
+This function is superseded by :symbol:`bson_array_as_canonical_extended_json()` and :symbol:`bson_array_as_relaxed_extended_json()`, which use the same `MongoDB Extended JSON format`_ as all other MongoDB drivers.
+To continue producing Legacy Extended JSON, :symbol:`bson_array_as_legacy_extended_json()` may be used.
+
+The caller is responsible for freeing the resulting UTF-8 encoded string by calling :symbol:`bson_free()` with the result.
 
 If non-NULL, ``length`` will be set to the length of the result in bytes.
 
@@ -38,36 +41,6 @@ If successful, a newly allocated UTF-8 encoded string and ``length`` is set.
 
 Upon failure, NULL is returned.
 
-Example
--------
-
-.. code-block:: c
-
-  #include <bson/bson.h>
-
-  int main ()
-  {
-     bson_t bson;
-     char *str;
-
-     bson_init (&bson);
-     /* BSON array is a normal BSON document with integer values for the keys,
-      * starting with 0 and continuing sequentially
-      */
-     BSON_APPEND_UTF8 (&bson, "0", "foo");
-     BSON_APPEND_UTF8 (&bson, "1", "bar");
-
-     str = bson_array_as_json (&bson, NULL);
-     /* Prints
-      * [ "foo", "bar" ]
-      */
-     printf ("%s\n", str);
-     bson_free (str);
-
-     bson_destroy (&bson);
-  }
-
-
 .. only:: html
 
   .. include:: includes/seealso/bson-as-json.txt

src/libbson/doc/bson_array_as_legacy_extended_json.rst

@@ -0,0 +1,51 @@
+:man_page: bson_array_as_legacy_extended_json
+
+bson_array_as_legacy_extended_json()
+====================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  char *
+  bson_array_as_legacy_extended_json (const bson_t *bson, size_t *length)
+
+Parameters
+----------
+
+* ``bson``: A :symbol:`bson_t`.
+* ``length``: An optional location for the length of the resulting string.
+
+Description
+-----------
+
+:symbol:`bson_array_as_legacy_extended_json()` encodes ``bson`` as a UTF-8 string using :doc:`libbson's Legacy Extended JSON <legacy_extended_json>`.
+The outermost element is encoded as a JSON array (``[ ... ]``), rather than a JSON document (``{ ... }``).
+This function is superseded by :symbol:`bson_array_as_canonical_extended_json()` and :symbol:`bson_array_as_relaxed_extended_json()`, which use the same `MongoDB Extended JSON format`_ as all other MongoDB drivers.
+
+The caller is responsible for freeing the resulting UTF-8 encoded string by calling :symbol:`bson_free()` with the result.
+
+If non-NULL, ``length`` will be set to the length of the result in bytes.
+
+Returns
+-------
+
+If successful, a newly allocated UTF-8 encoded string and ``length`` is set.
+
+Upon failure, NULL is returned.
+
+Example
+-------
+
+.. literalinclude:: ../examples/extended-json.c
+   :language: c
+   :start-after: // bson_array_as_legacy_extended_json ... begin
+   :end-before: // bson_array_as_legacy_extended_json ... end
+   :dedent: 6
+
+.. only:: html
+
+  .. include:: includes/seealso/bson-as-json.txt
+
+.. _MongoDB Extended JSON format: https://github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md

src/libbson/doc/bson_array_as_relaxed_extended_json.rst

@@ -20,7 +20,9 @@ Parameters
 Description
 -----------
 
-The :symbol:`bson_as_relaxed_extended_json()` encodes ``bson`` as a UTF-8 string in the relaxed `MongoDB Extended JSON format`_, except the outermost element is encoded as a JSON array, rather than a JSON document.
+:symbol:`bson_as_relaxed_extended_json()` encodes ``bson`` as a UTF-8 string in the Relaxed Extended JSON.
+The outermost element is encoded as a JSON array (``[ ... ]``), rather than a JSON document (``{ ... }``).
+See `MongoDB Extended JSON format`_ for a description of Extended JSON formats.
 
 The caller is responsible for freeing the resulting UTF-8 encoded string by calling :symbol:`bson_free()` with the result.
 
@@ -36,31 +38,11 @@ Upon failure, NULL is returned.
 Example
 -------
 
-.. code-block:: c
-
-  #include <bson/bson.h>
-
-  int main ()
-  {
-     bson_t bson;
-     char *str;
-
-     bson_init (&bson);
-     /* BSON array is a normal BSON document with integer values for the keys,
-      * starting with 0 and continuing sequentially
-      */
-     BSON_APPEND_DOUBLE (&bson, "0", 3.14);
-     BSON_APPEND_UTF8 (&bson, "1", "bar");
-
-     str = bson_array_as_relaxed_extended_json (&bson, NULL);
-     /* Prints
-      * [ 3.14, "bar" ]
-      */
-     printf ("%s\n", str);
-     bson_free (str);
-
-     bson_destroy (&bson);
-  }
+.. literalinclude:: ../examples/extended-json.c
+   :language: c
+   :start-after: // bson_array_as_relaxed_extended_json ... begin
+   :end-before: // bson_array_as_relaxed_extended_json ... end
+   :dedent: 6
 
 
 .. only:: html

src/libbson/doc/bson_as_canonical_extended_json.rst

@@ -20,7 +20,8 @@ Parameters
 Description
 -----------
 
-The :symbol:`bson_as_canonical_extended_json()` encodes ``bson`` as a UTF-8 string in the canonical `MongoDB Extended JSON format`_.
+:symbol:`bson_as_canonical_extended_json()` encodes ``bson`` as a UTF-8 string in the Canonical Extended JSON.
+See `MongoDB Extended JSON format`_ for a description of Extended JSON formats.
 
 The caller is responsible for freeing the resulting UTF-8 encoded string by calling :symbol:`bson_free()` with the result.
 
@@ -36,11 +37,11 @@ Upon failure, NULL is returned.
 Example
 -------
 
-.. code-block:: c
-
-  char *str = bson_as_canonical_extended_json (doc, NULL);
-  printf ("%s\n", str);
-  bson_free (str);
+.. literalinclude:: ../examples/extended-json.c
+   :language: c
+   :start-after: // bson_as_canonical_extended_json ... begin
+   :end-before: // bson_as_canonical_extended_json ... end
+   :dedent: 6
 
 
 .. only:: html

src/libbson/doc/bson_as_json.rst

@@ -3,13 +3,18 @@
 bson_as_json()
 ==============
 
+.. warning::
+   .. deprecated:: 1.29.0
+
+      This function is deprecated and should not be used in new code.
+
 Synopsis
 --------
 
 .. code-block:: c
 
   char *
-  bson_as_json (const bson_t *bson, size_t *length);
+  bson_as_json (const bson_t *bson, size_t *length) BSON_GNUC_DEPRECATED_FOR (bson_as_legacy_extended_json);
 
 Parameters
 ----------
@@ -20,7 +25,9 @@ Parameters
 Description
 -----------
 
-The :symbol:`bson_as_json()` function shall encode ``bson`` as a UTF-8 string using libbson's legacy JSON format. This function is superseded by :symbol:`bson_as_canonical_extended_json()` and :symbol:`bson_as_relaxed_extended_json()`, which use the same `MongoDB Extended JSON format`_ as all other MongoDB drivers.
+:symbol:`bson_as_json()` encodes ``bson`` as a UTF-8 string using :doc:`libbson's Legacy Extended JSON <legacy_extended_json>`.
+This function is superseded by :symbol:`bson_as_canonical_extended_json()` and :symbol:`bson_as_relaxed_extended_json()`, which use the same `MongoDB Extended JSON format`_ as all other MongoDB drivers.
+To continue producing Legacy Extended JSON, :symbol:`bson_as_legacy_extended_json()` may be used.
 
 The caller is responsible for freeing the resulting UTF-8 encoded string by calling :symbol:`bson_free()` with the result.
 
@@ -33,32 +40,6 @@ If successful, a newly allocated UTF-8 encoded string and ``length`` is set.
 
 Upon failure, NULL is returned.
 
-Example
--------
-
-.. code-block:: c
-
-  #include <bson/bson.h>
-
-  int main ()
-  {
-     bson_t bson;
-     char *str;
-
-     bson_init (&bson);
-     BSON_APPEND_UTF8 (&bson, "0", "foo");
-     BSON_APPEND_UTF8 (&bson, "1", "bar");
-
-     str = bson_as_json (&bson, NULL);
-     /* Prints
-      * { "0" : "foo", "1" : "bar" }
-      */
-     printf ("%s\n", str);
-     bson_free (str);
-
-     bson_destroy (&bson);
-  }
-
 .. only:: html
 
   .. include:: includes/seealso/bson-as-json.txt