CDRIVER-5946 remove deprecated index management API (#1360)

* CXX-3257 deprecate mongocxx::v_noabi::options::index::storage_options
* Replace deprecated storage_options with storage_engine
* Add test coverage for storage_engine override behavior

Author: eramongodb

CHANGELOG.md

@@ -9,9 +9,15 @@ Changes prior to 3.9.0 are documented as [release notes on GitHub](https://githu
 
 ## 4.1.0 [Unreleased]
 
+### Added
+
+- `storage_engine()` in `mongocxx::v_noabi::options::index`.
+
 ### Deprecated
 
 - Support for MacOS 11 (EOL since Nov 2020) and MacOS 12 (EOL since Oct 2021).
+- `storage_options()` in `mongocxx::v_noabi::options::index`: use `storage_engine()` instead.
+  - `base_storage_options` and `wiredtiger_storage_options` in `mongocxx::v_noabi::options::index` are also deprecated.
 
 ### Changed
 

examples/mongocxx/index.cpp

@@ -14,6 +14,7 @@
 
 #include <bsoncxx/builder/basic/document.hpp>
 #include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/json.hpp>
 
 #include <mongocxx/client.hpp>
 #include <mongocxx/instance.hpp>
@@ -59,15 +60,10 @@ int EXAMPLES_CDECL main() {
 
     // Create an index with storage engine options
     {
+        auto storage_engine = bsoncxx::from_json(R"({"wiredTiger": {"configString": "block_allocation=first"}})");
         db["restaurants"].drop();
         mongocxx::options::index index_options{};
-
-        // Use `std::make_unique` with C++14 and newer.
-        std::unique_ptr<mongocxx::options::index::wiredtiger_storage_options> wt_options{
-            new mongocxx::options::index::wiredtiger_storage_options()};
-
-        wt_options->config_string("block_allocation=first");
-        index_options.storage_options(std::move(wt_options));
+        index_options.storage_engine(storage_engine.view());
         db["restaurants"].create_index(make_document(kvp("cuisine", 1)), index_options);
     }
 }

src/mongocxx/include/mongocxx/v_noabi/mongocxx/options/index.hpp

@@ -49,6 +49,8 @@ class index {
     ///
     /// Base class representing the optional storage engine options for indexes.
     ///
+    /// @deprecated Use @ref mongocxx::v_noabi::options::index::storage_engine instead.
+    ///
     class MONGOCXX_ABI_EXPORT base_storage_options {
        public:
         virtual ~base_storage_options();
@@ -69,6 +71,8 @@ class index {
     ///
     /// The optional WiredTiger storage engine options for indexes.
     ///
+    /// @deprecated Use @ref mongocxx::v_noabi::options::index::storage_engine instead.
+    ///
     class MONGOCXX_ABI_EXPORT wiredtiger_storage_options final : public base_storage_options {
        public:
         ~wiredtiger_storage_options() override;
@@ -247,8 +251,9 @@ class index {
     MONGOCXX_ABI_EXPORT_CDECL(bsoncxx::v_noabi::stdx::optional<bool> const&) sparse() const;
 
     ///
-    /// Optionally used only in MongoDB 3.0.0 and higher. Specifies the storage engine options for
-    /// the index.
+    /// Specifies the storage engine options for the index.
+    ///
+    /// @important This option is overridden by `storage_engine` when set.
     ///
     /// @param storage_options
     ///   The storage engine options for the index.
@@ -257,18 +262,49 @@ class index {
     ///   A reference to the object on which this member function is being called.  This facilitates
     ///   method chaining.
     ///
-    MONGOCXX_ABI_EXPORT_CDECL(index&)
-    storage_options(std::unique_ptr<base_storage_options> storage_options);
+    /// @deprecated Use @ref mongocxx::v_noabi::options::index::storage_engine instead.
+    ///
+    MONGOCXX_DEPRECATED MONGOCXX_ABI_EXPORT_CDECL(index&) storage_options(
+        std::unique_ptr<base_storage_options> storage_options);
 
     ///
-    /// Optionally used only in MongoDB 3.0.0 and higher. Specifies the WiredTiger-specific storage
-    /// engine options for the index.
+    /// Specifies the WiredTiger-specific storage engine options for the index.
+    ///
+    /// @important This option is overridden by `storage_engine` when set.
     ///
     /// @param storage_options
     ///   The storage engine options for the index.
     ///
+    /// @deprecated Use @ref mongocxx::v_noabi::options::index::storage_engine instead.
+    ///
+    MONGOCXX_DEPRECATED MONGOCXX_ABI_EXPORT_CDECL(index&) storage_options(
+        std::unique_ptr<wiredtiger_storage_options> storage_options);
+
+    ///
+    /// Specifies the storage engine options for the index.
+    ///
+    /// @important This option overrides `storage_options` when set.
+    ///
+    /// The document must have the form `{ <storage-engine-name>: <options> }`, e.g.:
+    /// ```json
+    /// { "wiredTiger": {"configString": "block_compressor=zlib"} }
+    /// ```
+    ///
+    /// @param storage_engine
+    ///   The storage engine options for the index.
+    ///
+    /// @see
+    /// - [Specifying Storage Engine Options (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/method/db.createCollection/#std-label-create-collection-storage-engine-options)
+    /// - [Storage Engines for Self-Managed Deployments (MongoDB Manual)](https://www.mongodb.com/docs/manual/core/storage-engines/)
+    ///
     MONGOCXX_ABI_EXPORT_CDECL(index&)
-    storage_options(std::unique_ptr<wiredtiger_storage_options> storage_options);
+    storage_engine(bsoncxx::v_noabi::stdx::optional<bsoncxx::v_noabi::document::view> storage_engine);
+
+    ///
+    /// The current storage engine options.
+    ///
+    BSONCXX_ABI_EXPORT_CDECL(bsoncxx::v_noabi::stdx::optional<bsoncxx::v_noabi::document::view> const&)
+    storage_engine() const;
 
     ///
     /// Set a value, in seconds, as a TTL to control how long MongoDB retains documents in this
@@ -534,6 +570,7 @@ class index {
     bsoncxx::v_noabi::stdx::optional<bsoncxx::v_noabi::document::view> _collation;
     bsoncxx::v_noabi::stdx::optional<bool> _sparse;
     std::unique_ptr<base_storage_options> _storage_options;
+    bsoncxx::v_noabi::stdx::optional<bsoncxx::v_noabi::document::view> _storage_engine;
     bsoncxx::v_noabi::stdx::optional<std::chrono::seconds> _expire_after;
     bsoncxx::v_noabi::stdx::optional<std::int32_t> _version;
     bsoncxx::v_noabi::stdx::optional<bsoncxx::v_noabi::document::view> _weights;

src/mongocxx/lib/mongocxx/private/mongoc.hh

@@ -314,9 +314,6 @@ BSONCXX_PRIVATE_WARNINGS_POP();
     X(find_and_modify_opts_set_sort)                                      \
     X(find_and_modify_opts_set_update)                                    \
     X(handshake_data_append)                                              \
-    X(index_opt_geo_init)                                                 \
-    X(index_opt_init)                                                     \
-    X(index_opt_wt_init)                                                  \
     X(init)                                                               \
     /* X(log_set_handler) CDRIVER-5678: not __cdecl. */                   \
     X(read_concern_copy)                                                  \

src/mongocxx/lib/mongocxx/v_noabi/mongocxx/options/index.cpp

@@ -64,8 +64,12 @@ index& index::storage_options(std::unique_ptr<index::base_storage_options> stora
 }
 
 index& index::storage_options(std::unique_ptr<index::wiredtiger_storage_options> storage_options) {
-    _storage_options = std::unique_ptr<index::base_storage_options>(
-        static_cast<index::base_storage_options*>(storage_options.release()));
+    _storage_options = std::move(storage_options);
+    return *this;
+}
+
+index& index::storage_engine(bsoncxx::v_noabi::stdx::optional<bsoncxx::v_noabi::document::view> storage_engine) {
+    _storage_engine = std::move(storage_engine);
     return *this;
 }
 
@@ -156,6 +160,10 @@ std::unique_ptr<index::base_storage_options> const& index::storage_options() con
     return _storage_options;
 }
 
+bsoncxx::v_noabi::stdx::optional<bsoncxx::v_noabi::document::view> const& index::storage_engine() const {
+    return _storage_engine;
+}
+
 bsoncxx::v_noabi::stdx::optional<std::chrono::seconds> const& index::expire_after() const {
     return _expire_after;
 }
@@ -204,6 +212,12 @@ bsoncxx::v_noabi::stdx::optional<double> const& index::haystack_bucket_size() co
     return haystack_bucket_size_deprecated();
 }
 
+// CDRIVER-5946: mongoc_index_storage_opt_type_t was removed in mongoc 2.0.
+enum mongoc_index_storage_opt_type_t {
+    MONGOC_INDEX_STORAGE_OPT_MMAPV1,
+    MONGOC_INDEX_STORAGE_OPT_WIREDTIGER,
+};
+
 index::operator bsoncxx::v_noabi::document::view_or_value() {
     using namespace bsoncxx;
     using builder::basic::kvp;
@@ -280,7 +294,9 @@ index::operator bsoncxx::v_noabi::document::view_or_value() {
         root.append(kvp("collation", *_collation));
     }
 
-    if (_storage_options) {
+    if (_storage_engine) {
+        root.append(kvp("storageEngine", *_storage_engine));
+    } else if (_storage_options) {
         if (_storage_options->type() == MONGOC_INDEX_STORAGE_OPT_WIREDTIGER) {
             options::index::wiredtiger_storage_options const* wt_options =
                 static_cast<options::index::wiredtiger_storage_options const*>(_storage_options.get());
@@ -296,6 +312,7 @@ index::operator bsoncxx::v_noabi::document::view_or_value() {
             root.append(kvp("storageEngine", storage_doc));
         }
     }
+
     return root.extract();
 }
 

src/mongocxx/test/collection.cpp

@@ -2274,15 +2274,13 @@ TEST_CASE("create_index tests", "[collection]") {
 
         bsoncxx::stdx::string_view index_name{"storage_options_test"};
         bsoncxx::document::value keys = make_document(kvp("c", 1));
+        bsoncxx::document::value storage_engine =
+            from_json(R"({"wiredTiger": {"configString": "block_allocation=first"}})");
 
         options::index options{};
         options.name(index_name);
 
-        std::unique_ptr<options::index::wiredtiger_storage_options> wt_options =
-            bsoncxx::make_unique<options::index::wiredtiger_storage_options>();
-        wt_options->config_string("block_allocation=first");
-
-        REQUIRE_NOTHROW(options.storage_options(std::move(wt_options)));
+        REQUIRE_NOTHROW(options.storage_engine(storage_engine.view()));
         REQUIRE_NOTHROW(coll.create_index(keys.view(), options));
 
         auto validate = [](bsoncxx::document::view index) {

src/mongocxx/test/options/index.cpp

@@ -13,12 +13,14 @@
 // limitations under the License.
 
 #include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/json.hpp>
 #include <bsoncxx/types.hpp>
 
 #include <mongocxx/instance.hpp>
 #include <mongocxx/options/index.hpp>
 
 #include <bsoncxx/private/make_unique.hh>
+#include <bsoncxx/private/suppress_deprecation_warnings.hh>
 
 #include <bsoncxx/test/catch.hh>
 
@@ -35,8 +37,9 @@ TEST_CASE("index", "[index][option]") {
     instance::current();
 
     options::index idx;
-    std::unique_ptr<options::index::wiredtiger_storage_options> storage =
-        bsoncxx::make_unique<options::index::wiredtiger_storage_options>();
+    auto storage = bsoncxx::from_json(R"({"wiredTiger": {"configString": null}})");
+
+    auto idx_as_doc = [&idx] { return static_cast<bsoncxx::document::view_or_value>(idx); };
 
     auto collation = make_document(kvp("locale", "en_US"));
     auto partial_filter_expression = make_document(kvp("x", true));
@@ -59,7 +62,7 @@ TEST_CASE("index", "[index][option]") {
         CHECK_OPTIONAL_ARGUMENT(idx, haystack_bucket_size_deprecated, 90.0);
         CHECK_OPTIONAL_ARGUMENT(idx, weights, weights.view());
         CHECK_OPTIONAL_ARGUMENT(idx, partial_filter_expression, partial_filter_expression.view());
-        REQUIRE_NOTHROW(idx.storage_options(std::move(storage)));
+        CHECK_OPTIONAL_ARGUMENT(idx, storage_engine, storage.view());
     }
 
     SECTION("check cast to document") {
@@ -101,12 +104,29 @@ TEST_CASE("index", "[index][option]") {
         idx.twod_location_min(90.0);
         idx.haystack_bucket_size_deprecated(90.0);
         idx.weights(weights.view());
-        idx.storage_options(std::move(storage));
+        idx.storage_engine(storage.view());
+
+        auto doc = idx_as_doc();
+
+        REQUIRE(doc.view().length() == options_doc.view().length());
+        REQUIRE(doc.view() == options_doc.view());
+    }
+
+    SECTION("storage_engine overrides storage_options when set") {
+        auto engine = bsoncxx::from_json(R"({"wiredTiger": {"configString": "override"}})");
+        auto options = bsoncxx::make_unique<options::index::wiredtiger_storage_options>(); // configString: null
+
+        CHECK(idx_as_doc() == bsoncxx::from_json(R"({})"));
+
+        BSONCXX_SUPPRESS_DEPRECATION_WARNINGS_BEGIN
+        idx.storage_options(std::move(options));
+        BSONCXX_SUPPRESS_DEPRECATION_WARNINGS_END
+
+        CHECK(idx_as_doc() == bsoncxx::from_json(R"({"storageEngine": {"wiredTiger": {"configString": null}}})"));
 
-        bsoncxx::document::view_or_value d = static_cast<bsoncxx::document::view_or_value>(idx);
+        idx.storage_engine(engine.view());
 
-        REQUIRE(d.view().length() == options_doc.view().length());
-        REQUIRE(d.view() == options_doc.view());
+        CHECK(idx_as_doc() == make_document(kvp("storageEngine", engine.view())));
     }
 }
 } // namespace