Skip to main content

GoTry Documentation

Welcome to the official documentation for GoTry. This library provides a flexible and customizable way to manage retries and errors in Go applications.

Introduction​

GoTry simplifies retry logic in Go by providing a reusable, configurable, and fault-tolerant mechanism to handle transient failures, with optional backoff strategies and other enhancements.

Features​

  • Configurable retry logic: Customize retries with backoff strategies.
  • Jitter support: Adds randomness to avoid retry storms.
  • Adjustable multiplier: Define exponential growth for retries.
  • Simple API: Easy-to-use API for configuring retries.

Installation​

To install GoTry in your Go project, run:

go get github.com/PabloSanchi/gotry

Usage​

Here's an example of how to use GoTry to manage retries in your Go application:

package main

import (
	  "encoding/json"
	  "log"
	  "net/http"
	  "time"

	  retry "github.com/PabloSanchi/gotry"
)

const (
	  url = "https://official-joke-api.appspot.com/random_joke"
)

type Joke struct {
	  Type      string `json:"type"`
	  Setup     string `json:"setup"`
	  Punchline string `json:"punchline"`
	  Id        uint   `json:"id"`
}

func main() {
    resp, err := retry.Retry(
        func() (*http.Response, error) {
            return http.Get(url)
        },
        retry.WithRetries(2),
        retry.WithBackoff(2*time.Second),
        retry.WithExponentialBackoff(),
        retry.WithOnRetry(func(n uint, err error) {
                log.Printf("Retrying request after error: %v", err)
        }),
    )

    if err != nil {
        log.Fatalf("Request failed: %v", err)
    }
    defer resp.Body.Close()

    var joke Joke
    if err := json.NewDecoder(resp.Body).Decode(&joke); err != nil {
        log.Fatalf("Failed to decode response: %v", err)
    }

    log.Printf("Joke: %s", joke.Setup)
    log.Printf("Punchline: %s", joke.Punchline)
}

Parameters​

GoTry allows configuring various parameters for the retry logic:

  • Retries: Set the maximum number of retries.
  • Backoff: Choose between different backoff strategies (exponential, constant, etc.).
  • BackoffStrategies:
    • ExponentialBackoff: Increases the wait time exponentially between each retry.
    • LinearBackoff: Uses a multiplier to increase the wait time between retries. (backoff * multiplier) and multiplier is the retry attempt.
    • CustomBackoff: Implement your own backoff logic.
  • MaxJitter: Add randomness to the backoff to stagger the retries. (MaxJitter is the maximum value allowed to add to the backoff).
  • OnRetry: Callback function to execute on each retry.
  • RetryIf: Function to determine if a retry should be attempted based on the error.
  • Context: Context (provided or created) to control the retry loop.
type RetryConfig struct {
    retries         uint
    backoff         time.Duration
    backoffStrategy func(base time.Duration, n uint) time.Duration
    backoffLimit    time.Duration // maximum backoff time allowed
    maxJitter       time.Duration
    onRetry         OnRetryFunc
    retryIf         RetryIfFunc
    context         context.Context
}

Contribution​

We welcome contributions! To get started:

  1. Fork the repository
  2. Make your changes
  3. Submit a pull request.
note

Please ensure your changes are well-tested; No tested code will be reviewed nor accepted

License​

GoTry is licensed under the Apache License. See the LICENSE file for more details.

Contact​

For any questions or issues, feel free to open an issue in our GitHub repository.

Happy coding with GoTry! 🎉