Expose CosmosDB methods as traits (#281)

Author: Francesco Cogno

README.md

@@ -5,7 +5,7 @@
 
 [![Build Status](https://travis-ci.org/MindFlavor/AzureSDKForRust.svg?branch=master)](https://travis-ci.org/MindFlavor/AzureSDKForRust) [![Coverage Status](https://coveralls.io/repos/MindFlavor/AzureSDKForRust/badge.svg?branch=master&service=github)](https://coveralls.io/github/MindFlavor/AzureSDKForRust?branch=master) ![stability-unstable](https://img.shields.io/badge/stability-unstable-yellow.svg)
 
-[![tag](https://img.shields.io/github/tag/mindflavor/AzureSDKForRust.svg)](https://github.com/MindFlavor/AzureSDKForRust/tree/cosmos_0.43.1) [![release](https://img.shields.io/github/release/mindflavor/AzureSDKForRust.svg)](https://github.com/MindFlavor/AzureSDKForRust/releases/tag/cosmos_0.43.1) [![commitssince](https://img.shields.io/github/commits-since/mindflavor/AzureSDKForRust/cosmos_0.43.1)](https://github.com/MindFlavor/AzureSDKForRust/commits/master)
+[![tag](https://img.shields.io/github/tag/mindflavor/AzureSDKForRust.svg)](https://github.com/MindFlavor/AzureSDKForRust/tree/cosmos_0.100.0) [![release](https://img.shields.io/github/release/mindflavor/AzureSDKForRust.svg)](https://github.com/MindFlavor/AzureSDKForRust/releases/tag/cosmos_0.100.0) [![commitssince](https://img.shields.io/github/commits-since/mindflavor/AzureSDKForRust/cosmos_0.100.0)](https://github.com/MindFlavor/AzureSDKForRust/commits/master)
 
 [![GitHub contributors](https://img.shields.io/github/contributors/MindFlavor/AzureSDKForRust.svg)](https://github.com/MindFlavor/AzureSDKForRust/graphs/contributors)
 
@@ -50,7 +50,7 @@ You can find examples in the [```examples```](https://github.com/MindFlavor/Azur
 ```rust
 #[macro_use]
 extern crate serde_derive;
-// Using the prelude module of the CosmosDB crate makes easier to use the Rust Azure SDK for Cosmos
+// Using the prelude module of the Cosmos crate makes easier to use the Rust Azure SDK for Cosmos
 // DB.
 use azure_sdk_core::prelude::*;
 use azure_sdk_cosmos::prelude::*;
@@ -97,14 +97,15 @@ async fn main() -> Result<(), Box<dyn Error>> {
     let authorization_token = AuthorizationToken::new_master(&master_key)?;
 
     // Next we will create a Cosmos client.
-    let client = ClientBuilder::new(account, authorization_token.clone())?;
+    let client = ClientBuilder::new(account, authorization_token)?;
     // We know the database so we can obtain a database client.
-    let database_client = client.with_database(&database_name);
+    let database_client = client.with_database_client(database_name);
     // We know the collection so we can obtain a collection client.
-    let collection_client = database_client.with_collection(&collection_name);
+    let collection_client = database_client.with_collection_client(collection_name);
 
     // TASK 1 - Insert 10 documents
     println!("Inserting 10 documents...");
+    let mut session_token = None;
     for i in 0..10 {
         // define the document.
         let document_to_insert = Document::new(MySampleStruct {
@@ -114,31 +115,42 @@ async fn main() -> Result<(), Box<dyn Error>> {
             a_timestamp: chrono::Utc::now().timestamp(),
         });
 
-        // insert it!
-        collection_client
-            .create_document()
-            .with_document(&document_to_insert)
-            .with_partition_keys(PartitionKeys::new().push(&document_to_insert.document.a_number)?)
-            .with_is_upsert(true) // this option will overwrite a preexisting document (if any)
-            .execute()
-            .await?;
+        // insert it and store the returned session token for later use!
+        session_token = Some(
+            collection_client
+                .create_document()
+                .with_partition_keys(
+                    PartitionKeys::new().push(&document_to_insert.document.a_number)?,
+                )
+                .with_is_upsert(true) // this option will overwrite a preexisting document (if any)
+                .execute_with_document(&document_to_insert)
+                .await?
+                .session_token, // get only the session token, if everything else was ok!
+        );
     }
     // wow that was easy and fast, wasnt'it? :)
     println!("Done!");
 
+    let session_token = ConsistencyLevel::from(session_token.unwrap());
+
     // TASK 2
-    println!("\nStreaming documents");
-    // we limit the number of documents to 3 for each batch as a demonstration. In practice
-    // you will use a more sensible number (or accept the Azure default).
-    let stream = collection_client.list_documents().with_max_item_count(3);
-    let mut stream = Box::pin(stream.stream::<MySampleStruct>());
-    // TODO: As soon as the streaming functionality is stabilized
-    // in Rust we can substitute this while let Some... into
-    // for each (or whatever the Rust team picks).
-    while let Some(res) = stream.next().await {
-        let res = res?;
-        println!("Received {} documents in one batch!", res.documents.len());
-        res.documents.iter().for_each(|doc| println!("{:#?}", doc));
+    {
+        println!("\nStreaming documents");
+        // we limit the number of documents to 3 for each batch as a demonstration. In practice
+        // you will use a more sensible number (or accept the Azure default).
+        let stream = collection_client
+            .list_documents()
+            .with_consistency_level(session_token.clone())
+            .with_max_item_count(3);
+        let mut stream = Box::pin(stream.stream::<MySampleStruct>());
+        // TODO: As soon as the streaming functionality is stabilized
+        // in Rust we can substitute this while let Some... into
+        // for each (or whatever the Rust team picks).
+        while let Some(res) = stream.next().await {
+            let res = res?;
+            println!("Received {} documents in one batch!", res.documents.len());
+            res.documents.iter().for_each(|doc| println!("{:#?}", doc));
+        }
     }
 
     // TASK 3
@@ -147,6 +159,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
         .query_documents()
         .with_query(&("SELECT * FROM A WHERE A.a_number < 600".into())) // there are other ways to construct a query, this is the simplest.
         .with_query_cross_partition(true) // this will perform a cross partition query! notice how simple it is!
+        .with_consistency_level(session_token)
         .execute::<MySampleStruct>() // This will make sure the result is our custom struct!
         .await?
         .into_documents() // queries can return Documents or Raw json (ie without etag, _rid, etc...). Since our query return docs we convert with this function.
@@ -165,6 +178,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
         });
 
     // TASK 4
+    let session_token = ConsistencyLevel::from(query_documents_response.session_token.clone());
     for ref document in query_documents_response.results {
         // From our query above we are sure to receive a Document.
         println!(
@@ -174,11 +188,9 @@ async fn main() -> Result<(), Box<dyn Error>> {
 
         // to spice the delete a little we use optimistic concurreny
         collection_client
-            .with_document(
-                &document.result.id,
-                PartitionKeys::new().push(&document.result.a_number)?,
-            )
+            .with_document_client(&document.result.id as &str, document.result.a_number.into())
             .delete_document()
+            .with_consistency_level(session_token.clone())
             .with_if_match_condition((&document.document_attributes).into())
             .execute()
             .await?;
@@ -188,6 +200,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     // Now the list documents should return 4 documents!
     let list_documents_response = collection_client
         .list_documents()
+        .with_consistency_level(session_token)
         .execute::<serde_json::Value>() // you can use this if you don't know/care about the return type!
         .await?;
     assert_eq!(list_documents_response.documents.len(), 4);

azure_sdk_cosmos/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name          = "azure_sdk_cosmos"
-version       = "0.43.1"
+version       = "0.100.0"
 description   = "Rust wrappers around Microsoft Azure REST APIs - Azure Cosmos DB crate"
 readme        = "README.md"
 authors       = ["Francesco Cogno <francesco.cogno@outlook.com>", "Max Gortman <mgortman@microsoft.com>"]

…ure_sdk_cosmos/examples/attachments00.rs …re_sdk_cosmos/examples/attachments_00.rsazure_sdk_cosmos/examples/attachments00.rs renamed to azure_sdk_cosmos/examples/attachments_00.rs azure_sdk_cosmos/examples/attachments00.rs renamed to azure_sdk_cosmos/examples/attachments_00.rs

@@ -37,8 +37,8 @@ async fn main() -> Result<(), Box<dyn Error>> {
     let authorization_token = AuthorizationToken::new_master(&master_key)?;
 
     let client = ClientBuilder::new(account, authorization_token)?;
-    let client = client.with_database(&database_name);
-    let client = client.with_collection(&collection_name);
+    let client = client.into_database_client(database_name);
+    let client = client.into_collection_client(collection_name);
 
     let id = format!("unique_id{}", 100);
 
@@ -52,9 +52,8 @@ async fn main() -> Result<(), Box<dyn Error>> {
     // let's add an entity.
     match client
         .create_document()
-        .with_document(&doc)
         .with_partition_keys(PartitionKeys::new().push(&doc.document.id)?)
-        .execute()
+        .execute_with_document(&doc)
         .await
     {
         Ok(_) => {
@@ -67,15 +66,15 @@ async fn main() -> Result<(), Box<dyn Error>> {
 
     let mut partition_keys = PartitionKeys::new();
     partition_keys.push(&doc.document.id)?;
-    let document_client = client.with_document(&id, &partition_keys);
+    let document_client = client.with_document_client(id, partition_keys);
 
     // list attachments
     let ret = document_client.list_attachments().execute().await?;
     println!("list attachments == {:#?}", ret);
 
     // reference attachment
     println!("creating");
-    let attachment_client = document_client.with_attachment(&"myref03");
+    let attachment_client = document_client.with_attachment_client("myref06");
     let resp = attachment_client
         .create_reference()
         .with_consistency_level((&ret).into())
@@ -91,8 +90,17 @@ async fn main() -> Result<(), Box<dyn Error>> {
     // sure to find the just created attachment
     let session_token: ConsistencyLevel = resp.into();
 
+    let resp = attachment_client
+        .get()
+        .with_consistency_level(session_token)
+        .execute()
+        .await?;
+
+    println!("get attachment == {:#?}", resp);
+    let session_token: ConsistencyLevel = resp.into();
+
     println!("replacing");
-    let attachment_client = document_client.with_attachment(&"myref03");
+    let attachment_client = document_client.with_attachment_client("myref06");
     let resp = attachment_client
         .replace_reference()
         .with_consistency_level(session_token)
@@ -114,7 +122,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
 
     // slug attachment
     println!("creating slug attachment");
-    let attachment_client = document_client.with_attachment(&"slug00");
+    let attachment_client = document_client.with_attachment_client("slug00");
     let resp = attachment_client
         .create_slug()
         .with_consistency_level((&resp_delete).into())

azure_sdk_cosmos/examples/collection.rs

@@ -22,7 +22,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     // Once we have an authorization token you can create a client instance. You can change the
     // authorization token at later time if you need, for example, to escalate the privileges for a
     // single operation.
-    let client = ClientBuilder::new(account.clone(), authorization_token)?;
+    let client = ClientBuilder::new(&account, authorization_token)?;
 
     // The Cosmos' client exposes a lot of methods. This one lists the databases in the specified
     // account. Database do not implement Display but deref to &str so you can pass it to methods
@@ -39,7 +39,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     if let Some(db) = databases.databases.first() {
         println!("getting info of database {}", &db.id);
         let db = client
-            .with_database(&db.id)
+            .with_database_client(&db.id)
             .get_database()
             .execute()
             .await?;
@@ -50,7 +50,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     // list_collection method.
     for db in databases.databases {
         let collections = client
-            .with_database(&db.id)
+            .with_database_client(&db.id)
             .list_collections()
             .execute()
             .await?;
@@ -64,8 +64,8 @@ async fn main() -> Result<(), Box<dyn Error>> {
             println!("\tcollection {}", collection.id);
 
             let collection_response = client
-                .with_database(&db.id)
-                .with_collection(&collection.id)
+                .with_database_client(&db.id)
+                .with_collection_client(&collection.id)
                 .get_collection()
                 .execute()
                 .await?;

azure_sdk_cosmos/examples/create_delete_database.rs

@@ -27,7 +27,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     // Once we have an authorization token you can create a client instance. You can change the
     // authorization token at later time if you need, for example, to escalate the privileges for a
     // single operation.
-    let client = ClientBuilder::new(account.clone(), authorization_token)?;
+    let client = ClientBuilder::new(&account, authorization_token)?;
 
     // The Cosmos' client exposes a lot of methods. This one lists the databases in the specified
     // account. Database do not implement Display but deref to &str so you can pass it to methods
@@ -45,7 +45,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
 
     // create collection!
     {
-        let db_client = client.with_database(&database_name);
+        let db_client = client.with_database_client(&database_name);
 
         let indexes = IncludedPathIndex {
             kind: KeyKind::Hash,
@@ -79,7 +79,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
             create_collection_response
         );
 
-        let db_collection = db_client.with_collection(&"panzadoro");
+        let db_collection = db_client.with_collection_client("panzadoro");
 
         let get_collection_response = db_collection.get_collection().execute().await?;
         println!("get_collection_response == {:#?}", get_collection_response);
@@ -96,7 +96,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     }
 
     let resp = client
-        .with_database(&database_name)
+        .with_database_client(&database_name)
         .delete_database()
         .execute()
         .await?;

azure_sdk_cosmos/examples/database00.rs azure_sdk_cosmos/examples/database_00.rsazure_sdk_cosmos/examples/database00.rs renamed to azure_sdk_cosmos/examples/database_00.rs

@@ -22,18 +22,18 @@ async fn main() -> Result<(), Box<dyn Error>> {
 
     let authorization_token = AuthorizationToken::new_master(&master_key)?;
 
-    let client = ClientBuilder::new(account.clone(), authorization_token)?;
+    let client = ClientBuilder::new(&account, authorization_token)?;
 
     let dbs = client.list_databases().execute().await?;
 
     for db in dbs.databases {
         println!("database == {:?}", db);
-        let database = client.with_database(&db);
+        let database = client.with_database_client(db.name());
 
         let collections = database.list_collections().execute().await?;
         for collection in collections.collections {
             println!("collection == {:?}", collection);
-            let collection_client = database.with_collection(&collection);
+            let collection_client = database.with_collection_client(collection.id);
 
             if collection_client.collection_name().name() == "democ" {
                 println!("democ!");
@@ -53,10 +53,9 @@ async fn main() -> Result<(), Box<dyn Error>> {
                 let document = Document::new(v);
                 let resp = collection_client
                     .create_document()
-                    .with_document(&document)
                     .with_partition_keys(PartitionKeys::new().push(&43u32)?)
                     .with_is_upsert(true)
-                    .execute()
+                    .execute_with_document(&document)
                     .await?;
 
                 println!("resp == {:?}", resp);

azure_sdk_cosmos/examples/database_01.rs

@@ -0,0 +1,30 @@
+use azure_sdk_cosmos::prelude::*;
+use std::error::Error;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    // First we retrieve the account name and master key from environment variables.
+    // We expect master keys (ie, not resource constrained)
+    let master_key =
+        std::env::var("COSMOS_MASTER_KEY").expect("Set env variable COSMOS_MASTER_KEY first!");
+    let account = std::env::var("COSMOS_ACCOUNT").expect("Set env variable COSMOS_ACCOUNT first!");
+
+    let authorization_token = AuthorizationToken::new_master(&master_key)?;
+    let cosmos_client = ClientBuilder::new(&account, authorization_token)?;
+    //let databases = cosmos_client.list_databases().execute().await?;
+    //println!("databases == {:#?}", databases);
+
+    let database_client = cosmos_client.with_database_client("pollo");
+    println!("database_name == {}", database_client.database_name());
+
+    let collections = database_client.list_collections().execute().await?;
+    println!("collections == {:#?}", collections);
+
+    let collection_client = database_client.with_collection_client("cnt");
+    let collection = collection_client.get_collection().execute().await?;
+    println!("collection == {:#?}", collection);
+
+    //let collection_client = database_client.with_collection(&"cnt");
+
+    Ok(())
+}