gofast

README

Gofast

⚡️ Gofast is a HTTP client based on fasthttp with zero memory allocation.

Automatic struct binding let you focus on entity writing.

Install

go get -u github.com/wshops/gofast

Quick Start

package main

import (
	"fmt"
	"log"

	"github.com/wshops/gofast"
)

type Out struct {
	Hello string `json:"hello"`
}

func main() {
	fast := gofast.New()

	var out Out
	uri := "http://echo.jsontest.com/hello/world"
	err, code := fast.Get(uri, &out, nil)
	if err != nil {
		log.Fatalln(err)
	}
	if code == 200 {
		fmt.Printf("hello %v", out.Hello)
    }
	// hello world
}

Examples

Send request with body

The default encoding is JSON with application/json header.

You can also use map to bind value, but the worse performance you will get.

type CreateToken struct {
    ID     string `json:"id"`
    Secret string `json:"secret"`
}

type Token struct {
    Token     string `json:"token"`
    ExpiredAt string `json:"expired_at"`
}

fast := gofast.New()

uri := "https://example.com/api/v1/token"
body := CreateToken{
    ID:     "my-id",
    Secret: "my-secret",
}
var token Token
err, code := fast.Post(uri, &body, &token, nil)
if err != nil {
    log.Fatalln(err)
}
if code != 200 {
	fmt.Printf("token: %v, expired_at: %v", token.Token, token.ExpiredAt)
}

Get with header

type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

fast := gofast.New()

var user User
uri := "https://example.com/api/v1/users/100"
h := gofast.Header{fasthttp.HeaderAuthorization: "Bearer My-JWT"}
if err,_ := fast.Get(uri, &user, h); err != nil {
    log.Fatalln(err)
}
fmt.Printf("id: %v, name: %v", user.ID, user.Name)

URL encode

Post body with application/x-www-form-urlencoded header and get text.

fast := gofast.New(gofast.Config{
    RequestEncoder:  gofast.URLEncoder,
    ResponseDecoder: gofast.TextDecoder,
})

uri := "https://example.com/api/v1/token"
body := gofast.Body{
    "id":     "my-id",
    "secret": "my-secret",
}
var token string
if err,_ := fast.Post(uri, body, &token, nil); err != nil {
    log.Fatalln(err)
}

Customize error handler (deprecated)

Error handler will handle non 2xx HTTP status code.

cfg := gofast.Config{
    ErrorHandler: func(resp *fasthttp.Response) error {
        return fmt.Errorf("http code = %d", resp.StatusCode())
    },
}

fast := gofast.New(cfg)
err := fast.Get(uri, nil, nil)
// http code = 400

Benchmarks

$ go test -bench=. -benchmem -benchtime=10s -run=none -cpu 10
BenchmarkPostJSON-10         	 8168836	      1440 ns/op	       0 B/op	       0 allocs/op
BenchmarkPostURLEncode-10    	 8357803	      1443 ns/op	       0 B/op	       0 allocs/op
PASS
ok  	github.com/wshops/gofast	26.770s

Documentation

Index

• Variables
• type Client
  • func New(config ...Config) *Client
  • func (c *Client) Delete(uri string, in, out any, header Header) (error, int)
  • func (c *Client) Get(uri string, out any, header Header) (error, int)
  • func (c *Client) Patch(uri string, in, out any, header Header) (error, int)
  • func (c *Client) Post(uri string, in, out any, header Header) (error, int)
  • func (c *Client) PostForm(uri string, in map[string]string, out any, header Header) (error, int)
  • func (c *Client) Put(uri string, in, out any, header Header) (error, int)
• type Config
• type ErrorHandler
• type Header
• type RequestEncoder
• type ResponseDecoder

Variables

var ConfigDefault = Config{
	Name:                     "wshops",
	NoDefaultUserAgentHeader: false,
	ReadTimeout:              6 * time.Second,
	WriteTimeout:             6 * time.Second,
	RequestEncoder:           JSONEncoder,
	ResponseDecoder:          JSONDecoder,
	ErrorHandler:             defaultErrorHandler,
}

ConfigDefault is the default config

var JSONDecoder = func(resp *fasthttp.Response, out any) error {
	if err := json.Unmarshal(resp.Body(), out); err != nil {

		return err
	}
	return nil
}

var JSONEncoder = func(req *fasthttp.Request, in any) error {
	req.Header.SetContentType("application/json")
	return json.NewEncoder(req.BodyWriter()).Encode(in)
}

var TextDecoder = func(resp *fasthttp.Response, out any) error {
	s := out.(*string)
	*s = string(resp.Body())
	return nil
}

var URLEncoder = func(req *fasthttp.Request, in any) error {
	args := fasthttp.AcquireArgs()
	defer fasthttp.ReleaseArgs(args)

	for k, v := range in.(map[string]string) {
		args.Set(k, v)
	}
	if _, err := args.WriteTo(req.BodyWriter()); err != nil {
		return err
	}
	req.Header.SetContentType("application/x-www-form-urlencoded")
	return nil
}

Types

type Client

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

func New

func New(config ...Config) *Client

func (*Client) Delete

func (c *Client) Delete(uri string, in, out any, header Header) (error, int)

func (*Client) Get

func (c *Client) Get(uri string, out any, header Header) (error, int)

func (*Client) Patch

func (c *Client) Patch(uri string, in, out any, header Header) (error, int)

func (*Client) Post

func (c *Client) Post(uri string, in, out any, header Header) (error, int)

func (*Client) PostForm

func (c *Client) PostForm(uri string, in map[string]string, out any, header Header) (error, int)

func (*Client) Put

func (c *Client) Put(uri string, in, out any, header Header) (error, int)

type Config

type Config struct {
	// fasthttp client configurations
	Name                     string
	NoDefaultUserAgentHeader bool
	ReadTimeout              time.Duration
	WriteTimeout             time.Duration

	// RequestEncoder encode request before send
	RequestEncoder RequestEncoder

	// ResponseDecoder decode response after send
	ResponseDecoder ResponseDecoder

	// ErrorHandler handle the status code without 2xx
	ErrorHandler ErrorHandler
}

type ErrorHandler

type ErrorHandler func(resp *fasthttp.Response) error

type Header

type Header map[string]string

type RequestEncoder

type RequestEncoder func(req *fasthttp.Request, in any) error

type ResponseDecoder

type ResponseDecoder func(resp *fasthttp.Response, out any) error