Struct RetryPolicy 

pub struct RetryPolicy { /* private fields */ }

Which failures a call repeats, how often, and how long it waits first.

Build one from RetryPolicy::default and its setters, then give it to a client with ClientBuilder::retry or to one call with SystemOne::retry or ListModels::retry. A policy given to a call replaces the client’s for that call only.

A failed attempt is retried when all of these hold, checked in this order:

1. The failure is retryable: a timeout (unless api_timeout_error is off), a connection failure (unless api_connection_error is off), or an API error whose status is in http_statuses - or else the predicate says so. A request that could not be built, a response that did not decode and a response over the size limit are never retryable on their own; only the predicate can ask for them.
2. Fewer than max_retries retries have been made.
3. The wait before the next attempt, added to the time the call has already taken, stays below the timeout budget.

The wait is what the server asked for in retry-after-ms or Retry-After, when respect_retry_after is on and the failure carries one, however long that is. Otherwise it is the backoff: backoff_initial doubled once per attempt up to backoff_max, less a random share of up to backoff_jitter of it, in whole milliseconds.

When retrying stops, the call fails with the last attempt’s error exactly as that attempt produced it.

use std::time::Duration;

use typesafe_sdk::{RetryPolicy, StatusSet};

let policy = RetryPolicy::default()
    .max_retries(3)
    .backoff_max(Duration::from_secs(2))
    .http_statuses([429, 502, 503, 504].into_iter().collect::<StatusSet>())
    .timeout(Duration::from_secs(10))?;

Implementations

impl RetryPolicy

pub const fn new() -> Self

The Python SDK’s defaults, which Default also gives: 2 retries, a backoff from 500 ms up to 5 s with a jitter of 0.25, the statuses of StatusSet::DEFAULT, Retry-After respected, connection failures and timeouts retried, no predicate, and a budget of 30 s.

pub fn max_retries(self, retries: u32) -> Self

The most retries after the first attempt; 0 makes one attempt only.

pub fn backoff_initial(self, delay: Duration) -> Self

The wait after the first failed attempt, doubled after each later one up to backoff_max. Zero turns the backoff off, so retries follow each other at once.

pub fn backoff_max(self, delay: Duration) -> Self

The longest backoff. Zero turns the backoff off. A delay the server asks for is not capped by it.

pub fn backoff_jitter(self, jitter: f64) -> Result<Self, Error>

The largest share of each backoff that is randomly taken off it, from 0 (none) to 1 (up to all of it), so that clients which failed together do not retry together.

Errors

Returns an ErrorKind::Config error when jitter is not a number from 0 to 1, NaN and the infinities included.

pub fn http_statuses(self, statuses: StatusSet) -> Self

The statuses whose API errors are retried; StatusSet::DEFAULT unless set.

A status counts only for a response the SDK reports as ErrorKind::Api. A success status in the set has no effect: a success response whose body does not decode is an ErrorKind::ResponseValidation error and is not retried for its status, since the same body would come back; a predicate can still ask for it.

pub fn respect_retry_after(self, respect: bool) -> Self

Whether a delay the server asks for in retry-after-ms or Retry-After replaces the backoff. On unless turned off.

The budget set with timeout is what bounds such a delay: without a budget (no_timeout) a server’s Retry-After is obeyed however long it is. Keep a budget, or turn this off, when the server is not trusted.

pub fn api_connection_error(self, retry: bool) -> Self

Whether an attempt that got no response - a refused, failed or broken connection, ErrorKind::Connection - is retried. On unless turned off.

pub fn api_timeout_error(self, retry: bool) -> Self

Whether an attempt that ran past its deadline, ErrorKind::Timeout, is retried. On unless turned off.

pub fn predicate<F>(self, predicate: F) -> Self

where F: Fn(&Error) -> bool + Send + Sync + 'static,

A rule of the caller’s own: a failure it returns true for is retried, in addition to the ones the other settings retry.

It is called once for each failed attempt, with the error that attempt ended with, before the attempt count and the budget are checked; a failure the other settings already retry may skip it. It sees every failure an attempt can end with, a response that did not decode or was over the size limit included, and runs on the task that sends the call, so it should return quickly.

pub fn timeout(self, budget: Duration) -> Result<Self, Error>

The most time one call may take in all - every attempt and every wait between them. Retrying stops before a wait that would reach it, and the call fails with the last error. 30 s unless set.

This is not the deadline of one attempt, which the client and each call set with their own timeout.

Errors

Returns an ErrorKind::Config error for a budget of zero.

pub fn no_timeout(self) -> Self

No budget for the whole call: only the attempt count stops retrying.

The budget is also what bounds a delay the server asks for: without it, a server’s Retry-After is obeyed however long it is. Keep a budget, or turn respect_retry_after off, when the server is not trusted.

Trait Implementations

impl Clone for RetryPolicy

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RetryPolicy

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Every setting; a predicate, which has no text of its own, prints as <predicate>.

impl Default for RetryPolicy

fn default() -> Self

Returns the “default value” for a type.