pax_global_header00006660000000000000000000000064124451066750014524gustar00rootroot0000000000000052 comment=f13a4c640b823e9eaf06975d8e8981f9551250e8 retry-subscriber-2.0.2/000077500000000000000000000000001244510667500150335ustar00rootroot00000000000000retry-subscriber-2.0.2/.gitignore000066400000000000000000000000731244510667500170230ustar00rootroot00000000000000.idea .DS_STORE coverage phpunit.xml composer.lock vendor/ retry-subscriber-2.0.2/.travis.yml000066400000000000000000000002661244510667500171500ustar00rootroot00000000000000language: php php: - 5.4 - 5.5 - 5.6 - hhvm before_script: - composer self-update - composer install --no-interaction --prefer-source --dev script: vendor/bin/phpunit retry-subscriber-2.0.2/CHANGELOG.md000066400000000000000000000003661244510667500166510ustar00rootroot00000000000000# CHANGELOG ## 2.0.2 - 2014-12-19 * Using the `getRetryCount()` method of the event rather than tracking retries in a request config variable. ## 2.0.1 - 2014-12-03 * No longer requires cURL. ## 2.0.0 - 2014-10-12 * Updating for Guzzle 5 retry-subscriber-2.0.2/LICENSE000066400000000000000000000021271244510667500160420ustar00rootroot00000000000000Copyright (c) 2014 Michael Dowling, https://github.com/mtdowling Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. retry-subscriber-2.0.2/Makefile000066400000000000000000000002761244510667500165000ustar00rootroot00000000000000test: vendor/bin/phpunit coverage: vendor/bin/phpunit --coverage-html=artifacts/coverage view-coverage: open artifacts/coverage/index.html clean: rm -rf artifacts/* .PHONY: coverage retry-subscriber-2.0.2/README.rst000066400000000000000000000136401244510667500165260ustar00rootroot00000000000000======================= Guzzle Retry Subscriber ======================= Retries failed HTTP requests using customizable retry strategies. Here's a simple example of how it's used: .. code-block:: php use GuzzleHttp\Subscriber\Retry\RetrySubscriber; // Retry 500 and 503 responses $retry = new RetrySubscriber([ 'filter' => RetrySubscriber::createStatusFilter() ]); $client = new GuzzleHttp\Client(); $client->getEmitter()->attach($retry); Installing ---------- Add the following to your composer.json: .. code-block:: javascript { "require": { "guzzlehttp/retry-subscriber": "~1.0" } } Creating a RetrySubscriber -------------------------- The constructor of the RetrySubscriber accepts an associative array of configuration options: filter (callable) (Required) Filter used to determine whether or not to retry a request. The filter must be a callable that accepts the current number of retries as the first argument and a ``GuzzleHttp\Event\AbstractTransferEvent`` object as the second argument. The filter must return ``true`` or ``false`` to denote if the request must be retried. delay Callable that accepts the number of retries as the first argument and a ``GuzzleHttp\Event\AbstractTransferEvent`` as the second argument. The callable must return the amount of of time (in milliseconds) to delay. If no ``delay`` configuration value is provided, then a default exponential backoff implementation is used. max Integer representing the maximum number of retries to allow before giving up. If no ``max`` configuration value is provided, then a request will be retried 5 times. Determining what should be retried ---------------------------------- The required ``filter`` option of the RetrySubscriber's constructor is a callable that is invoked to determine if a request should be retried. When the filter is invoked, it is provided the current retry count for the request and a ``GuzzleHttp\Event\CompleteEvent`` or ``GuzzleHttp\Event\ErrorEvent`` (both events extend from ``GuzzleHttp\Event\AbstractTransferEvent``, so you should typehint on that). The filter must then return true if the request should be retried, or false if it should not be retried. Here's an example of retrying failed 500 responses sent to the ``/foo`` endpoint: .. code-block:: php use GuzzleHttp\Event\AbstractTransferEvent; use GuzzleHttp\Subscriber\Retry\RetrySubscriber; $retry = new RetrySubscriber([ 'filter' => function ($retries, AbstractTransferEvent $event) { $resource = $event->getRequest()->getResource(); // A response is not always received (e.g., for timeouts) $code = $event->getResponse() ? $event->getResponse()->getStatusCode() : null; return $resource == '/foo' && $code == 500; } ]); $client = new GuzzleHttp\Client(); $client->getEmitter()->attach($retry); Filter Chains ~~~~~~~~~~~~~ You can create more customizable retry logic with filter chains, which are created using the static ``RetrySubscriber::createFilterChain()`` method. This method accepts an array of callable filters that are each invoked one after the other. The filters in the chain should return one of the following values, which affects how the rest of the chain is executed. * ``RetrySubscriber::RETRY`` (i.e., ``true``) – Retry the request. * ``RetrySubscriber::DEFER`` (i.e., ``false``) – Defer to the next filter in the chain. * ``RetrySubscriber::BREAK_CHAIN`` (i.e., ``-1``) – Stop the filter chain, and do **not** retry the request. Here's an example using filter chains that retries failed 500 and 503 responses for only idempotent or "safe" requests as defined by `RFC 7231 `_. .. code-block:: php use GuzzleHttp\Event\AbstractTransferEvent; use GuzzleHttp\Subscriber\Retry\RetrySubscriber; // Retry 500 and 503 responses that were sent as GET and HEAD requests. $filter = RetrySubscriber::createChainFilter([ // Does early filter to force non-idempotent methods to NOT be retried. RetrySubscriber::createIdempotentFilter(), // Performs the last check, returning ``true`` or ``false`` based on // if the response received a 500 or 503 status code. RetrySubscriber::createStatusFilter([500, 503]) ]); $retry = new RetrySubscriber(['filter' => $filter]); $client = new GuzzleHttp\Client(); $client->getEmitter()->attach($retry); Customizing the amount of delay ------------------------------- ``delay`` is an optional configuration option in the RetrySubscriber's constructor that is a callable used to determine the amount of time to delay before retrying a request that has been marked as needing a retry. The callable accepts the current number of retries and either a ``GuzzleHttp\Event\CompleteEvent`` or a ``GuzzleHttp\Event\ErrorEvent``. The function must then return an integer or float representing the amount of time in milliseconds to sleep. .. note:: Omitting this argument will use a default exponential backoff strategy. Here's an example of creating a custom delay that always delays for 1 millisecond: .. code-block:: php use GuzzleHttp\Subscriber\Retry\RetrySubscriber; $retry = new RetrySubscriber([ 'filter' => RetrySubscriber::createStatusFilter(), 'delay' => function ($number, $event) { return 1; } ]); Changing the max number of retries ---------------------------------- You can also specify an optional max number of retries in the ``max`` configuration option of the RetrySubscriber's constructor. If not specified, a request can be retried up to 5 times before it is allowed to fail. .. code-block:: php use GuzzleHttp\Subscriber\Retry\RetrySubscriber; $retry = new RetrySubscriber([ 'filter' => RetrySubscriber::createStatusFilter(), 'max' => 3 ]); retry-subscriber-2.0.2/composer.json000066400000000000000000000014521244510667500175570ustar00rootroot00000000000000{ "name": "guzzlehttp/retry-subscriber", "description": "Retries failed HTTP requests using customizable retry strategies (Guzzle 4+)", "homepage": "http://guzzlephp.org/", "keywords": ["retry", "http", "guzzle"], "license": "MIT", "authors": [ { "name": "Michael Dowling", "email": "mtdowling@gmail.com", "homepage": "https://github.com/mtdowling" } ], "require": { "php": ">=5.4.0", "guzzlehttp/guzzle": "~5.1" }, "require-dev": { "guzzlehttp/log-subscriber": "~1.0", "phpunit/phpunit": "~4.0" }, "autoload": { "psr-4": { "GuzzleHttp\\Subscriber\\Retry\\": "src/" } }, "extra": { "branch-alias": { "dev-master": "1.0-dev" } } } retry-subscriber-2.0.2/phpunit.xml.dist000066400000000000000000000005431244510667500202100ustar00rootroot00000000000000 tests src retry-subscriber-2.0.2/src/000077500000000000000000000000001244510667500156225ustar00rootroot00000000000000retry-subscriber-2.0.2/src/RetrySubscriber.php000066400000000000000000000214241244510667500214670ustar00rootroot00000000000000filter = $config['filter']; $this->delayFn = isset($config['delay']) ? $config['delay'] : [__CLASS__, 'exponentialDelay']; $this->maxRetries = isset($config['max']) ? $config['max'] : 5; } public function getEvents() { return [ // Fire before responses are verified (e.g., HttpError). 'complete' => ['onComplete', RequestEvents::VERIFY_RESPONSE + 100], // Fire last to retry only if absolutely necessary. 'error' => ['onComplete', RequestEvents::LATE] ]; } public function onComplete(AbstractRetryableEvent $event) { $retries = $event->getRetryCount(); if ($retries >= $this->maxRetries) { return; } $filterFn = $this->filter; if ($filterFn($retries, $event)) { $delayFn = $this->delayFn; $event->retry($delayFn($retries, $event)); } } /** * Returns an exponential delay calculation in milliseconds. * * @param int $retries Number of retries so far * @param AbstractTransferEvent $event Event containing transaction info * * @return int Returns the number of milliseconds to sleep */ public static function exponentialDelay( $retries, AbstractTransferEvent $event ) { return (int) pow(2, $retries - 1); } /** * Creates a delay function that logs each retry before proxying to a * wrapped delay function. * * @param callable $delayFn Delay function to proxy to * @param LoggerInterface $logger Logger used to log messages * @param string|Formatter $formatter Message formatter to format messages * * @return callable */ public static function createLoggingDelay( callable $delayFn, LoggerInterface $logger, $formatter = null ) { if (!$formatter) { $formatter = new Formatter(self::MSG_FORMAT); } elseif (!($formatter instanceof Formatter)) { $formatter = new Formatter($formatter); } return function ( $retries, AbstractTransferEvent $event ) use ($delayFn, $logger, $formatter) { $delay = $delayFn($retries, $event); $logger->log(LogLevel::NOTICE, $formatter->format( $event->getRequest(), $event->getResponse(), $event instanceof ErrorEvent ? $event->getException() : null, [ 'retries' => $retries + 1, 'delay' => $delay ] + $event->getTransferInfo() )); return $delay; }; } /** * Creates a retry filter based on HTTP status codes * * @param array $failureStatuses Pass an array of status codes to override * the default of [500, 503]. * @return callable */ public static function createStatusFilter( array $failureStatuses = [500, 503] ) { // Convert the array of values into a set for hash lookups $failureStatuses = array_fill_keys($failureStatuses, true); return function ( $retries, AbstractTransferEvent $event ) use ($failureStatuses) { if (!($response = $event->getResponse())) { return false; } return isset($failureStatuses[$response->getStatusCode()]); }; } /** * Creates a retry filter based on whether an HTTP method is considered * "safe" or "idempotent" based on RFC 7231. * * If the HTTP request method is a PUT, POST, or PATCH request, then the * request will not be retried. Otherwise, the filter will defer to other * filters if added to a filter chain via `createFilterChain()`. * * @return callable * @link http://tools.ietf.org/html/rfc7231#section-4.2.2 */ public static function createIdempotentFilter() { static $retry = ['GET' => true, 'HEAD' => true, 'PUT' => true, 'DELETE' => true, 'OPTIONS' => true, 'TRACE' => true]; return function ($retries, AbstractTransferEvent $e) use ($retry) { return isset($retry[$e->getRequest()->getMethod()]) ? self::DEFER : self::BREAK_CHAIN; }; } /** * Creates a retry filter based on cURL error codes. * * @param array $errorCodes Pass an array of curl error codes to override * the default list of error codes. * @return callable */ public static function createCurlFilter($errorCodes = null) { // Only use the cURL filter if cURL is loaded. if (!extension_loaded('curl')) { return function () { return false; }; } $errorCodes = $errorCodes ?: [ CURLE_OPERATION_TIMEOUTED, CURLE_COULDNT_RESOLVE_HOST, CURLE_COULDNT_CONNECT, CURLE_SSL_CONNECT_ERROR, CURLE_GOT_NOTHING ]; $errorCodes = array_fill_keys($errorCodes, 1); return function ($retries, AbstractTransferEvent $e) use ($errorCodes) { return isset($errorCodes[(int) $e->getTransferInfo('curl_result')]); }; } /** * Creates a retry filter that retries connection exceptions. * * @return callable */ public static function createConnectFilter() { return function ($retries, AbstractTransferEvent $event) { return $event instanceof ErrorEvent && $event->getException() instanceof ConnectException; }; } /** * Creates a chain of callables that triggers one after the other until a * callable returns true (which results in a true return value), or a * callable short circuits the chain by returning -1 (resulting in a false * return value). * * @param array $filters Array of callables that accept the number of * retries and an after send event and return true to retry the * transaction, false to not retry and pass to the next filter in the * chain, or -1 to not retry and to immediately break the chain. * * @return callable Returns a filter that can be used to determine if a * transaction should be retried */ public static function createChainFilter(array $filters) { return function ( $retries, AbstractTransferEvent $event ) use ($filters) { foreach ($filters as $filter) { $result = $filter($retries, $event); if ($result === self::RETRY) { return true; } elseif ($result === self::BREAK_CHAIN) { return false; } } return false; }; } } retry-subscriber-2.0.2/tests/000077500000000000000000000000001244510667500161755ustar00rootroot00000000000000retry-subscriber-2.0.2/tests/RetrySubscriberTest.php000066400000000000000000000220301244510667500226740ustar00rootroot00000000000000createEvent(new Response(500)); $this->assertTrue($f(1, $e)); $e = $this->createEvent(new Response(503)); $this->assertTrue($f(0, $e)); $e = $this->createEvent(new Response(200)); $this->assertFalse($f(1, $e)); } public function testCreatesCustomStatusFilter() { $f = RetrySubscriber::createStatusFilter([202, 304]); $e = $this->createEvent(new Response(500)); $this->assertFalse($f(1, $e)); $e = $this->createEvent(new Response(503)); $this->assertFalse($f(0, $e)); $e = $this->createEvent(new Response(202)); $this->assertTrue($f(1, $e)); $e = $this->createEvent(); $this->assertFalse($f(1, $e)); } public function testCreatesIdempotentFilter() { $u = 'http://foo.com'; $f = RetrySubscriber::createIdempotentFilter(); $e = $this->createEvent(new Response(500), new Request('GET', $u)); $this->assertFalse($f(1, $e)); $e = $this->createEvent(new Response(500), new Request('PUT', $u)); $this->assertFalse($f(1, $e)); $e = $this->createEvent(new Response(500), new Request('DELETE', $u)); $this->assertFalse($f(1, $e)); $e = $this->createEvent(new Response(500), new Request('HEAD', $u)); $this->assertFalse($f(1, $e)); $e = $this->createEvent(new Response(500), new Request('OPTIONS', $u)); $this->assertFalse($f(1, $e)); $e = $this->createEvent(new Response(500), new Request('POST', $u)); $this->assertSame(-1, $f(1, $e)); $e = $this->createEvent(new Response(500), new Request('PATCH', $u)); $this->assertSame(-1, $f(1, $e)); } public function testCreatesDefaultCurlFilter() { $f = RetrySubscriber::createCurlFilter(); $e = $this->createEvent(null, null, null, ['curl_result' => CURLE_COULDNT_CONNECT]); $this->assertTrue($f(1, $e)); $e = $this->createEvent(null, null, null, ['curl_result' => CURLE_OK]); $this->assertFalse($f(0, $e)); } public function testCreatesCustomCurlFilter() { $f = RetrySubscriber::createCurlFilter([CURLE_OK]); $e = $this->createEvent(null, null, null, ['curl_result' => CURLE_RECV_ERROR]); $this->assertFalse($f(1, $e)); $e = $this->createEvent(null, null, null, ['curl_result' => CURLE_OK]); $this->assertTrue($f(0, $e)); } public function testCreatesConnectionFilter() { $f = RetrySubscriber::createConnectFilter(); $e = $this->createEvent( null, null, new ConnectException('foo', new Request('GET', 'http://foo.com')), [], 'GuzzleHttp\Event\ErrorEvent' ); $this->assertTrue($f(1, $e)); $e = $this->createEvent(null, null, null); $this->assertFalse($f(0, $e)); } public function testCreatesChainFilter() { $e = $this->createEvent(new Response(500)); $f = RetrySubscriber::createChainFilter([ function () { return RetrySubscriber::DEFER; }, function () { return RetrySubscriber::RETRY; }, ]); $this->assertTrue($f(1, $e)); $f = RetrySubscriber::createChainFilter([function () { return RetrySubscriber::DEFER; }]); $this->assertFalse($f(1, $e)); $f = RetrySubscriber::createChainFilter([function () { return RetrySubscriber::RETRY; }]); $this->assertTrue($f(1, $e)); } public function testChainFilterCanBreakChainWhenFiltering() { $e = $this->createEvent(new Response(500)); $f = RetrySubscriber::createChainFilter([ function () { return RetrySubscriber::DEFER; }, function () { return RetrySubscriber::BREAK_CHAIN; }, function () { $this->fail('Did not break chain!'); }, ]); $this->assertFalse($f(1, $e)); } public function testCreateLoggingDelayFilter() { $str = fopen('php://temp', 'r+'); $l = new SimpleLogger($str); $e = $this->createEvent(new Response(500)); $f = RetrySubscriber::createLoggingDelay(function () { return true; }, $l); $this->assertTrue($f(2, $e)); rewind($str); $this->assertContains('500 Internal Server Error - Retries: 3, Delay: 1', stream_get_contents($str)); } public function testCreateLoggingDelayFilterWithCustomFormat() { $str = fopen('php://temp', 'r+'); $l = new SimpleLogger($str); $e = $this->createEvent(new Response(500)); $f = RetrySubscriber::createLoggingDelay(function () { return true; }, $l, 'Foo'); $this->assertTrue($f(2, $e)); rewind($str); $this->assertContains('Foo', stream_get_contents($str)); } public function testCalculatesExponentialDelay() { $e = $this->createEvent(new Response(500)); $this->assertEquals(0, RetrySubscriber::exponentialDelay(0, $e)); $this->assertEquals(1, RetrySubscriber::exponentialDelay(1, $e)); $this->assertEquals(2, RetrySubscriber::exponentialDelay(2, $e)); $this->assertEquals(4, RetrySubscriber::exponentialDelay(3, $e)); $this->assertEquals(8, RetrySubscriber::exponentialDelay(4, $e)); } public function testProvidesDefaultDelay() { $retry = new RetrySubscriber([ 'filter' => function () { static $times = 0; return ++$times == 1; } ]); $mock = new Mock([new Response(200), new Response(200)]); $client = new Client(); $client->getEmitter()->attach($mock); $client->getEmitter()->attach($retry); $client->get('http://httbin.org/get'); } public function testProvidesDefaultSleepFn() { $called = false; $retry = new RetrySubscriber([ 'filter' => function () { static $times = 0; return ++$times == 1; }, 'delay' => function () use (&$called) { $called = true; return 0; } ]); $mock = new Mock([new Response(200), new Response(200)]); $client = new Client(); $client->getEmitter()->attach($mock); $client->getEmitter()->attach($retry); $client->get('http://httbin.org/get'); $this->assertTrue($called); } public function testAllowsFailureAfterMax() { $called = 0; $retry = new RetrySubscriber([ 'filter' => function () use (&$called) { $called++; return true; }, 'max' => 2 ]); $mock = new Mock([new Response(500), new Response(500), new Response(500)]); $client = new Client(); $client->getEmitter()->attach($mock); $client->getEmitter()->attach($retry); try { $client->get('http://httbin.org/get'); $this->fail('Did not fail'); } catch (ServerException $e) { $this->assertEquals(2, $called); $this->assertCount(0, $mock); } } /** * @expectedException \InvalidArgumentException */ public function testEnsuresFilterIsProvided() { new RetrySubscriber([]); } private function createEvent( ResponseInterface $response = null, RequestInterface $request = null, \Exception $exception = null, array $transferInfo = [], $type = 'GuzzleHttp\Event\AbstractTransferEvent' ) { if (!$request) { $request = new Request('GET', 'http://www.foo.com'); } $e = $this->getMockBuilder($type) ->setMethods(['getResponse', 'getTransferInfo', 'getRequest', 'getException']) ->disableOriginalConstructor() ->getMockForAbstractClass(); $e->expects($this->any()) ->method('getRequest') ->will($this->returnValue($request)); $e->expects($this->any()) ->method('getResponse') ->will($this->returnValue($response)); $e->expects($this->any()) ->method('getException') ->will($this->returnValue($exception)); $e->expects($this->any()) ->method('getTransferInfo') ->will($this->returnCallback(function ($arg) use ($transferInfo) { return $arg ? (isset($transferInfo[$arg]) ? $transferInfo[$arg] : null) : $transferInfo; })); return $e; } }