-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
add docs for retry and circuit breaker
- update docs for curl cmd and upgrading v3 - update license file
- Loading branch information
Showing
5 changed files
with
229 additions
and
24 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -186,7 +186,7 @@ | |
| same "printed page" as the copyright notice for easier | ||
| identification within third-party archives. | ||
|
|
||
| Copyright [yyyy] [name of copyright owner] | ||
| Copyright 2024-Present Jeevanandam M ([email protected]) | ||
|
|
||
| Licensed under the Apache License, Version 2.0 (the "License"); | ||
| you may not use this file except in compliance with the License. | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
|
|
||
| # Circuit Breaker | ||
|
|
||
| A circuit breaker is used to improve system stability and resiliency. It is different from the retry mechanism. | ||
|
|
||
| {{% hint info %}} | ||
| **Hint:** Combining the Circuit Breaker with [Retry Mechanism]({{% relref "retry-mechanism" %}}) typically provides a comprehensive approach to handling failures. | ||
| {{% /hint %}} | ||
|
|
||
| ## Default Values | ||
|
|
||
| * Timeout is `10s` | ||
| * Failure threshold is `3` | ||
| * Success threshold is `1` | ||
| * Circuir break policy | ||
| * Status Code `500` and above | ||
|
|
||
|
|
||
| ## Example | ||
|
|
||
| ```go | ||
| // create circuit breaker with required values, override as required | ||
| cb := resty.NewCircuitBreaker(). | ||
| SetTimeout(15 * time.Second). | ||
| SetFailThreshold(10). | ||
| SetSuccessThreshold(5) | ||
|
|
||
| // create Resty client | ||
| client := resty.New(). | ||
| SetCircuitBreaker(cb) | ||
| defer client.Close() | ||
|
|
||
| // start using the client ... | ||
| ``` | ||
|
|
||
|
|
||
| ## Methods | ||
|
|
||
| * [CircuitBreaker.SetTimeout]({{% param Resty.V3.GoDocLinkPrefix %}}CircuitBreaker.SetTimeout) | ||
| * [CircuitBreaker.SetFailThreshold]({{% param Resty.V3.GoDocLinkPrefix %}}CircuitBreaker.SetFailThreshold) | ||
| * [CircuitBreaker.SetSuccessThreshold]({{% param Resty.V3.GoDocLinkPrefix %}}CircuitBreaker.SetSuccessThreshold) | ||
| * [CircuitBreaker.SetPolicies]({{% param Resty.V3.GoDocLinkPrefix %}}CircuitBreaker.SetPolicies) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,46 +1,53 @@ | ||
| --- | ||
| title: "CURL Command Generation" | ||
| bookHidden: true | ||
| --- | ||
|
|
||
| # CURL Command Generation | ||
| # Curl Command | ||
|
|
||
| Resty provides a way to generate the CURL command in debug mode. | ||
| Resty provides an option to generate the curl command for the request. | ||
|
|
||
| By default, Resty does not log the curl command in the debug log since it has the potential to leak sensitive data unless explicitly enabled via [Client.SetDebugLogCurlCmd]({{% param Resty.V3.GoDocLinkPrefix %}}Client.SetDebugLogCurlCmd). | ||
|
|
||
| {{% hint info %}} | ||
| **NOTE:** Client-level settings can be overridden at the request level. | ||
| {{% /hint %}} | ||
|
|
||
| {{% hint warning %}} | ||
| **NOTE:** | ||
|
|
||
| - Potential to leak sensitive data from [Request]() and [Response]() in the debug log. | ||
| - Beware of memory usage since the request body is reread. | ||
| - Potential to leak sensitive data from [Request]({{% param Resty.V3.GoDocLinkPrefix %}}Request) and [Response]({{% param Resty.V3.GoDocLinkPrefix %}}Response) in the debug log when the debug log option is enabled. | ||
| - Additional memory usage since the request body was reread. | ||
| - curl body is not generated for `io.Reader` and multipart request flow. | ||
| {{% /hint %}} | ||
|
|
||
| ## Methods | ||
| * [Client.EnableGenerateCurlOnDebug]({{% param Resty.V3.GoDocLinkPrefix %}}Client.EnableGenerateCurlOnDebug) | ||
| * [Client.DisableGenerateCurlOnDebug]({{% param Resty.V3.GoDocLinkPrefix %}}Client.DisableGenerateCurlOnDebug) | ||
| * [Client.SetGenerateCurlOnDebug]({{% param Resty.V3.GoDocLinkPrefix %}}Client.SetGenerateCurlOnDebug) | ||
| * [Request.EnableGenerateCurlOnDebug]({{% param Resty.V3.GoDocLinkPrefix %}}Request.EnableGenerateCurlOnDebug) | ||
| * [Request.DisableGenerateCurlOnDebug]({{% param Resty.V3.GoDocLinkPrefix %}}Request.DisableGenerateCurlOnDebug) | ||
| * [Request.SetGenerateCurlOnDebug]({{% param Resty.V3.GoDocLinkPrefix %}}Request.SetGenerateCurlOnDebug) | ||
| ## Example | ||
|
|
||
| ```go | ||
| c := resty.New() | ||
| defer c.Close() | ||
|
|
||
| res, err := c.R(). | ||
| EnableDebug(). | ||
| EnableGenerateCurlOnDebug(). | ||
| SetGenerateCurlCmd(true). | ||
| SetBody(map[string]string{ | ||
| "name": "Alex", | ||
| }). | ||
| Post("https://httpbin.org/post") | ||
|
|
||
| curlCmdStr := res.Request.GenerateCurlCommand() | ||
| curlCmdStr := res.Request.CurlCommand() | ||
| fmt.Println(err, curlCmdStr) | ||
|
|
||
| // Result: | ||
| // curl -X POST -H 'Content-Type: application/json' -H 'User-Agent: go-resty/3.0.0 (https://resty.dev)' -d '{"name":"Alex"}' https://httpbin.org/post | ||
| ``` | ||
|
|
||
| ## Methods | ||
|
|
||
| ### Client | ||
|
|
||
| * [Client.EnableGenerateCurlCmd]({{% param Resty.V3.GoDocLinkPrefix %}}Client.EnableGenerateCurlCmd) | ||
| * [Client.DisableGenerateCurlCmd]({{% param Resty.V3.GoDocLinkPrefix %}}Client.DisableGenerateCurlCmd) | ||
| * [Client.SetGenerateCurlCmd]({{% param Resty.V3.GoDocLinkPrefix %}}Client.SetGenerateCurlCmd) | ||
| * [Client.SetDebugLogCurlCmd]({{% param Resty.V3.GoDocLinkPrefix %}}Client.SetDebugLogCurlCmd) | ||
|
|
||
| ### Request | ||
|
|
||
| * [Request.EnableGenerateCurlCmd]({{% param Resty.V3.GoDocLinkPrefix %}}Request.EnableGenerateCurlCmd) | ||
| * [Request.DisableGenerateCurlCmd]({{% param Resty.V3.GoDocLinkPrefix %}}Request.DisableGenerateCurlCmd) | ||
| * [Request.SetGenerateCurlCmd]({{% param Resty.V3.GoDocLinkPrefix %}}Request.SetGenerateCurlCmd) | ||
| * [Request.SetDebugLogCurlCmd]({{% param Resty.V3.GoDocLinkPrefix %}}Request.SetDebugLogCurlCmd) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,118 @@ | ||
|
|
||
| # Retry Mechanism | ||
|
|
||
| The retry mechanism plays a crucial role in modern system integration by enabling effective handling of failures. | ||
|
|
||
| Resty provides exponential backoff with a jitter strategy out of the box; a custom retry strategy could be employed to override this default. | ||
|
|
||
| {{% hint info %}} | ||
| **Hint:** Combining the Retry strategy with [Circuit Breaker]({{% relref "circuit-breaker" %}}) typically provides a comprehensive approach to handling failures. | ||
| {{% /hint %}} | ||
|
|
||
|
|
||
| ## Default Values | ||
|
|
||
| * Retry count is `0` | ||
| * Total retry attempts = `first attempt + retry count` | ||
| * Retry minimum wait time is `100ms` | ||
| * Retry maximum wait time is `2000ms` | ||
| * Retry strategy is exponential backoff with a jitter | ||
|
|
||
|
|
||
| ## Default Behavior | ||
|
|
||
| * Respects header `Retry-After` if present | ||
| * Resets reader on retry request if the `io.ReadSeeker` interface is supported. | ||
| * Retries only on Idempotent HTTP Verb - GET, HEAD, PUT, DELETE, OPTIONS, and TRACE ([RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110.html#name-method-registration), [RFC 5789](https://datatracker.ietf.org/doc/html/rfc5789.html)) | ||
| * Use [Client.SetAllowNonIdempotentRetry]({{% param Resty.V3.GoDocLinkPrefix %}}Client.SetAllowNonIdempotentRetry) or [Request.SetAllowNonIdempotentRetry]({{% param Resty.V3.GoDocLinkPrefix %}}Request.SetAllowNonIdempotentRetry). If additional control is necessary, utilize the custom retry condition. | ||
| * Applies [default retry conditions]({{% relref "#default-conditions" %}}) | ||
| * It can be disabled via [Client.SetRetryDefaultConditions]({{% param Resty.V3.GoDocLinkPrefix %}}Client.SetRetryDefaultConditions) or [Request.SetRetryDefaultConditions]({{% param Resty.V3.GoDocLinkPrefix %}}Request.SetRetryDefaultConditions) | ||
|
|
||
|
|
||
| ## Default Conditions | ||
|
|
||
| * Condition gets applied in the following order | ||
| * No Retry | ||
| * TLS certificate verification error | ||
| * Too many redirects error | ||
| * Scheme error | ||
| * Invalid header error | ||
| * Response is nil | ||
| * Retry | ||
| * Status Code is 429 Too Many Requests | ||
| * Status Code is 500 or above (but not Status Code 501 Not Implemented) | ||
| * Status Code is 0 | ||
|
|
||
|
|
||
| ## Examples | ||
|
|
||
| ```go | ||
| // Retry configuration can be set at the client or request level | ||
| client. | ||
| SetRetryCount(3). | ||
| SetRetryWaitTime(2 * time.Second). | ||
| SetRetryMaxWaitTime(5 * time.Second) | ||
| ``` | ||
|
|
||
| ### Constant Delay | ||
|
|
||
| Use a custom retry strategy approach to perform constant/fixed delay. | ||
|
|
||
| ```go | ||
| // Retry configuration can be set at the client or request level | ||
| client. | ||
| SetRetryStrategy(func(_ *resty.Response, _ error) (time.Duration, error) { | ||
| return 3 * time.Second, nil | ||
| }) | ||
| ``` | ||
|
|
||
| ### Retry Hook | ||
|
|
||
| Utilize the retry hook(s) to perform logic between retries. | ||
|
|
||
| ```go | ||
| // Retry configuration can be set at the client or request level | ||
| client. | ||
| AddRetryHook(func(res *resty.Response, err error) { | ||
| // perform logic here | ||
| }) | ||
| ``` | ||
|
|
||
| ### Retry Conditions | ||
|
|
||
| ```go | ||
| // Retry configuration can be set at the client or request level | ||
| // NOTE: first default retry conditions get applied | ||
| // before user-defined retry conditions | ||
| client. | ||
| AddRetryCondition(func(res *resty.Response, err error) bool { | ||
| // perform logic here | ||
|
|
||
| // return true if retry is required otherwise, return false | ||
| return true | ||
| }) | ||
| ``` | ||
|
|
||
|
|
||
| ## Methods | ||
|
|
||
| ### Client | ||
|
|
||
| * [Client.SetRetryCount]({{% param Resty.V3.GoDocLinkPrefix %}}Client.SetRetryCount) | ||
| * [Client.SetRetryWaitTime]({{% param Resty.V3.GoDocLinkPrefix %}}Client.SetRetryWaitTime) | ||
| * [Client.SetRetryMaxWaitTime]({{% param Resty.V3.GoDocLinkPrefix %}}Client.SetRetryMaxWaitTime) | ||
| * [Client.SetRetryStrategy]({{% param Resty.V3.GoDocLinkPrefix %}}Client.SetRetryStrategy) | ||
| * [Client.SetRetryDefaultConditions]({{% param Resty.V3.GoDocLinkPrefix %}}Client.SetRetryDefaultConditions) | ||
| * [Client.AddRetryHook]({{% param Resty.V3.GoDocLinkPrefix %}}Client.AddRetryHook) | ||
| * [Client.AddRetryCondition]({{% param Resty.V3.GoDocLinkPrefix %}}Client.AddRetryCondition) | ||
|
|
||
|
|
||
| ### Request | ||
|
|
||
| * [Request.SetRetryCount]({{% param Resty.V3.GoDocLinkPrefix %}}Request.SetRetryCount) | ||
| * [Request.SetRetryWaitTime]({{% param Resty.V3.GoDocLinkPrefix %}}Request.SetRetryWaitTime) | ||
| * [Request.SetRetryMaxWaitTime]({{% param Resty.V3.GoDocLinkPrefix %}}Request.SetRetryMaxWaitTime) | ||
| * [Request.SetRetryStrategy]({{% param Resty.V3.GoDocLinkPrefix %}}Request.SetRetryStrategy) | ||
| * [Request.SetRetryDefaultConditions]({{% param Resty.V3.GoDocLinkPrefix %}}Request.SetRetryDefaultConditions) | ||
| * [Request.AddRetryHook]({{% param Resty.V3.GoDocLinkPrefix %}}Request.AddRetryHook) | ||
| * [Request.AddRetryCondition]({{% param Resty.V3.GoDocLinkPrefix %}}Request.AddRetryCondition) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters