RUST-913 Add versioned API migration example for count (#419)

Author: abr-egn

src/test/documentation_examples.rs

@@ -1,10 +1,11 @@
 use bson::Document;
 use futures::TryStreamExt;
+use semver::Version;
 use tokio::sync::RwLockReadGuard;
 
 use crate::{
     bson::{doc, Bson},
-    error::Result,
+    error::{ErrorKind, Result},
     options::{ClientOptions, FindOptions, ServerApi, ServerApiVersion},
     test::{TestClient, DEFAULT_URI, LOCK},
     Client,
@@ -1369,12 +1370,19 @@ async fn delete_examples(collection: &Collection<Document>) -> Result<()> {
 
 #[allow(unused_variables)]
 #[cfg(not(feature = "sync"))]
-async fn versioned_api_examples() -> Result<()> {
+async fn versioned_api_examples() -> std::result::Result<(), Box<dyn std::error::Error>> {
     let setup_client = TestClient::new().await;
     if setup_client.server_version_lt(4, 9) {
         println!("skipping versioned API examples due to unsupported server version");
         return Ok(());
     }
+    if setup_client.is_sharded() && setup_client.server_version <= Version::new(5, 0, 2) {
+        // See SERVER-58794.
+        println!(
+            "skipping versioned API examples due to unsupported server version on sharded topology"
+        );
+        return Ok(());
+    }
 
     let uri = DEFAULT_URI.clone();
     // Start Versioned API Example 1
@@ -1414,6 +1422,75 @@ async fn versioned_api_examples() -> Result<()> {
     let client = Client::with_options(options)?;
     // End Versioned API Example 4
 
+    let mut options = ClientOptions::parse(&uri).await?;
+    let server_api = ServerApi::builder()
+        .version(ServerApiVersion::V1)
+        .strict(true)
+        .build();
+    options.server_api = Some(server_api);
+    let client = Client::with_options(options)?;
+    let db = client.database("versioned-api-migration-examples");
+    db.collection::<Document>("sales").drop(None).await?;
+
+    use std::{error::Error, result::Result};
+    // Start Versioned API Example 5
+    // With the `bson-chrono-0_4` feature enabled, this function can be dropped in favor of using
+    // `chrono::DateTime` values directly.
+    fn iso_date(text: &str) -> Result<bson::DateTime, Box<dyn Error>> {
+        let chrono_dt = chrono::DateTime::parse_from_rfc3339(text)?;
+        Ok(bson::DateTime::from_millis(chrono_dt.timestamp_millis()))
+    }
+    db.collection("sales").insert_many(vec![
+        doc! { "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : iso_date("2021-01-01T08:00:00Z")? },
+        doc! { "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : iso_date("2021-02-03T09:05:00Z")? },
+        doc! { "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : iso_date("2021-02-03T09:00:00Z")? },
+        doc! { "_id" : 4, "item" : "abc", "price" : 10, "quantity" : 10, "date" : iso_date("2021-02-15T08:00:00Z")? },
+        doc! { "_id" : 5, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : iso_date("2021-02-15T09:05:00Z")? },
+        doc! { "_id" : 6, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : iso_date("2021-02-15T12:05:10Z")? },
+        doc! { "_id" : 7, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : iso_date("2021-02-15T14:12:12Z")? },
+        doc! { "_id" : 8, "item" : "abc", "price" : 10, "quantity" : 5, "date" : iso_date("2021-03-16T20:20:13Z")? }
+    ], None).await?;
+    // End Versioned API Example 5
+
+    // Start Versioned API Example 6
+    let result = db
+        .run_command(
+            doc! {
+                "count": "sales"
+            },
+            None,
+        )
+        .await;
+    if let Err(err) = &result {
+        println!("{:#?}", err.kind);
+        // Prints:
+        // Command(
+        //     CommandError {
+        //         code: 323,
+        //         code_name: "APIStrictError",
+        //         message: "Provided apiStrict:true, but the command count is not in API Version 1. Information on supported commands and migrations in API Version 1 can be found at https://dochub.mongodb.org/core/manual-versioned-api",
+        //     },
+        // )
+    }
+    // End Versioned API Example 6
+    if let ErrorKind::Command(ref err) = *result.as_ref().unwrap_err().kind {
+        assert_eq!(err.code, 323);
+        assert_eq!(err.code_name, "APIStrictError".to_string());
+    } else {
+        panic!("invalid result {:?}", result);
+    };
+
+    // Start Versioned API Example 7
+    let count = db
+        .collection::<Document>("sales")
+        .count_documents(None, None)
+        .await?;
+    // End Versioned API Example 7
+
+    // Start Versioned API Example 8
+    assert_eq!(count, 8);
+    // End Versioned API Example 8
+
     Ok(())
 }