avoca

README

Avoca

Description

Yet another HTTP client \o/

Installation

go get -u github.com/vthiery/avoca

Usage

package main

import (
	"context"
	"fmt"
	"net/http"
	"time"

	"github.com/vthiery/avoca"
	"github.com/vthiery/retry"
)

func main() {
	client := avoca.NewClient(
		avoca.WithHTTPClient(
			&http.Client{
				// Timeout the HTTP connection after 200 ms.
				Timeout: 200 * time.Millisecond,
			},
		),
		// Perform maximum 10 attempts with an exponential backoff.
		avoca.WithRetrier(
			retry.New(
				retry.WithMaxAttempts(10),
				retry.WithBackoff(
					retry.NewExponentialBackoff(
						100*time.Millisecond, // minWait
						1*time.Second,        // maxWait
						2*time.Millisecond,   // maxJitter
					),
				),
			),
		),
		// Only retry when the status code is >= 500
		avoca.WithRetryPolicy(
			func(statusCode int) bool {
				return statusCode >= http.StatusInternalServerError
			},
		),
	)

	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	res, err := client.Get(ctx, "http://google.com", nil)
	if err != nil {
		fmt.Printf("failed to GET: %v\n", err)
	}
	defer res.Body.Close()
}

Documentation

Index

• Variables
• type Client
  • func NewClient(opts ...Option) *Client
  • func (c *Client) Delete(ctx context.Context, url string, headers http.Header) (*http.Response, error)
  • func (c *Client) Do(req *http.Request) (*http.Response, error)
  • func (c *Client) Get(ctx context.Context, url string, headers http.Header) (*http.Response, error)
  • func (c *Client) Patch(ctx context.Context, url string, body io.Reader, headers http.Header) (*http.Response, error)
  • func (c *Client) Post(ctx context.Context, url string, body io.Reader, headers http.Header) (*http.Response, error)
  • func (c *Client) Put(ctx context.Context, url string, body io.Reader, headers http.Header) (*http.Response, error)
• type Doer
• type Option
  • func WithHTTPClient(client Doer) Option
  • func WithRetrier(retrier Retrier) Option
  • func WithRetryPolicy(retryPolicy RetryPolicy) Option
• type RequestCreationError
  • func (e *RequestCreationError) Error() string
• type Retrier
• type RetryPolicy

Variables

var ErrStatusCode = errors.New("status code internal error")

ErrStatusCode is used internally to be able to differentiate between an actual error from the underlying HTTP client and an error that is returned for to retry retryable HTTP codes (from policy).

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client composes a Doer and a Retrier. By default, the client uses:

• a http.Client with a timeout set to 60 * time.Second
• a retrier that does not retry
• a retry policy that return false for all HTTP codes

func NewClient

func NewClient(opts ...Option) *Client

NewClient returns a new instance of the Client.

func (*Client) Delete

func (c *Client) Delete(ctx context.Context, url string, headers http.Header) (*http.Response, error)

Delete makes a HTTP DELETE request to provided URL.

func (*Client) Do

func (c *Client) Do(req *http.Request) (*http.Response, error)

Do makes an HTTP request with the native `http.Do` interface.

func (*Client) Get

func (c *Client) Get(ctx context.Context, url string, headers http.Header) (*http.Response, error)

Get makes a HTTP GET request to provided URL.

func (*Client) Patch

func (c *Client) Patch(ctx context.Context, url string, body io.Reader, headers http.Header) (*http.Response, error)

Patch makes a HTTP PATCH request to provided URL.

func (*Client) Post

func (c *Client) Post(ctx context.Context, url string, body io.Reader, headers http.Header) (*http.Response, error)

Post makes a HTTP POST request to provided URL.

func (*Client) Put

func (c *Client) Put(ctx context.Context, url string, body io.Reader, headers http.Header) (*http.Response, error)

Put makes a HTTP PUT request to provided URL.

type Doer

type Doer interface {
	Do(*http.Request) (*http.Response, error)
}

Doer interface that match the standard HTTP client `http.Do` interface.

type Option

type Option func(*Client)

Option represents the client options.

func WithHTTPClient

func WithHTTPClient(client Doer) Option

WithHTTPClient sets a custom HTTP client.

func WithRetrier

func WithRetrier(retrier Retrier) Option

WithRetrier sets the strategy for retrying.

func WithRetryPolicy

func WithRetryPolicy(retryPolicy RetryPolicy) Option

WithRetryPolicy sets the retry policy.

type RequestCreationError

type RequestCreationError struct {
	Err error
}

RequestCreationError is used to signal the request creation failed.

func (*RequestCreationError) Error

func (e *RequestCreationError) Error() string

Error returns the error message.

type Retrier

type Retrier interface {
	Do(context.Context, func(context.Context) error) error
}

Retrier interface that allows to perform retries.

type RetryPolicy

type RetryPolicy func(statusCode int) bool

RetryPolicy describes the retry policy based on HTTP codes. It should return true for retryable HTTP code and false otherwise.