diff --git a/docs/core/addon/_category_.json b/docs/core/addon/_category_.json new file mode 100644 index 00000000000..0d3a6ea3995 --- /dev/null +++ b/docs/core/addon/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "\uD83D\uDD0C Addon", + "position": 5, + "collapsed": true, + "link": { + "type": "generated-index", + "description": "Addon is an additional useful package that can be used in Fiber." + } +} diff --git a/docs/core/addon/retry.md b/docs/core/addon/retry.md new file mode 100644 index 00000000000..2ed6a9f5d74 --- /dev/null +++ b/docs/core/addon/retry.md @@ -0,0 +1,126 @@ +--- +id: retry +--- + +# Retry Addon + +Retry addon for [Fiber](https://github.com/gofiber/fiber) designed to apply retry mechanism for unsuccessful network +operations. This addon uses an exponential backoff algorithm with jitter. It calls the function multiple times and tries +to make it successful. If all calls are failed, then, it returns an error. It adds a jitter at each retry step because adding +a jitter is a way to break synchronization across the client and avoid collision. + +## Table of Contents + +- [Retry Addon](#retry-addon) +- [Table of Contents](#table-of-contents) +- [Signatures](#signatures) +- [Examples](#examples) +- [Default Config](#default-config) +- [Custom Config](#custom-config) +- [Config](#config) +- [Default Config Example](#default-config-example) + +## Signatures + +```go +func NewExponentialBackoff(config ...retry.Config) *retry.ExponentialBackoff +``` + +## Examples + +```go +package main + +import ( + "fmt" + + "github.com/gofiber/fiber/v3/addon/retry" + "github.com/gofiber/fiber/v3/client" +) + +func main() { + expBackoff := retry.NewExponentialBackoff(retry.Config{}) + + // Local variables that will be used inside of Retry + var resp *client.Response + var err error + + // Retry a network request and return an error to signify to try again + err = expBackoff.Retry(func() error { + client := client.New() + resp, err = client.Get("https://gofiber.io") + if err != nil { + return fmt.Errorf("GET gofiber.io failed: %w", err) + } + if resp.StatusCode() != 200 { + return fmt.Errorf("GET gofiber.io did not return OK 200") + } + return nil + }) + + // If all retries failed, panic + if err != nil { + panic(err) + } + fmt.Printf("GET gofiber.io succeeded with status code %d\n", resp.StatusCode()) +} +``` + +## Default Config + +```go +retry.NewExponentialBackoff() +``` + +## Custom Config + +```go +retry.NewExponentialBackoff(retry.Config{ + InitialInterval: 2 * time.Second, + MaxBackoffTime: 64 * time.Second, + Multiplier: 2.0, + MaxRetryCount: 15, +}) +``` + +## Config + +```go +// Config defines the config for addon. +type Config struct { + // InitialInterval defines the initial time interval for backoff algorithm. + // + // Optional. Default: 1 * time.Second + InitialInterval time.Duration + + // MaxBackoffTime defines maximum time duration for backoff algorithm. When + // the algorithm is reached this time, rest of the retries will be maximum + // 32 seconds. + // + // Optional. Default: 32 * time.Second + MaxBackoffTime time.Duration + + // Multiplier defines multiplier number of the backoff algorithm. + // + // Optional. Default: 2.0 + Multiplier float64 + + // MaxRetryCount defines maximum retry count for the backoff algorithm. + // + // Optional. Default: 10 + MaxRetryCount int +} +``` + +## Default Config Example + +```go +// DefaultConfig is the default config for retry. +var DefaultConfig = Config{ + InitialInterval: 1 * time.Second, + MaxBackoffTime: 32 * time.Second, + Multiplier: 2.0, + MaxRetryCount: 10, + currentInterval: 1 * time.Second, +} +``` diff --git a/docs/core/client/_category_.json b/docs/core/client/_category_.json index 61fad7ac4e4..f5a63aa2ffa 100644 --- a/docs/core/client/_category_.json +++ b/docs/core/client/_category_.json @@ -1,6 +1,6 @@ { "label": "\uD83C\uDF0E Client", - "position": 5, + "position": 6, "link": { "type": "generated-index", "description": "HTTP client for Fiber." diff --git a/docs/core/extra/_category_.json b/docs/core/extra/_category_.json index 3398bed555f..55d68c94ba4 100644 --- a/docs/core/extra/_category_.json +++ b/docs/core/extra/_category_.json @@ -1,6 +1,6 @@ { "label": "\uD83E\uDDE9 Extra", - "position": 6, + "position": 8, "link": { "type": "generated-index", "description": "Extra contents for Fiber." diff --git a/docs/core/guide/_category_.json b/docs/core/guide/_category_.json index 62226d5d68e..fd203a8bb08 100644 --- a/docs/core/guide/_category_.json +++ b/docs/core/guide/_category_.json @@ -1,6 +1,6 @@ { "label": "\uD83D\uDCD6 Guide", - "position": 5, + "position": 7, "link": { "type": "generated-index", "description": "Guides for Fiber." diff --git a/docs/core/whats_new.md b/docs/core/whats_new.md index 4185a7e3ad7..5c3dd6ac9ae 100644 --- a/docs/core/whats_new.md +++ b/docs/core/whats_new.md @@ -33,6 +33,7 @@ Here's a quick overview of the changes in Fiber `v3`: - [Filesystem](#filesystem) - [Monitor](#monitor) - [Healthcheck](#healthcheck) +- [🔌 Addons](#-addons) - [📋 Migration guide](#-migration-guide) ## Drop for old Go versions @@ -939,6 +940,59 @@ The Healthcheck middleware has been enhanced to support more than two routes, wi Refer to the [healthcheck middleware migration guide](./middleware/healthcheck.md) or the [general migration guide](#-migration-guide) to review the changes. +## 🔌 Addons + +In v3, Fiber introduced Addons. Addons are additional useful packages that can be used in Fiber. + +### Retry + +The Retry addon is a new addon that implements a retry mechanism for unsuccessful network operations. It uses an exponential backoff algorithm with jitter. +It calls the function multiple times and tries to make it successful. If all calls are failed, then, it returns an error. +It adds a jitter at each retry step because adding a jitter is a way to break synchronization across the client and avoid collision. + +
+Example + +```go +package main + +import ( + "fmt" + + "github.com/gofiber/fiber/v3/addon/retry" + "github.com/gofiber/fiber/v3/client" +) + +func main() { + expBackoff := retry.NewExponentialBackoff(retry.Config{}) + + // Local variables that will be used inside of Retry + var resp *client.Response + var err error + + // Retry a network request and return an error to signify to try again + err = expBackoff.Retry(func() error { + client := client.New() + resp, err = client.Get("https://gofiber.io") + if err != nil { + return fmt.Errorf("GET gofiber.io failed: %w", err) + } + if resp.StatusCode() != 200 { + return fmt.Errorf("GET gofiber.io did not return OK 200") + } + return nil + }) + + // If all retries failed, panic + if err != nil { + panic(err) + } + fmt.Printf("GET gofiber.io succeeded with status code %d\n", resp.StatusCode()) +} +``` + +
+ ## 📋 Migration guide - [🚀 App](#-app-1)