From c2d65d4c1d7e664dfcead0d2ef9d28d42f459225 Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Thu, 3 Jan 2019 17:34:46 +0100 Subject: [PATCH 01/10] improve retry documentation and add all options --- plugins/retry.rst | 65 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 48 insertions(+), 17 deletions(-) diff --git a/plugins/retry.rst b/plugins/retry.rst index b3b3e71..98071a0 100644 --- a/plugins/retry.rst +++ b/plugins/retry.rst @@ -1,22 +1,14 @@ Retry Plugin ============ -The ``RetryPlugin`` can automatically attempt to re-send a request that failed, to work around -unreliable connections and servers. It relies on errors to throw exceptions, so you need to -place something like the :doc:`ErrorPlugin ` later in the plugin chain:: +The ``RetryPlugin`` can automatically attempt to re-send a request that failed, +to work around unreliable connections and servers. It re-sends the request when +an exception is thrown, unless the exception is a HttpException for a status +code in the 5xx server error range. Since version 2.0, responses with status +codes in the 5xx range are also retried. Each retry attempt is delayed by an +exponential backoff time. - use Http\Discovery\HttpClientDiscovery; - use Http\Client\Common\PluginClient; - use Http\Client\Common\Plugin\ErrorPlugin; - use Http\Client\Common\Plugin\RetryPlugin; - - $pluginClient = new PluginClient( - HttpClientDiscovery::find(), - [ - new RetryPlugin(), - new ErrorPlugin(), - ] - ); +See below for how to configure that behaviour. .. warning:: @@ -30,8 +22,8 @@ but simply tries again from the current position. Async ----- -This plugin is not fully compatible with asynchronous behavior, as the wait between retries is done -with a blocking call to a sleep function. +This plugin is not fully compatible with asynchronous behavior, as the wait +between retries is done with a blocking call to a sleep function. Options ------- @@ -39,3 +31,42 @@ Options ``retries``: int (default: 1) Number of retry attempts to make before giving up. + +``error_response_decider``: callable (default: retry if status code is in 5xx range) + +A callback function that gets the request and response to decide whether the +request should be retried. + +``exception_decider``: callable (default: retry if not a HttpException or status code is in 5xx range) + +A callback function that gets a request and an exception to decide after a +failure whether the request should be retried. + +``error_response_delay``: callable (default: exponential backoff) + +A callback that gets a request and response and the current number of retries +and returns how many microseconds we should wait before trying again. + +``exception_delay``: callable (default: exponential backoff) + +A callback that gets a request, an exception and the current number of retries +and returns how many microseconds we should wait before trying again. + +Interaction with Exceptions +--------------------------- + +If you use the :doc:`ErrorPlugin `, you should place it later in the +plugin chain:: + + use Http\Discovery\HttpClientDiscovery; + use Http\Client\Common\PluginClient; + use Http\Client\Common\Plugin\ErrorPlugin; + use Http\Client\Common\Plugin\RetryPlugin; + + $pluginClient = new PluginClient( + HttpClientDiscovery::find(), + [ + new RetryPlugin(), + new ErrorPlugin(), + ] + ); From fa98b224b171344c4b5ea1757312feb81ba4029d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rk=20S=C3=A1gi-Kaz=C3=A1r?= Date: Sun, 6 Jan 2019 10:33:05 +0100 Subject: [PATCH 02/10] Update plugins/retry.rst Co-Authored-By: dbu --- plugins/retry.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/retry.rst b/plugins/retry.rst index 98071a0..897a3a2 100644 --- a/plugins/retry.rst +++ b/plugins/retry.rst @@ -55,7 +55,7 @@ and returns how many microseconds we should wait before trying again. Interaction with Exceptions --------------------------- -If you use the :doc:`ErrorPlugin `, you should place it later in the +If you use the :doc:`ErrorPlugin `, you should place it after the RetryPlugin in the plugin chain:: use Http\Discovery\HttpClientDiscovery; From aea180db8a144c1d9f356bc61839c5da13264e53 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rk=20S=C3=A1gi-Kaz=C3=A1r?= Date: Sun, 6 Jan 2019 10:33:38 +0100 Subject: [PATCH 03/10] Update plugins/retry.rst Co-Authored-By: dbu --- plugins/retry.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/retry.rst b/plugins/retry.rst index 897a3a2..c602a57 100644 --- a/plugins/retry.rst +++ b/plugins/retry.rst @@ -49,7 +49,7 @@ and returns how many microseconds we should wait before trying again. ``exception_delay``: callable (default: exponential backoff) -A callback that gets a request, an exception and the current number of retries +A callback that receives a request, an exception, the current number of retries and returns how many microseconds we should wait before trying again. Interaction with Exceptions From 9fe22125be7a6268e5ec2cb31a876be93b6bd8c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rk=20S=C3=A1gi-Kaz=C3=A1r?= Date: Sun, 6 Jan 2019 10:33:46 +0100 Subject: [PATCH 04/10] Update plugins/retry.rst Co-Authored-By: dbu --- plugins/retry.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/retry.rst b/plugins/retry.rst index c602a57..59b19b3 100644 --- a/plugins/retry.rst +++ b/plugins/retry.rst @@ -47,7 +47,7 @@ failure whether the request should be retried. A callback that gets a request and response and the current number of retries and returns how many microseconds we should wait before trying again. -``exception_delay``: callable (default: exponential backoff) +``exception_delay``: callable (default behaviour: exponential backoff) A callback that receives a request, an exception, the current number of retries and returns how many microseconds we should wait before trying again. From 02f48553bf714e13b98b3608a9aec0d60d1c9d9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rk=20S=C3=A1gi-Kaz=C3=A1r?= Date: Sun, 6 Jan 2019 10:33:55 +0100 Subject: [PATCH 05/10] Update plugins/retry.rst Co-Authored-By: dbu --- plugins/retry.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/retry.rst b/plugins/retry.rst index 59b19b3..4653911 100644 --- a/plugins/retry.rst +++ b/plugins/retry.rst @@ -44,7 +44,7 @@ failure whether the request should be retried. ``error_response_delay``: callable (default: exponential backoff) -A callback that gets a request and response and the current number of retries +A callback that receives a request, a response, the current number of retries and returns how many microseconds we should wait before trying again. ``exception_delay``: callable (default behaviour: exponential backoff) From 7a62e5298bf07fb49d93cba3a5d50e72c2b240f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rk=20S=C3=A1gi-Kaz=C3=A1r?= Date: Sun, 6 Jan 2019 10:34:00 +0100 Subject: [PATCH 06/10] Update plugins/retry.rst Co-Authored-By: dbu --- plugins/retry.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/retry.rst b/plugins/retry.rst index 4653911..bad98c1 100644 --- a/plugins/retry.rst +++ b/plugins/retry.rst @@ -42,7 +42,7 @@ request should be retried. A callback function that gets a request and an exception to decide after a failure whether the request should be retried. -``error_response_delay``: callable (default: exponential backoff) +``error_response_delay``: callable (default behaviour: exponential backoff) A callback that receives a request, a response, the current number of retries and returns how many microseconds we should wait before trying again. From 67b028bd3e1c1edeab048476932c3263614f880c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rk=20S=C3=A1gi-Kaz=C3=A1r?= Date: Sun, 6 Jan 2019 10:34:06 +0100 Subject: [PATCH 07/10] Update plugins/retry.rst Co-Authored-By: dbu --- plugins/retry.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/retry.rst b/plugins/retry.rst index bad98c1..e8cf74f 100644 --- a/plugins/retry.rst +++ b/plugins/retry.rst @@ -39,7 +39,7 @@ request should be retried. ``exception_decider``: callable (default: retry if not a HttpException or status code is in 5xx range) -A callback function that gets a request and an exception to decide after a +A callback function that receives a request and an exception to decide after a failure whether the request should be retried. ``error_response_delay``: callable (default behaviour: exponential backoff) From 5b103c1e7a9a934590c302cdca8e292f35f4a263 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rk=20S=C3=A1gi-Kaz=C3=A1r?= Date: Sun, 6 Jan 2019 10:34:20 +0100 Subject: [PATCH 08/10] Update plugins/retry.rst Co-Authored-By: dbu --- plugins/retry.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/retry.rst b/plugins/retry.rst index e8cf74f..32908b9 100644 --- a/plugins/retry.rst +++ b/plugins/retry.rst @@ -37,7 +37,7 @@ Number of retry attempts to make before giving up. A callback function that gets the request and response to decide whether the request should be retried. -``exception_decider``: callable (default: retry if not a HttpException or status code is in 5xx range) +``exception_decider``: callable (default behaviour: retry if the exception is not an HttpException or status code is in 5xx range) A callback function that receives a request and an exception to decide after a failure whether the request should be retried. From ad65e10631fd1d1b42c9e9e337708a8e2115b175 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rk=20S=C3=A1gi-Kaz=C3=A1r?= Date: Sun, 6 Jan 2019 10:34:30 +0100 Subject: [PATCH 09/10] Update plugins/retry.rst Co-Authored-By: dbu --- plugins/retry.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/retry.rst b/plugins/retry.rst index 32908b9..c694dcd 100644 --- a/plugins/retry.rst +++ b/plugins/retry.rst @@ -32,7 +32,7 @@ Options Number of retry attempts to make before giving up. -``error_response_decider``: callable (default: retry if status code is in 5xx range) +``error_response_decider``: callable (default behaviour: retry if status code is in 5xx range) A callback function that gets the request and response to decide whether the request should be retried. From 6253e528b4fd6cd141241e367dcbbef3b91d004b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rk=20S=C3=A1gi-Kaz=C3=A1r?= Date: Sun, 6 Jan 2019 10:34:35 +0100 Subject: [PATCH 10/10] Update plugins/retry.rst Co-Authored-By: dbu --- plugins/retry.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/retry.rst b/plugins/retry.rst index c694dcd..0d8b702 100644 --- a/plugins/retry.rst +++ b/plugins/retry.rst @@ -34,7 +34,7 @@ Number of retry attempts to make before giving up. ``error_response_decider``: callable (default behaviour: retry if status code is in 5xx range) -A callback function that gets the request and response to decide whether the +A callback function that receives the request and response to decide whether the request should be retried. ``exception_decider``: callable (default behaviour: retry if the exception is not an HttpException or status code is in 5xx range)