goreq

package module
v0.0.0-...-bcd34c9 Latest Latest
Warning

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

 Go to latest Published: Dec 4, 2017 License: MIT Imports: 19 Imported by: 0

README

Build Status GoDoc

GoReq

Simple and sane HTTP request library for Go language.

Table of Contents

Why GoReq?

Go has very nice native libraries that allows you to do lots of cool things. But sometimes those libraries are too low level, which means that to do a simple thing, like an HTTP Request, it takes some time. And if you want to do something as simple as adding a timeout to a request, you will end up writing several lines of code.

This is why we think GoReq is useful. Because you can do all your HTTP requests in a very simple and comprehensive way, while enabling you to do more advanced stuff by giving you access to the native API.

How do I install it?

go get github.com/franela/goreq

What can I do with it?

Making requests with different methods

GET
res, err := goreq.Request{ Uri: "http://www.google.com" }.Do()

GoReq default method is GET.

You can also set value to GET method easily

type Item struct {
        Limit int
        Skip int
        Fields string
}

item := Item {
        Limit: 3,
        Skip: 5,
        Fields: "Value",
}

res, err := goreq.Request{
        Uri: "http://localhost:3000/",
        QueryString: item,
}.Do()

The sample above will send http://localhost:3000/?limit=3&skip=5&fields=Value

Alternatively the url tag can be used in struct fields to customize encoding properties

type Item struct {
        TheLimit int `url:"the_limit"`
        TheSkip string `url:"the_skip,omitempty"`
        TheFields string `url:"-"`
}

item := Item {
        TheLimit: 3,
        TheSkip: "",
        TheFields: "Value",
}

res, err := goreq.Request{
        Uri: "http://localhost:3000/",
        QueryString: item,
}.Do()

The sample above will send http://localhost:3000/?the_limit=3

QueryString also support url.Values

item := url.Values{}
item.Set("Limit", 3)
item.Add("Field", "somefield")
item.Add("Field", "someotherfield")

res, err := goreq.Request{
        Uri: "http://localhost:3000/",
        QueryString: item,
}.Do()

The sample above will send http://localhost:3000/?limit=3&field=somefield&field=someotherfield

Tags

Struct field url tag is mainly used as the request parameter name. Tags can be comma separated multiple values, 1st value is for naming and rest has special meanings.

  • special tag for 1st value

    • -: value is ignored if set this

  • special tag for rest 2nd value

    • omitempty: zero-value is ignored if set this
    • squash: the fields of embedded struct is used for parameter
Tag Examples
type Place struct {
    Country string `url:"country"`
    City    string `url:"city"`
    ZipCode string `url:"zipcode,omitempty"`
}

type Person struct {
    Place `url:",squash"`

    FirstName string `url:"first_name"`
    LastName  string `url:"last_name"`
    Age       string `url:"age,omitempty"`
    Password  string `url:"-"`
}

johnbull := Person{
	Place: Place{ // squash the embedded struct value
		Country: "UK",
		City:    "London",
		ZipCode: "SW1",
	},
	FirstName: "John",
	LastName:  "Doe",
	Age:       "35",
	Password:  "my-secret", // ignored for parameter
}

goreq.Request{
	Uri:         "http://localhost/",
	QueryString: johnbull,
}.Do()
// =>  `http://localhost/?first_name=John&last_name=Doe&age=35&country=UK&city=London&zip_code=SW1`


// age and zipcode will be ignored because of `omitempty`
// but firstname isn't.
samurai := Person{
	Place: Place{ // squash the embedded struct value
		Country: "Japan",
		City:    "Tokyo",
	},
	LastName: "Yagyu",
}

goreq.Request{
	Uri:         "http://localhost/",
	QueryString: samurai,
}.Do()
// =>  `http://localhost/?first_name=&last_name=yagyu&country=Japan&city=Tokyo`
POST
res, err := goreq.Request{ Method: "POST", Uri: "http://www.google.com" }.Do()

Sending payloads in the Body

You can send string, Reader or interface{} in the body. The first two will be sent as text. The last one will be marshalled to JSON, if possible.

type Item struct {
    Id int
    Name string
}

item := Item{ Id: 1111, Name: "foobar" }

res, err := goreq.Request{
    Method: "POST",
    Uri: "http://www.google.com",
    Body: item,
}.Do()

Specifiying request headers

We think that most of the times the request headers that you use are: Host, Content-Type, Accept and User-Agent. This is why we decided to make it very easy to set these headers.

res, err := goreq.Request{
    Uri: "http://www.google.com",
    Host: "foobar.com",
    Accept: "application/json",
    ContentType: "application/json",
    UserAgent: "goreq",
}.Do()

But sometimes you need to set other headers. You can still do it.

req := goreq.Request{ Uri: "http://www.google.com" }

req.AddHeader("X-Custom", "somevalue")

req.Do()

Alternatively you can use the WithHeader function to keep the syntax short

res, err = goreq.Request{ Uri: "http://www.google.com" }.WithHeader("X-Custom", "somevalue").Do()

Cookies can be either set at the request level by sending a CookieJar in the CookieJar request field or you can use goreq's one-liner WithCookie method as shown below

res, err := goreq.Request{
    Uri: "http://www.google.com",
}.
WithCookie(&http.Cookie{Name: "c1", Value: "v1"}).
Do()

Setting timeouts

GoReq supports 2 kind of timeouts. A general connection timeout and a request specific one. By default the connection timeout is of 1 second. There is no default for request timeout, which means it will wait forever.

You can change the connection timeout doing:

goreq.SetConnectTimeout(100 * time.Millisecond)

And specify the request timeout doing:

res, err := goreq.Request{
    Uri: "http://www.google.com",
    Timeout: 500 * time.Millisecond,
}.Do()

Using the Response and Error

GoReq will always return 2 values: a Response and an Error. If Error is not nil it means that an error happened while doing the request and you shouldn't use the Response in any way. You can check what happened by getting the error message:

fmt.Println(err.Error())

And to make it easy to know if it was a timeout error, you can ask the error or return it:

if serr, ok := err.(*goreq.Error); ok {
    if serr.Timeout() {
        ...
    }
}
return err

If you don't get an error, you can safely use the Response.

res.Uri // return final URL location of the response (fulfilled after redirect was made)
res.StatusCode // return the status code of the response
res.Body // gives you access to the body
res.Body.ToString() // will return the body as a string
res.Header.Get("Content-Type") // gives you access to all the response headers

Remember that you should always close res.Body if it's not nil

Receiving JSON

GoReq will help you to receive and unmarshal JSON.

type Item struct {
    Id int
    Name string
}

var item Item

res.Body.FromJsonTo(&item)

Sending/Receiving Compressed Payloads

GoReq supports gzip, deflate and zlib compression of requests' body and transparent decompression of responses provided they have a correct Content-Encoding header.

Using gzip compression:
res, err := goreq.Request{
    Method: "POST",
    Uri: "http://www.google.com",
    Body: item,
    Compression: goreq.Gzip(),
}.Do()
Using deflate/zlib compression:
res, err := goreq.Request{
    Method: "POST",
    Uri: "http://www.google.com",
    Body: item,
    Compression: goreq.Deflate(),
}.Do()
Using compressed responses:

If servers replies a correct and matching Content-Encoding header (gzip requires Content-Encoding: gzip and deflate Content-Encoding: deflate) goreq transparently decompresses the response so the previous example should always work:

type Item struct {
    Id int
    Name string
}
res, err := goreq.Request{
    Method: "POST",
    Uri: "http://www.google.com",
    Body: item,
    Compression: goreq.Gzip(),
}.Do()
var item Item
res.Body.FromJsonTo(&item)

If no Content-Encoding header is replied by the server GoReq will return the crude response.

Proxy

If you need to use a proxy for your requests GoReq supports the standard http_proxy env variable as well as manually setting the proxy for each request

res, err := goreq.Request{
    Method: "GET",
    Proxy: "http://myproxy:myproxyport",
    Uri: "http://www.google.com",
}.Do()
Proxy basic auth is also supported
res, err := goreq.Request{
    Method: "GET",
    Proxy: "http://user:pass@myproxy:myproxyport",
    Uri: "http://www.google.com",
}.Do()

Debug

If you need to debug your http requests, it can print the http request detail.

res, err := goreq.Request{
	Method:      "GET",
	Uri:         "http://www.google.com",
	Compression: goreq.Gzip(),
	ShowDebug:   true,
}.Do()
fmt.Println(res, err)

and it will print the log:

GET / HTTP/1.1
Host: www.google.com
Accept:
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type:
Getting raw Request & Response

To get the Request:

req := goreq.Request{
        Host: "foobar.com",
}

//req.Request will return a new instance of an http.Request so you can safely use it for something else
request, _ := req.NewRequest()

To get the Response:

res, err := goreq.Request{
	Method:      "GET",
	Uri:         "http://www.google.com",
	Compression: goreq.Gzip(),
	ShowDebug:   true,
}.Do()

// res.Response will contain the original http.Response structure 
fmt.Println(res.Response, err)

TODO:

We do have a couple of issues pending we'll be addressing soon. But feel free to contribute and send us PRs (with tests please 😄).

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var DefaultClient = &http.Client{Transport: DefaultTransport}
View Source 
var DefaultDialer = &net.Dialer{Timeout: 1000 * time.Millisecond}
View Source 
var DefaultTransport http.RoundTripper = &http.Transport{Dial: DefaultDialer.Dial, Proxy: http.ProxyFromEnvironment}

Functions

func Deflate 

func Deflate() *compression

func Gzip 

func Gzip() *compression

func SetConnectTimeout 

func SetConnectTimeout(duration time.Duration)

func Zlib 

func Zlib() *compression

Types

type Body 

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

func (*Body) Close 

func (b *Body) Close() error

func (*Body) FromJsonTo 

func (b *Body) FromJsonTo(o interface{}) error

func (*Body) Read 

func (b *Body) Read(p []byte) (int, error)

func (*Body) ToString 

func (b *Body) ToString() (string, error)

type Error 

type Error struct {
	Err error
	// contains filtered or unexported fields
}

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Timeout 

func (e *Error) Timeout() bool

type Request 

type Request struct {
	Method          string
	Uri             string
	Body            interface{}
	QueryString     interface{}
	Timeout         time.Duration
	ContentType     string
	Accept          string
	Host            string
	UserAgent       string
	Insecure        bool
	MaxRedirects    int
	RedirectHeaders bool
	Proxy           string

	Compression       *compression
	BasicAuthUsername string
	BasicAuthPassword string
	CookieJar         http.CookieJar
	ShowDebug         bool
	OnBeforeRequest   func(goreq *Request, httpreq *http.Request)
	// contains filtered or unexported fields
}

func (*Request) AddCookie 

func (r *Request) AddCookie(c *http.Cookie)

func (*Request) AddHeader 

func (r *Request) AddHeader(name string, value string)

func (*Request) AddProxyConnectHeader 

func (r *Request) AddProxyConnectHeader(name string, value string)

func (Request) Do 

func (r Request) Do() (*Response, error)

func (Request) NewRequest 

func (r Request) NewRequest() (*http.Request, error)

func (Request) WithCookie 

func (r Request) WithCookie(c *http.Cookie) Request

func (Request) WithHeader 

func (r Request) WithHeader(name string, value string) Request

func (Request) WithProxyConnectHeader 

func (r Request) WithProxyConnectHeader(name string, value string) Request

type Response 

type Response struct {
	*http.Response
	Uri  string
	Body *Body
	// contains filtered or unexported fields
}

func (Response) CancelRequest 

func (r Response) CancelRequest()

Source Files

View all Source files

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.