|
1 | 1 | # retry |
2 | 2 |
|
3 | | -[](https://travis-ci.org/avast/retry-go) |
4 | | -[](https://ci.appveyor.com/project/JaSei/retry-go) |
5 | | -[](https://goreportcard.com/report/github.com/avast/retry-go) |
6 | | -[](http://godoc.org/github.com/avast/retry-go) |
| 3 | +[](https://github.com/avast/retry-go/releases/latest) |
| 4 | +[](LICENSE.md) |
| 5 | +[](https://travis-ci.org/avast/retry-go) |
| 6 | +[](https://ci.appveyor.com/project/JaSei/retry-go) |
| 7 | +[](https://goreportcard.com/report/github.com/avast/retry-go) |
| 8 | +[](http://godoc.org/github.com/avast/retry-go) |
| 9 | +[](https://codecov.io/github/avast/retry-go?branch=master) |
7 | 10 | [](https://sourcegraph.com/github.com/avast/retry-go?badge) |
8 | | -[](https://codecov.io/github/avast/retry-go?branch=master) |
9 | 11 |
|
10 | 12 | Simple library for retry mechanism |
11 | 13 |
|
12 | | -slightly inspired by [Try::Tiny::Retry](https://metacpan.org/pod/Try::Tiny::Retry) |
| 14 | +slightly inspired by |
| 15 | +[Try::Tiny::Retry](https://metacpan.org/pod/Try::Tiny::Retry) |
13 | 16 |
|
14 | | -## INSTALL && USE |
15 | 17 |
|
16 | | -To get the package, execute: |
| 18 | +### SYNOPSIS |
17 | 19 |
|
| 20 | +http get with retry: |
| 21 | + |
| 22 | + url := "http://example.com" |
| 23 | + var body []byte |
| 24 | + |
| 25 | + err := retry.Retry( |
| 26 | + func() error { |
| 27 | + resp, err := http.Get(url) |
| 28 | + if err != nil { |
| 29 | + return err |
| 30 | + } |
| 31 | + defer resp.Body.Close() |
| 32 | + body, err = ioutil.ReadAll(resp.Body) |
| 33 | + if err != nil { |
| 34 | + return err |
| 35 | + } |
| 36 | + |
| 37 | + return nil |
| 38 | + }, |
| 39 | + ) |
| 40 | + |
| 41 | + fmt.Println(body) |
| 42 | + |
| 43 | +[next examples](https://github.com/avast/retry-go/examples) |
| 44 | + |
| 45 | + |
| 46 | +### SEE ALSO |
| 47 | + |
| 48 | +* [giantswarm/retry-go](https://github.com/giantswarm/retry-go) - slightly |
| 49 | +complicated interface. |
| 50 | + |
| 51 | +* [sethgrid/pester](https://github.com/sethgrid/pester) - only http retry for |
| 52 | +http calls with retries and backoff |
| 53 | + |
| 54 | +* [cenkalti/backoff](https://github.com/cenkalti/backoff) - Go port of the |
| 55 | +exponential backoff algorithm from Google's HTTP Client Library for Java. Really |
| 56 | +complicated interface. |
| 57 | + |
| 58 | +## Usage |
| 59 | + |
| 60 | +#### func Retry |
| 61 | + |
| 62 | +```go |
| 63 | +func Retry(retryableFunction Retryable) error |
| 64 | +``` |
| 65 | +Retry - simple retry |
| 66 | + |
| 67 | +#### func RetryCustom |
| 68 | + |
| 69 | +```go |
| 70 | +func RetryCustom(retryableFunction Retryable, onRetryFunction OnRetry, opts RetryOpts) error |
18 | 71 | ``` |
19 | | -go get gopkg.in/avast/retry-go.v0 |
| 72 | +RetryCustom - the most customizable retry is possible set OnRetry function |
| 73 | +callback which are called each retry |
| 74 | + |
| 75 | +#### func RetryWithOpts |
| 76 | + |
| 77 | +```go |
| 78 | +func RetryWithOpts(retryableFunction Retryable, opts RetryOpts) error |
20 | 79 | ``` |
| 80 | +RetryWithOpts - customizable retry via RetryOpts |
21 | 81 |
|
22 | | -To import this package, add the following line to your code: |
| 82 | +#### type Error |
23 | 83 |
|
24 | 84 | ```go |
25 | | -import "gopkg.in/avast/retry-go.v0" |
| 85 | +type Error []error |
26 | 86 | ``` |
27 | 87 |
|
28 | | -### EXAMPLE |
| 88 | +Error type represents list of errors in retry |
29 | 89 |
|
30 | | -http get with retry: |
| 90 | +#### func (Error) Error |
31 | 91 |
|
32 | 92 | ```go |
33 | | -url := "http://example.com" |
34 | | -var body []byte |
| 93 | +func (e Error) Error() string |
| 94 | +``` |
| 95 | +Error method return string representation of Error It is an implementation of |
| 96 | +error interface |
35 | 97 |
|
36 | | -err := retry.Retry( |
37 | | - func() error { |
38 | | - resp, err := http.Get(url) |
39 | | - if err != nil { |
40 | | - return err |
41 | | - } |
42 | | - defer resp.Body.Close() |
43 | | - body, err = ioutil.ReadAll(resp.Body) |
44 | | - if err != nil { |
45 | | - return err |
46 | | - } |
| 98 | +#### func (Error) WrappedErrors |
47 | 99 |
|
48 | | - return nil |
49 | | - }, |
50 | | -) |
| 100 | +```go |
| 101 | +func (e Error) WrappedErrors() []error |
| 102 | +``` |
| 103 | +WrappedErrors returns the list of errors that this Error is wrapping. It is an |
| 104 | +implementation of the errwrap.Wrapper interface so that multierror.Error can be |
| 105 | +used with that library. |
51 | 106 |
|
52 | | -fmt.Println(body) |
| 107 | +#### type OnRetry |
| 108 | + |
| 109 | +```go |
| 110 | +type OnRetry func(n uint, err error) |
53 | 111 | ``` |
54 | 112 |
|
55 | | -[next examples](examples) |
| 113 | +Function signature of OnRetry function n = count of tries |
| 114 | + |
| 115 | +#### type RetryOpts |
| 116 | + |
| 117 | +```go |
| 118 | +type RetryOpts struct { |
| 119 | +} |
| 120 | +``` |
| 121 | + |
| 122 | +Struct for configure retry tries - count of tries delay - waiting time units - |
| 123 | +waiting time unit (for tests purpose) |
| 124 | + |
| 125 | +#### func NewRetryOpts |
| 126 | + |
| 127 | +```go |
| 128 | +func NewRetryOpts() RetryOpts |
| 129 | +``` |
| 130 | +Create new RetryOpts struct with default values default tries are 10 default |
| 131 | +delay are 1e5 default units are microsecond |
| 132 | + |
| 133 | +#### func (RetryOpts) Delay |
| 134 | + |
| 135 | +```go |
| 136 | +func (opts RetryOpts) Delay(delay time.Duration) RetryOpts |
| 137 | +``` |
| 138 | +Delay setter |
| 139 | + |
| 140 | +#### func (RetryOpts) Tries |
| 141 | + |
| 142 | +```go |
| 143 | +func (opts RetryOpts) Tries(tries uint) RetryOpts |
| 144 | +``` |
| 145 | +Tries setter |
| 146 | + |
| 147 | +#### func (RetryOpts) Units |
| 148 | + |
| 149 | +```go |
| 150 | +func (opts RetryOpts) Units(timeUnit time.Duration) RetryOpts |
| 151 | +``` |
| 152 | +Units setter |
| 153 | + |
| 154 | +#### type Retryable |
| 155 | + |
| 156 | +```go |
| 157 | +type Retryable func() error |
| 158 | +``` |
| 159 | + |
| 160 | +Function signature of retryable function |
| 161 | + |
| 162 | +## Contributing |
| 163 | + |
| 164 | +Contributions are very much welcome. |
| 165 | + |
| 166 | +### Makefile |
| 167 | + |
| 168 | +Makefile provides several handy rules, like README.md `generator` , `setup` for prepare build/dev environment, `test`, `cover`, etc... |
| 169 | + |
| 170 | +Try `make help` for more information. |
| 171 | + |
| 172 | +### Before pull request |
| 173 | + |
| 174 | +please try: |
| 175 | +* run tests (`make test`) |
| 176 | +* run linter (`make lint`) |
| 177 | +* if your IDE don't automaticaly do `go fmt`, run `go fmt` (`make fmt`) |
| 178 | + |
| 179 | +### README |
| 180 | + |
| 181 | +README.md are generate from template [.godocdown.tmpl](.godocdown.tmpl) and code documentation via [godocdown](https://github.com/robertkrimen/godocdown). |
56 | 182 |
|
57 | | -## SEE ALSO |
58 | | -* [giantswarm/retry-go](https://github.com/giantswarm/retry-go) - slightly complicated interface. |
59 | | -* [sethgrid/pester](https://github.com/sethgrid/pester) - only http retry for http calls with retries and backoff |
60 | | -* [cenkalti/backoff](https://github.com/cenkalti/backoff) - Go port of the exponential backoff algorithm from Google's HTTP Client Library for Java. Really complicated interface. |
| 183 | +Never edit README.md direct, because your change will be lost. |
0 commit comments