RUST-649 Document versioned API usage with examples (#316)

Author: patrickfreed

src/client/options/mod.rs

@@ -248,19 +248,22 @@ impl<'de> Deserialize<'de> for ServerApiVersion {
     }
 }
 
-/// Declares a versioned server API
+/// Options used to declare a versioned server API.
 #[derive(Clone, Debug, Deserialize, PartialEq, TypedBuilder)]
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
 pub(crate) struct ServerApi {
-    /// The version string of the declared API version
+    /// The declared API version.
     pub version: ServerApiVersion,
 
-    /// Whether the server should return errors for features that are not part of the API version
+    /// Whether the MongoDB server should reject all commands that are not part of the
+    /// declared API version. This includes command options and aggregation pipeline stages.
     #[builder(default)]
     pub strict: Option<bool>,
 
-    /// Whether the server should return errors for deprecated features
+    /// Whether the MongoDB server should return command failures when functionality that is
+    /// deprecated from the declared API version is used.
+    /// Note that at the time of this writing, no deprecations in version 1 exist.
     #[builder(default)]
     pub deprecation_errors: Option<bool>,
 }
@@ -400,9 +403,15 @@ pub struct ClientOptions {
     #[builder(default)]
     pub selection_criteria: Option<SelectionCriteria>,
 
-    /// The declared API version
+    /// The declared API version for this client.
+    /// The declared API version is applied to all commands run through the client, including those
+    /// sent through any [crate::Database] or [crate::Collection] derived from the client.
     ///
-    /// The default value is to have no declared API version
+    /// Specifying versioned API options in the command document passed to
+    /// [crate::Database::run_command] AND declaring an API version on the client is not
+    /// supported and is considered undefined behaviour. To run any command with a different API
+    /// version or without declaring one, create a separate client that declares the
+    /// appropriate API version.
     #[builder(default, skip)]
     pub(crate) server_api: Option<ServerApi>,
 

src/test/documentation_examples.rs

@@ -1,10 +1,12 @@
 use futures::TryStreamExt;
+use tokio::sync::RwLockReadGuard;
 
 use crate::{
     bson::{doc, Bson},
     error::Result,
-    options::FindOptions,
-    test::TestClient,
+    options::{ClientOptions, CursorType, FindOptions, ServerApi, ServerApiVersion},
+    test::{TestClient, DEFAULT_URI, LOCK},
+    Client,
     Collection,
 };
 
@@ -1364,9 +1366,68 @@ async fn delete_examples(collection: &Collection) -> Result<()> {
     Ok(())
 }
 
+#[allow(unused_variables)]
+#[cfg(not(feature = "sync"))]
+async fn versioned_api_examples() -> Result<()> {
+    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(());
+    }
+
+    let uri = DEFAULT_URI.clone();
+    // Start 1. Declare an API version on a client
+    let mut options = ClientOptions::parse(&uri).await?;
+    let server_api = ServerApi::builder()
+        .version(ServerApiVersion::Version1)
+        .build();
+    options.server_api = Some(server_api);
+    let client = Client::with_options(options)?;
+    let cursor = client
+        .database("versioned_api_example")
+        .collection("example")
+        .find(None, None)
+        .await?;
+    // End 1.
+
+    // Start 2. Strict option
+    let mut options = ClientOptions::parse(&uri).await?;
+    let server_api = ServerApi::builder()
+        .version(ServerApiVersion::Version1)
+        .strict(true)
+        .build();
+    options.server_api = Some(server_api);
+    let client = Client::with_options(options)?;
+
+    let find_options = FindOptions::builder()
+        .cursor_type(CursorType::Tailable)
+        .build();
+    let cursor = client
+        .database("versioned_api_example")
+        .collection("example")
+        .find(None, find_options)
+        .await
+        .expect_err("should fail");
+    // End 2.
+
+    // Start 3. deprecationErrors option
+    let mut options = ClientOptions::parse(&uri).await?;
+    let server_api = ServerApi::builder()
+        .version(ServerApiVersion::Version1)
+        .deprecation_errors(true)
+        .build();
+    options.server_api = Some(server_api);
+    let client = Client::with_options(options)?;
+    // End 3.
+
+    Ok(())
+}
+
 #[cfg_attr(feature = "tokio-runtime", tokio::test)]
 #[cfg_attr(feature = "async-std-runtime", async_std::test)]
 async fn test() {
+    let _guard: RwLockReadGuard<_> = LOCK.run_concurrently().await;
+
     let client = TestClient::new().await;
     let coll = client
         .database("documentation_examples")
@@ -1383,4 +1444,5 @@ async fn test() {
     projection_examples(&coll).await.unwrap();
     update_examples(&coll).await.unwrap();
     delete_examples(&coll).await.unwrap();
+    versioned_api_examples().await.unwrap();
 }

src/test/mod.rs

@@ -5,6 +5,7 @@ mod client;
 mod coll;
 mod cursor;
 mod db;
+#[cfg(not(feature = "sync"))]
 mod documentation_examples;
 mod spec;
 mod util;