RUST-372 Allow hinting the delete command (#190)

Author: isabelatkinson

src/coll/options.rs

@@ -254,7 +254,7 @@ pub struct ReplaceOptions {
 /// [`Collection::delete_one`](../struct.Collection.html#method.delete_one) or
 /// [`Collection::delete_many`](../struct.Collection.html#method.delete_many) operation.
 #[serde_with::skip_serializing_none]
-#[derive(Debug, Default, TypedBuilder, Serialize)]
+#[derive(Clone, Debug, Default, TypedBuilder, Serialize)]
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
 pub struct DeleteOptions {
@@ -268,12 +268,17 @@ pub struct DeleteOptions {
     /// The write concern for the operation.
     #[builder(default)]
     pub write_concern: Option<WriteConcern>,
+
+    /// The index to use for the operation.
+    /// Only available in MongoDB 4.4+.
+    #[builder(default)]
+    pub hint: Option<Hint>,
 }
 
 /// Specifies the options to a
 /// [`Collection::find_one_and_delete`](../struct.Collection.html#method.find_one_and_delete)
 /// operation.
-#[derive(Debug, Default, TypedBuilder)]
+#[derive(Clone, Debug, Default, TypedBuilder)]
 #[non_exhaustive]
 pub struct FindOneAndDeleteOptions {
     /// The maximum amount of time to allow the query to run.
@@ -301,6 +306,11 @@ pub struct FindOneAndDeleteOptions {
     /// information on how to use this option.
     #[builder(default)]
     pub collation: Option<Collation>,
+
+    /// The index to use for the operation.
+    /// Only available in MongoDB 4.4+.
+    #[builder(default)]
+    pub hint: Option<Hint>,
 }
 
 /// Specifies the options to a

src/operation/find_and_modify/mod.rs

@@ -75,7 +75,27 @@ impl Operation for FindAndModify {
     type O = Option<Document>;
     const NAME: &'static str = "findAndModify";
 
-    fn build(&self, _description: &StreamDescription) -> Result<Command> {
+    fn build(&self, description: &StreamDescription) -> Result<Command> {
+        if self.options.hint.is_some() {
+            match description.max_wire_version {
+                Some(version) if version < 8 => {
+                    return Err(ErrorKind::OperationError {
+                        message: "Specifying a hint is not supported on server versions < 4.4"
+                            .to_string(),
+                    }
+                    .into());
+                }
+                None => {
+                    return Err(ErrorKind::OperationError {
+                        message: "Specifying a hint is not supported on server versions < 4.4"
+                            .to_string(),
+                    }
+                    .into());
+                }
+                _ => {}
+            }
+        }
+
         let mut body: Document = doc! {
             Self::NAME: self.ns.coll.clone(),
             "query": self.query.clone(),

src/operation/find_and_modify/options.rs

@@ -10,6 +10,7 @@ use crate::{
         FindOneAndDeleteOptions,
         FindOneAndReplaceOptions,
         FindOneAndUpdateOptions,
+        Hint,
         ReturnDocument,
         UpdateModifications,
     },
@@ -67,6 +68,9 @@ pub(super) struct FindAndModifyOptions {
 
     #[builder(default)]
     pub(crate) collation: Option<Collation>,
+
+    #[builder(default)]
+    pub(crate) hint: Option<Hint>,
 }
 
 impl FindAndModifyOptions {
@@ -80,6 +84,7 @@ impl FindAndModifyOptions {
             .projection(opts.projection)
             .sort(opts.sort)
             .write_concern(opts.write_concern)
+            .hint(opts.hint)
             .build()
     }
 

src/test/coll.rs

@@ -2,12 +2,22 @@ use std::time::Duration;
 
 use futures::stream::StreamExt;
 use lazy_static::lazy_static;
+use semver::VersionReq;
 
 use crate::{
     bson::{doc, Bson, Document},
-    error::ErrorKind,
+    error::{ErrorKind, Result},
     event::command::CommandStartedEvent,
-    options::{AggregateOptions, FindOptions, InsertManyOptions, UpdateOptions},
+    options::{
+        AggregateOptions,
+        DeleteOptions,
+        FindOneAndDeleteOptions,
+        FindOptions,
+        Hint,
+        InsertManyOptions,
+        UpdateOptions,
+    },
+    results::DeleteResult,
     test::{
         util::{drop_collection, CommandEvent, EventClient, TestClient},
         LOCK,
@@ -515,23 +525,11 @@ async fn allow_disk_use_test(options: FindOptions, expected_value: Option<bool>)
         .collection(function_name!());
     coll.find(None, options).await.unwrap();
 
-    let events = event_client.command_events.read().unwrap();
-    let mut iter = events.iter().filter(|event| match event {
-        CommandEvent::CommandStartedEvent(CommandStartedEvent { command_name, .. }) => {
-            command_name == "find"
-        }
-        _ => false,
-    });
+    let events = event_client.get_command_started_events("find");
+    assert_eq!(events.len(), 1);
 
-    let event = iter.next().unwrap();
-    let allow_disk_use = match event {
-        CommandEvent::CommandStartedEvent(CommandStartedEvent { command, .. }) => {
-            command.get_bool("allowDiskUse").ok()
-        }
-        _ => None,
-    };
+    let allow_disk_use = events[0].command.get_bool("allowDiskUse").ok();
     assert_eq!(allow_disk_use, expected_value);
-    assert_eq!(iter.count(), 0);
 }
 
 #[cfg_attr(feature = "tokio-runtime", tokio::test)]
@@ -545,3 +543,120 @@ async fn ns_not_found_suppression() {
     coll.drop(None).await.expect("drop should not fail");
     coll.drop(None).await.expect("drop should not fail");
 }
+
+async fn delete_hint_test(options: Option<DeleteOptions>, name: &str) {
+    let _guard = LOCK.run_concurrently().await;
+
+    let client = EventClient::new().await;
+    let coll = client.database(name).collection(name);
+    let _: Result<DeleteResult> = coll.delete_many(doc! {}, options.clone()).await;
+
+    let events = client.get_command_started_events("delete");
+    assert_eq!(events.len(), 1);
+
+    let event_hint = events[0].command.get("hint").cloned();
+    let expected_hint = match options {
+        Some(options) => options.hint.map(|hint| hint.to_bson()),
+        None => None,
+    };
+    assert_eq!(event_hint, expected_hint);
+}
+
+#[cfg_attr(feature = "tokio-runtime", tokio::test)]
+#[cfg_attr(feature = "async-std-runtime", async_std::test)]
+#[function_name::named]
+async fn delete_hint_keys_specified() {
+    let options = DeleteOptions::builder().hint(Hint::Keys(doc! {})).build();
+    delete_hint_test(Some(options), function_name!()).await;
+}
+
+#[cfg_attr(feature = "tokio-runtime", tokio::test)]
+#[cfg_attr(feature = "async-std-runtime", async_std::test)]
+#[function_name::named]
+async fn delete_hint_string_specified() {
+    let options = DeleteOptions::builder()
+        .hint(Hint::Name(String::new()))
+        .build();
+    delete_hint_test(Some(options), function_name!()).await;
+}
+
+#[cfg_attr(feature = "tokio-runtime", tokio::test)]
+#[cfg_attr(feature = "async-std-runtime", async_std::test)]
+#[function_name::named]
+async fn delete_hint_not_specified() {
+    delete_hint_test(None, function_name!()).await;
+}
+
+async fn find_one_and_delete_hint_test(options: Option<FindOneAndDeleteOptions>, name: &str) {
+    let _guard = LOCK.run_concurrently().await;
+    let client = EventClient::new().await;
+
+    let req = VersionReq::parse("< 4.2").unwrap();
+    if options.is_some() && req.matches(&client.server_version) {
+        return;
+    }
+
+    let coll = client.database(name).collection(name);
+    let _: Result<Option<Document>> = coll.find_one_and_delete(doc! {}, options.clone()).await;
+
+    let events = client.get_command_started_events("findAndModify");
+    assert_eq!(events.len(), 1);
+
+    let event_hint = events[0].command.get("hint").cloned();
+    let expected_hint = options.and_then(|options| options.hint.map(|hint| hint.to_bson()));
+    assert_eq!(event_hint, expected_hint);
+}
+
+#[cfg_attr(feature = "tokio-runtime", tokio::test)]
+#[cfg_attr(feature = "async-std-runtime", async_std::test)]
+#[function_name::named]
+async fn find_one_and_delete_hint_keys_specified() {
+    let options = FindOneAndDeleteOptions::builder()
+        .hint(Hint::Keys(doc! {}))
+        .build();
+    find_one_and_delete_hint_test(Some(options), function_name!()).await;
+}
+
+#[cfg_attr(feature = "tokio-runtime", tokio::test)]
+#[cfg_attr(feature = "async-std-runtime", async_std::test)]
+#[function_name::named]
+async fn find_one_and_delete_hint_string_specified() {
+    let options = FindOneAndDeleteOptions::builder()
+        .hint(Hint::Name(String::new()))
+        .build();
+    find_one_and_delete_hint_test(Some(options), function_name!()).await;
+}
+
+#[cfg_attr(feature = "tokio-runtime", tokio::test)]
+#[cfg_attr(feature = "async-std-runtime", async_std::test)]
+#[function_name::named]
+async fn find_one_and_delete_hint_not_specified() {
+    find_one_and_delete_hint_test(None, function_name!()).await;
+}
+
+#[cfg_attr(feature = "tokio-runtime", tokio::test)]
+#[cfg_attr(feature = "async-std-runtime", async_std::test)]
+#[function_name::named]
+async fn find_one_and_delete_hint_server_version() {
+    let _guard = LOCK.run_concurrently().await;
+
+    let client = EventClient::new().await;
+    let coll = client.database(function_name!()).collection("coll");
+
+    let options = FindOneAndDeleteOptions::builder()
+        .hint(Hint::Name(String::new()))
+        .build();
+    let res = coll.find_one_and_delete(doc! {}, options).await;
+
+    let req1 = VersionReq::parse("< 4.2").unwrap();
+    let req2 = VersionReq::parse("4.2.*").unwrap();
+    if req1.matches(&client.server_version) {
+        let error = res.expect_err("find one and delete should fail");
+        assert!(matches!(error.kind.as_ref(), ErrorKind::OperationError { .. }));
+    } else if req2.matches(&client.server_version) {
+        let error = res.expect_err("find one and delete should fail");
+        assert!(matches!(error.kind.as_ref(), ErrorKind::CommandError { .. }));
+    } else {
+        assert!(res.is_ok());
+    }
+}

src/test/db.rs

@@ -9,7 +9,7 @@ use crate::{
     error::Result,
     options::{AggregateOptions, CreateCollectionOptions, IndexOptionDefaults},
     test::{
-        util::{CommandEvent, EventClient, TestClient},
+        util::{EventClient, TestClient},
         LOCK,
     },
     Database,
@@ -351,25 +351,14 @@ async fn index_option_defaults_test(defaults: Option<IndexOptionDefaults>, name:
     db.create_collection(name, options).await.unwrap();
     db.drop(None).await.unwrap();
 
-    let events = client.command_events.read().unwrap();
-    let mut iter = events.iter().filter_map(|event| match event {
-        CommandEvent::CommandStartedEvent(event) => {
-            if event.command_name == "create" {
-                Some(event)
-            } else {
-                None
-            }
-        }
-        _ => None,
-    });
+    let events = client.get_command_started_events("create");
+    assert_eq!(events.len(), 1);
 
-    let event = iter.next().unwrap();
-    let event_defaults = match event.command.get_document("indexOptionDefaults") {
+    let event_defaults = match events[0].command.get_document("indexOptionDefaults") {
         Ok(defaults) => Some(IndexOptionDefaults {
             storage_engine: defaults.get_document("storageEngine").unwrap().clone(),
         }),
         Err(_) => None,
     };
     assert_eq!(event_defaults, defaults);
-    assert!(iter.next().is_none());
 }

src/test/util/event.rs

@@ -192,6 +192,24 @@ impl EventClient {
             String::from("single")
         }
     }
+
+    /// Gets all of the command started events for a specified command name.
+    pub fn get_command_started_events(&self, command_name: &str) -> Vec<CommandStartedEvent> {
+        let events = self.command_events.read().unwrap();
+        events
+            .iter()
+            .filter_map(|event| match event {
+                CommandEvent::CommandStartedEvent(event) => {
+                    if event.command_name == command_name {
+                        Some(event.clone())
+                    } else {
+                        None
+                    }
+                }
+                _ => None,
+            })
+            .collect()
+    }
 }
 
 #[cfg_attr(feature = "tokio-runtime", tokio::test)]