Download the PHP package caseyamcl/guzzle_retry_middleware without Composer

Guzzle Retry Middleware

This is a Guzzle v6/7+ middleware library that implements automatic retry of requests when HTTP servers respond with 503 or 429 status codes. It can also be configured to retry requests that timeout.

If a server supplies a Retry-After header, this middleware will delay subsequent requests per the server's instructed wait period.

Unlike the built-in RetryAfter middleware, this middleware provides some default behavior for negotiating retries based on rules in the HTTP Spec. You can drop it right into your request stack without any additional configuration.

Features, at-a-glance:

• Automatically retries HTTP requests when a server responds with a 429 or 503 status (or any HTTP status code; this is configurable)
• Sets a retry delay based on the Retry-After HTTP header, if it is sent, or automatically backs off exponentially if no Retry-After header is sent (also configurable)
• Optionally retries requests that time out (via the connect_timeout or timeout options)
• Set an optional callback when a retry occurs (useful for logging/reporting)
• Specify a maximum number of retry attempts before giving up (default: 10)
• Near-100% test coverage, good inline documentation, and PSR-12 compliant

Install

Via Composer

Usage

Basically:

This is the default configuration. If a HTTP server responds with a 429 or 503 status, this middleware with intercept the response and retry it up to 10 times before giving up and doing whatever behavior Guzzle would do by default (by default, throwing a BadResponseException).

If the server provides a RetryAfter header, this middleware will wait the specified time before attempting a request again. If not, then it will back off, waiting longer each time between requests until giving up after 10 attempts.

Options

The following options are available:

Each option is discussed in detail below.

Configuring Options

Options can be set in one of three places:

If you specify options in two or more places, the configuration is merged as follows:

1. Individual request options take precedence over Guzzle constructor options
2. Guzzle constructor options take precedence over middleware constructor options.

Setting maximum retry attempts

This value should be an integer equal to or greater than 0. Setting 0 or a negative effectively disables this middleware.

Setting this value to 0 is useful when you want to retry attempts by default, but disable retries for a particular request:

Setting status codes to retry

By default, this middleware will retry requests when the server responds with a 429 or 503 HTTP status code. But, you can configure this:

If the response includes a RetryAfter header, but its status code is not in the list, it will not be processed.

Note: I haven't tested this, but I sincerely believe you will see some wonky behavior if you attempt to use this middleware with 3xx responses. I don't suggest it.

Setting default retry delay

If the response includes a valid RetryAfter header, this middleware will delay the next retry attempt the amount of time that the server specifies in that header.

If the response includes a non-valid RetryAfter or does not provide a RetryAfter header, then this middleware will use a default back-off algorithm: multipler * number-of-attempts:

Response with RetryAfter header:

Without RetryAfter, the number of requests is multiplied by the multiplier (default: 1.5):

You can set a custom default multiplier:

You can also pass in a custom algorithm for setting the default delay timeout if you specify a callable for default_retry_multiplier:

Retrying requests that timeout

You can configure this middleware to retry requests that timeout. Simply set the retry_on_timeout option to true:

On-Retry callback

You can supply a callback method that will be called before each time a request is retried. This is useful for logging, reporting, or anything else you can think of.

If you specify a callback, it will be called before the middleware calls the usleep() delay function.

The request and options arguments are sent by reference in case you want to modify them in the callback before the request is re-sent.

Enabling or disabling per-request

Suppose that you have setup default retry options as follows:

You can disable retry for individual requests as by setting the retry_enabled parameter in the request options:

Adding a custom retry header to HTTP responses

Sometimes for debugging purposes, it is useful to know how many times a request was retried when getting a response. For this purpose, this library can add a custom header to responses; simply set the expose_retry_header option to TRUE.

Note: This modifies the HTTP response on the client. If you don't want to alter the response retrieved from the server, you can also use callbacks to get the request count.

Example:

You can also specify a custom header key:

Modifying the expected header name from Retry-After

You can change the header that the client expects the server to respond with. By default, the client looks for the Retry-After header, but in some edge-cases, servers may choose to respond with a different header.

Setting a custom date format for the Retry-After header

You can change the expected date format expected from the server that the client library expects. By default, this library expects an RFC 2822 header as defined in the HTTP spec. In certain edge-cases, the server may implement some other date format. This library allows for the possibility of that.

Note: Be careful not to use this option with the Unix epoch (u) format. The client will interpret this value as an integer and subsequently timeout
for a very, very long time.

Setting a maximum allowable timeout value

If you want the client to not accept timeout values greater than a certain value, set the max_allowable_timeout_secs option. This will return a static number once the timeout reaches a specified length regardless if it is calculated using the default backoff algorithm or returned from the server via the Retry-After header.

By default, this value is null, which means there is no limit.

Setting a hard time ceiling for all retries

If you want to set a hard time-limit for all retry requests, set the give_up_after_secs option. If set, this will be checked before the number of retries is, so any requests will fail even if you haven't reached your retry count limit.

Setting specific HTTP methods to retry on

By default, this library retries all request methods (GET, POST, PATCH, etc...). If you want to limit the HTTP methods that this library will retry requests for, specify the retry_on_methods option with an array of methods:

Custom retry decision logic

Occasionally, servers will fail to provide an appropriate HTTP error code when a response needs to be retried. For example, consider a server that returns a 200 status code, but with a message body instructing you to wait. In cases like this, you can use the should_retry_callback option to implement a callback method that returns true (should retry) or false (should not retry).

It's important to note that the callback will be called only if all the following circumstances are true:

• The retry_enabled option is true (default: true)
• The number of retries has not exceeded the value set in max_retry_attempts (default: 10)
• The total time elapsed is less than the give_up_after_secs value (default: disabled)

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

Note: Since this library tests timeouts, a few of the tests take a 2-3 seconds to run.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Casey McLaughlin
• Jachim Coudenys
• Markus Podar
• All contributors

License

The MIT License (MIT). Please see License File for more information.