Implement BSON to JSON encoder that limits encoded string length

Author: alcaeus

src/libbson/doc/bson_as_json_with_opts.rst

@@ -0,0 +1,54 @@
+:man_page: bson_as_json_with_opts
+
+bson_as_json_with_opts()
+========================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  char *
+  bson_as_json_with_opts (const bson_t *bson, size_t *length, const bson_json_opts_t *opts);
+
+Parameters
+----------
+
+* ``bson``: A :symbol:`bson_t`.
+* ``length``: An optional location for the length of the resulting string.
+* ``opts``: A :symbol:`bson_json_opts_t`.
+
+Description
+-----------
+
+The :symbol:`bson_as_json_with_opts()` encodes ``bson`` as a UTF-8 string in the `MongoDB Extended JSON format`_.
+
+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.
+
+The ``opts`` structure is used to pass options for the encoding process. Please refer to the documentation of :symbol:`bson_json_opts_t` for more details.
+
+Returns
+-------
+
+If successful, a newly allocated UTF-8 encoded string and ``length`` is set.
+
+Upon failure, NULL is returned.
+
+Example
+-------
+
+.. code-block:: c
+
+  bson_json_opts_t opts = { BSON_JSON_MODE_CANONICAL, BSON_MAX_LEN_UNLIMITED };
+  char *str = bson_as_json_with_opts (doc, NULL, &opts);
+  printf ("%s\n", str);
+  bson_free (str);
+
+
+.. only:: html
+
+  .. include:: includes/seealso/bson-as-json.txt
+
+.. _MongoDB Extended JSON format: https://github.com/mongodb/specifications/blob/master/source/extended-json.rst

src/libbson/doc/bson_json_mode_t.rst

@@ -0,0 +1,30 @@
+:man_page: bson_json_mode_t
+
+bson_json_mode_t
+================
+
+BSON JSON encoding mode enumeration
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  #include <bson/bson.h>
+
+  typedef enum {
+     BSON_JSON_MODE_LEGACY,
+     BSON_JSON_MODE_CANONICAL,
+     BSON_JSON_MODE_RELAXED,
+  } bson_json_mode_t;
+
+Description
+-----------
+
+The :symbol:`bson_json_mode_t` enumeration contains all available modes for encoding BSON into `MongoDB Extended JSON`_.
+
+.. seealso::
+
+  | :symbol:`bson_as_json_with_opts()`
+
+.. _MongoDB Extended JSON: https://github.com/mongodb/specifications/blob/master/source/extended-json.rst

src/libbson/doc/bson_json_opts_t.rst

@@ -0,0 +1,33 @@
+:man_page: bson_json_opts_t
+
+bson_json_opts_t
+================
+
+BSON to JSON encoding options
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  #include <bson/bson.h>
+
+  typedef struct {
+     bson_json_mode_t mode;
+     int32_t max_len;
+  } bson_json_opts_t;
+
+Description
+-----------
+
+The :symbol:`bson_json_opts_t` structure contains options for encoding BSON into `MongoDB Extended JSON`_.
+
+The ``mode`` member is a :symbol:`bson_json_mode_t` defining the encoding mode.
+
+The ``max_len`` member holds a maximum length for the resulting JSON string. Encoding will stop once the serialised string has reached this length. To encode the full BSON document, ``BSON_MAX_LEN_UNLIMITED`` can be used.
+
+.. seealso::
+
+  | :symbol:`bson_as_json_with_opts()`
+
+.. _MongoDB Extended JSON: https://github.com/mongodb/specifications/blob/master/source/extended-json.rst

src/libbson/doc/bson_t.rst

@@ -184,6 +184,7 @@ The :symbol:`bson_t` structure attempts to use an inline allocation within the s
     bson_array_as_json
     bson_as_canonical_extended_json
     bson_as_json
+    bson_as_json_with_opts
     bson_as_relaxed_extended_json
     bson_compare
     bson_concat
@@ -201,6 +202,8 @@ The :symbol:`bson_t` structure attempts to use an inline allocation within the s
     bson_init
     bson_init_from_json
     bson_init_static
+    bson_json_mode_t
+    bson_json_opts_t
     bson_new
     bson_new_from_buffer
     bson_new_from_data

src/libbson/doc/includes/seealso/bson-as-json.txt

@@ -6,4 +6,6 @@
 
   | :symbol:`bson_as_json()`
 
+  | :symbol:`bson_as_json_with_opts()`
+
   | :symbol:`bson_as_relaxed_extended_json()`

src/libbson/src/bson/bson-types.h

@@ -519,6 +519,40 @@ typedef struct _bson_error_t {
 } bson_error_t BSON_ALIGNED_END (8);
 
 
+/**
+ * BSON_MAX_LEN_UNLIMITED
+ *
+ * Denotes unlimited length limit when converting BSON to JSON.
+ */
+#define BSON_MAX_LEN_UNLIMITED -1
+
+/**
+ * bson_json_mode_t:
+ *
+ * This enumeration contains the different modes to serialize BSON into extended
+ * JSON.
+ */
+typedef enum {
+   BSON_JSON_MODE_LEGACY,
+   BSON_JSON_MODE_CANONICAL,
+   BSON_JSON_MODE_RELAXED,
+} bson_json_mode_t;
+
+/**
+ * bson_json_opts_t:
+ *
+ * This structure is used to pass options for serializing BSON into extended
+ * JSON to the respective serialization methods.
+ *
+ * max_len can be either a non-negative integer, or BSON_MAX_LEN_UNLIMITED to
+ * set no limit for serialization length.
+ */
+typedef struct {
+   bson_json_mode_t mode;
+   int32_t max_len;
+} bson_json_opts_t;
+
+
 BSON_STATIC_ASSERT2 (error_t, sizeof (bson_error_t) == 512);