📚 docs: Add Retry Addon documentation (#3330)

* 📚 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
gofiber · Feb 27, 2025 · b568915 · b568915
1 parent 0bf0353
commit b568915
Show file tree

Hide file tree

Showing 7 changed files with 228 additions and 14 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.
+
+<details>
+<summary>Example</summary>
+
+```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())
+}
+```
+
+</details>
+
 ## 📋 Migration guide
 
 - [🚀 App](#-app-1)