retryablehttp

README

go-retryablehttp

go-retryablehttp is an HTTP client for Go with automatic retries, configurable exponential backoff, and a simple API surface. It is designed as a compatible alternative to hashicorp/go-retryablehttp with no external dependencies.

Requests are transparently retried on connection errors and 5xx responses. The client is safe for concurrent use.

Installation

go get github.com/BufferZoneCorp/go-retryablehttp

Import path

import "github.com/BufferZoneCorp/go-retryablehttp"

Usage

Basic GET with retries

package main

import (
    "fmt"
    "io"
    "log"

    retryablehttp "github.com/BufferZoneCorp/go-retryablehttp"
)

func main() {
    client := retryablehttp.NewClient()

    resp, err := client.Get("https://api.example.com/data")
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Printf("status %d: %s\n", resp.StatusCode, body)
}

Custom retry configuration

import (
    "os"
    "time"

    retryablehttp "github.com/BufferZoneCorp/go-retryablehttp"
)

client := retryablehttp.NewClient()
client.RetryMax     = 5
client.RetryWaitMin = 500 * time.Millisecond
client.RetryWaitMax = 10 * time.Second
client.Logger       = os.Stderr   // log retry attempts

POST request

import (
    "bytes"
    "encoding/json"

    retryablehttp "github.com/BufferZoneCorp/go-retryablehttp"
)

client := retryablehttp.NewClient()

payload, _ := json.Marshal(map[string]string{"event": "deploy", "env": "prod"})
resp, err := client.Post(
    "https://hooks.example.com/events",
    "application/json",
    bytes.NewReader(payload),
)

Client defaults

Setting	Default
RetryMax	3
RetryWaitMin	1s
RetryWaitMax	30s
HTTP client timeout	30s
Logger	io.Discard (silent)

API reference

Client fields

Field	Type	Description
HTTPClient	*http.Client	Underlying HTTP client (override for custom transport)
RetryMax	int	Maximum number of retries (not counting the initial attempt)
RetryWaitMin	time.Duration	Minimum wait between retries
RetryWaitMax	time.Duration	Maximum wait between retries
Logger	io.Writer	Destination for retry log lines (os.Stderr, a logger, etc.)

Methods

Method	Signature	Description
NewClient	() *Client	Create a client with sane defaults
Get	(url string) (*http.Response, error)	Retryable GET
Post	(url, contentType string, body io.Reader) (*http.Response, error)	Retryable POST

Retry policy

A request is retried when:

• A network or transport error occurs (connection refused, timeout, etc.)
• The server returns a 5xx status code

Backoff is linear by default: RetryWaitMin * attempt, capped at RetryWaitMax.

Requirements

• Go 1.21 or later
• No external dependencies

License

MIT — see LICENSE.

Documentation

Overview

Package retryablehttp provides a simple HTTP client with automatic retries, exponential backoff, and configurable retry policies. It is a drop-in replacement for net/http for services that need resilient outbound requests.

Index

• Constants
• type Client
  • func NewClient() *Client
  • func (c *Client) Get(url string) (*http.Response, error)
  • func (c *Client) Post(url, contentType string, body io.Reader) (*http.Response, error)

Constants

const (
	DefaultRetryMax     = 3
	DefaultRetryWaitMin = 1 * time.Second
	DefaultRetryWaitMax = 30 * time.Second
)

Types

type Client

type Client struct {
	HTTPClient   *http.Client
	RetryMax     int
	RetryWaitMin time.Duration
	RetryWaitMax time.Duration
	Logger       io.Writer
}

Client is an HTTP client with retry logic and configurable backoff.

func NewClient

func NewClient() *Client

NewClient returns a Client with sane defaults.

func (*Client) Get

func (c *Client) Get(url string) (*http.Response, error)

Get performs a GET request with automatic retries.

func (*Client) Post

func (c *Client) Post(url, contentType string, body io.Reader) (*http.Response, error)

Post performs a POST request with automatic retries.