From b568915b70c43a7ed02f5909ee72f1151ecd79e5 Mon Sep 17 00:00:00 2001 From: Giovanni Rivera Date: Wed, 26 Feb 2025 23:46:41 -0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20docs:=20Add=20Retry=20Addon=20do?= =?UTF-8?q?cumentation=20(#3330)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 📚 Doc: Add addon tab to /docs * 📚 Doc: Add retry to addon docs * 📚 Doc: Update retry README.md * 🎨 Styles: Update addon/retry docs to respect markdownlint-cli2 * 📚 Doc: Update addon tab description to be singular * 📚 Doc: Use retry prefix in retry docs * 📚 Doc: Add retry addon to whats_new.md * 🎨 Styles: Update whats_new.md to respect markdownlint-cli2 --- addon/retry/README.md | 47 ++++++++++---- docs/addon/_category_.json | 9 +++ docs/addon/retry.md | 126 ++++++++++++++++++++++++++++++++++++ docs/client/_category_.json | 2 +- docs/extra/_category_.json | 2 +- docs/guide/_category_.json | 2 +- docs/whats_new.md | 54 ++++++++++++++++ 7 files changed, 228 insertions(+), 14 deletions(-) create mode 100644 docs/addon/_category_.json create mode 100644 docs/addon/retry.md diff --git a/addon/retry/README.md b/addon/retry/README.md index a3af4407..e6e1c34b 100644 --- a/addon/retry/README.md +++ b/addon/retry/README.md @@ -19,17 +19,47 @@ a jitter is a way to break synchronization across the client and avoid collision ## Signatures ```go -func NewExponentialBackoff(config ...Config) *ExponentialBackoff +func NewExponentialBackoff(config ...retry.Config) *retry.ExponentialBackoff ``` ## Examples -Firstly, import the addon from Fiber, - ```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 @@ -58,28 +88,23 @@ type Config struct { // // 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 - - // currentInterval tracks the current waiting time. - // - // Optional. Default: 1 * time.Second - currentInterval time.Duration } ``` diff --git a/docs/addon/_category_.json b/docs/addon/_category_.json new file mode 100644 index 00000000..0d3a6ea3 --- /dev/null +++ b/docs/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/addon/retry.md b/docs/addon/retry.md new file mode 100644 index 00000000..2ed6a9f5 --- /dev/null +++ b/docs/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/client/_category_.json b/docs/client/_category_.json index 61fad7ac..f5a63aa2 100644 --- a/docs/client/_category_.json +++ b/docs/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/extra/_category_.json b/docs/extra/_category_.json index 3398bed5..55d68c94 100644 --- a/docs/extra/_category_.json +++ b/docs/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/guide/_category_.json b/docs/guide/_category_.json index 62226d5d..fd203a8b 100644 --- a/docs/guide/_category_.json +++ b/docs/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/whats_new.md b/docs/whats_new.md index 4185a7e3..5c3dd6ac 100644 --- a/docs/whats_new.md +++ b/docs/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)