httpclient

package module
v0.4.1 Latest Latest
Warning

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

 Go to latest Published: Jan 7, 2015 License: MIT Imports: 15 Imported by: 0

README

go-httpclient Build Status

Advanced HTTP client for golang.

Features

  • Chainable API
  • Direct file upload
  • Timeout
  • Proxy(HTTP, SOCKS5, SOCKS4, SOCKS4A)
  • Cookie
  • GZIP
  • Redirect Policy

Installation

go get github.com/ddliu/go-httpclient

Usage

Initialize

Use NewHttpClient to create a client with some options and headers.

package main

import (
    "github.com/ddliu/go-httpclient"
)

var c := httpclient.NewHttpClient(httpclient.Map {
    httpclient.OPT_USERAGENT: "my awsome httpclient",
    "Accept-Language": "en-us",
})

The OPT_XXX options define basic behaviours of this client, other values are default request headers of this request. They are shared between different HTTP requests.

It's also possible to use the client without explicitly create it.

package main

import (
    "github.com/ddliu/go-httpclient"
)

httpclient.Get("http://google.com", nil)
GET/POST

In most cases you just need the Get and Post method after initializing:

func (this *HttpClient) Get(url string, params map[string]string) (*httpclient.Response, error)

func (this *HttpClient) Post(url string, params map[string]string) (*httpclient.Response, error)

    res, err := c.Get("http://google.com/search", map[string]string{
        "q": "news",
    })

    fmt.Println(res.StatusCode, err)

    // post file
    res, err := c.Post("http://dropbox.com/upload", map[string]string {
        "@file": "/tmp/hello.pdf",
    })

    fmt.Println(res, err)
Customize Request

Before you start a new HTTP request with Get or Post method, you can specify options, headers or cookies.

c.
    WithHeader("User-Agent", "Super Robot").
    WithHeader("custom-header", "value").
    WithHeaders(map[string]string {
        "another-header": "another-value",
        "and-another-header": "another-value",
    }).
    WithOption(httpclent.OPT_TIMEOUT, 60).
    WithCookie(&http.Cookie{
        Name: "uid",
        Value: "123",
    }).
    Get("http://github.com", nil)
Response

The httpclient.Response is a thin wrap of http.Response.

// traditional
res, err := c.Get("http://google.com", nil)
bodyBytes, err := ioutil.ReadAll(res.Body)
res.Body.Close()

// ToString
res, err = c.Get("http://google.com", nil)
bodyString := res.ToString()

// ReadAll
res, err = c.Get("http://google.com", nil)
bodyBytes := res.ReadAll()
Handle Cookies
url := "http://github.com"
c.
    WithCookie(&http.Cookie{
        Name: "uid",
        Value: "123",
    }).
    Get(url, nil)

for _, cookie := range c.Cookies() {
    fmt.Println(cookie.Name, cookie.Value)
}

for k, v := range c.CookieValues() {
    fmt.Println(k, v)
}

fmt.Println(c.CookieValue("uid"))
Concurrent Safe

If you've created one client and want to start many requests concurrently, remember to call the Begin method when you begin:

c := httpclient.NewHttpClient(nil)

go func() {
    c.
        Begin().
        WithHeader("Req-A", "a").
        Get("http://google.com")
}()
go func() {
    c.
        Begin().
        WithHeader("Req-B", "b").
        Get("http://google.com")
}()
Error Checking

You can use httpclient.IsTimeoutError to check for timeout error:

res, err := c.Get("http://google.com", nil)
if httpclient.IsTimeoutError(err) {
    // do something
}
Full Example

See examples/main.go

Options

Available options as below:

  • OPT_FOLLOWLOCATION: TRUE to follow any "Location: " header that the server sends as part of the HTTP header. Default to true.
  • OPT_CONNECTTIMEOUT: The number of seconds to wait while trying to connect. Use 0 to wait indefinitely.
  • OPT_CONNECTTIMEOUT_MS: The number of milliseconds to wait while trying to connect. Use 0 to wait indefinitely.
  • OPT_MAXREDIRS: The maximum amount of HTTP redirections to follow. Use this option alongside OPT_FOLLOWLOCATION.
  • OPT_PROXYTYPE: Specify the proxy type. Valid options are PROXY_HTTP, PROXY_SOCKS4, PROXY_SOCKS5, PROXY_SOCKS4A. Only PROXY_HTTP is supported currently.
  • OPT_TIMEOUT: The maximum number of seconds to allow httpclient functions to execute.
  • OPT_TIMEOUT_MS: The maximum number of milliseconds to allow httpclient functions to execute.
  • OPT_COOKIEJAR: Set to true to enable the default cookiejar, or you can set to a http.CookieJar instance to use a customized jar. Default to true.
  • OPT_INTERFACE: TODO
  • OPT_PROXY: Proxy host and port(127.0.0.1:1080).
  • OPT_REFERER: The Referer header of the request.
  • OPT_USERAGENT: The User-Agent header of the request. Default to "go-httpclient v{{VERSION}}".
  • OPT_REDIRECT_POLICY: Function to check redirect.
  • OPT_PROXY_FUNC: Function to specify proxy.

API

See godoc.

TODO

  • Socks proxy support

Changelog

v0.4.1 (2015-01-07)

Add default client for convience.

v0.4.0 (2014-09-29)

Fix gzip.

Improve constructor: support both default options and headers.

v0.3.3 (2014-05-25)

Pass through useragent during redirects.

Support error checking.

v0.3.2 (2014-05-21)

Fix cookie, add cookie retrieving methods

v0.3.1 (2014-05-20)

Add shortcut for response

v0.3.0 (2014-05-20)

API improvements

Cookie support

Concurrent safe

v0.2.1 (2014-05-18)

Make http.Client reusable

v0.2.0 (2014-02-17)

Rewrite API, make it simple

v0.1.0 (2014-02-14)

Initial release

Documentation

Overview

Powerful and easy to use http client

Powerful and easy to use http client

Index

Constants

View Source 
const (
	ERR_DEFAULT
	ERR_TIMEOUT
	ERR_REDIRECT_POLICY
)

Package errors

View Source 
const (
	VERSION   = "0.4.1"
	USERAGENT = "go-httpclient v" + VERSION

	PROXY_HTTP    = 0
	PROXY_SOCKS4  = 4
	PROXY_SOCKS5  = 5
	PROXY_SOCKS4A = 6

	// CURL like OPT
	OPT_AUTOREFERER       = 58
	OPT_FOLLOWLOCATION    = 52
	OPT_CONNECTTIMEOUT    = 78
	OPT_CONNECTTIMEOUT_MS = 156
	OPT_MAXREDIRS         = 68
	OPT_PROXYTYPE         = 101
	OPT_TIMEOUT           = 13
	OPT_TIMEOUT_MS        = 155
	OPT_COOKIEJAR         = 10082
	OPT_INTERFACE         = 10062
	OPT_PROXY             = 10004
	OPT_REFERER           = 10016
	OPT_USERAGENT         = 10018

	// Other OPT
	OPT_REDIRECT_POLICY = 100000
	OPT_PROXY_FUNC      = 100001
)

Constants definations CURL options, see https://github.com/bagder/curl/blob/169fedbdce93ecf14befb6e0e1ce6a2d480252a3/packages/OS400/curl.inc.in

Variables

View Source 
var Begin func() *HttpClient
View Source 
var CONST = map[string]int{
	"OPT_AUTOREFERER":       58,
	"OPT_FOLLOWLOCATION":    52,
	"OPT_CONNECTTIMEOUT":    78,
	"OPT_CONNECTTIMEOUT_MS": 156,
	"OPT_MAXREDIRS":         68,
	"OPT_PROXYTYPE":         101,
	"OPT_TIMEOUT":           13,
	"OPT_TIMEOUT_MS":        155,
	"OPT_COOKIEJAR":         10082,
	"OPT_INTERFACE":         10062,
	"OPT_PROXY":             10004,
	"OPT_REFERER":           10016,
	"OPT_USERAGENT":         10018,

	"OPT_REDIRECT_POLICY": 100000,
	"OPT_PROXY_FUNC":      100001,
}

String map of options

View Source 
var CookieValue func(string, string) string
View Source 
var CookieValues func(string) map[string]string
View Source 
var Cookies func(string) []*http.Cookie
View Source 
var Do func(string, string, map[string]string, io.Reader) (*Response, error)
View Source 
var Get func(string, map[string]string) (*Response, error)
View Source 
var Post func(string, map[string]string) (*Response, error)
View Source 
var PostMultipart func(string, map[string]string) (*Response, error)
View Source 
var WithCookie func(...*http.Cookie) *HttpClient
View Source 
var WithHeader func(string, string) *HttpClient
View Source 
var WithHeaders func(map[string]string) *HttpClient
View Source 
var WithOption func(int, interface{}) *HttpClient
View Source 
var WithOptions func(Map) *HttpClient

Functions

func IsRedirectError added in v0.3.3 

func IsRedirectError(err error) bool

Check a redirect error

func IsTimeoutError added in v0.3.3 

func IsTimeoutError(err error) bool

Check a timeout error.

func Option 

func Option(o map[string]interface{}) map[int]interface{}

Convert options with string keys to desired format.

Types

type Error added in v0.3.3 

type Error struct {
	Code    int
	Message string
}

Custom error

func (Error) Error added in v0.3.3 

func (this Error) Error() string

Implement the error interface

type HttpClient 

type HttpClient struct {
	// Default options of this client.
	Options map[int]interface{}

	// Default headers of this client.
	Headers map[string]string
	// contains filtered or unexported fields
}

Powerful and easy to use HTTP client.

func NewHttpClient 

func NewHttpClient(defaults Map) *HttpClient

Create an HTTP client.

Specify default options and headers of this client.

func (*HttpClient) Begin added in v0.3.0 

func (this *HttpClient) Begin() *HttpClient

Begin marks the begining of a request, it's necessary for concurrent requests.

func (*HttpClient) CookieValue added in v0.3.2 

func (this *HttpClient) CookieValue(url_ string, key string) string

Get cookie value of a specified cookie name.

func (*HttpClient) CookieValues added in v0.3.2 

func (this *HttpClient) CookieValues(url_ string) map[string]string

Get cookie values(k-v map) of the client jar.

func (*HttpClient) Cookies added in v0.3.2 

func (this *HttpClient) Cookies(url_ string) []*http.Cookie

Get cookies of the client jar.

func (*HttpClient) Do added in v0.2.1 

func (this *HttpClient) Do(method string, url string, headers map[string]string,
	body io.Reader) (*Response, error)

Start a request, and get the response.

Usually we just need the Get and Post method.

func (*HttpClient) Get 

func (this *HttpClient) Get(url string, params map[string]string) (*Response,
	error)

The GET request

func (*HttpClient) Post 

func (this *HttpClient) Post(url string, params map[string]string) (*Response,
	error)

The POST request

With multipart set to true, the request will be encoded as "multipart/form-data".

If any of the params key starts with "@", it is considered as a form file (similar to CURL but different).

func (*HttpClient) PostMultipart added in v0.2.1 

func (this *HttpClient) PostMultipart(url string, params map[string]string) (
	*Response, error)

Post with the request encoded as "multipart/form-data".

func (*HttpClient) WithCookie added in v0.3.0 

func (this *HttpClient) WithCookie(cookies ...*http.Cookie) *HttpClient

Specify cookies of the current request.

func (*HttpClient) WithHeader added in v0.2.1 

func (this *HttpClient) WithHeader(k string, v string) *HttpClient

Specify a header of the current request.

func (*HttpClient) WithHeaders added in v0.2.1 

func (this *HttpClient) WithHeaders(m map[string]string) *HttpClient

Specify multiple headers of the current request.

func (*HttpClient) WithOption added in v0.2.1 

func (this *HttpClient) WithOption(k int, v interface{}) *HttpClient

Specify an option of the current request.

func (*HttpClient) WithOptions added in v0.2.1 

func (this *HttpClient) WithOptions(m Map) *HttpClient

Specify multiple options of the current request.

type Map added in v0.4.0 

type Map map[interface{}]interface{}

Map is a mixed structure with options and headers

type Response added in v0.3.1 

type Response struct {
	*http.Response
}

Thin wrapper of http.Response(can also be used as http.Response).

func (*Response) ReadAll added in v0.3.1 

func (this *Response) ReadAll() ([]byte, error)

Read response body into a byte slice.

func (*Response) ToString added in v0.3.1 

func (this *Response) ToString() (string, error)

Read response body into string.

Source Files

View all Source files

Directories

Path Synopsis

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.