Get final state from pollers (Azure#3183)

Resolves Azure#2757

Author: heaths

sdk/core/azure_core/CHANGELOG.md

@@ -4,14 +4,21 @@
 
 ### Features Added
 
+- Added `Response::to_raw_response()` function to create a `RawResponse` from cloned data.
 - Added `UrlExt::append_path()`.
+- Implemented `IntoFuture` for a `Poller`. Call `await` on a Poller to get the final model, or `into_stream()` to get a `futures::Stream` to poll the operation manually.
 
 ### Breaking Changes
 
+- Added `F: Format` type parameter to `Poller` and `PollerResult`.
+- Added `Format` associated type to `StatusMonitor`.
+- Added `Format::deserialize()` function to `Format` trait.
+- Added `S` type parameter to `xml::from_xml` congruent with `json::from_json()`.
 - Moved deserializers and serializers for optional base64-encoded bytes to `base64::option` module. `base64` module now deserializes or serializes non-optional fields congruent with the `time` module.
 - Removed `constants` module.
 - Removed `CustomHeaders` policy.
 - Removed `ErrorKind::MockFramework`.
+- Removed `Poller::wait()` function. Call `await` on a `Poller` to wait for it to complete and, upon success, return the final model.
 - Removed `xml::read_xml_str()`.
 - Renamed `xml::read_xml()` to `xml::from_xml()` congruent with `json::from_json()`.
 

sdk/core/azure_core/README.md

@@ -379,19 +379,12 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         ..Default::default()
     };
 
-    // Wait for the certificate operation to complete and get the last status monitor.
-    let operation = client
+    // Wait for the certificate operation to complete and get the certificate.
+    let certificate = client
         .begin_create_certificate("certificate-name", body.try_into()?, None)?
-        .wait()
         .await?
-        // Deserialize the CertificateOperation:
         .into_body()?;
 
-    if matches!(operation.status, Some(status) if status == "completed") {
-        let target = operation.target.ok_or("expected target")?;
-        println!("Created certificate {}", target);
-    }
-
     Ok(())
 }
 ```

sdk/core/azure_core/examples/core_pager.rs

@@ -13,7 +13,7 @@ use std::sync::{
     Arc,
 };
 
-// This example demonstrates using a Pager to list secret properties from Key Vault.
+/// This example demonstrates using a [`Pager`] to list secret properties from Key Vault.
 async fn test_pager() -> Result<(), Box<dyn std::error::Error>> {
     let mut options = SecretClientOptions::default();
 
@@ -30,7 +30,7 @@ async fn test_pager() -> Result<(), Box<dyn std::error::Error>> {
     )?;
 
     // List secret properties using a Pager.
-    let mut pager = client.list_secret_properties(None)?.into_stream();
+    let mut pager = client.list_secret_properties(None)?;
     let mut names = Vec::new();
     while let Some(secret) = pager.try_next().await? {
         names.push(secret.resource_id()?.name);
@@ -40,15 +40,57 @@ async fn test_pager() -> Result<(), Box<dyn std::error::Error>> {
     Ok(())
 }
 
+/// This example demonstrates using a [`PageIterator`] to list pages of secret properties from Key Vault.
+///
+/// Some clients may return a `PageIterator` if there are no items to iterate or multiple items to iterate.
+/// The following example shows how you can also get a `PageIterator` from a [`Pager`] to iterate over pages instead of items.
+/// The pattern for iterating pages is otherwise the same:
+async fn test_page_iterator() -> Result<(), Box<dyn std::error::Error>> {
+    let mut options = SecretClientOptions::default();
+
+    // Ignore: this is only set up for testing.
+    // You normally would create credentials from `azure_identity` and
+    // use the default transport in production.
+    let (credential, transport) = setup()?;
+    options.client_options.transport = Some(Transport::new(transport));
+
+    let client = SecretClient::new(
+        "https://my-vault.vault.azure.net",
+        credential,
+        Some(options),
+    )?;
+
+    // List secret properties using a Pager.
+    let mut pager = client.list_secret_properties(None)?.into_pages();
+    let mut names = Vec::new();
+    while let Some(page) = pager.try_next().await? {
+        let page = page.into_body()?;
+        for secret in page.value {
+            names.push(secret.resource_id()?.name);
+        }
+    }
+    assert_eq!(names, vec!["secret-a", "secret-b", "secret-c"]);
+
+    Ok(())
+}
+
 // ----- BEGIN TEST SETUP -----
 #[tokio::test]
 async fn test_core_pager() -> Result<(), Box<dyn std::error::Error>> {
     test_pager().await
 }
 
+#[tokio::test]
+async fn test_core_page_iterator() -> Result<(), Box<dyn std::error::Error>> {
+    test_page_iterator().await
+}
+
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    test_pager().await
+    test_pager().await?;
+    test_page_iterator().await?;
+
+    Ok(())
 }
 
 #[allow(clippy::type_complexity)]

sdk/core/azure_core/examples/core_poller.rs

@@ -12,13 +12,13 @@ use azure_core_test::{credentials::MockCredential, http::MockHttpClient};
 use azure_security_keyvault_certificates::{
     models::CreateCertificateParameters, CertificateClient, CertificateClientOptions,
 };
-use futures::FutureExt;
+use futures::{FutureExt as _, TryStreamExt as _};
 use std::sync::{
     atomic::{AtomicUsize, Ordering},
     Arc,
 };
 
-// This example demonstrates using a Poller to create a certificate with the CertificateClient.
+/// This example demonstrates using a [`Poller`] to await a long-running operation (LRO) to create a certificate with the CertificateClient.
 async fn test_poller() -> Result<(), Box<dyn std::error::Error>> {
     let mut options = CertificateClientOptions::default();
 
@@ -38,13 +38,59 @@ async fn test_poller() -> Result<(), Box<dyn std::error::Error>> {
     let params = CreateCertificateParameters::default();
 
     // Start a create_certificate long-running operation.
-    let operation = client
+    let certificate = client
         .begin_create_certificate("my-cert", params.try_into()?, None)?
-        .wait()
         .await?
         .into_body()?;
-    assert_eq!(operation.status.as_deref(), Some("completed"));
-    assert!(operation.target.is_some());
+    assert_eq!(
+        certificate.id,
+        Some("https://my-vault.vault.azure.net/certificates/my-cert/version".into())
+    );
+    assert_eq!(certificate.cer, Some(b"test".to_vec()));
+
+    Ok(())
+}
+
+/// This example demonstrates using a [`Poller`] to manually poll status for a long-running operation (LRO) to create a certificate with the CertificateClient.
+///
+/// If you want to manually poll status updates, you can use the `Poller` as a stream by calling [`try_next`](futures::TryStreamExt::try_next) on a mutable reference.
+/// The stream will end when the operation completes, and the final status contains information about the completed operation.
+async fn test_poller_stream() -> Result<(), Box<dyn std::error::Error>> {
+    let mut options = CertificateClientOptions::default();
+
+    // Ignore: this is only set up for testing.
+    // You normally would create credentials from `azure_identity` and
+    // use the default transport in production.
+    let (credential, transport) = setup()?;
+    options.client_options.transport = Some(Transport::new(transport));
+
+    let client = CertificateClient::new(
+        "https://my-vault.vault.azure.net",
+        credential,
+        Some(options),
+    )?;
+
+    // Minimal create parameters (empty policy for mock)
+    let params = CreateCertificateParameters::default();
+
+    // Start a create_certificate long-running operation and manually poll status.
+    let mut poller = client.begin_create_certificate("my-cert", params.try_into()?, None)?;
+
+    // Manually poll status updates until completion
+    let mut final_status = None;
+    while let Some(status) = poller.try_next().await? {
+        let status = status.into_body()?;
+        assert!(status.error.is_none());
+        final_status = Some(status);
+    }
+
+    // The last status should indicate completion
+    let status = final_status.expect("expected at least one status update");
+    assert_eq!(status.status.as_deref(), Some("completed"));
+    assert_eq!(
+        status.target.as_deref(),
+        Some("https://my-vault.vault.azure.net/certificates/my-cert")
+    );
 
     Ok(())
 }
@@ -55,11 +101,20 @@ async fn test_core_poller() -> Result<(), Box<dyn std::error::Error>> {
     test_poller().await
 }
 
+#[tokio::test]
+async fn test_core_poller_stream() -> Result<(), Box<dyn std::error::Error>> {
+    test_poller_stream().await
+}
+
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    test_poller().await
+    test_poller().await?;
+    test_poller_stream().await?;
+
+    Ok(())
 }
 
+/// Setup for the await example - returns all 3 responses including the final target
 #[allow(clippy::type_complexity)]
 fn setup() -> Result<(Arc<dyn TokenCredential>, Arc<dyn HttpClient>), Box<dyn std::error::Error>> {
     let credential: Arc<dyn TokenCredential> = MockCredential::new()?;
@@ -74,7 +129,7 @@ fn setup() -> Result<(Arc<dyn TokenCredential>, Arc<dyn HttpClient>), Box<dyn st
                     0 => {
                         // Initial POST to start operation
                         assert_eq!(request.method(), Method::Post);
-                        assert!(request.url().path().starts_with("/certificates/my-cert/create"));
+                        assert_eq!(request.url().path(), "/certificates/my-cert/create");
                         let mut headers = Headers::new();
                         headers.insert(RETRY_AFTER, "0");
                         Ok(BufResponse::from_bytes(
@@ -86,13 +141,23 @@ fn setup() -> Result<(Arc<dyn TokenCredential>, Arc<dyn HttpClient>), Box<dyn st
                     1 => {
                         // Polling GET for status
                         assert_eq!(request.method(), Method::Get);
-                        assert!(request.url().path().starts_with("/certificates/my-cert/pending"));
+                        assert_eq!(request.url().path(), "/certificates/my-cert/pending");
                         Ok(BufResponse::from_bytes(
                             StatusCode::Ok,
                             Headers::new(),
                             r#"{"id":"https://my-vault.vault.azure.net/certificates/my-cert/pending","status":"completed","target":"https://my-vault.vault.azure.net/certificates/my-cert"}"#,
                         ))
                     }
+                    2 => {
+                        // Final GET for the target
+                        assert_eq!(request.method(), Method::Get);
+                        assert_eq!(request.url().path(), "/certificates/my-cert");
+                        Ok(BufResponse::from_bytes(
+                            StatusCode::Ok,
+                            Headers::new(),
+                            r#"{"id":"https://my-vault.vault.azure.net/certificates/my-cert/version","cer":"dGVzdA=="}"#,
+                        ))
+                    }
                     _ => panic!("unexpected request count {idx}"),
                 }
             }