The initial plan for addressing CDRIVER-3303 was to remove _mongoc_cmd_parts_ensure_copied from mongoc-cmd.c and refactor its code into mongoc_cmd_parts_init in the same file. However, it turned out that this approach had numerous drawbacks.

First, there are numerous assertions of the form

   /* not yet assembled */
   BSON_ASSERT (!parts->assembled.command);

Since the refactoring resulted in a value being assigned to parts->assembled.command during the call to mongoc_cmd_parts_init, it then became necessary to implement a flag. The flag, tentatively called is_finalized was initialized to false, then set to true whenever command assembly was considered complete. Assertions like those above would be replaced with something like

   /* not yet assembled */
   BSON_ASSERT (!parts->is_finalized);

However, the handling of parts->extra then required that places where _mongoc_cmd_parts_ensure_copied had been called instead make a call like bson_concat (&parts->assembled_body, &parts->extra);. This made the code generally less readable and apparently created a situation where earlier options might still be overwritten by options which were set later.

Additionally, it is not clear that multiple calls to mongoc_cmd_parts_append_opts are idempotent. Specifically, near the end of the function is the following

      if (!bson_append_iter (&parts->extra, bson_iter_key (iter), -1, iter)) {
         RETURN (false);
      }

That code makes it seem like repeated calls to mongoc_cmd_parts_append_opts with the same options will result in duplicate options being appended to the command.

The task is to implement a more robust approach that eliminates the clunky _mongoc_cmd_parts_ensure_copied function and properly handles appending duplicate options.