Release 4.0.0

denisyukphp · May 17, 2024 · a050035 · a050035
2 parents 3d2070b + 790df2f
commit a050035
Show file tree

Hide file tree

Showing 87 changed files with 1,577 additions and 1,217 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -8,7 +8,6 @@
 /README.md export-ignore
 /build/ export-ignore
 /composer.lock export-ignore
-/docs/ export-ignore
 /phpunit.xml.dist export-ignore
 /psalm-baseline.xml export-ignore
 /psalm.xml export-ignore

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -4,15 +4,13 @@ on:
   push:
     paths-ignore:
       - 'build/**'
-      - 'docs/**'
       - '.editorconfig'
       - '.gitattributes'
       - 'LICENSE'
       - 'README.md'
   pull_request:
     paths-ignore:
       - 'build/**'
-      - 'docs/**'
       - '.editorconfig'
       - '.gitattributes'
       - 'LICENSE'
@@ -22,68 +20,55 @@ jobs:
   parallel-lint:
     name: 'ParallelLint'
     runs-on: 'ubuntu-latest'
-
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
-
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.1'
+          php-version: '8.2'
           coverage: none
-
       - name: Install dependencies
         uses: ramsey/composer-install@v2
-
       - name: Run ParallelLint
         run: composer parallel-lint -- --no-progress --ignore-fails
 
   psalm:
     name: 'Psalm'
     runs-on: 'ubuntu-latest'
-
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
-
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.1'
+          php-version: '8.2'
           coverage: none
-
       - name: Install dependencies
         uses: ramsey/composer-install@v2
-
       - name: Run Psalm
-        run: composer psalm -- --no-progress --no-cache --output-format=github
+        run: composer psalm -- --show-info=false --no-progress --no-suggestions --no-cache
 
   php-cs-fixer:
     name: 'PHPCsFixer'
     runs-on: 'ubuntu-latest'
-
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
-
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.1'
+          php-version: '8.2'
           coverage: none
-
       - name: Install dependencies
         uses: ramsey/composer-install@v2
-
       - name: Run PHPCsFixer
         run: composer php-cs-fixer:diff -- --no-interaction --using-cache=no
 
   phpunit:
     name: 'PHPUnit'
     needs: ['parallel-lint', 'psalm', 'php-cs-fixer']
     runs-on: ${{ matrix.operating-system }}
-
     strategy:
       fail-fast: false
       matrix:
@@ -92,24 +77,21 @@ jobs:
           - 'windows-latest'
         php-version:
           - '8.1'
+          - '8.2'
         composer-dependency:
           - 'lowest'
           - 'highest'
-
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
-
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php-version }}
           coverage: none
-
       - name: Install dependencies
         uses: ramsey/composer-install@v2
         with:
           dependency-versions: ${{ matrix.composer-dependency }}
-
       - name: Run PHPUnit
         run: composer phpunit -- --no-interaction --do-not-cache-result
diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1,11 @@
+FROM php:8.2-cli
+
+RUN \
+    apt-get update ; \
+    apt-get install -y unzip ; \
+    pecl install pcov ; \
+    docker-php-ext-enable pcov ;
+
+COPY --from=composer:2.4 /usr/bin/composer /usr/local/bin/composer
+
+WORKDIR /usr/local/packages/backoff/
diff --git a/LICENSE b/LICENSE
@@ -1,4 +1,4 @@
-Copyright (c) 2022 Orangesoft
+Copyright (c) 2021 Orangesoft
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/Makefile b/Makefile
@@ -0,0 +1,5 @@
+init:
+	docker build -t backoff:8.2 ./
+
+exec:
+	docker run --name backoff --rm --interactive --tty --volume ${PWD}:/usr/local/packages/backoff/ backoff:8.2 /bin/bash
diff --git a/README.md b/README.md
@@ -20,33 +20,36 @@ This package requires PHP 8.1 or later.
 
 ## Quick usage
 
-Configure BackOff and ExceptionClassifier to retry your business logic when an exception will be thrown:
+Configure `Orangesoft\BackOff\Retry\BackOffRetry::class`, any of back-off classes, and `Orangesoft\BackOff\Retry\ExceptionClassifier\ExceptionClassifier::class` to retry a business logic when an exception is thrown:
 
 ```php
 <?php
 
 use Orangesoft\BackOff\ExponentialBackOff;
-use Orangesoft\BackOff\Duration\Seconds;
+use Orangesoft\BackOff\Duration\Microseconds;
 use Orangesoft\BackOff\Retry\ExceptionClassifier\ExceptionClassifier;
-use Orangesoft\BackOff\Retry\Retry;
+use Orangesoft\BackOff\Retry\BackOffRetry;
 
-$backOff = new ExponentialBackOff(
+$backOffRetry = new BackOffRetry(
     maxAttempts: 3,
-    baseTime: new Seconds(1),
-    capTime: new Seconds(60),
+    baseTime: new Microseconds(1_000),
+    capTime: new Microseconds(10_000),
+    backOff: new ExponentialBackOff(
+        multiplier: 2.0,
+    ),
+    exceptionClassifier: new ExceptionClassifier(
+        classNames: [
+            \Exception::class,
+        ],
+    ),
 );
-
-$exceptionClassifier = new ExceptionClassifier([
-    \RuntimeException::class,
-]);
-
-$retry = new Retry($backOff, $exceptionClassifier);
 ```
 
-Put the business logic in a callback function and call it:
+Use the `Orangesoft\BackOff\Retry\BackOffRetry::call(callable $callback): mixed` method to wrap the business logic and call it with retry functionality:
 
 ```php
-$retry->call(function (): int {
+/** @var int $result */
+$result = $backOffRetry->call(static function (): int {
     $random = mt_rand(5, 10);
 
     if (0 === $random % 2) {
@@ -57,14 +60,61 @@ $retry->call(function (): int {
 });
 ```
 
-After the exception is thrown call will be retried with a back-off time until max attempts has been reached.
+The following back-off strategies are available:
+
+- [Orangesoft\BackOff\CallbackBackOff](./src/CallbackBackOff.php)
+- [Orangesoft\BackOff\DecorrelatedJitterBackOff](./src/DecorrelatedJitterBackOff.php)
+- [Orangesoft\BackOff\ExponentialBackOff](./src/ExponentialBackOff.php)
+- [Orangesoft\BackOff\FibonacciBackOff](./src/FibonacciBackOff.php)
+- [Orangesoft\BackOff\LinearBackOff](./src/LinearBackOff.php)
+- [Orangesoft\BackOff\PermanentBackOff](./src/PermanentBackOff.php)
+
+## Enable Jitter
+
+Pass the implementation of `Orangesoft\BackOff\Jitter\JitterInterface::class` to the back-off class and jitter will be enabled:
+
+```php
+<?php
+
+use Orangesoft\BackOff\ExponentialBackOff;
+use Orangesoft\BackOff\Duration\Microseconds;
+use Orangesoft\BackOff\Jitter\EqualJitter;
+
+$exponentialBackOff = new ExponentialBackOff(
+    multiplier: 2.0,
+    jitter: new EqualJitter(),
+);
+
+$exponentialBackOff->backOff(
+    attempt: 1,
+    baseTime: new Microseconds(1_000),
+    capTime: new Microseconds(512_000),
+);
+```
+
+Below you can see the time intervals in microseconds for exponential back-off with a multiplier of 2.0 and equal jitter, where the base time is 1000 μs and the cap time is 512000 μs:
+
+```text
++---------+---------------------------+--------------------+
+| attempt | exponential back-off (μs) | equal jitter (μs)  |
++---------+---------------------------+--------------------+
+|       1 |                     1_000 |         [0, 1_000] |
+|       2 |                     2_000 |     [1_000, 2_000] |
+|       3 |                     4_000 |     [2_000, 4_000] |
+|       4 |                     8_000 |     [4_000, 8_000] |
+|       5 |                    16_000 |    [8_000, 16_000] |
+|       6 |                    32_000 |   [16_000, 32_000] |
+|       7 |                    64_000 |   [32_000, 64_000] |
+|       8 |                   128_000 |  [64_000, 128_000] |
+|       9 |                   256_000 | [128_000, 256_000] |
+|      10 |                   512_000 | [256_000, 512_000] |
++---------+---------------------------+--------------------+
+```
 
-## Documentation
+The following jitters are available:
 
-- [Configure Generator](docs/index.md#configure-generator)
-- [Enable Jitter](docs/index.md#enable-jitter)
-- [Duration sleep](docs/index.md#duration-sleep)
-- [Use BackOff](docs/index.md#use-backoff)
-- [Retry exceptions](docs/index.md#retry-exceptions)
+- [Orangesoft\BackOff\Jitter\EqualJitter](./src/Jitter/EqualJitter.php)
+- [Orangesoft\BackOff\Jitter\FullJitter](./src/Jitter/FullJitter.php)
+- [Orangesoft\BackOff\Jitter\ScatteredJitter](./src/Jitter/ScatteredJitter.php)
 
-Read more about Back-off and Jitter on [AWS Architecture Blog](https://aws.amazon.com/ru/blogs/architecture/exponential-backoff-and-jitter/).
+Read more about Back-Off and Jitter on [AWS Architecture Blog](https://aws.amazon.com/ru/blogs/architecture/exponential-backoff-and-jitter/).
diff --git a/composer.json b/composer.json
@@ -1,15 +1,12 @@
 {
     "name": "orangesoft/backoff",
-    "description": "Back-off algorithm implementation",
+    "description": "Back-off algorithm implementation.",
     "keywords": [
         "backoff",
-        "exponential",
-        "linear",
-        "constant",
-        "decorrelation",
+        "duration",
         "jitter",
-        "sleeper",
-        "retry"
+        "retry",
+        "sleeper"
     ],
     "license": "MIT",
     "authors": [
@@ -24,7 +21,8 @@
         "sort-packages": true
     },
     "require": {
-        "php": "^8.1"
+        "php": "^8.1",
+        "beberlei/assert": "^3.3"
     },
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^3.10",
@@ -38,7 +36,10 @@
     "autoload": {
         "psr-4": {
             "Orangesoft\\BackOff\\": "./src/"
-        }
+        },
+        "files": [
+            "./helpers.php"
+        ]
     },
     "autoload-dev": {
         "psr-4": {
@@ -47,15 +48,18 @@
     },
     "scripts": {
         "phpunit": "./vendor/bin/phpunit --verbose --colors=always --no-coverage",
+        "phpunit:clear-cache": "rm ./build/cache/phpunit.cache",
         "phpunit-coverage": "./vendor/bin/phpunit --verbose --colors=always --coverage-text",
         "phpunit-coverage-html": "./vendor/bin/phpunit --verbose --colors=always --coverage-html ./build/logs/phpunit-coverage/",
         "parallel-lint": "./vendor/bin/parallel-lint --colors ./src/ ./tests/",
         "php-cs-fixer:fix": "./vendor/bin/php-cs-fixer fix --verbose --ansi --show-progress=dots",
         "php-cs-fixer:diff": "./vendor/bin/php-cs-fixer fix --verbose --ansi --dry-run --diff",
+        "php-cs-fixer:clear-cache": "rm ./build/cache/php-cs-fixer.cache",
         "psalm": "./vendor/bin/psalm --show-info=true",
-        "psalm:set-baseline": "@psalm --set-baseline=./psalm-baseline.xml",
-        "psalm:update-baseline": "@psalm --update-baseline",
-        "psalm:ignore-baseline": "@psalm --ignore-baseline",
+        "psalm:clear-cache": "rm -rf ./build/cache/psalm/",
+        "psalm:set-baseline": "@psalm --set-baseline=./psalm-baseline.xml --no-cache",
+        "psalm:update-baseline": "@psalm --update-baseline --no-cache",
+        "psalm:ignore-baseline": "@psalm --ignore-baseline --no-cache",
         "test": [
             "@parallel-lint",
             "@psalm",