Iterate over items asynchronously from Pager (#2659)

* Iterator over items asynchronously from Pager

For functions that return a `Pager<T>`, callers will iterate over items across all pages asynchronously by default but can get an async iterator (`Stream`) over pages as well.

Resolves #2205

* Update CHANGELOG for PagerResult changes

* Resolve PR feedback

Author: heaths

Cargo.lock

@@ -5,10 +5,16 @@
 ### Features Added
 
 - Added `#[safe]` attribute helper for `SafeDebug` derive macro to show or hide types and members as appropriate.
+- Added `Page` trait to facilitate the `ItemIterator`.
+- Added `PageIterator` to asynchronously iterator all pages.
 
 ### Breaking Changes
 
-- Removed `AccessToken::is_expired()`
+- A `Pager` now asynchronously iterates over items across all pages. Call `Pager::into_pages()` to get a `PageIterator` to asynchronously iterate over all pages.
+- Removed `AccessToken::is_expired()`.
+- Renamed `PagerResult::Continue` to `More` and its `continuation` field to `next`.
+- Renamed `PagerResult::Complete` to `Done`.
+- Renamed `PageStream` to `ItemIterator`.
 
 ### Bugs Fixed
 

sdk/core/azure_core/CHANGELOG.md

@@ -14,7 +14,7 @@ edition.workspace = true
 rust-version.workspace = true
 
 [dependencies]
-async-lock = { workspace = true }
+async-lock.workspace = true
 async-trait.workspace = true
 bytes.workspace = true
 futures.workspace = true

sdk/core/azure_core/Cargo.toml

@@ -14,7 +14,7 @@ so that once you learn how to use these APIs in one client library, you will kno
 Typically, you will not need to install `azure_core`;
 it will be installed for you when you install one of the client libraries using it.
 In case you want to install it explicitly - to implement your own client library, for example -
-you can find the crates.io package [here][Package (crates.io)].
+you can find the [package on crates.io][Package (crates.io)].
 
 ## Key concepts
 
@@ -178,7 +178,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
 ### Consuming service methods returning `Pager<T>`
 
-If a service call returns multiple values in pages, it would return `Result<Pager<T>>` as a result. You can iterator over each page's vector of results.
+If a service call returns multiple values in pages, it would return `Result<Pager<T>>` as a result. You can iterate all items from all pages.
 
 ```rust no_run
 use azure_identity::DefaultAzureCredential;
@@ -195,8 +195,39 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         None,
     )?;
 
-    // get a stream
-    let mut pager = client.list_secret_properties(None)?.into_stream();
+    // get a stream of items
+    let mut pager = client.list_secret_properties(None)?;
+
+    // poll the pager until there are no more SecretListResults
+    while let Some(secret) = pager.try_next().await? {
+        // get the secret name from the ID
+        let name = secret.resource_id()?.name;
+        println!("Found secret with name: {}", name);
+    }
+
+    Ok(())
+}
+```
+
+To instead iterate over all pages, call `into_pages()` on the returned `Pager`.
+
+```rust no_run
+use azure_identity::DefaultAzureCredential;
+use azure_security_keyvault_secrets::{ResourceExt, SecretClient};
+use futures::TryStreamExt;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // create a client
+    let credential = DefaultAzureCredential::new()?;
+    let client = SecretClient::new(
+        "https://<your-key-vault-name>.vault.azure.net/",
+        credential.clone(),
+        None,
+    )?;
+
+    // get a stream of pages
+    let mut pager = client.list_secret_properties(None)?.into_pages();
 
     // poll the pager until there are no more SecretListResults
     while let Some(secrets) = pager.try_next().await? {
@@ -213,7 +244,6 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
-<!-- ## Troubleshooting -->
 ## Troubleshooting
 
 ### Logging