hx

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 14, 2019 License: MIT Imports: 14 Imported by: 3

README

hx

CI GoDoc codecov License

Developer-friendly, Production-ready and extensible HTTP client for Go

Features

...

Plugins
  • retry
  • pb - Marshaling and Unmarshaling protocol buffers

Examples

Simple GET
type Content struct {
	Body string `json:"body"`
}

var cont Content

ctx := context.Background()
err := hx.Get(ctx, "https://api.example.com/contents/1",
	hx.WhenSuccess(hx.AsJSON(&cont)),
	hx.WhenFailure(hx.AsError()),
)
Real-world
func init() {
	defaultTransport := hxutil.CloneTransport(http.DefaultTransport.(*http.Transport))

	// Tweak keep-alive configuration
	defaultTransport.MaxIdleConns = 500
	defaultTransport.MaxIdleConnsPerHost = 100

	// Set global options
	hx.DefaultOptions = append(
		hx.DefaultOptions,
		hx.UserAgent(fmt.Sprintf("yourapp (%s)", hx.DefaultUserAgent)),
		hx.Transport(defaultTransport),
		hx.TransportFrom(func(rt http.RoundTripper) http.RoundTripper {
			return &ochttp.Transport{Base: rt}
		}),
	)
}

func NewContentAPI() *hx.Client {
	// Set common options for API ciient
	return &ContentAPI{
		client: hx.NewClient(
			hx.BaseURL("https://api.example.com"),
		),
	}
}

type ContentAPI struct {
	client *hx.Client
}

func (a *ContentAPI) GetContent(ctx context.Context, id int) (*Content, error) {
	var cont Content

	err := a.client.Get(ctx, hx.Path("api", "contents", id),
		hx.WhenSuccess(hx.AsJSON(&cont)),
		hx.WhenFailure(hx.AsError()),
	)

	if err != nil {
		// ...
	}

	return &cont, nil
}

func (a *ContentAPI) CreateContent(ctx context.Context, in *Content) (*Content, error) {
	var out Content

	err := a.client.Post(ctx, "/api/contents",
		hx.JSON(in),
		hx.WhenSuccess(hx.AsJSON(&out)),
		hx.WhenStatus(hx.AsJSONError(&InvalidArgument{}), http.StatusBadRequest),
		hx.WhenFailure(hx.AsError()),
	)

	if err != nil {
		var (
			invalidArgErr *InvalidArgument
			respErr       *hx.ResponseError
		)
		if errors.As(err, &invalidArgErr) {
			// handle known error
		} else if errors.As(err, &respErr) {
			// handle unknown response error
		} else {
			err := errors.Unwrap(err)
			// handle unknown error
		}
	}

	return &out, nil
}

Documentation

Index

Examples

Constants

View Source 
const Version = "0.3.0"

Variables

View Source 
var (
	DefaultUserAgent = fmt.Sprintf("hx/%s; %s", Version, runtime.Version())
	DefaultOptions   = []Option{
		UserAgent(DefaultUserAgent),
	}
)

Functions

func Delete 

func Delete(ctx context.Context, url string, opts ...Option) error

func Get 

func Get(ctx context.Context, url string, opts ...Option) error
Example 
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/izumin5210/hx"
)

func main() {
	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		switch {
		case r.Method == http.MethodGet && r.URL.Path == "/echo":
			err := json.NewEncoder(w).Encode(map[string]string{
				"message": r.URL.Query().Get("message"),
			})
			if err != nil {
				w.WriteHeader(http.StatusInternalServerError)
				return
			}
		default:
			w.WriteHeader(http.StatusNotFound)
		}
	}))
	defer ts.Close()

	var out struct {
		Message string `json:"message"`
	}

	ctx := context.Background()
	err := hx.Get(
		ctx,
		ts.URL+"/echo",
		hx.Query("message", "It Works!"),
		hx.WhenSuccess(hx.AsJSON(&out)),
		hx.WhenFailure(hx.AsError()),
	)
	if err != nil {
		// Handle errors...
	}
	fmt.Println(out.Message)

}

Output:

It Works!

func Patch 

func Patch(ctx context.Context, url string, opts ...Option) error

func Path 

func Path(elem ...interface{}) string

func Post 

func Post(ctx context.Context, url string, opts ...Option) error

func Put 

func Put(ctx context.Context, url string, opts ...Option) error

Types

type Client 

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

func NewClient 

func NewClient(opts ...Option) *Client

NewClient creates a new http client instance.

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, url string, opts ...Option) error

func (*Client) Get 

func (c *Client) Get(ctx context.Context, url string, opts ...Option) error

func (*Client) Patch 

func (c *Client) Patch(ctx context.Context, url string, opts ...Option) error

func (*Client) Post 

func (c *Client) Post(ctx context.Context, url string, opts ...Option) error

func (*Client) Put 

func (c *Client) Put(ctx context.Context, url string, opts ...Option) error

func (*Client) With added in v0.2.0 

func (c *Client) With(opts ...Option) *Client

With clones the current client and applies the given options.

type Config 

type Config struct {
	URL              *url.URL
	Body             io.Reader
	HTTPClient       *http.Client
	QueryParams      url.Values
	RequestHandlers  []RequestHandler
	ResponseHandlers []ResponseHandler
}

func NewConfig added in v0.1.1 

func NewConfig() (*Config, error)

func (*Config) Apply 

func (cfg *Config) Apply(opts ...Option) error

func (*Config) DoRequest 

func (cfg *Config) DoRequest(ctx context.Context, meth string) (*http.Response, error)

type Option 

type Option interface {
	ApplyOption(*Config) error
}

func Authorization 

func Authorization(scheme, token string) Option

Authorization sets an authorization scheme and a token of an user.

func BaseURL 

func BaseURL(baseURL *url.URL) Option

func BasicAuth 

func BasicAuth(username, password string) Option

BasicAuth sets an username and a password for basic authentication.

func Bearer 

func Bearer(token string) Option

func Body 

func Body(v interface{}) Option

Body sets data to request body.

func CombineOptions 

func CombineOptions(opts ...Option) Option

func HTTPClient 

func HTTPClient(cli *http.Client) Option

HTTPClient sets a HTTP client that used to send HTTP request(s).

func HandleRequest added in v0.2.0 

func HandleRequest(f func(*http.Request) (*http.Request, error)) Option

func HandleResponse added in v0.2.0 

func HandleResponse(f func(*http.Response, error) (*http.Response, error)) Option
func Header(k, v string) Option

Header sets a value to request header.

func JSON 

func JSON(v interface{}) Option

JSON sets data to request body as json.

func Query 

func Query(k, v string) Option

Query sets an url query parameter.

func Timeout 

func Timeout(t time.Duration) Option

Timeout sets the max duration for http request(s).

func Transport 

func Transport(rt http.RoundTripper) Option

Transport sets the round tripper to http.Client.

func TransportFrom 

func TransportFrom(f func(http.RoundTripper) http.RoundTripper) Option

TransportFrom sets the round tripper to http.Client.

func TransportFunc added in v0.2.0 

func TransportFunc(f func(*http.Request, http.RoundTripper) (*http.Response, error)) Option

func URL 

func URL(urlStr string) Option

func UserAgent 

func UserAgent(ua string) Option

func When 

func When(cond ResponseHandlerCond, rh ResponseHandler) Option

func WhenClientError 

func WhenClientError(h ResponseHandler) Option

func WhenFailure 

func WhenFailure(h ResponseHandler) Option

func WhenServerError 

func WhenServerError(h ResponseHandler) Option

func WhenStatus 

func WhenStatus(h ResponseHandler, codes ...int) Option

func WhenSuccess 

func WhenSuccess(h ResponseHandler) Option

type OptionFunc 

type OptionFunc func(*Config) error

func (OptionFunc) ApplyOption added in v0.1.1 

func (f OptionFunc) ApplyOption(c *Config) error

type RequestHandler 

type RequestHandler func(*http.Request) (*http.Request, error)

type ResponseError 

type ResponseError struct {
	Response *http.Response
	Err      error
}

func (*ResponseError) Error 

func (e *ResponseError) Error() string

func (*ResponseError) Unwrap 

func (e *ResponseError) Unwrap() error

type ResponseHandler 

type ResponseHandler func(*http.Response, error) (*http.Response, error)

func AsError 

func AsError() ResponseHandler

func AsJSON 

func AsJSON(dst interface{}) ResponseHandler

func AsJSONError added in v0.2.0 

func AsJSONError(dst error) ResponseHandler

AsJSONError is ResponseHandler that will populate an error with the JSON returned within the response body. And it will wrap the error with ResponseError and return it. 

err := hx.Post(ctx, "https://example.com/posts",
	hx.JSON(body)
	hx.WhenSuccess(hx.AsJSON(&post), http.StatusBadRequest),
	hx.WhenStatus(hx.AsErrorOf(&InvalidArgument{}), http.StatusBadRequest),
	hx.WhenFailure(hx.AsError()),
)
if err != nil {
	var (
		invalidArgErr *InvalidArgument
		respErr       *hx.ResponseError
	)
	if errors.As(err, &invalidArgErr) {
		// handle known error
	} else if errors.As(err, &respErr) {
		// handle unknown response error
	} else {
		err := errors.Unwrap(err)
		// handle unknown error
	}
}

type ResponseHandlerCond 

type ResponseHandlerCond func(*http.Response, error) bool
var (
	IsSuccess        ResponseHandlerCond = checkStatus(func(c int) bool { return c/100 == 2 })
	IsFailure        ResponseHandlerCond = Not(IsSuccess)
	IsClientError    ResponseHandlerCond = checkStatus(func(c int) bool { return c/100 == 4 })
	IsServerError    ResponseHandlerCond = checkStatus(func(c int) bool { return c/100 == 5 })
	IsTemporaryError ResponseHandlerCond = func(r *http.Response, err error) bool {
		terr, ok := err.(interface{ Temporary() bool })
		return ok && terr.Temporary()
	}
)

func Any 

func Any(conds ...ResponseHandlerCond) ResponseHandlerCond

func IsStatus 

func IsStatus(codes ...int) ResponseHandlerCond

func Not 

func Not(cond ResponseHandlerCond) ResponseHandlerCond

Source Files

View all Source files

Directories

Path Synopsis
pb module
retry module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.