Skip to content

Commit b568915

Browse files
grivera64grivera64
authored
📚 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
1 parent 0bf0353 commit b568915

File tree

7 files changed

+228
-14
lines changed

7 files changed

+228
-14
lines changed

‎addon/retry/README.md

+36-11
Original file line numberDiff line numberDiff line change
@@ -19,17 +19,47 @@ a jitter is a way to break synchronization across the client and avoid collision
1919
## Signatures
2020

2121
```go
22-
func NewExponentialBackoff(config ...Config) *ExponentialBackoff
22+
func NewExponentialBackoff(config ...retry.Config) *retry.ExponentialBackoff
2323
```
2424

2525
## Examples
2626

27-
Firstly, import the addon from Fiber,
28-
2927
```go
28+
package main
29+
3030
import (
31+
"fmt"
32+
3133
"github.com/gofiber/fiber/v3/addon/retry"
34+
"github.com/gofiber/fiber/v3/client"
3235
)
36+
37+
func main() {
38+
expBackoff := retry.NewExponentialBackoff(retry.Config{})
39+
40+
// Local variables that will be used inside of Retry
41+
var resp *client.Response
42+
var err error
43+
44+
// Retry a network request and return an error to signify to try again
45+
err = expBackoff.Retry(func() error {
46+
client := client.New()
47+
resp, err = client.Get("https://gofiber.io")
48+
if err != nil {
49+
return fmt.Errorf("GET gofiber.io failed: %w", err)
50+
}
51+
if resp.StatusCode() != 200 {
52+
return fmt.Errorf("GET gofiber.io did not return OK 200")
53+
}
54+
return nil
55+
})
56+
57+
// If all retries failed, panic
58+
if err != nil {
59+
panic(err)
60+
}
61+
fmt.Printf("GET gofiber.io succeeded with status code %d\n", resp.StatusCode())
62+
}
3363
```
3464

3565
## Default Config
@@ -58,28 +88,23 @@ type Config struct {
5888
//
5989
// Optional. Default: 1 * time.Second
6090
InitialInterval time.Duration
61-
91+
6292
// MaxBackoffTime defines maximum time duration for backoff algorithm. When
6393
// the algorithm is reached this time, rest of the retries will be maximum
6494
// 32 seconds.
6595
//
6696
// Optional. Default: 32 * time.Second
6797
MaxBackoffTime time.Duration
68-
98+
6999
// Multiplier defines multiplier number of the backoff algorithm.
70100
//
71101
// Optional. Default: 2.0
72102
Multiplier float64
73-
103+
74104
// MaxRetryCount defines maximum retry count for the backoff algorithm.
75105
//
76106
// Optional. Default: 10
77107
MaxRetryCount int
78-
79-
// currentInterval tracks the current waiting time.
80-
//
81-
// Optional. Default: 1 * time.Second
82-
currentInterval time.Duration
83108
}
84109
```
85110

‎docs/addon/_category_.json

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"label": "\uD83D\uDD0C Addon",
3+
"position": 5,
4+
"collapsed": true,
5+
"link": {
6+
"type": "generated-index",
7+
"description": "Addon is an additional useful package that can be used in Fiber."
8+
}
9+
}

‎docs/addon/retry.md

+126
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
id: retry
3+
---
4+
5+
# Retry Addon
6+
7+
Retry addon for [Fiber](https://github.com/gofiber/fiber) designed to apply retry mechanism for unsuccessful network
8+
operations. This addon uses an exponential backoff algorithm with jitter. It calls the function multiple times and tries
9+
to make it successful. If all calls are failed, then, it returns an error. It adds a jitter at each retry step because adding
10+
a jitter is a way to break synchronization across the client and avoid collision.
11+
12+
## Table of Contents
13+
14+
- [Retry Addon](#retry-addon)
15+
- [Table of Contents](#table-of-contents)
16+
- [Signatures](#signatures)
17+
- [Examples](#examples)
18+
- [Default Config](#default-config)
19+
- [Custom Config](#custom-config)
20+
- [Config](#config)
21+
- [Default Config Example](#default-config-example)
22+
23+
## Signatures
24+
25+
```go
26+
func NewExponentialBackoff(config ...retry.Config) *retry.ExponentialBackoff
27+
```
28+
29+
## Examples
30+
31+
```go
32+
package main
33+
34+
import (
35+
"fmt"
36+
37+
"github.com/gofiber/fiber/v3/addon/retry"
38+
"github.com/gofiber/fiber/v3/client"
39+
)
40+
41+
func main() {
42+
expBackoff := retry.NewExponentialBackoff(retry.Config{})
43+
44+
// Local variables that will be used inside of Retry
45+
var resp *client.Response
46+
var err error
47+
48+
// Retry a network request and return an error to signify to try again
49+
err = expBackoff.Retry(func() error {
50+
client := client.New()
51+
resp, err = client.Get("https://gofiber.io")
52+
if err != nil {
53+
return fmt.Errorf("GET gofiber.io failed: %w", err)
54+
}
55+
if resp.StatusCode() != 200 {
56+
return fmt.Errorf("GET gofiber.io did not return OK 200")
57+
}
58+
return nil
59+
})
60+
61+
// If all retries failed, panic
62+
if err != nil {
63+
panic(err)
64+
}
65+
fmt.Printf("GET gofiber.io succeeded with status code %d\n", resp.StatusCode())
66+
}
67+
```
68+
69+
## Default Config
70+
71+
```go
72+
retry.NewExponentialBackoff()
73+
```
74+
75+
## Custom Config
76+
77+
```go
78+
retry.NewExponentialBackoff(retry.Config{
79+
InitialInterval: 2 * time.Second,
80+
MaxBackoffTime: 64 * time.Second,
81+
Multiplier: 2.0,
82+
MaxRetryCount: 15,
83+
})
84+
```
85+
86+
## Config
87+
88+
```go
89+
// Config defines the config for addon.
90+
type Config struct {
91+
// InitialInterval defines the initial time interval for backoff algorithm.
92+
//
93+
// Optional. Default: 1 * time.Second
94+
InitialInterval time.Duration
95+
96+
// MaxBackoffTime defines maximum time duration for backoff algorithm. When
97+
// the algorithm is reached this time, rest of the retries will be maximum
98+
// 32 seconds.
99+
//
100+
// Optional. Default: 32 * time.Second
101+
MaxBackoffTime time.Duration
102+
103+
// Multiplier defines multiplier number of the backoff algorithm.
104+
//
105+
// Optional. Default: 2.0
106+
Multiplier float64
107+
108+
// MaxRetryCount defines maximum retry count for the backoff algorithm.
109+
//
110+
// Optional. Default: 10
111+
MaxRetryCount int
112+
}
113+
```
114+
115+
## Default Config Example
116+
117+
```go
118+
// DefaultConfig is the default config for retry.
119+
var DefaultConfig = Config{
120+
InitialInterval: 1 * time.Second,
121+
MaxBackoffTime: 32 * time.Second,
122+
Multiplier: 2.0,
123+
MaxRetryCount: 10,
124+
currentInterval: 1 * time.Second,
125+
}
126+
```

‎docs/client/_category_.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"label": "\uD83C\uDF0E Client",
3-
"position": 5,
3+
"position": 6,
44
"link": {
55
"type": "generated-index",
66
"description": "HTTP client for Fiber."

‎docs/extra/_category_.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"label": "\uD83E\uDDE9 Extra",
3-
"position": 6,
3+
"position": 8,
44
"link": {
55
"type": "generated-index",
66
"description": "Extra contents for Fiber."

‎docs/guide/_category_.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"label": "\uD83D\uDCD6 Guide",
3-
"position": 5,
3+
"position": 7,
44
"link": {
55
"type": "generated-index",
66
"description": "Guides for Fiber."

‎docs/whats_new.md

+54
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ Here's a quick overview of the changes in Fiber `v3`:
3333
- [Filesystem](#filesystem)
3434
- [Monitor](#monitor)
3535
- [Healthcheck](#healthcheck)
36+
- [🔌 Addons](#-addons)
3637
- [📋 Migration guide](#-migration-guide)
3738

3839
## Drop for old Go versions
@@ -939,6 +940,59 @@ The Healthcheck middleware has been enhanced to support more than two routes, wi
939940

940941
Refer to the [healthcheck middleware migration guide](./middleware/healthcheck.md) or the [general migration guide](#-migration-guide) to review the changes.
941942

943+
## 🔌 Addons
944+
945+
In v3, Fiber introduced Addons. Addons are additional useful packages that can be used in Fiber.
946+
947+
### Retry
948+
949+
The Retry addon is a new addon that implements a retry mechanism for unsuccessful network operations. It uses an exponential backoff algorithm with jitter.
950+
It calls the function multiple times and tries to make it successful. If all calls are failed, then, it returns an error.
951+
It adds a jitter at each retry step because adding a jitter is a way to break synchronization across the client and avoid collision.
952+
953+
<details>
954+
<summary>Example</summary>
955+
956+
```go
957+
package main
958+
959+
import (
960+
"fmt"
961+
962+
"github.com/gofiber/fiber/v3/addon/retry"
963+
"github.com/gofiber/fiber/v3/client"
964+
)
965+
966+
func main() {
967+
expBackoff := retry.NewExponentialBackoff(retry.Config{})
968+
969+
// Local variables that will be used inside of Retry
970+
var resp *client.Response
971+
var err error
972+
973+
// Retry a network request and return an error to signify to try again
974+
err = expBackoff.Retry(func() error {
975+
client := client.New()
976+
resp, err = client.Get("https://gofiber.io")
977+
if err != nil {
978+
return fmt.Errorf("GET gofiber.io failed: %w", err)
979+
}
980+
if resp.StatusCode() != 200 {
981+
return fmt.Errorf("GET gofiber.io did not return OK 200")
982+
}
983+
return nil
984+
})
985+
986+
// If all retries failed, panic
987+
if err != nil {
988+
panic(err)
989+
}
990+
fmt.Printf("GET gofiber.io succeeded with status code %d\n", resp.StatusCode())
991+
}
992+
```
993+
994+
</details>
995+
942996
## 📋 Migration guide
943997

944998
- [🚀 App](#-app-1)

0 commit comments

Comments
 (0)