Skip to content

Commit 5d82ca6

Browse files
coryancoryan
authored
docs: improve LRO policy guide (#2333)
Say something about the need to set the retry policy too. I also changed all the examples to set a retry policy, that should avoid some future flakes when we run these tests.
1 parent a0d101d commit 5d82ca6

File tree

4 files changed

+117
-12
lines changed

4 files changed

+117
-12
lines changed

‎guide/samples/src/lro.rs

Lines changed: 39 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,19 @@ use google_cloud_speech_v2 as speech;
1919

2020
// ANCHOR: start
2121
pub async fn start(project_id: &str) -> crate::Result<()> {
22+
use google_cloud_gax::retry_policy::Aip194Strict;
23+
use google_cloud_gax::retry_policy::RetryPolicyExt;
24+
use std::time::Duration;
25+
2226
// ANCHOR: client
23-
let client = speech::client::Speech::builder().build().await?;
27+
let client = speech::client::Speech::builder()
28+
.with_retry_policy(
29+
Aip194Strict
30+
.with_attempt_limit(5)
31+
.with_time_limit(Duration::from_secs(30)),
32+
)
33+
.build()
34+
.await?;
2435
// ANCHOR_END: client
2536

2637
// ANCHOR: request-builder
@@ -68,12 +79,24 @@ pub async fn start(project_id: &str) -> crate::Result<()> {
6879

6980
// ANCHOR: automatic
7081
pub async fn automatic(project_id: &str) -> crate::Result<()> {
82+
use google_cloud_gax::retry_policy::Aip194Strict;
83+
use google_cloud_gax::retry_policy::RetryPolicyExt;
84+
use std::time::Duration;
85+
7186
// ANCHOR: automatic-use
7287
use google_cloud_lro::Poller;
7388
// ANCHOR_END: automatic-use
74-
// ANCHOR: automatic-prepare
75-
let client = speech::client::Speech::builder().build().await?;
7689

90+
let client = speech::client::Speech::builder()
91+
.with_retry_policy(
92+
Aip194Strict
93+
.with_attempt_limit(5)
94+
.with_time_limit(Duration::from_secs(30)),
95+
)
96+
.build()
97+
.await?;
98+
99+
// ANCHOR: automatic-prepare
77100
let response = client
78101
.batch_recognize()
79102
.set_recognizer(format!(
@@ -111,11 +134,22 @@ pub async fn automatic(project_id: &str) -> crate::Result<()> {
111134

112135
// ANCHOR: polling
113136
pub async fn polling(project_id: &str) -> crate::Result<()> {
137+
use google_cloud_gax::retry_policy::Aip194Strict;
138+
use google_cloud_gax::retry_policy::RetryPolicyExt;
139+
use std::time::Duration;
140+
114141
// ANCHOR: polling-use
115142
use google_cloud_lro::{Poller, PollingResult};
116143
// ANCHOR_END: polling-use
117-
// ANCHOR: polling-prepare
118-
let client = speech::client::Speech::builder().build().await?;
144+
145+
let client = speech::client::Speech::builder()
146+
.with_retry_policy(
147+
Aip194Strict
148+
.with_attempt_limit(5)
149+
.with_time_limit(Duration::from_secs(30)),
150+
)
151+
.build()
152+
.await?;
119153

120154
let mut poller = client
121155
.batch_recognize()
@@ -137,7 +171,6 @@ pub async fn polling(project_id: &str) -> crate::Result<()> {
137171
.set_model("short")
138172
.set_auto_decoding_config(speech::model::AutoDetectDecodingConfig::new()),
139173
)
140-
// ANCHOR_END: polling-prepare
141174
// ANCHOR: polling-poller
142175
.poller();
143176
// ANCHOR_END: polling-poller

‎guide/samples/src/pagination.rs

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,17 @@ use google_cloud_gax as gax;
1818

1919
pub async fn paginator_iterate_pages(project_id: &str) -> crate::Result<()> {
2020
use google_cloud_gax::paginator::Paginator as _;
21+
use google_cloud_gax::retry_policy::AlwaysRetry;
22+
use google_cloud_gax::retry_policy::RetryPolicyExt;
2123
use google_cloud_secretmanager_v1 as secret_manager;
24+
use std::time::Duration;
2225

2326
let client = secret_manager::client::SecretManagerService::builder()
27+
.with_retry_policy(
28+
AlwaysRetry
29+
.with_attempt_limit(5)
30+
.with_time_limit(Duration::from_secs(15)),
31+
)
2432
.build()
2533
.await?;
2634

@@ -44,9 +52,17 @@ pub async fn paginator_iterate_pages(project_id: &str) -> crate::Result<()> {
4452
pub async fn paginator_stream_pages(project_id: &str) -> crate::Result<()> {
4553
use futures::stream::StreamExt;
4654
use google_cloud_gax::paginator::Paginator as _;
55+
use google_cloud_gax::retry_policy::AlwaysRetry;
56+
use google_cloud_gax::retry_policy::RetryPolicyExt;
4757
use google_cloud_secretmanager_v1 as secret_manager;
58+
use std::time::Duration;
4859

4960
let client = secret_manager::client::SecretManagerService::builder()
61+
.with_retry_policy(
62+
AlwaysRetry
63+
.with_attempt_limit(5)
64+
.with_time_limit(Duration::from_secs(15)),
65+
)
5066
.build()
5167
.await?;
5268

@@ -74,9 +90,17 @@ pub async fn paginator_iterate_items(project_id: &str) -> crate::Result<()> {
7490
// ANCHOR: paginator-use
7591
use google_cloud_gax::paginator::ItemPaginator as _;
7692
// ANCHOR_END: paginator-use
93+
use google_cloud_gax::retry_policy::AlwaysRetry;
94+
use google_cloud_gax::retry_policy::RetryPolicyExt;
7795
use google_cloud_secretmanager_v1 as secret_manager;
96+
use std::time::Duration;
7897

7998
let client = secret_manager::client::SecretManagerService::builder()
99+
.with_retry_policy(
100+
AlwaysRetry
101+
.with_attempt_limit(5)
102+
.with_time_limit(Duration::from_secs(15)),
103+
)
80104
.build()
81105
.await?;
82106

@@ -97,9 +121,17 @@ pub async fn paginator_iterate_items(project_id: &str) -> crate::Result<()> {
97121
pub async fn paginator_stream_items(project_id: &str) -> crate::Result<()> {
98122
use futures::stream::StreamExt;
99123
use google_cloud_gax::paginator::ItemPaginator as _;
124+
use google_cloud_gax::retry_policy::AlwaysRetry;
125+
use google_cloud_gax::retry_policy::RetryPolicyExt;
100126
use google_cloud_secretmanager_v1 as secret_manager;
127+
use std::time::Duration;
101128

102129
let client = secret_manager::client::SecretManagerService::builder()
130+
.with_retry_policy(
131+
AlwaysRetry
132+
.with_attempt_limit(5)
133+
.with_time_limit(Duration::from_secs(15)),
134+
)
103135
.build()
104136
.await?;
105137

@@ -123,9 +155,17 @@ pub async fn paginator_stream_items(project_id: &str) -> crate::Result<()> {
123155
}
124156

125157
pub async fn pagination_page_token(project_id: &str) -> crate::Result<()> {
158+
use google_cloud_gax::retry_policy::AlwaysRetry;
159+
use google_cloud_gax::retry_policy::RetryPolicyExt;
126160
use google_cloud_secretmanager_v1 as secret_manager;
161+
use std::time::Duration;
127162

128163
let client = secret_manager::client::SecretManagerService::builder()
164+
.with_retry_policy(
165+
AlwaysRetry
166+
.with_attempt_limit(5)
167+
.with_time_limit(Duration::from_secs(15)),
168+
)
129169
.build()
130170
.await?;
131171

‎guide/samples/src/polling_policies.rs

Lines changed: 24 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -138,20 +138,30 @@ pub async fn client_errors(project_id: &str) -> crate::Result<()> {
138138
// ANCHOR: client-errors-use
139139
use google_cloud_gax::polling_error_policy::Aip194Strict;
140140
use google_cloud_gax::polling_error_policy::PollingErrorPolicyExt;
141+
use google_cloud_gax::retry_policy;
142+
use google_cloud_gax::retry_policy::RetryPolicyExt;
141143
use std::time::Duration;
142144
// ANCHOR_END: client-errors-use
143145
use google_cloud_lro::Poller;
144146

145147
// ANCHOR: client-errors-client
146-
let client = speech::client::Speech::builder()
147-
.with_polling_error_policy(
148-
Aip194Strict
148+
let builder = speech::client::Speech::builder().with_polling_error_policy(
149+
Aip194Strict
150+
.with_attempt_limit(100)
151+
.with_time_limit(Duration::from_secs(300)),
152+
);
153+
// ANCHOR_END: client-errors-client
154+
155+
// ANCHOR: client-errors-client-retry
156+
let client = builder
157+
.with_retry_policy(
158+
retry_policy::Aip194Strict
149159
.with_attempt_limit(100)
150160
.with_time_limit(Duration::from_secs(300)),
151161
)
152162
.build()
153163
.await?;
154-
// ANCHOR_END: client-errors-client
164+
// ANCHOR_END: client-errors-client-retry
155165

156166
// ANCHOR: client-errors-builder
157167
let response = client
@@ -194,6 +204,8 @@ pub async fn rpc_errors(project_id: &str) -> crate::Result<()> {
194204
// ANCHOR: rpc-errors-use
195205
use google_cloud_gax::polling_error_policy::Aip194Strict;
196206
use google_cloud_gax::polling_error_policy::PollingErrorPolicyExt;
207+
use google_cloud_gax::retry_policy;
208+
use google_cloud_gax::retry_policy::RetryPolicyExt;
197209
use std::time::Duration;
198210
// ANCHOR_END: rpc-errors-use
199211
// ANCHOR: rpc-errors-builder-trait
@@ -202,7 +214,14 @@ pub async fn rpc_errors(project_id: &str) -> crate::Result<()> {
202214
use google_cloud_lro::Poller;
203215

204216
// ANCHOR: rpc-errors-client
205-
let client = speech::client::Speech::builder().build().await?;
217+
let client = speech::client::Speech::builder()
218+
.with_retry_policy(
219+
retry_policy::Aip194Strict
220+
.with_attempt_limit(100)
221+
.with_time_limit(Duration::from_secs(300)),
222+
)
223+
.build()
224+
.await?;
206225
// ANCHOR_END: rpc-errors-client
207226

208227
// ANCHOR: rpc-errors-builder

‎guide/src/configuring_polling_policies.md

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -151,12 +151,18 @@ conservative choice is [Aip194Strict]:
151151
If you are planning to use the same polling policy for all (or even most)
152152
requests with the same client then consider setting this as a client option.
153153

154-
Initialize the client with the configuration you want:
154+
Add the polling policies that you will use for all long running operations:
155155

156156
```rust,ignore
157157
{{#include ../samples/src/polling_policies.rs:client-errors-client}}
158158
```
159159

160+
You can also add retry policies to handle errors in the initial request:
161+
162+
```rust,ignore
163+
{{#include ../samples/src/polling_policies.rs:client-errors-client-retry}}
164+
```
165+
160166
Unless you override the policy with a [per-request setting] this policy will be
161167
in effect for any long-running operation started with the client. In this
162168
example, if you make a call such as:
@@ -211,6 +217,13 @@ You can issue this request as usual. For example:
211217
{{#include ../samples/src/polling_policies.rs:rpc-errors-print}}
212218
```
213219

220+
Consider adding a retry policy in case the initial request to start the LRO
221+
fails:
222+
223+
```rust,ignore
224+
{{#include ../samples/src/polling_policies.rs:rpc-errors-client}}
225+
```
226+
214227
See
215228
[below](#configuring-the-retryable-polling-errors-for-a-specific-request-complete-code)
216229
for the complete code.

0 commit comments

Comments
 (0)