package module
v0.0.0-...-a913b2c Latest Latest

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

Go to latest
Published: Sep 13, 2020 License: MIT Imports: 20 Imported by: 7



Advanced HTTP client for golang.


  • Chainable API
  • Direct file upload
  • Timeout
  • SOCKS5 Proxy
  • Cookie
  • GZIP
  • Redirect Policy
  • Cancel(with context)


go get
Original code from this, i'm add some features, like SOCKS5 proxy

Quick Start

package main

import (

func main() {
    httpclient.Defaults(httpclient.Map {
        httpclient.OPT_USERAGENT: "my awsome httpclient",
        "Accept-Language": "en-us",

    res, err := httpclient.Get("", map[string]string{
        "q": "news",

    println(res.StatusCode, err)



Use httpclient.Defaults to setup default behaviors of the HTTP client.

httpclient.Defaults(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.

Sending Request
// get
httpclient.Get("", map[string]string{
    "q": "news",

// get with url.Values
httpclient.Get("", url.Values{
    "q": []string{"news", "today"}

// post
httpclient.Post("", map[string]string {
    "name": "value"

// post file(multipart)
httpclient.Post("", map[string]string {
    "@file": "/tmp/hello.pdf",

// put json
    "name": "hello",

// delete

// options

// head
Customize Request

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

    WithHeader("User-Agent", "Super Robot").
    WithHeader("custom-header", "value").
    WithHeaders(map[string]string {
        "another-header": "another-value",
        "and-another-header": "another-value",
    WithOption(httpclient.OPT_TIMEOUT, 60).
        Name: "uid",
        Value: "123",

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

// traditional
res, err := httpclient.Get("")
bodyBytes, err := ioutil.ReadAll(res.Body)

// ToString
res, err = httpclient.Get("")
bodyString, err := res.ToString()

// ReadAll
res, err = httpclient.Get("")
bodyBytes, err := res.ReadAll()
Handle Cookies
url := ""
        Name: "uid",
        Value: "123",

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

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

Concurrent Safe

If you want to start many requests concurrently, remember to call the Begin method when you begin:

go func() {
        WithHeader("Req-A", "a").
go func() {
        WithHeader("Req-B", "b").

Error Checking

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

res, err := httpclient.Get("")
if httpclient.IsTimeoutError(err) {
    // do something
Full Example

See examples/main.go


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_SOCKS5 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_PROXY: ProxyURL.
  • 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. Valid options are PROXY_HTTP, PROXY_SOCKS4, PROXY_SOCKS5, PROXY_SOCKS4A. currently not supported.
  • OPT_UNSAFE_TLS: Set to true to disable TLS certificate checking.
  • OPT_DEBUG: Print request info.
  • OPT_CONTEXT: Set context.context (can be used to cancel request).

Seperate Clients

By using the httpclient.Get, httpclient.Post methods etc, you are using a default shared HTTP client.

If you need more than one client in a single programme. Just create and use them seperately.

c1 := httpclient.NewHttpClient().Defaults(httpclient.Map {
    httpclient.OPT_USERAGENT: "browser1",


c2 := httpclient.NewHttpClient().Defaults(httpclient.Map {
    httpclient.OPT_USERAGENT: "browser2",





View Source
const (

Package errors

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

	PROXY_HTTP    = 0

	// CURL like OPT
	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_PROXY_FUNC      = 100001
	OPT_DEBUG           = 100002
	OPT_UNSAFE_TLS      = 100004

	OPT_CONTEXT = 100005

Constants definations CURL options, see


View Source
var Begin = defaultClient.Begin

Begin -

View Source
var CONST = map[string]int{
	"OPT_AUTOREFERER":       58,
	"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_PROXY_FUNC":      100001,
	"OPT_DEBUG":           100002,
	"OPT_UNSAFE_TLS":      100004,
	"OPT_CONTEXT":         100005,

CONST - String map of options

View Source
var Connect = defaultClient.Connect

Connect -

View Source
var CookieValue = defaultClient.CookieValue

CookieValue -

View Source
var CookieValues = defaultClient.CookieValues

CookieValues -

View Source
var Cookies = defaultClient.Cookies

Cookies -

View Source
var Defaults = defaultClient.Defaults

Defaults -

View Source
var Delete = defaultClient.Delete

Delete -

View Source
var Do = defaultClient.Do

Do -

View Source
var Get = defaultClient.Get

Get -

View Source
var Head = defaultClient.Head

Head -

View Source
var Options = defaultClient.Options

Options -

View Source
var Patch = defaultClient.Patch

Patch -

View Source
var PatchJson = defaultClient.PatchJson

PatchJson -

View Source
var Post = defaultClient.Post

Post -

View Source
var PostJson = defaultClient.PostJson

PostJson -

View Source
var PostMultipart = defaultClient.PostMultipart

PostMultipart -

View Source
var Put = defaultClient.Put

Put -

View Source
var PutJson = defaultClient.PutJson

PutJson -

View Source
var Trace = defaultClient.Trace

Trace -

View Source
var WithCookie = defaultClient.WithCookie

WithCookie -

View Source
var WithHeader = defaultClient.WithHeader

WithHeader -

View Source
var WithHeaders = defaultClient.WithHeaders

WithHeaders -

View Source
var WithOption = defaultClient.WithOption

WithOption -

View Source
var WithOptions = defaultClient.WithOptions

WithOptions -


func IsRedirectError

func IsRedirectError(err error) bool

Check a redirect error

func IsTimeoutError

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.


type Error

type Error struct {
	Code    int
	Message string

Custom error

func (Error) Error

func (this Error) Error() string

Implement the error interface

type HttpClient

type HttpClient struct {

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

HttpClient - Powerful and easy to use HTTP client.

func NewHttpClient

func NewHttpClient() *HttpClient

Create an HTTP client.

func (*HttpClient) Begin

func (cc *HttpClient) Begin() *HttpClient

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

func (*HttpClient) Connect

func (cc *HttpClient) Connect(url string, params[string]string) (*Response, error)

The CONNECT request

func (*HttpClient) CookieValue

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

Get cookie value of a specified cookie name.

func (*HttpClient) CookieValues

func (cc *HttpClient) CookieValues(url string) map[string]string

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

func (*HttpClient) Cookies

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

Get cookies of the client jar.

func (*HttpClient) Defaults

func (cc *HttpClient) Defaults(defaults Map) *HttpClient

Defaults - Set default options and headers.

func (*HttpClient) Delete

func (cc *HttpClient) Delete(url string, params ...interface{}) (*Response, error)

The DELETE request

func (*HttpClient) Do

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

Do -Start a request, and get the response. Usually we just need the Get and Post method.

func (*HttpClient) Get

func (cc *HttpClient) Get(url string, params ...interface{}) (*Response, error)

The GET request

func (*HttpClient) Head

func (cc *HttpClient) Head(url string) (*Response, error)

The HEAD request

func (*HttpClient) Options

func (cc *HttpClient) Options(url string, params[string]string) (*Response, error)

The OPTIONS request

func (*HttpClient) Patch

func (cc *HttpClient) Patch(url string, params[string]string) (*Response, error)

The PATCH request

func (*HttpClient) PatchJson

func (cc *HttpClient) PatchJson(url string, data interface{}) (*Response, error)

Patch json data

func (*HttpClient) Post

func (cc *HttpClient) Post(url string, params interface{}) (*Response,

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) PostJson

func (cc *HttpClient) PostJson(url string, data interface{}) (*Response, error)

func (*HttpClient) PostMultipart

func (cc *HttpClient) PostMultipart(url string, params interface{}) (
	*Response, error)

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

func (*HttpClient) Put

func (cc *HttpClient) Put(url string, body io.Reader) (*Response, error)

The PUT request

func (*HttpClient) PutJson

func (cc *HttpClient) PutJson(url string, data interface{}) (*Response, error)

Put json data

func (*HttpClient) Trace

func (cc *HttpClient) Trace(url string, params[string]string) (*Response, error)

The TRACE request

func (*HttpClient) WithCookie

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

WithCookie - Specify cookies of the current request.

func (*HttpClient) WithHeader

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

WithHeader - Temporarily specify a header of the current request.

func (*HttpClient) WithHeaders

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

WithHeaders - Temporarily specify multiple headers of the current request.

func (*HttpClient) WithOption

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

WithOption - Temporarily specify an option of the current request.

func (*HttpClient) WithOptions

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

WithOptions - Temporarily specify multiple options of the current request.

type Map

type Map map[interface{}]interface{}

Map is a mixed structure with options and headers

type ProxyURL

type ProxyURL struct {
	Host     string
	Scheme   string
	Path     string
	Port     int
	Origin   string
	Username string
	Password string
	WithAuth bool

ProxyURL -

type Response

type Response struct {

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

func (*Response) ReadAll

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

ReadAll - Read response body into a byte slice.

func (*Response) ToString

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

Read response body into string.


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL