Merge pull request #4 from reugn/develop

v0.4.0

README.md

@@ -2,30 +2,75 @@
 [![Build](https://github.com/reugn/kotlin-backoff/actions/workflows/build.yml/badge.svg)](https://github.com/reugn/kotlin-backoff/actions/workflows/build.yml)
 [![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.github.reugn/kotlin-backoff/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.github.reugn/kotlin-backoff/)
 
-A simple Kotlin Exponential Backoff library designed for `kotlinx.coroutines`.
+Any I/O resource can be temporarily unavailable and cause requests to fail.
+Use this library to catch errors and retry, slowing down according to your chosen strategy.
+Add validation rules for the result and error types if needed.
 
-## Getting started
-Gradle:
+## Installation
+`kotlin-backoff` is available on Maven Central.  
+Add the library as a dependency to your project:
 ```kotlin
 dependencies {
-    implementation("io.github.reugn:kotlin-backoff:<version>")
+    implementation("io.github.reugn:kotlin-backoff:0.4.0")
 }
 ```
 
-## Examples
+## Backoff strategies
+Below is a list of backoff strategies implemented. To create your own strategy, implement the `Strategy` interface.
+
+### Exponential strategy
+A strategy in which the next delay interval is calculated using `baseDelayMs * expBase.pow(attempt)` where:
+* `baseDelayMs` is the base delay in milliseconds.
+* `attempt` is the number of unsuccessful attempts that have been made.
+* `expBase` is the exponent base configured for the strategy.
+
+The specified jitter¹ and scale factor² are applied to the calculated interval.
+The delay time cannot exceed the specified maximum delay in milliseconds.
+
+### Polynomial strategy
+A strategy in which the next delay interval is calculated using `baseDelayMs * attempt.pow(exponent)` where:
+* `baseDelayMs` is the base delay in milliseconds.
+* `attempt` is the number of unsuccessful attempts that have been made.
+* `exponent` is the exponent configured for the strategy.
+
+The specified jitter¹ and scale factor² are applied to the calculated interval.
+The delay time cannot exceed the specified maximum delay in milliseconds.
+
+### Fixed strategy
+A strategy that returns the delay time as a fixed value determined by the attempt number.
+
+### Constant strategy
+A simple backoff strategy that constantly returns the same value.
+The specified jitter¹ is applied to the interval. No jitter by default.
+
+---
+¹ Jitter adds a retry randomization factor to reduce resource congestion.
+Specify 1.0 for full jitter, 0.0 for no jitter.
+
+² The delay determined by the backoff strategy is multiplied by the scale factor. By default, the coefficient is 1.
+
+## Usage example
+First, create an instance of `StrategyBackoff`. Then perform the operation, which may fail, using the `retry` or `withRetries` methods.
 ```kotlin
-private val action = suspend { URL("http://worldclockapi.com/api/json/utc/now").readText() }
+private suspend fun urlAction(): String = withContext(Dispatchers.IO) {
+    URL("http://worldclockapi.com/api/json/utc/now").readText()
+}
 
 @Test
-fun urlTest() {
-    val backoff = StrategyBackoff<String>(Duration.ofMillis(500), { s -> s.isNotEmpty() }, 3,
-        Strategy.expFullJitter(2), ::nonFatal)
-    val result = runBlocking { backoff.retry(action) }
+fun `remote URL`() {
+    val backoff = StrategyBackoff<String>(
+        maxRetries = 3,
+        strategy = ExponentialStrategy(),
+        errorValidator = ::nonFatal,
+        resultValidator = { s -> s.isNotEmpty() },
+    )
+    val result = runBlocking { backoff.withRetries(::urlAction) }
+
     assert(result.isOk())
-    assertEquals(result.retries, 1)
+    assertEquals(result.retries, 0)
 }
 ```
-More examples can be found in the test section.
+For more examples, see the [tests](./src/test/kotlin/io/github/reugn/kotlin/backoff).
 
 ## License
 Licensed under the [Apache 2.0 License](./LICENSE).

build.gradle.kts

@@ -3,14 +3,13 @@ import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 plugins {
     java
     `java-library`
-    kotlin("jvm") version "1.5.10"
-    kotlin("plugin.serialization") version "1.5.10"
+    kotlin("jvm") version "1.6.0"
+    kotlin("plugin.serialization") version "1.6.0"
     `maven-publish`
     signing
 }
 
 group = "io.github.reugn"
-version = "0.3.0"
 
 repositories {
     mavenCentral()
@@ -22,9 +21,9 @@ java {
 }
 
 dependencies {
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.2")
     implementation("org.jetbrains.kotlinx:kotlinx-serialization-runtime:1.0-M1-1.4.0-rc")
-    testImplementation("org.junit.jupiter:junit-jupiter:5.6.0")
+    testImplementation("org.junit.jupiter:junit-jupiter:5.8.2")
 }
 
 tasks.withType<KotlinCompile> {
@@ -44,7 +43,7 @@ publishing {
             from(components["java"])
             pom {
                 name.set(project.name)
-                description.set("A simple Exponential Backoff library for Kotlin.")
+                description.set("An exponential backoff library for Kotlin.")
                 url.set("https://github.com/reugn/kotlin-backoff")
                 licenses {
                     license {

gradle.properties

@@ -1 +1,2 @@
-kotlin.code.style=official
+kotlin.code.style=official
+version=0.4.0

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,5 @@
-#Tue Feb 11 15:11:05 IST 2020
-distributionUrl=https\://services.gradle.org/distributions/gradle-7.0.2-all.zip
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-zipStorePath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.3.1-bin.zip
 zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

gradlew

@@ -1,5 +1,21 @@
 #!/usr/bin/env sh
 
+#
+# Copyright 2015 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
 ##############################################################################
 ##
 ##  Gradle start up script for UN*X
@@ -28,7 +44,7 @@ APP_NAME="Gradle"
 APP_BASE_NAME=`basename "$0"`
 
 # Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
-DEFAULT_JVM_OPTS=""
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
 
 # Use the maximum available, or set MAX_FD != -1 to use that value.
 MAX_FD="maximum"
@@ -66,6 +82,7 @@ esac
 
 CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
 
+
 # Determine the Java command to use to start the JVM.
 if [ -n "$JAVA_HOME" ] ; then
     if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
@@ -109,10 +126,11 @@ if $darwin; then
     GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\""
 fi
 
-# For Cygwin, switch paths to Windows format before running java
-if $cygwin ; then
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if [ "$cygwin" = "true" -o "$msys" = "true" ] ; then
     APP_HOME=`cygpath --path --mixed "$APP_HOME"`
     CLASSPATH=`cygpath --path --mixed "$CLASSPATH"`
+
     JAVACMD=`cygpath --unix "$JAVACMD"`
 
     # We build the pattern for arguments to be converted via cygpath
@@ -138,19 +156,19 @@ if $cygwin ; then
         else
             eval `echo args$i`="\"$arg\""
         fi
-        i=$((i+1))
+        i=`expr $i + 1`
     done
     case $i in
-        (0) set -- ;;
-        (1) set -- "$args0" ;;
-        (2) set -- "$args0" "$args1" ;;
-        (3) set -- "$args0" "$args1" "$args2" ;;
-        (4) set -- "$args0" "$args1" "$args2" "$args3" ;;
-        (5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;;
-        (6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;;
-        (7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;;
-        (8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;;
-        (9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;;
+        0) set -- ;;
+        1) set -- "$args0" ;;
+        2) set -- "$args0" "$args1" ;;
+        3) set -- "$args0" "$args1" "$args2" ;;
+        4) set -- "$args0" "$args1" "$args2" "$args3" ;;
+        5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;;
+        6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;;
+        7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;;
+        8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;;
+        9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;;
     esac
 fi
 
@@ -159,14 +177,9 @@ save () {
     for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done
     echo " "
 }
-APP_ARGS=$(save "$@")
+APP_ARGS=`save "$@"`
 
 # Collect all arguments for the java command, following the shell quoting and substitution rules
 eval set -- $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS "\"-Dorg.gradle.appname=$APP_BASE_NAME\"" -classpath "\"$CLASSPATH\"" org.gradle.wrapper.GradleWrapperMain "$APP_ARGS"
 
-# by default we should be in the correct project dir, but when run from Finder on Mac, the cwd is wrong
-if [ "$(uname)" = "Darwin" ] && [ "$HOME" = "$PWD" ]; then
-  cd "$(dirname "$0")"
-fi
-
 exec "$JAVACMD" "$@"

gradlew.bat

@@ -1,3 +1,19 @@
+@rem
+@rem Copyright 2015 the original author or authors.
+@rem
+@rem Licensed under the Apache License, Version 2.0 (the "License");
+@rem you may not use this file except in compliance with the License.
+@rem You may obtain a copy of the License at
+@rem
+@rem      https://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing, software
+@rem distributed under the License is distributed on an "AS IS" BASIS,
+@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+@rem See the License for the specific language governing permissions and
+@rem limitations under the License.
+@rem
+
 @if "%DEBUG%" == "" @echo off
 @rem ##########################################################################
 @rem
@@ -13,15 +29,18 @@ if "%DIRNAME%" == "" set DIRNAME=.
 set APP_BASE_NAME=%~n0
 set APP_HOME=%DIRNAME%
 
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
 @rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
-set DEFAULT_JVM_OPTS=
+set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
 
 @rem Find java.exe
 if defined JAVA_HOME goto findJavaFromJavaHome
 
 set JAVA_EXE=java.exe
 %JAVA_EXE% -version >NUL 2>&1
-if "%ERRORLEVEL%" == "0" goto init
+if "%ERRORLEVEL%" == "0" goto execute
 
 echo.
 echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
@@ -35,7 +54,7 @@ goto fail
 set JAVA_HOME=%JAVA_HOME:"=%
 set JAVA_EXE=%JAVA_HOME%/bin/java.exe
 
-if exist "%JAVA_EXE%" goto init
+if exist "%JAVA_EXE%" goto execute
 
 echo.
 echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
@@ -45,28 +64,14 @@ echo location of your Java installation.
 
 goto fail
 
-:init
-@rem Get command-line arguments, handling Windows variants
-
-if not "%OS%" == "Windows_NT" goto win9xME_args
-
-:win9xME_args
-@rem Slurp the command line arguments.
-set CMD_LINE_ARGS=
-set _SKIP=2
-
-:win9xME_args_slurp
-if "x%~1" == "x" goto execute
-
-set CMD_LINE_ARGS=%*
-
 :execute
 @rem Setup the command line
 
 set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
 
+
 @rem Execute Gradle
-"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %CMD_LINE_ARGS%
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
 
 :end
 @rem End local scope for the variables with windows NT shell

src/main/kotlin/io/github/reugn/kotlin/backoff/Backoff.kt

@@ -1,8 +1,17 @@
 package io.github.reugn.kotlin.backoff
 
-import io.github.reugn.kotlin.backoff.utils.Result
+import io.github.reugn.kotlin.backoff.util.Result
 
 interface Backoff<T> {
 
-    suspend fun retry(f: suspend () -> T): Result<T, Exception>
+    /**
+     * Retries the specified operation with delays and returns the result.
+     */
+    suspend fun retry(operation: suspend () -> T): Result<T, Throwable>
+
+    /**
+     * Executes the specified operation with retries and returns the result.
+     * The difference from [retry] is that the first time the operation is performed without delay.
+     */
+    suspend fun withRetries(operation: suspend () -> T): Result<T, Throwable>
 }