{"id":20610534,"url":"https://github.com/reugn/kotlin-backoff","last_synced_at":"2025-04-15T04:32:19.682Z","repository":{"id":45495835,"uuid":"240526193","full_name":"reugn/kotlin-backoff","owner":"reugn","description":"An exponential backoff library for Kotlin","archived":false,"fork":false,"pushed_at":"2022-02-11T08:34:04.000Z","size":149,"stargazers_count":40,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-12T02:51:19.673Z","etag":null,"topics":["backoff","exponential-backoff","fault-tolerance","kotlin","kotlin-library","retry","retry-library","retry-strategies"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reugn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-14T14:26:59.000Z","updated_at":"2023-01-23T01:07:57.000Z","dependencies_parsed_at":"2022-07-19T00:17:12.672Z","dependency_job_id":null,"html_url":"https://github.com/reugn/kotlin-backoff","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reugn%2Fkotlin-backoff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reugn%2Fkotlin-backoff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reugn%2Fkotlin-backoff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reugn%2Fkotlin-backoff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reugn","download_url":"https://codeload.github.com/reugn/kotlin-backoff/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249006570,"owners_count":21197299,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backoff","exponential-backoff","fault-tolerance","kotlin","kotlin-library","retry","retry-library","retry-strategies"],"created_at":"2024-11-16T10:17:07.908Z","updated_at":"2025-04-15T04:32:19.655Z","avatar_url":"https://github.com/reugn.png","language":"Kotlin","funding_links":[],"categories":["容错组件"],"sub_categories":["微服务框架"],"readme":"# kotlin-backoff\n[![Build](https://github.com/reugn/kotlin-backoff/actions/workflows/build.yml/badge.svg)](https://github.com/reugn/kotlin-backoff/actions/workflows/build.yml)\n[![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/)\n\nAny I/O resource can be temporarily unavailable and cause requests to fail.\nUse this library to catch errors and retry, slowing down according to your chosen strategy.\nAdd validation rules for the result and error types if needed.\n\n## Installation\n`kotlin-backoff` is available on Maven Central.  \nAdd the library as a dependency to your project:\n```kotlin\ndependencies {\n    implementation(\"io.github.reugn:kotlin-backoff:0.4.0\")\n}\n```\n\n## Backoff strategies\nBelow is a list of backoff strategies implemented. To create your own strategy, implement the `Strategy` interface.\n\n### Exponential strategy\nA strategy in which the next delay interval is calculated using `baseDelayMs * expBase.pow(attempt)` where:\n* `baseDelayMs` is the base delay in milliseconds.\n* `attempt` is the number of unsuccessful attempts that have been made.\n* `expBase` is the exponent base configured for the strategy.\n\nThe specified jitter¹ and scale factor² are applied to the calculated interval.\nThe delay time cannot exceed the specified maximum delay in milliseconds.\n\n### Polynomial strategy\nA strategy in which the next delay interval is calculated using `baseDelayMs * attempt.pow(exponent)` where:\n* `baseDelayMs` is the base delay in milliseconds.\n* `attempt` is the number of unsuccessful attempts that have been made.\n* `exponent` is the exponent configured for the strategy.\n\nThe specified jitter¹ and scale factor² are applied to the calculated interval.\nThe delay time cannot exceed the specified maximum delay in milliseconds.\n\n### Fixed strategy\nA strategy that returns the delay time as a fixed value determined by the attempt number.\n\n### Constant strategy\nA simple backoff strategy that constantly returns the same value.\nThe specified jitter¹ is applied to the interval. No jitter by default.\n\n---\n¹ Jitter adds a retry randomization factor to reduce resource congestion.\nSpecify 1.0 for full jitter, 0.0 for no jitter.\n\n² The delay determined by the backoff strategy is multiplied by the scale factor. By default, the coefficient is 1.\n\n## Usage example\nFirst, create an instance of `StrategyBackoff`. Then perform the operation, which may fail, using the `retry` or `withRetries` methods.\n```kotlin\nprivate suspend fun urlAction(): String = withContext(Dispatchers.IO) {\n    URL(\"http://worldclockapi.com/api/json/utc/now\").readText()\n}\n\n@Test\nfun `remote URL`() {\n    val backoff = StrategyBackoff\u003cString\u003e(\n        maxRetries = 3,\n        strategy = ExponentialStrategy(),\n        errorValidator = ::nonFatal,\n        resultValidator = { s -\u003e s.isNotEmpty() },\n    )\n    val result = runBlocking { backoff.withRetries(::urlAction) }\n\n    assert(result.isOk())\n    assertEquals(result.retries, 0)\n}\n```\nFor more examples, see the [tests](./src/test/kotlin/io/github/reugn/kotlin/backoff).\n\n## License\nLicensed under the [Apache 2.0 License](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freugn%2Fkotlin-backoff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freugn%2Fkotlin-backoff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freugn%2Fkotlin-backoff/lists"}