CDRIVER-5733 fix behavior of bson_string_truncate (#1736)

* test behavior of `bson_truncate`

* support truncating above `INT_MAX`

* avoid realloc for truncation of same size

* note realloc uses power-of-two boundary

* document possible abort

This may occur if `bson_string_truncate` is called with UINT32_MAX.

* reword size limit warnings

---------

Co-authored-by: Ezra Chung <[email protected]>

Author: kevinAlbs

src/libbson/doc/bson_string_append.rst

@@ -22,4 +22,4 @@ Description
 
 Appends the ASCII or UTF-8 encoded string ``str`` to ``string``. This is not suitable for embedding NULLs in strings.
 
-.. warning:: This function will abort if the length of the resulting string (including the NULL terminator) would exceed ``UINT32_MAX``.
+.. warning:: The length of the resulting string (including the ``NULL`` terminator) MUST NOT exceed ``UINT32_MAX``.

src/libbson/doc/bson_string_append_c.rst

@@ -22,4 +22,4 @@ Description
 
 Appends ``c`` to the string builder ``string``.
 
-.. warning:: This function will abort if the length of the resulting string (including the NULL terminator) would exceed ``UINT32_MAX``.
+.. warning:: The length of the resulting string (including the ``NULL`` terminator) MUST NOT exceed ``UINT32_MAX``.

src/libbson/doc/bson_string_append_printf.rst

@@ -23,4 +23,4 @@ Description
 
 Like bson_string_append() but formats a printf style string and then appends that to ``string``.
 
-.. warning:: This function will abort if the length of the resulting string (including the NULL terminator) would exceed ``UINT32_MAX``.
+.. warning:: The length of the resulting string (including the ``NULL`` terminator) MUST NOT exceed ``UINT32_MAX``.

src/libbson/doc/bson_string_append_unichar.rst

@@ -22,4 +22,4 @@ Description
 
 Appends a unicode character to string. The character will be encoded into its multi-byte UTF-8 representation.
 
-.. warning:: This function will abort if the length of the resulting string (including the NULL terminator) would exceed ``UINT32_MAX``.
+.. warning:: The length of the resulting string (including the ``NULL`` terminator) MUST NOT exceed ``UINT32_MAX``.

src/libbson/doc/bson_string_new.rst

@@ -21,7 +21,7 @@ Description
 
 Creates a new string builder, which uses power-of-two growth of buffers. Use the various bson_string_append*() functions to append to the string.
 
-.. warning:: This function will abort if the length of the resulting string (including the NULL terminator) would exceed ``UINT32_MAX``.
+.. warning:: The length of the resulting string (including the ``NULL`` terminator) MUST NOT exceed ``UINT32_MAX``.
 
 Returns
 -------

src/libbson/doc/bson_string_truncate.rst

@@ -24,3 +24,4 @@ Truncates the string so that it is ``len`` bytes in length. This must be smaller
 
 A ``\0`` byte will be placed where the end of the string occurs.
 
+.. warning:: The length of the resulting string (including the ``NULL`` terminator) MUST NOT exceed ``UINT32_MAX``.

src/libbson/src/bson/bson-string.c

@@ -292,7 +292,7 @@ bson_string_append_printf (bson_string_t *string, const char *format, ...)
  *       Truncate the string @string to @len bytes.
  *
  *       The underlying memory will be released via realloc() down to
- *       the minimum required size specified by @len.
+ *       the minimum required size (at power-of-two boundary) specified by @len.
  *
  * Returns:
  *       None.
@@ -307,19 +307,17 @@ void
 bson_string_truncate (bson_string_t *string, /* IN */
                       uint32_t len)          /* IN */
 {
-   uint32_t alloc;
-
-   BSON_ASSERT (string);
-   BSON_ASSERT (len < INT_MAX);
-
-   alloc = len + 1;
-
-   if (alloc < 16) {
-      alloc = 16;
+   BSON_ASSERT_PARAM (string);
+   if (len == string->len) {
+      return;
    }
-
-   if (!bson_is_power_of_two (alloc)) {
-      alloc = (uint32_t) bson_next_power_of_two ((size_t) alloc);
+   uint32_t needed = len;
+   BSON_ASSERT (needed < UINT32_MAX);
+   needed += 1u; // Add one for trailing NULL byte.
+   uint32_t alloc = bson_next_power_of_two_u32 (needed);
+   if (alloc == 0) {
+      // Overflowed: saturate at UINT32_MAX.
+      alloc = UINT32_MAX;
    }
 
    string->str = bson_realloc (string->str, alloc);

src/libbson/tests/test-string.c

@@ -304,6 +304,61 @@ test_bson_strcasecmp (void)
    BSON_ASSERT (bson_strcasecmp ("FoZ", "foo") > 0);
 }
 
+static void
+test_bson_string_truncate (void)
+{
+   // Test truncating.
+   {
+      bson_string_t *str = bson_string_new ("foobar");
+      ASSERT_CMPSIZE_T (str->len, ==, 6u);
+      ASSERT_CMPSIZE_T (str->alloc, ==, 8u);
+
+      bson_string_truncate (str, 2);
+      ASSERT_CMPSTR (str->str, "fo");
+      ASSERT_CMPSIZE_T (str->len, ==, 2u);
+      ASSERT_CMPSIZE_T (str->alloc, ==, 4u);
+      bson_string_free (str, true);
+   }
+
+   // Test truncating to same length.
+   {
+      bson_string_t *str = bson_string_new ("foobar");
+      ASSERT_CMPSIZE_T (str->len, ==, 6u);
+      ASSERT_CMPSIZE_T (str->alloc, ==, 8u);
+
+      bson_string_truncate (str, 6u);
+      ASSERT_CMPSTR (str->str, "foobar");
+      ASSERT_CMPUINT32 (str->len, ==, 6u);
+      ASSERT_CMPSIZE_T (str->alloc, ==, 8u);
+      bson_string_free (str, true);
+   }
+
+   // Test truncating to 0.
+   {
+      bson_string_t *str = bson_string_new ("foobar");
+      ASSERT_CMPSIZE_T (str->len, ==, 6u);
+      ASSERT_CMPSIZE_T (str->alloc, ==, 8u);
+
+      bson_string_truncate (str, 0u);
+      ASSERT_CMPSTR (str->str, "");
+      ASSERT_CMPUINT32 (str->len, ==, 0u);
+      ASSERT_CMPSIZE_T (str->alloc, ==, 1u);
+      bson_string_free (str, true);
+   }
+
+   // Test truncating beyond string length.
+   // The documentation for `bson_string_truncate` says the truncated length "must be smaller or equal to the current
+   // length of the string.". However, `bson_string_truncate` does not reject greater lengths. For backwards
+   // compatibility, this behavior is preserved.
+   {
+      bson_string_t *str = bson_string_new ("a");
+      bson_string_truncate (str, 2u); // Is not rejected.
+      ASSERT_CMPUINT32 (str->len, ==, 2u);
+      ASSERT_CMPUINT32 (str->alloc, ==, 4u);
+      bson_string_free (str, true);
+   }
+}
+
 static void
 test_bson_string_capacity (void *unused)
 {
@@ -356,6 +411,16 @@ test_bson_string_capacity (void *unused)
       large_str[UINT32_MAX - 2u] = 's'; // Restore.
    }
 
+   // Can truncate strings of length close to UINT32_MAX - 1.
+   {
+      large_str[UINT32_MAX - 1u] = '\0'; // Set size.
+      bson_string_t *str = bson_string_new (large_str);
+      bson_string_truncate (str, UINT32_MAX - 2); // Truncate one character.
+      ASSERT_CMPSIZE_T (strlen (str->str), ==, UINT32_MAX - 2u);
+      bson_string_free (str, true);
+      large_str[UINT32_MAX - 1u] = 's'; // Restore.
+   }
+
    bson_free (large_str);
 }
 
@@ -385,4 +450,5 @@ test_string_install (TestSuite *suite)
    TestSuite_Add (suite, "/bson/string/strcasecmp", test_bson_strcasecmp);
    TestSuite_AddFull (
       suite, "/bson/string/capacity", test_bson_string_capacity, NULL, NULL, skip_if_no_large_allocations);
+   TestSuite_Add (suite, "/bson/string/truncate", test_bson_string_truncate);
 }