req

package module
v3.2.1 Latest Latest
Warning

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

 Go to latest Published: Feb 7, 2022 License: MIT Imports: 49 Imported by: 803

README

Req

Simplified Golang HTTP client library with Black Magic, Less Code and More Efficiency.

Big News

Brand new v3 version is out, which is completely rewritten, bringing revolutionary innovations and many superpowers, try and enjoy :)

If you want to use the older version, check it out on v1 branch.

v2 is a transitional version, cuz some breaking changes were introduced during v2 refactoring, checkout v2 branch if you want.

Table of Contents

Features

  • Simple and chainable methods for both client-level and request-level settings, and the request-level setting takes precedence if both are set.
  • Powerful and convenient debug utilites, including debug logs, performance traces, dump complete request and response content, and even provide global wrapper methods to test with minimal code (see Debugging - Log/Trace/Dump.
  • Easy making HTTP test with code instead of tools like curl or postman, req provide global wrapper methods and MustXXX to test API with minimal code (see Quick HTTP Test).
  • Detect the charset of response body and decode it to utf-8 automatically to avoid garbled characters by default (see Auto-Decode).
  • Automatic marshal and unmarshal for JSON and XML content type and fully customizable.
  • Works fine both with HTTP/2 and HTTP/1.1, HTTP/2 is preferred by default if server support.
  • Exportable Transport, easy to integrate with existing http.Client, debug APIs with minimal code change.
  • Easy Download and Upload.
  • Easy set header, cookie, path parameter, query parameter, form data, basic auth, bearer token for both client and request level.
  • Easy set timeout, proxy, certs, redirect policy, cookie jar, compression, keepalives etc for client.
  • Support middleware before request sent and after got response.

Quick Start

Install

go get github.com/imroc/req/v3

Import

import "github.com/imroc/req/v3"

// For test, you can create and send a request with the global default
// client, use DevMode to see all details, try and suprise :)
req.DevMode()
req.Get("https://api.github.com/users/imroc")

// Create and send a request with the custom client and settings
client := req.C(). // Use C() to create a client
    SetUserAgent("my-custom-client"). // Chainable client settings
    SetTimeout(5 * time.Second).
    DevMode()
resp, err := client.R(). // Use R() to create a request
    SetHeader("Accept", "application/vnd.github.v3+json"). // Chainable request settings
    SetPathParam("username", "imroc").
    SetQueryParam("page", "1").
    SetResult(&result).
    Get("https://api.github.com/users/{username}/repos")

Checkout more runnable examples in the examples direcotry.

Debugging - Dump/Log/Trace

Dump the Content

// Enable dump at client level, which will dump for all requests,
// including all content of request and response and output
// to stdout by default.
client := req.C().EnableDumpAll()
client.R().Get("https://httpbin.org/get")

/* Output
:authority: httpbin.org
:method: GET
:path: /get
:scheme: https
user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.71 Safari/537.36
accept-encoding: gzip

:status: 200
date: Wed, 26 Jan 2022 06:39:20 GMT
content-type: application/json
content-length: 372
server: gunicorn/19.9.0
access-control-allow-origin: *
access-control-allow-credentials: true

{
  "args": {},
  "headers": {
    "Accept-Encoding": "gzip",
    "Host": "httpbin.org",
    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.71 Safari/537.36",
    "X-Amzn-Trace-Id": "Root=1-61f0ec98-5958c02662de26e458b7672b"
  },
  "origin": "103.7.29.30",
  "url": "https://httpbin.org/get"
}
*/
	
// Customize client level dump settings with predefined convenience settings. 
client.EnableDumpAllWithoutBody(). // Only dump the header of request and response
    EnableDumpAllAsync(). // Dump asynchronously to improve performance
    EnableDumpAllToFile("reqdump.log") // Dump to file without printing it out
// Send request to see the content that have been dumpped	
client.R().Get(url) 

// Enable dump with fully customized settings at client level.
opt := &req.DumpOptions{
            Output:         os.Stdout,
            RequestHeader:  true,
            ResponseBody:   true,
            RequestBody:    false,
            ResponseHeader: false,
            Async:          false,
        }
client.SetCommonDumpOptions(opt).EnableDumpAll()
client.R().Get("https://www.baidu.com/")

// Change settings dynamiclly
opt.ResponseBody = false
client.R().Get("https://www.baidu.com/")

// You can also enable dump at request level, dump to memory and will not print it out
// by default, you can call `Response.Dump()` to get the dump result and print
// only if you want to.
resp, err := client.R().EnableDump().SetBody("test body").Post("https://httpbin.org/post")
if err != nil {
    fmt.Println("err:", err)
    fmt.Println("raw content:\n", resp.Dump())
    return
}
if resp.StatusCode > 299 {
    fmt.Println("bad status:", resp.Status)
    fmt.Println("raw content:\n", resp.Dump())
	return
}

// Similarly, also support to customize dump settings with predefined convenience settings at request level.
resp, err = client.R().EnableDumpWithoutRequest().SetBody("test body").Post("https://httpbin.org/post")
// ...
resp, err = client.R().SetDumpOptions(opt).EnableDump().SetBody("test body").Post("https://httpbin.org/post")

Enable DebugLog for Deeper Insights

// Logging is enabled by default, but only output the warning and error message.
// Use `EnableDebugLog` to enable debug level logging.
client := req.C().EnableDebugLog()
client.R().Get("http://baidu.com/s?wd=req")
/* Output
2022/01/26 15:46:29.279368 DEBUG [req] GET http://baidu.com/s?wd=req
2022/01/26 15:46:29.469653 DEBUG [req] charset iso-8859-1 detected in Content-Type, auto-decode to utf-8
2022/01/26 15:46:29.469713 DEBUG [req] <redirect> GET http://www.baidu.com/s?wd=req
...
*/

// SetLogger with nil to disable all log
client.SetLogger(nil)

// Or customize the logger with your own implementation.
client.SetLogger(logger)

Enable Trace to Analyze Performance

// Enable trace at request level
client := req.C()
resp, err := client.R().EnableTrace().Get("https://api.github.com/users/imroc")
if err != nil {
	log.Fatal(err)
}
trace := resp.TraceInfo() // Use `resp.Request.TraceInfo()` to avoid unnecessary struct copy in production.
fmt.Println(trace.Blame()) // Print out exactly where the http request is slowing down.
fmt.Println("----------")
fmt.Println(trace) // Print details

/* Output
the request total time is 2.562416041s, and costs 1.289082208s from connection ready to server respond frist byte
--------
TotalTime         : 2.562416041s
DNSLookupTime     : 445.246375ms
TCPConnectTime    : 428.458µs
TLSHandshakeTime  : 825.888208ms
FirstResponseTime : 1.289082208s
ResponseTime      : 1.712375ms
IsConnReused:     : false
RemoteAddr        : 98.126.155.187:443
*/

// Enable trace at client level
client.EnableTraceAll()
resp, err = client.R().Get(url)
// ...

DevMode

If you want to enable all debug features (dump, debug log and tracing), just call DevMode():

client := req.C().DevMode()
client.R().Get("https://imroc.cc")

Quick HTTP Test

Test with Global Wrapper Methods

req wrap methods of both Client and Request with global methods, which is delegated to default client, it's very convenient when making API test.

// Call the global methods just like the Client's methods,
// so you can treat package name `req` as a Client, and
// you don't need to create any client explicitly.
req.SetTimeout(5 * time.Second).
	SetCommonBasicAuth("imroc", "123456").
	SetCommonHeader("Accept", "application/json").
	SetUserAgent("my api client").
	DevMode()

// Call the global method just like the Request's method,
// which will create request automatically using the default
// client, so you can treat package name `req` as a Request,
// and you don't need to create request explicitly.
req.SetQueryParam("page", "2").
	SetHeader("Accept", "text/xml"). // Override client level settings at request level.
	Get("https://api.example.com/repos")

Test with MustXXX

Use MustXXX to ignore error handling during test, make it possible to complete a complex test with just one line of code:

fmt.Println(req.DevMode().R().MustGet("https://imroc.cc").TraceInfo())

URL Path and Query Parameter

Path Parameter

Use SetPathParam or SetPathParams to replace variable in the url path:

client := req.C().DevMode()

client.R().
    SetPathParam("owner", "imroc"). // Set a path param, which will replace the vairable in url path
    SetPathParams(map[string]string{ // Set multiple path params at once 
        "repo": "req",
        "path": "README.md",
    }).Get("https://api.github.com/repos/{owner}/{repo}/contents/{path}") // path parameter will replace path variable in the url
/* Output
2022/01/23 14:43:59.114592 DEBUG [req] GET https://api.github.com/repos/imroc/req/contents/README.md
...
*/

// You can also set the common PathParam for every request on client
client.SetCommonPathParam(k1, v1).SetCommonPathParams(pathParams)
	
resp1, err := client.Get(url1)
...

resp2, err := client.Get(url2)
...

Query Parameter

Use SetQueryParam, SetQueryParams or SetQueryString to append url query parameter:

client := req.C().DevMode()

// Set query parameter at request level.
client.R().
    SetQueryParam("a", "a"). // Set a query param, which will be encoded as query parameter in url
    SetQueryParams(map[string]string{ // Set multiple query params at once 
        "b": "b",
        "c": "c",
    }).SetQueryString("d=d&e=e"). // Set query params as a raw query string
    Get("https://api.github.com/repos/imroc/req/contents/README.md?x=x")
/* Output
2022/01/23 14:43:59.114592 DEBUG [req] GET https://api.github.com/repos/imroc/req/contents/README.md?x=x&a=a&b=b&c=c&d=d&e=e
...
*/

// You can also set the query parameter at client level.
client.SetCommonQueryParam(k, v).
    SetCommonQueryParams(queryParams).
    SetCommonQueryString(queryString).
	
resp1, err := client.Get(url1)
...
resp2, err := client.Get(url2)
...

// Add query parameter with multiple values at request level.
client.R().AddQueryParam("key", "value1").AddQueryParam("key", "value2").Get("https://httpbin.org/get")
/* Output
2022/02/05 08:49:26.260780 DEBUG [req] GET https://httpbin.org/get?key=value1&key=value2
...
 */


// Multiple values also supported at client level.
client.AddCommonQueryParam("key", "value1").AddCommonQueryParam("key", "value2")

Form Data

client := req.C().EnableDumpOnlyRequest()
client.R().SetFormData(map[string]string{
    "username": "imroc",
    "blog":     "https://imroc.cc",
}).Post("https://httpbin.org/post")
/* Output
:authority: httpbin.org
:method: POST
:path: /post
:scheme: https
content-type: application/x-www-form-urlencoded
accept-encoding: gzip
user-agent: req/v2 (https://github.com/imroc/req)

blog=https%3A%2F%2Fimroc.cc&username=imroc
*/

// Multi value form data
v := url.Values{
    "multi": []string{"a", "b", "c"},
}
client.R().SetFormDataFromValues(v).Post("https://httpbin.org/post")
/* Output
:authority: httpbin.org
:method: POST
:path: /post
:scheme: https
content-type: application/x-www-form-urlencoded
accept-encoding: gzip
user-agent: req/v2 (https://github.com/imroc/req)

multi=a&multi=b&multi=c
*/

// You can also set form data in client level
client.SetCommonFormData(m)
client.SetCommonFormDataFromValues(v)

GET, HEAD, and OPTIONS requests ignores form data by default

Set Header

// Let's dump the header to see what's going on
client := req.C().EnableDumpOnlyHeader() 

// Send a request with multiple headers and cookies
client.R().
    SetHeader("Accept", "application/json"). // Set one header
    SetHeaders(map[string]string{ // Set multiple headers at once 
        "My-Custom-Header": "My Custom Value",
        "User":             "imroc",
    }).Get("https://www.baidu.com/")

/* Output
GET / HTTP/1.1
Host: www.baidu.com
User-Agent: req/v2 (https://github.com/imroc/req)
Accept: application/json
My-Custom-Header: My Custom Value
User: imroc
Accept-Encoding: gzip
*/

// You can also set the common header and cookie for every request on client.
client.SetCommonHeader(header).SetCommonHeaders(headers)

resp1, err := client.R().Get(url1)
...
resp2, err := client.R().Get(url2)
...

Set Cookie

// Let's dump the header to see what's going on
client := req.C().EnableDumpOnlyHeader() 

// Send a request with multiple headers and cookies
client.R().
    SetCookies(
		&http.Cookie{
            Name:     "testcookie1",
            Value:    "testcookie1 value",
            Path:     "/",
            Domain:   "baidu.com",
            MaxAge:   36000,
            HttpOnly: false,
            Secure:   true,
        },
        &http.Cookie{
            Name:     "testcookie2",
            Value:    "testcookie2 value",
            Path:     "/",
            Domain:   "baidu.com",
            MaxAge:   36000,
            HttpOnly: false,
            Secure:   true,
        },
    ).Get("https://www.baidu.com/")

/* Output
GET / HTTP/1.1
Host: www.baidu.com
User-Agent: req/v2 (https://github.com/imroc/req)
Accept: application/json
Cookie: testcookie1="testcookie1 value"; testcookie2="testcookie2 value"
Accept-Encoding: gzip
*/

// You can also set the common cookie for every request on client.
client.SetCommonCookies(cookie1, cookie2, cookie3)

resp1, err := client.R().Get(url1)
...
resp2, err := client.R().Get(url2)

You can also customize the CookieJar:

// Set your own http.CookieJar implementation
client.SetCookieJar(jar)

// Set to nil to disable CookieJar
client.SetCookieJar(nil)

Body and Marshal/Unmarshal

Request Body

// Create a client that dump request
client := req.C().EnableDumpOnlyRequest()
// SetBody accepts string, []byte, io.Reader, use type assertion to
// determine the data type of body automatically. 
client.R().SetBody("test").Post("https://httpbin.org/post")
/* Output
:authority: httpbin.org
:method: POST
:path: /post
:scheme: https
accept-encoding: gzip
user-agent: req/v2 (https://github.com/imroc/req)

test
*/

// If it cannot determine, like map and struct, then it will wait
// and marshal to JSON or XML automatically according to the `Content-Type`
// header that have been set before or after, default to json if not set.
type User struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}
user := &User{Name: "imroc", Email: "roc@imroc.cc"}
client.R().SetBody(user).Post("https://httpbin.org/post")
/* Output
:authority: httpbin.org
:method: POST
:path: /post
:scheme: https
content-type: application/json; charset=utf-8
accept-encoding: gzip
user-agent: req/v2 (https://github.com/imroc/req)

{"name":"imroc","email":"roc@imroc.cc"}
*/


// You can use more specific methods to avoid type assertions and improves performance,
client.R().SetBodyJsonString(`{"username": "imroc"}`).Post("https://httpbin.org/post")
/*
:authority: httpbin.org
:method: POST
:path: /post
:scheme: https
content-type: application/json; charset=utf-8
accept-encoding: gzip
user-agent: req/v2 (https://github.com/imroc/req)

{"username": "imroc"}
*/

// Marshal body and set `Content-Type` automatically without any guess
cient.R().SetBodyXmlMarshal(user).Post("https://httpbin.org/post")
/* Output
:authority: httpbin.org
:method: POST
:path: /post
:scheme: https
content-type: text/xml; charset=utf-8
accept-encoding: gzip
user-agent: req/v2 (https://github.com/imroc/req)

<User><Name>imroc</Name><Email>roc@imroc.cc</Email></User>
*/

Response Body

// Define success body struct
type User struct {
    Name string `json:"name"`
    Blog string `json:"blog"`
}
// Define error body struct
type ErrorMessage struct {
    Message string `json:"message"`
}
// Create a client and dump body to see details
client := req.C().EnableDumpOnlyBody()

// Send a request and unmarshal result automatically according to
// response `Content-Type`
user := &User{}
errMsg := &ErrorMessage{}
resp, err := client.R().
	SetResult(user). // Set success result
	SetError(errMsg). // Set error result
	Get("https://api.github.com/users/imroc")
if err != nil {
    log.Fatal(err)
}
fmt.Println("----------")

if resp.IsSuccess() { // status `code >= 200 and <= 299` is considered as success
	// Must have been marshaled to user if no error returned before
    fmt.Printf("%s's blog is %s\n", user.Name, user.Blog)
} else if resp.IsError() { // status `code >= 400` is considered as error
	// Must have been marshaled to errMsg if no error returned before
    fmt.Println("got error:", errMsg.Message) 
} else {
    log.Fatal("unknown http status:", resp.Status)
}
/* Output
{"login":"imroc","id":7448852,"node_id":"MDQ6VXNlcjc0NDg4NTI=","avatar_url":"https://avatars.githubusercontent.com/u/7448852?v=4","gravatar_id":"","url":"https://api.github.com/users/imroc","html_url":"https://github.com/imroc","followers_url":"https://api.github.com/users/imroc/followers","following_url":"https://api.github.com/users/imroc/following{/other_user}","gists_url":"https://api.github.com/users/imroc/gists{/gist_id}","starred_url":"https://api.github.com/users/imroc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/imroc/subscriptions","organizations_url":"https://api.github.com/users/imroc/orgs","repos_url":"https://api.github.com/users/imroc/repos","events_url":"https://api.github.com/users/imroc/events{/privacy}","received_events_url":"https://api.github.com/users/imroc/received_events","type":"User","site_admin":false,"name":"roc","company":"Tencent","blog":"https://imroc.cc","location":"China","email":null,"hireable":true,"bio":"I'm roc","twitter_username":"imrocchan","public_repos":129,"public_gists":0,"followers":362,"following":151,"created_at":"2014-04-30T10:50:46Z","updated_at":"2022-01-24T23:32:53Z"}
----------
roc's blog is https://imroc.cc
*/

// Or you can also unmarshal response later
if resp.IsSuccess() {
    err = resp.Unmarshal(user)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s's blog is %s\n", user.Name, user.Blog)
} else {
    fmt.Println("bad response:", resp)
}

// Also, you can get the raw response and Unmarshal by yourself
yaml.Unmarshal(resp.Bytes())

Customize JSON&XML Marshal/Unmarshal

// Example of registering json-iterator
import jsoniter "github.com/json-iterator/go"

json := jsoniter.ConfigCompatibleWithStandardLibrary

client := req.C().
	SetJsonMarshal(json.Marshal).
	SetJsonUnmarshal(json.Unmarshal)

// Similarly, XML functions can also be customized
client.SetXmlMarshal(xmlMarshalFunc).SetXmlUnmarshal(xmlUnmarshalFunc)

Disable Auto-Read Response Body

Response body will be read into memory if it's not a download request by default, you can disable it if you want (normally you don't need to do this).

client.DisableAutoReadResponse()

resp, err := client.R().Get(url)
if err != nil {
	log.Fatal(err)
}
io.Copy(dst, resp.Body)

Custom Certificates

client := req.R()

// Set root cert and client cert from file path
client.SetRootCertsFromFile("/path/to/root/certs/pemFile1.pem", "/path/to/root/certs/pemFile2.pem", "/path/to/root/certs/pemFile3.pem"). // Set root cert from one or more pem files
    SetCertFromFile("/path/to/client/certs/client.pem", "/path/to/client/certs/client.key") // Set client cert and key cert file
	
// You can also set root cert from string
client.SetRootCertFromString("-----BEGIN CERTIFICATE-----XXXXXX-----END CERTIFICATE-----")

// And set client cert with 
cert1, err := tls.LoadX509KeyPair("/path/to/client/certs/client.pem", "/path/to/client/certs/client.key")
if err != nil {
    log.Fatalf("ERROR client certificate: %s", err)
}
// ...

// you can add more certs if you want
client.SetCerts(cert1, cert2, cert3)

Basic Auth and Bearer Token

client := req.C()

// Set basic auth for all request
client.SetCommonBasicAuth("imroc", "123456")

// Set bearer token for all request
client.SetCommonBearerAuthToken("MDc0ZTg5YmU4Yzc5MjAzZGJjM2ZiMzkz")

// Set basic auth for a request, will override client's basic auth setting.
client.R().SetBasicAuth("myusername", "mypassword").Get("https://api.example.com/profile")

// Set bearer token for a request, will override client's bearer token setting.
client.R().SetBearerToken("NGU1ZWYwZDJhNmZhZmJhODhmMjQ3ZDc4").Get("https://api.example.com/profile")

Download and Upload

Download

// Create a client with default download direcotry
client := req.C().SetOutputDirectory("/path/to/download").EnableDumpNoResponseBody()

// Download to relative file path, this will be downloaded
// to /path/to/download/test.jpg
client.R().SetOutputFile("test.jpg").Get(url)

// Download to absolute file path, ignore the output directory
// setting from Client
client.R().SetOutputFile("/tmp/test.jpg").Get(url)

// You can also save file to any `io.WriteCloser`
file, err := os.Create("/tmp/test.jpg")
if err != nil {
	fmt.Println(err)
	return
}
client.R().SetOutput(file).Get(url)

Multipart Upload

client := req.().EnableDumpNoRequestBody() // Request body contains unreadable binary, do not dump

client.R().SetFile("pic", "test.jpg"). // Set form param name and filename
    SetFile("pic", "/path/to/roc.png"). // Multiple files using the same form param name
    SetFiles(map[string]string{ // Set multiple files using map
        "exe": "test.exe",
        "src": "main.go",
    }).
    SetFormData(map[string]string{ // Set from param using map
        "name":  "imroc",
        "email": "roc@imroc.cc",
    }).
	SetFromDataFromValues(values). // You can also set form data using `url.Values`
    Post("http://127.0.0.1:8888/upload")

// You can also use io.Reader to upload
avatarImgFile, _ := os.Open("avatar.png")
client.R().SetFileReader("avatar", "avatar.png", avatarImgFile).Post(url)
*/

Auto-Decode

Req detect the charset of response body and decode it to utf-8 automatically to avoid garbled characters by default.

Its principle is to detect whether Content-Type header at first, if it's not the text content type (json, xml, html and so on), req will not try to decode. If it is, then req will try to find the charset information, if it's not included in the header, it will try to sniff the body's content to determine the charset, if found and is not utf-8, then decode it to utf-8 automatically, if the charset is not sure, it will not decode, and leave the body untouched.

You can also disable if you don't need or care a lot about performance:

client.DisableAutoDecode()

Also you can make some customization:

// Try to auto-detect and decode all content types (some server may return incorrect Content-Type header)
client.SetAutoDecodeAllType()

// Only auto-detect and decode content which `Content-Type` header contains "html" or "json"
client.SetAutoDecodeContentType("html", "json")

// Or you can customize the function to determine whether to decode
fn := func(contentType string) bool {
    if regexContentType.MatchString(contentType) {
        return true
    }
    return false
}
client.SetAutoDecodeAllTypeFunc(fn)

Request and Response Middleware

client := req.C()

// Registering Request Middleware
client.OnBeforeRequest(func(c *req.Client, r *req.Request) error {
	// You can access Client and current Request object to do something
	// as you need

    return nil  // return nil if it is success
  })

// Registering Response Middleware
client.OnAfterResponse(func(c *req.Client, r *req.Response) error {
    // You can access Client and current Response object to do something
    // as you need

    return nil  // return nil if it is success
  })

Redirect Policy

client := req.C().EnableDumpOnlyRequest()

client.SetRedirectPolicy(
    // Only allow up to 5 redirects
    req.MaxRedirectPolicy(5),
    // Only allow redirect to same domain.
    // e.g. redirect "www.imroc.cc" to "imroc.cc" is allowed, but "google.com" is not
    req.SameDomainRedirectPolicy(),
)

client.SetRedirectPolicy(
    // Only *.google.com/google.com and *.imroc.cc/imroc.cc is allowed to redirect
    req.AllowedDomainRedirectPolicy("google.com", "imroc.cc"),
    // Only allow redirect to same host.
    // e.g. redirect "www.imroc.cc" to "imroc.cc" is not allowed, only "www.imroc.cc" is allowed
    req.SameHostRedirectPolicy(),
)

// All redirect is not allowd
client.SetRedirectPolicy(req.NoRedirectPolicy())

// Or customize the redirect with your own implementation
client.SetRedirectPolicy(func(req *http.Request, via []*http.Request) error {
    // ...
})

Proxy

Req use proxy http.ProxyFromEnvironment by default, which will read the HTTP_PROXY/HTTPS_PROXY/http_proxy/https_proxy environment variable, and setup proxy if environment variable is been set. You can customize it if you need:

// Set proxy from proxy url
client.SetProxyURL("http://myproxy:8080")

// Custmize the proxy function with your own implementation
client.SetProxy(func(request *http.Request) (*url.URL, error) {
    //...
})

// Disable proxy
client.SetProxy(nil)

TODO List

  • Add tests.
  • Wrap more transport settings into client.
  • Support retry.
  • Support unix socket.
  • Support h2c.

License

Req released under MIT license, refer LICENSE file.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var NoBody = noBody{}

NoBody is an io.ReadCloser with no bytes. Read always returns EOF and Close always returns nil. It can be used in an outgoing client request to explicitly signal that a request has zero bytes. An alternative, however, is to simply set Request.Body to nil.

Functions

func CanonicalMIMEHeaderKey 

func CanonicalMIMEHeaderKey(s string) string

CanonicalMIMEHeaderKey returns the canonical format of the MIME header key s. The canonicalization converts the first letter and any letter following a hyphen to upper case; the rest are converted to lowercase. For example, the canonical key for "accept-encoding" is "Accept-Encoding". MIME header keys are assumed to be ASCII only. If s contains a space or invalid header field bytes, it is returned without modifications.

func SetDefaultClient 

func SetDefaultClient(c *Client)

SetDefaultClient override the global default Client.

Types

type Client 

type Client struct {
	BaseURL               string
	PathParams            map[string]string
	QueryParams           urlpkg.Values
	Headers               http.Header
	Cookies               []*http.Cookie
	FormData              urlpkg.Values
	DebugLog              bool
	AllowGetMethodPayload bool
	// contains filtered or unexported fields
}

Client is the req's http client.

func AddCommonQueryParam 

func AddCommonQueryParam(key, value string) *Client

AddCommonQueryParam is a global wrapper methods which delegated to the default client's AddCommonQueryParam.

func C 

func C() *Client

C create a new client.

func DefaultClient 

func DefaultClient() *Client

DefaultClient returns the global default Client.

func DevMode 

func DevMode() *Client

DevMode is a global wrapper methods which delegated to the default client's DevMode.

func DisableAllowGetMethodPayload 

func DisableAllowGetMethodPayload() *Client

DisableAllowGetMethodPayload is a global wrapper methods which delegated to the default client's DisableAllowGetMethodPayload.

func DisableAutoDecode 

func DisableAutoDecode() *Client

DisableAutoDecode is a global wrapper methods which delegated to the default client's DisableAutoDecode.

func DisableAutoReadResponse 

func DisableAutoReadResponse() *Client

DisableAutoReadResponse is a global wrapper methods which delegated to the default client's DisableAutoReadResponse.

func DisableCompression 

func DisableCompression() *Client

DisableCompression is a global wrapper methods which delegated to the default client's DisableCompression.

func DisableDebugLog 

func DisableDebugLog() *Client

DisableDebugLog is a global wrapper methods which delegated to the default client's DisableDebugLog.

func DisableDumpAll 

func DisableDumpAll() *Client

DisableDumpAll is a global wrapper methods which delegated to the default client's DisableDumpAll.

func DisableForceHTTP1 added in v3.2.0 

func DisableForceHTTP1() *Client

DisableForceHTTP1 is a global wrapper methods which delegated to the default client's DisableForceHTTP1.

func DisableKeepAlives 

func DisableKeepAlives() *Client

DisableKeepAlives is a global wrapper methods which delegated to the default client's DisableKeepAlives.

func DisableTraceAll 

func DisableTraceAll() *Client

DisableTraceAll is a global wrapper methods which delegated to the default client's DisableTraceAll.

func EnableAllowGetMethodPayload 

func EnableAllowGetMethodPayload() *Client

EnableAllowGetMethodPayload is a global wrapper methods which delegated to the default client's EnableAllowGetMethodPayload.

func EnableAutoDecode 

func EnableAutoDecode() *Client

EnableAutoDecode is a global wrapper methods which delegated to the default client's EnableAutoDecode.

func EnableAutoReadResponse 

func EnableAutoReadResponse() *Client

EnableAutoReadResponse is a global wrapper methods which delegated to the default client's EnableAutoReadResponse.

func EnableCompression 

func EnableCompression() *Client

EnableCompression is a global wrapper methods which delegated to the default client's EnableCompression.

func EnableDebugLog 

func EnableDebugLog() *Client

EnableDebugLog is a global wrapper methods which delegated to the default client's EnableDebugLog.

func EnableDumpAll 

func EnableDumpAll() *Client

EnableDumpAll is a global wrapper methods which delegated to the default client's EnableDumpAll.

func EnableDumpAllAsync 

func EnableDumpAllAsync() *Client

EnableDumpAllAsync is a global wrapper methods which delegated to the default client's EnableDumpAllAsync.

func EnableDumpAllTo 

func EnableDumpAllTo(output io.Writer) *Client

EnableDumpAllTo is a global wrapper methods which delegated to the default client's EnableDumpAllTo.

func EnableDumpAllToFile 

func EnableDumpAllToFile(filename string) *Client

EnableDumpAllToFile is a global wrapper methods which delegated to the default client's EnableDumpAllToFile.

func EnableDumpAllWithoutBody 

func EnableDumpAllWithoutBody() *Client

EnableDumpAllWithoutBody is a global wrapper methods which delegated to the default client's EnableDumpAllWithoutBody.

func EnableDumpAllWithoutHeader 

func EnableDumpAllWithoutHeader() *Client

EnableDumpAllWithoutHeader is a global wrapper methods which delegated to the default client's EnableDumpAllWithoutHeader.

func EnableDumpAllWithoutRequest added in v3.1.0 

func EnableDumpAllWithoutRequest() *Client

EnableDumpAllWithoutRequest is a global wrapper methods which delegated to the default client's EnableDumpAllWithoutRequest.

func EnableDumpAllWithoutRequestBody 

func EnableDumpAllWithoutRequestBody() *Client

EnableDumpAllWithoutRequestBody is a global wrapper methods which delegated to the default client's EnableDumpAllWithoutRequestBody.

func EnableDumpAllWithoutResponse 

func EnableDumpAllWithoutResponse() *Client

EnableDumpAllWithoutResponse is a global wrapper methods which delegated to the default client's EnableDumpAllWithoutResponse.

func EnableDumpAllWithoutResponseBody 

func EnableDumpAllWithoutResponseBody() *Client

EnableDumpAllWithoutResponseBody is a global wrapper methods which delegated to the default client's EnableDumpAllWithoutResponseBody.

func EnableForceHTTP1 added in v3.2.0 

func EnableForceHTTP1() *Client

EnableForceHTTP1 is a global wrapper methods which delegated to the default client's EnableForceHTTP1.

func EnableKeepAlives 

func EnableKeepAlives() *Client

EnableKeepAlives is a global wrapper methods which delegated to the default client's EnableKeepAlives.

func EnableTraceAll 

func EnableTraceAll() *Client

EnableTraceAll is a global wrapper methods which delegated to the default client's EnableTraceAll.

func NewClient 

func NewClient() *Client

NewClient is the alias of C

func OnAfterResponse 

func OnAfterResponse(m ResponseMiddleware) *Client

OnAfterResponse is a global wrapper methods which delegated to the default client's OnAfterResponse.

func OnBeforeRequest 

func OnBeforeRequest(m RequestMiddleware) *Client

OnBeforeRequest is a global wrapper methods which delegated to the default client's OnBeforeRequest.

func SetAutoDecodeAllType 

func SetAutoDecodeAllType() *Client

SetAutoDecodeAllType is a global wrapper methods which delegated to the default client's SetAutoDecodeAllType.

func SetAutoDecodeAllTypeFunc 

func SetAutoDecodeAllTypeFunc(fn func(contentType string) bool) *Client

SetAutoDecodeAllTypeFunc is a global wrapper methods which delegated to the default client's SetAutoDecodeAllTypeFunc.

func SetAutoDecodeContentType 

func SetAutoDecodeContentType(contentTypes ...string) *Client

SetAutoDecodeContentType is a global wrapper methods which delegated to the default client's SetAutoDecodeContentType.

func SetBaseURL 

func SetBaseURL(u string) *Client

SetBaseURL is a global wrapper methods which delegated to the default client's SetBaseURL.

func SetCertFromFile 

func SetCertFromFile(certFile, keyFile string) *Client

SetCertFromFile is a global wrapper methods which delegated to the default client's SetCertFromFile.

func SetCerts 

func SetCerts(certs ...tls.Certificate) *Client

SetCerts is a global wrapper methods which delegated to the default client's SetCerts.

func SetCommonBasicAuth 

func SetCommonBasicAuth(username, password string) *Client

SetCommonBasicAuth is a global wrapper methods which delegated to the default client's SetCommonBasicAuth.

func SetCommonBearerAuthToken 

func SetCommonBearerAuthToken(token string) *Client

SetCommonBearerAuthToken is a global wrapper methods which delegated to the default client's SetCommonBearerAuthToken.

func SetCommonContentType 

func SetCommonContentType(ct string) *Client

SetCommonContentType is a global wrapper methods which delegated to the default client's SetCommonContentType.

func SetCommonCookies 

func SetCommonCookies(cookies ...*http.Cookie) *Client

SetCommonCookies is a global wrapper methods which delegated to the default client's SetCommonCookies.

func SetCommonDumpOptions 

func SetCommonDumpOptions(opt *DumpOptions) *Client

SetCommonDumpOptions is a global wrapper methods which delegated to the default client's SetCommonDumpOptions.

func SetCommonFormData 

func SetCommonFormData(data map[string]string) *Client

SetCommonFormData is a global wrapper methods which delegated to the default client's SetCommonFormData.

func SetCommonFormDataFromValues 

func SetCommonFormDataFromValues(data urlpkg.Values) *Client

SetCommonFormDataFromValues is a global wrapper methods which delegated to the default client's SetCommonFormDataFromValues.

func SetCommonHeader 

func SetCommonHeader(key, value string) *Client

SetCommonHeader is a global wrapper methods which delegated to the default client's SetCommonHeader.

func SetCommonHeaders 

func SetCommonHeaders(hdrs map[string]string) *Client

SetCommonHeaders is a global wrapper methods which delegated to the default client's SetCommonHeaders.

func SetCommonQueryParam 

func SetCommonQueryParam(key, value string) *Client

SetCommonQueryParam is a global wrapper methods which delegated to the default client's SetCommonQueryParam.

func SetCommonQueryParams 

func SetCommonQueryParams(params map[string]string) *Client

SetCommonQueryParams is a global wrapper methods which delegated to the default client's SetCommonQueryParams.

func SetCommonQueryString 

func SetCommonQueryString(query string) *Client

SetCommonQueryString is a global wrapper methods which delegated to the default client's SetCommonQueryString.

func SetCookieJar 

func SetCookieJar(jar http.CookieJar) *Client

SetCookieJar is a global wrapper methods which delegated to the default client's SetCookieJar.

func SetDial added in v3.2.0 

func SetDial(fn func(ctx context.Context, network, addr string) (net.Conn, error)) *Client

SetDial is a global wrapper methods which delegated to the default client's SetDial.

func SetDialTLS added in v3.2.0 

func SetDialTLS(fn func(ctx context.Context, network, addr string) (net.Conn, error)) *Client

SetDialTLS is a global wrapper methods which delegated to the default client's SetDialTLS.

func SetJsonMarshal 

func SetJsonMarshal(fn func(v interface{}) ([]byte, error)) *Client

SetJsonMarshal is a global wrapper methods which delegated to the default client's SetJsonMarshal.

func SetJsonUnmarshal 

func SetJsonUnmarshal(fn func(data []byte, v interface{}) error) *Client

SetJsonUnmarshal is a global wrapper methods which delegated to the default client's SetJsonUnmarshal.

func SetLogger 

func SetLogger(log Logger) *Client

SetLogger is a global wrapper methods which delegated to the default client's SetLogger.

func SetOutputDirectory 

func SetOutputDirectory(dir string) *Client

SetOutputDirectory is a global wrapper methods which delegated to the default client's SetOutputDirectory.

func SetProxy 

func SetProxy(proxy func(*http.Request) (*urlpkg.URL, error)) *Client

SetProxy is a global wrapper methods which delegated to the default client's SetProxy.

func SetProxyURL 

func SetProxyURL(proxyUrl string) *Client

SetProxyURL is a global wrapper methods which delegated to the default client's SetProxyURL.

func SetRedirectPolicy 

func SetRedirectPolicy(policies ...RedirectPolicy) *Client

SetRedirectPolicy is a global wrapper methods which delegated to the default client's SetRedirectPolicy.

func SetRootCertFromString 

func SetRootCertFromString(pemContent string) *Client

SetRootCertFromString is a global wrapper methods which delegated to the default client's SetRootCertFromString.

func SetRootCertsFromFile 

func SetRootCertsFromFile(pemFiles ...string) *Client

SetRootCertsFromFile is a global wrapper methods which delegated to the default client's SetRootCertsFromFile.

func SetScheme 

func SetScheme(scheme string) *Client

SetScheme is a global wrapper methods which delegated to the default client's SetScheme.

func SetTLSClientConfig 

func SetTLSClientConfig(conf *tls.Config) *Client

SetTLSClientConfig is a global wrapper methods which delegated to the default client's SetTLSClientConfig.

func SetTLSHandshakeTimeout added in v3.2.0 

func SetTLSHandshakeTimeout(timeout time.Duration) *Client

SetTLSHandshakeTimeout is a global wrapper methods which delegated to the default client's SetTLSHandshakeTimeout.

func SetTimeout 

func SetTimeout(d time.Duration) *Client

SetTimeout is a global wrapper methods which delegated to the default client's SetTimeout.

func SetUserAgent 

func SetUserAgent(userAgent string) *Client

SetUserAgent is a global wrapper methods which delegated to the default client's SetUserAgent.

func SetXmlMarshal 

func SetXmlMarshal(fn func(v interface{}) ([]byte, error)) *Client

SetXmlMarshal is a global wrapper methods which delegated to the default client's SetXmlMarshal.

func SetXmlUnmarshal 

func SetXmlUnmarshal(fn func(data []byte, v interface{}) error) *Client

SetXmlUnmarshal is a global wrapper methods which delegated to the default client's SetXmlUnmarshal.

func (*Client) AddCommonQueryParam 

func (c *Client) AddCommonQueryParam(key, value string) *Client

AddCommonQueryParam add a URL query parameter with a key-value pair at client level

func (*Client) Clone 

func (c *Client) Clone() *Client

Clone copy and returns the Client

func (*Client) DevMode 

func (c *Client) DevMode() *Client

DevMode enables: 1. Dump content of all requests and responses to see details. 2. Output debug log for deeper insights. 3. Trace all requests, so you can get trace info to analyze performance. 4. Set User-Agent to pretend to be a web browser, avoid returning abnormal data from some sites.

func (*Client) DisableAllowGetMethodPayload 

func (c *Client) DisableAllowGetMethodPayload() *Client

DisableAllowGetMethodPayload disables sending GET method requests with body.

func (*Client) DisableAutoDecode 

func (c *Client) DisableAutoDecode() *Client

DisableAutoDecode disable auto detect charset and decode to utf-8 (enabled by default)

func (*Client) DisableAutoReadResponse 

func (c *Client) DisableAutoReadResponse() *Client

DisableAutoReadResponse disable read response body automatically (enabled by default).

func (*Client) DisableCompression 

func (c *Client) DisableCompression() *Client

DisableCompression disables the compression (enabled by default), which prevents the Transport from requesting compression with an "Accept-Encoding: gzip" request header when the Request contains no existing Accept-Encoding value. If the Transport requests gzip on its own and gets a gzipped response, it's transparently decoded in the Response.Body. However, if the user explicitly requested gzip it is not automatically uncompressed.

func (*Client) DisableDebugLog 

func (c *Client) DisableDebugLog() *Client

DisableDebugLog disables debug level log (disabled by default).

func (*Client) DisableDumpAll 

func (c *Client) DisableDumpAll() *Client

DisableDumpAll disables the dump.

func (*Client) DisableForceHTTP1 added in v3.2.0 

func (c *Client) DisableForceHTTP1() *Client

DisableForceHTTP1 disable force using HTTP1 (disabled by default)

func (*Client) DisableKeepAlives 

func (c *Client) DisableKeepAlives() *Client

DisableKeepAlives disables HTTP keep-alives (enabled by default) and will only use the connection to the server for a single HTTP request .

This is unrelated to the similarly named TCP keep-alives.

func (*Client) DisableTraceAll 

func (c *Client) DisableTraceAll() *Client

DisableTraceAll disables the trace at client level.

func (*Client) EnableAllowGetMethodPayload 

func (c *Client) EnableAllowGetMethodPayload() *Client

EnableAllowGetMethodPayload allows sending GET method requests with body.

func (*Client) EnableAutoDecode 

func (c *Client) EnableAutoDecode() *Client

EnableAutoDecode enables auto detect charset and decode to utf-8 (enabled by default)

func (*Client) EnableAutoReadResponse 

func (c *Client) EnableAutoReadResponse() *Client

EnableAutoReadResponse enable read response body automatically (enabled by default).

func (*Client) EnableCompression 

func (c *Client) EnableCompression() *Client

EnableCompression enables the compression (enabled by default), which prevents the Transport from requesting compression with an "Accept-Encoding: gzip" request header when the Request contains no existing Accept-Encoding value. If the Transport requests gzip on its own and gets a gzipped response, it's transparently decoded in the Response.Body. However, if the user explicitly requested gzip it is not automatically uncompressed.

func (*Client) EnableDebugLog 

func (c *Client) EnableDebugLog() *Client

EnableDebugLog enables debug level log (disabled by default).

func (*Client) EnableDumpAll 

func (c *Client) EnableDumpAll() *Client

EnableDumpAll enables dump for all requests, including all content for the request and response by default.

func (*Client) EnableDumpAllAsync 

func (c *Client) EnableDumpAllAsync() *Client

EnableDumpAllAsync enables dump for all requests and output asynchronously, can be used for debugging in production environment without affecting performance.

func (*Client) EnableDumpAllTo 

func (c *Client) EnableDumpAllTo(output io.Writer) *Client

EnableDumpAllTo enables dump for all requests and save to the specified io.Writer.

func (*Client) EnableDumpAllToFile 

func (c *Client) EnableDumpAllToFile(filename string) *Client

EnableDumpAllToFile enables dump for all requests and save to the specified filename.

func (*Client) EnableDumpAllWithoutBody 

func (c *Client) EnableDumpAllWithoutBody() *Client

EnableDumpAllWithoutBody enables dump for all requests with only header of request and response included.

func (*Client) EnableDumpAllWithoutHeader 

func (c *Client) EnableDumpAllWithoutHeader() *Client

EnableDumpAllWithoutHeader enables dump for all requests with only body of request and response included.

func (*Client) EnableDumpAllWithoutRequest added in v3.1.0 

func (c *Client) EnableDumpAllWithoutRequest() *Client

EnableDumpAllWithoutRequest enables dump for all requests with only request header and body included.

func (*Client) EnableDumpAllWithoutRequestBody 

func (c *Client) EnableDumpAllWithoutRequestBody() *Client

EnableDumpAllWithoutRequestBody enables dump for all requests, with request body excluded, can be used in upload request to avoid dump the unreadable binary content.

func (*Client) EnableDumpAllWithoutResponse 

func (c *Client) EnableDumpAllWithoutResponse() *Client

EnableDumpAllWithoutResponse enables dump for all requests with only request header and body included.

func (*Client) EnableDumpAllWithoutResponseBody 

func (c *Client) EnableDumpAllWithoutResponseBody() *Client

EnableDumpAllWithoutResponseBody enables dump for all requests, with response body excluded, can be used in download request to avoid dump the unreadable binary content.

func (*Client) EnableForceHTTP1 added in v3.2.0 

func (c *Client) EnableForceHTTP1() *Client

EnableForceHTTP1 enables force using HTTP1 (disabled by default)

func (*Client) EnableKeepAlives 

func (c *Client) EnableKeepAlives() *Client

EnableKeepAlives enables HTTP keep-alives (enabled by default) and will only use the connection to the server for a single HTTP request .

This is unrelated to the similarly named TCP keep-alives.

func (*Client) EnableTraceAll 

func (c *Client) EnableTraceAll() *Client

EnableTraceAll enables the trace at client level.

func (*Client) NewRequest 

func (c *Client) NewRequest() *Request

NewRequest is the alias of R()

func (*Client) OnAfterResponse 

func (c *Client) OnAfterResponse(m ResponseMiddleware) *Client

OnAfterResponse add a response middleware which hooks after response received.

func (*Client) OnBeforeRequest 

func (c *Client) OnBeforeRequest(m RequestMiddleware) *Client

OnBeforeRequest add a request middleware which hooks before request sent.

func (*Client) R 

func (c *Client) R() *Request

R create a new request.

func (*Client) SetAutoDecodeAllType 

func (c *Client) SetAutoDecodeAllType() *Client

SetAutoDecodeAllType enables to try auto-detect and decode all content type to utf-8.

func (*Client) SetAutoDecodeAllTypeFunc 

func (c *Client) SetAutoDecodeAllTypeFunc(fn func(contentType string) bool) *Client

SetAutoDecodeAllTypeFunc set the custmize function that determins the content-type whether if should be auto-detected and decode to utf-8

func (*Client) SetAutoDecodeContentType 

func (c *Client) SetAutoDecodeContentType(contentTypes ...string) *Client

SetAutoDecodeContentType set the content types that will be auto-detected and decode to utf-8

func (*Client) SetBaseURL 

func (c *Client) SetBaseURL(u string) *Client

SetBaseURL set the default base url, will be used if request url is a relative url.

func (*Client) SetCertFromFile 

func (c *Client) SetCertFromFile(certFile, keyFile string) *Client

SetCertFromFile helps to set client certificates from cert and key file

func (*Client) SetCerts 

func (c *Client) SetCerts(certs ...tls.Certificate) *Client

SetCerts helps to set client certificates

func (*Client) SetCommonBasicAuth 

func (c *Client) SetCommonBasicAuth(username, password string) *Client

SetCommonBasicAuth set the basic auth for all requests.

func (*Client) SetCommonBearerAuthToken 

func (c *Client) SetCommonBearerAuthToken(token string) *Client

SetCommonBearerAuthToken set the bearer auth token for all requests.

func (*Client) SetCommonContentType 

func (c *Client) SetCommonContentType(ct string) *Client

SetCommonContentType set the `Content-Type` header for all requests.

func (*Client) SetCommonCookies 

func (c *Client) SetCommonCookies(cookies ...*http.Cookie) *Client

SetCommonCookies set cookies at client level.

func (*Client) SetCommonDumpOptions 

func (c *Client) SetCommonDumpOptions(opt *DumpOptions) *Client

SetCommonDumpOptions configures the underlying Transport's DumpOptions

func (*Client) SetCommonFormData 

func (c *Client) SetCommonFormData(data map[string]string) *Client

SetCommonFormData set the form data from map for all requests which method allows payload.

func (*Client) SetCommonFormDataFromValues 

func (c *Client) SetCommonFormDataFromValues(data urlpkg.Values) *Client

SetCommonFormDataFromValues set the form data from url.Values for all requests which method allows payload.

func (*Client) SetCommonHeader 

func (c *Client) SetCommonHeader(key, value string) *Client

SetCommonHeader set a header for all requests.

func (*Client) SetCommonHeaders 

func (c *Client) SetCommonHeaders(hdrs map[string]string) *Client

SetCommonHeaders set headers for all requests.

func (*Client) SetCommonQueryParam 

func (c *Client) SetCommonQueryParam(key, value string) *Client

SetCommonQueryParam set a URL query parameter with a key-value pair at client level.

func (*Client) SetCommonQueryParams 

func (c *Client) SetCommonQueryParams(params map[string]string) *Client

SetCommonQueryParams sets the URL query parameters with a map at client level.

func (*Client) SetCommonQueryString 

func (c *Client) SetCommonQueryString(query string) *Client

SetCommonQueryString set URL query parameters using the raw query string.

func (*Client) SetCookieJar 

func (c *Client) SetCookieJar(jar http.CookieJar) *Client

SetCookieJar set the `CookeJar` to the underlying `http.Client`

func (*Client) SetDial added in v3.2.0 

func (c *Client) SetDial(fn func(ctx context.Context, network, addr string) (net.Conn, error)) *Client

SetDial set the customized Dial function.

func (*Client) SetDialTLS added in v3.2.0 

func (c *Client) SetDialTLS(fn func(ctx context.Context, network, addr string) (net.Conn, error)) *Client

SetDialTLS set the customized DialTLSContext

func (*Client) SetJsonMarshal 

func (c *Client) SetJsonMarshal(fn func(v interface{}) ([]byte, error)) *Client

SetJsonMarshal set json marshal function which will be used to marshal request body.

func (*Client) SetJsonUnmarshal 

func (c *Client) SetJsonUnmarshal(fn func(data []byte, v interface{}) error) *Client

SetJsonUnmarshal set the JSON unmarshal function which will be used to unmarshal response body.

func (*Client) SetLogger 

func (c *Client) SetLogger(log Logger) *Client

SetLogger set the logger for req, set to nil to disable logger.

func (*Client) SetOutputDirectory 

func (c *Client) SetOutputDirectory(dir string) *Client

SetOutputDirectory set output directory that response will be downloaded to.

func (*Client) SetProxy 

func (c *Client) SetProxy(proxy func(*http.Request) (*urlpkg.URL, error)) *Client

SetProxy set the proxy function.

func (*Client) SetProxyURL 

func (c *Client) SetProxyURL(proxyUrl string) *Client

SetProxyURL set a proxy from the proxy url.

func (*Client) SetRedirectPolicy 

func (c *Client) SetRedirectPolicy(policies ...RedirectPolicy) *Client

SetRedirectPolicy helps to set the RedirectPolicy.

func (*Client) SetRootCertFromString 

func (c *Client) SetRootCertFromString(pemContent string) *Client

SetRootCertFromString helps to set root CA cert from string

func (*Client) SetRootCertsFromFile 

func (c *Client) SetRootCertsFromFile(pemFiles ...string) *Client

SetRootCertsFromFile helps to set root certs from files

func (*Client) SetScheme 

func (c *Client) SetScheme(scheme string) *Client

SetScheme sets custom default scheme in the client, will be used when there is no scheme in the request url.

func (*Client) SetTLSClientConfig 

func (c *Client) SetTLSClientConfig(conf *tls.Config) *Client

SetTLSClientConfig sets the client tls config.

func (*Client) SetTLSHandshakeTimeout added in v3.2.0 

func (c *Client) SetTLSHandshakeTimeout(timeout time.Duration) *Client

SetTLSHandshakeTimeout set the TLS handshake timeout.

func (*Client) SetTimeout 

func (c *Client) SetTimeout(d time.Duration) *Client

SetTimeout set the timeout for all requests.

func (*Client) SetUserAgent 

func (c *Client) SetUserAgent(userAgent string) *Client

SetUserAgent set the "User-Agent" header for all requests.

func (*Client) SetXmlMarshal 

func (c *Client) SetXmlMarshal(fn func(v interface{}) ([]byte, error)) *Client

SetXmlMarshal set the XML marshal function which will be used to marshal request body.

func (*Client) SetXmlUnmarshal 

func (c *Client) SetXmlUnmarshal(fn func(data []byte, v interface{}) error) *Client

SetXmlUnmarshal set the XML unmarshal function which will be used to unmarshal response body.

type DumpOptions 

type DumpOptions struct {
	Output         io.Writer
	RequestHeader  bool
	RequestBody    bool
	ResponseHeader bool
	ResponseBody   bool
	Async          bool
}

DumpOptions controls the dump behavior.

func (*DumpOptions) Clone 

func (do *DumpOptions) Clone() *DumpOptions

type Logger 

type Logger interface {
	Errorf(format string, v ...interface{})
	Warnf(format string, v ...interface{})
	Debugf(format string, v ...interface{})
}

Logger interface is to abstract the logging from Resty. Gives control to the Resty users, choice of the logger.

func NewLogger 

func NewLogger(output io.Writer, prefix string, flag int) Logger

NewLogger create a Logger wraps the *log.Logger

type RedirectPolicy 

type RedirectPolicy func(req *http.Request, via []*http.Request) error

func AllowedDomainRedirectPolicy 

func AllowedDomainRedirectPolicy(hosts ...string) RedirectPolicy

AllowedDomainRedirectPolicy allows redirect only if the redirected domain match one of the domain that specified.

func AllowedHostRedirectPolicy 

func AllowedHostRedirectPolicy(hosts ...string) RedirectPolicy

AllowedHostRedirectPolicy allows redirect only if the redirected host match one of the host that specified.

func MaxRedirectPolicy 

func MaxRedirectPolicy(noOfRedirect int) RedirectPolicy

MaxRedirectPolicy specifies the max number of redirect

func NoRedirectPolicy 

func NoRedirectPolicy() RedirectPolicy

NoRedirectPolicy disable redirect behaviour

func SameDomainRedirectPolicy 

func SameDomainRedirectPolicy() RedirectPolicy

func SameHostRedirectPolicy 

func SameHostRedirectPolicy() RedirectPolicy

SameHostRedirectPolicy allows redirect only if the redirected host is the same as original host, e.g. redirect to "www.imroc.cc" from "imroc.cc" is not the allowed.

type Request 

type Request struct {
	URL         string
	PathParams  map[string]string
	QueryParams urlpkg.Values
	FormData    urlpkg.Values
	Headers     http.Header
	Cookies     []*http.Cookie
	Result      interface{}
	Error       interface{}

	RawRequest *http.Request
	StartTime  time.Time
	// contains filtered or unexported fields
}

Request is the http request

func AddQueryParam 

func AddQueryParam(key, value string) *Request

AddQueryParam is a global wrapper methods which delegated to the default client, create a request and AddQueryParam for request.

func DisableTrace 

func DisableTrace() *Request

DisableTrace is a global wrapper methods which delegated to the default client, create a request and DisableTrace for request.

func EnableDump 

func EnableDump() *Request

EnableDump is a global wrapper methods which delegated to the default client, create a request and EnableDump for request.

func EnableDumpTo 

func EnableDumpTo(output io.Writer) *Request

EnableDumpTo is a global wrapper methods which delegated to the default client, create a request and EnableDumpTo for request.

func EnableDumpToFile 

func EnableDumpToFile(filename string) *Request

EnableDumpToFile is a global wrapper methods which delegated to the default client, create a request and EnableDumpToFile for request.

func EnableDumpWithoutBody 

func EnableDumpWithoutBody() *Request

EnableDumpWithoutBody is a global wrapper methods which delegated to the default client, create a request and EnableDumpWithoutBody for request.

func EnableDumpWithoutHeader 

func EnableDumpWithoutHeader() *Request

EnableDumpWithoutHeader is a global wrapper methods which delegated to the default client, create a request and EnableDumpWithoutHeader for request.

func EnableDumpWithoutRequest 

func EnableDumpWithoutRequest() *Request

EnableDumpWithoutRequest is a global wrapper methods which delegated to the default client, create a request and EnableDumpWithoutRequest for request.

func EnableDumpWithoutRequestBody added in v3.1.0 

func EnableDumpWithoutRequestBody() *Request

EnableDumpWithoutRequestBody is a global wrapper methods which delegated to the default client, create a request and EnableDumpWithoutRequestBody for request.

func EnableDumpWithoutResponse 

func EnableDumpWithoutResponse() *Request

EnableDumpWithoutResponse is a global wrapper methods which delegated to the default client, create a request and EnableDumpWithoutResponse for request.

func EnableDumpWithoutResponseBody added in v3.1.0 

func EnableDumpWithoutResponseBody() *Request

EnableDumpWithoutResponseBody is a global wrapper methods which delegated to the default client, create a request and EnableDumpWithoutResponseBody for request.

func EnableTrace 

func EnableTrace() *Request

EnableTrace is a global wrapper methods which delegated to the default client, create a request and EnableTrace for request.

func NewRequest 

func NewRequest() *Request

NewRequest is a global wrapper methods which delegated to the default client's NewRequest.

func R 

func R() *Request

R is a global wrapper methods which delegated to the default client's R().

func SetBasicAuth 

func SetBasicAuth(username, password string) *Request

SetBasicAuth is a global wrapper methods which delegated to the default client, create a request and SetBasicAuth for request.

func SetBearerAuthToken 

func SetBearerAuthToken(token string) *Request

SetBearerAuthToken is a global wrapper methods which delegated to the default client, create a request and SetBearerAuthToken for request.

func SetBody 

func SetBody(body interface{}) *Request

SetBody is a global wrapper methods which delegated to the default client, create a request and SetBody for request.

func SetBodyBytes 

func SetBodyBytes(body []byte) *Request

SetBodyBytes is a global wrapper methods which delegated to the default client, create a request and SetBodyBytes for request.

func SetBodyJsonBytes 

func SetBodyJsonBytes(body []byte) *Request

SetBodyJsonBytes is a global wrapper methods which delegated to the default client, create a request and SetBodyJsonBytes for request.

func SetBodyJsonMarshal 

func SetBodyJsonMarshal(v interface{}) *Request

SetBodyJsonMarshal is a global wrapper methods which delegated to the default client, create a request and SetBodyJsonMarshal for request.

func SetBodyJsonString 

func SetBodyJsonString(body string) *Request

SetBodyJsonString is a global wrapper methods which delegated to the default client, create a request and SetBodyJsonString for request.

func SetBodyString 

func SetBodyString(body string) *Request

SetBodyString is a global wrapper methods which delegated to the default client, create a request and SetBodyString for request.

func SetBodyXmlBytes 

func SetBodyXmlBytes(body []byte) *Request

SetBodyXmlBytes is a global wrapper methods which delegated to the default client, create a request and SetBodyXmlBytes for request.

func SetBodyXmlMarshal 

func SetBodyXmlMarshal(v interface{}) *Request

SetBodyXmlMarshal is a global wrapper methods which delegated to the default client, create a request and SetBodyXmlMarshal for request.

func SetBodyXmlString 

func SetBodyXmlString(body string) *Request

SetBodyXmlString is a global wrapper methods which delegated to the default client, create a request and SetBodyXmlString for request.

func SetContentType 

func SetContentType(contentType string) *Request

SetContentType is a global wrapper methods which delegated to the default client, create a request and SetContentType for request.

func SetContext 

func SetContext(ctx context.Context) *Request

SetContext is a global wrapper methods which delegated to the default client, create a request and SetContext for request.

func SetCookies 

func SetCookies(cookies ...*http.Cookie) *Request

SetCookies is a global wrapper methods which delegated to the default client, create a request and SetCookies for request.

func SetDumpOptions 

func SetDumpOptions(opt *DumpOptions) *Request

func SetError 

func SetError(error interface{}) *Request

SetError is a global wrapper methods which delegated to the default client, create a request and SetError for request.

func SetFile 

func SetFile(paramName, filePath string) *Request

SetFile is a global wrapper methods which delegated to the default client, create a request and SetFile for request.

func SetFileReader 

func SetFileReader(paramName, filePath string, reader io.Reader) *Request

SetFileReader is a global wrapper methods which delegated to the default client, create a request and SetFileReader for request.

func SetFiles 

func SetFiles(files map[string]string) *Request

SetFiles is a global wrapper methods which delegated to the default client, create a request and SetFiles for request.

func SetFormData 

func SetFormData(data map[string]string) *Request

SetFormData is a global wrapper methods which delegated to the default client, create a request and SetFormData for request.

func SetFormDataFromValues 

func SetFormDataFromValues(data urlpkg.Values) *Request

SetFormDataFromValues is a global wrapper methods which delegated to the default client, create a request and SetFormDataFromValues for request.

func SetHeader 

func SetHeader(key, value string) *Request

SetHeader is a global wrapper methods which delegated to the default client, create a request and SetHeader for request.

func SetHeaders 

func SetHeaders(hdrs map[string]string) *Request

SetHeaders is a global wrapper methods which delegated to the default client, create a request and SetHeaders for request.

func SetOutput 

func SetOutput(output io.Writer) *Request

SetOutput is a global wrapper methods which delegated to the default client, create a request and SetOutput for request.

func SetOutputFile 

func SetOutputFile(file string) *Request

SetOutputFile is a global wrapper methods which delegated to the default client, create a request and SetOutputFile for request.

func SetPathParam 

func SetPathParam(key, value string) *Request

SetPathParam is a global wrapper methods which delegated to the default client, create a request and SetPathParam for request.

func SetPathParams 

func SetPathParams(params map[string]string) *Request

SetPathParams is a global wrapper methods which delegated to the default client, create a request and SetPathParams for request.

func SetQueryParam 

func SetQueryParam(key, value string) *Request

SetQueryParam is a global wrapper methods which delegated to the default client, create a request and SetQueryParam for request.

func SetQueryParams 

func SetQueryParams(params map[string]string) *Request

SetQueryParams is a global wrapper methods which delegated to the default client, create a request and SetQueryParams for request.

func SetQueryString 

func SetQueryString(query string) *Request

SetQueryString is a global wrapper methods which delegated to the default client, create a request and SetQueryString for request.

func SetResult 

func SetResult(result interface{}) *Request

SetResult is a global wrapper methods which delegated to the default client, create a request and SetResult for request.

func (*Request) AddQueryParam 

func (r *Request) AddQueryParam(key, value string) *Request

AddQueryParam add a URL query parameter with a key-value pair at request level.

func (*Request) Context 

func (r *Request) Context() context.Context

Context method returns the Context if its already set in request otherwise it creates new one using `context.Background()`.

func (*Request) Delete 

func (r *Request) Delete(url string) (*Response, error)

Delete Send the request with DELETE method and specified url.

func (*Request) DisableTrace 

func (r *Request) DisableTrace() *Request

DisableTrace disables trace.

func (*Request) EnableDump 

func (r *Request) EnableDump() *Request

EnableDump enables dump, including all content for the request and response by default.

func (*Request) EnableDumpTo 

func (r *Request) EnableDumpTo(output io.Writer) *Request

EnableDumpTo enables dump and save to the specified io.Writer.

func (*Request) EnableDumpToFile 

func (r *Request) EnableDumpToFile(filename string) *Request

EnableDumpToFile enables dump and save to the specified filename.

func (*Request) EnableDumpWithoutBody 

func (r *Request) EnableDumpWithoutBody() *Request

EnableDumpWithoutBody enables dump only header for the request and response.

func (*Request) EnableDumpWithoutHeader 

func (r *Request) EnableDumpWithoutHeader() *Request

EnableDumpWithoutHeader enables dump only body for the request and response.

func (*Request) EnableDumpWithoutRequest 

func (r *Request) EnableDumpWithoutRequest() *Request

EnableDumpWithoutRequest enables dump only response.

func (*Request) EnableDumpWithoutRequestBody added in v3.1.0 

func (r *Request) EnableDumpWithoutRequestBody() *Request

EnableDumpWithoutRequestBody enables dump with request body excluded, can be used in upload request to avoid dump the unreadable binary content.

func (*Request) EnableDumpWithoutResponse 

func (r *Request) EnableDumpWithoutResponse() *Request

EnableDumpWithoutResponse enables dump only request.

func (*Request) EnableDumpWithoutResponseBody added in v3.1.0 

func (r *Request) EnableDumpWithoutResponseBody() *Request

EnableDumpWithoutResponseBody enables dump with response body excluded, can be used in download request to avoid dump the unreadable binary content.

func (*Request) EnableTrace 

func (r *Request) EnableTrace() *Request

EnableTrace enables trace.

func (*Request) Get 

func (r *Request) Get(url string) (*Response, error)

Get Send the request with GET method and specified url.

func (*Request) Head 

func (r *Request) Head(url string) (*Response, error)

Head Send the request with HEAD method and specified url.

func (*Request) MustDelete 

func (r *Request) MustDelete(url string) *Response

MustDelete like Delete, panic if error happens, should only be used to test without error handling.

func (*Request) MustGet 

func (r *Request) MustGet(url string) *Response

MustGet like Get, panic if error happens, should only be used to test without error handling.

func (*Request) MustHead 

func (r *Request) MustHead(url string) *Response

MustHead like Head, panic if error happens, should only be used to test without error handling.

func (*Request) MustOptions 

func (r *Request) MustOptions(url string) *Response

MustOptions like Options, panic if error happens, should only be used to test without error handling.

func (*Request) MustPatch 

func (r *Request) MustPatch(url string) *Response

MustPatch like Patch, panic if error happens, should only be used to test without error handling.

func (*Request) MustPost 

func (r *Request) MustPost(url string) *Response

MustPost like Post, panic if error happens.

func (*Request) MustPut 

func (r *Request) MustPut(url string) *Response

MustPut like Put, panic if error happens, should only be used to test without error handling.

func (*Request) Options 

func (r *Request) Options(url string) (*Response, error)

Options Send the request with OPTIONS method and specified url.

func (*Request) Patch 

func (r *Request) Patch(url string) (*Response, error)

Patch Send the request with PATCH method and specified url.

func (*Request) Post 

func (r *Request) Post(url string) (*Response, error)

Post Send the request with POST method and specified url.

func (*Request) Put 

func (r *Request) Put(url string) (*Response, error)

Put Send the request with Put method and specified url.

func (*Request) Send 

func (r *Request) Send(method, url string) (*Response, error)

Send sends the http request.

func (*Request) SetBasicAuth 

func (r *Request) SetBasicAuth(username, password string) *Request

SetBasicAuth set the basic auth at request level.

func (*Request) SetBearerAuthToken 

func (r *Request) SetBearerAuthToken(token string) *Request

SetBearerAuthToken set the bearer auth token at request level.

func (*Request) SetBody 

func (r *Request) SetBody(body interface{}) *Request

SetBody set the request body, accepts string, []byte, io.Reader, map and struct.

func (*Request) SetBodyBytes 

func (r *Request) SetBodyBytes(body []byte) *Request

SetBodyBytes set the request body as []byte.

func (*Request) SetBodyJsonBytes 

func (r *Request) SetBodyJsonBytes(body []byte) *Request

SetBodyJsonBytes set the request body as []byte and set Content-Type header as "application/json; charset=utf-8"

func (*Request) SetBodyJsonMarshal 

func (r *Request) SetBodyJsonMarshal(v interface{}) *Request

SetBodyJsonMarshal set the request body that marshaled from object, and set Content-Type header as "application/json; charset=utf-8"

func (*Request) SetBodyJsonString 

func (r *Request) SetBodyJsonString(body string) *Request

SetBodyJsonString set the request body as string and set Content-Type header as "application/json; charset=utf-8"

func (*Request) SetBodyString 

func (r *Request) SetBodyString(body string) *Request

SetBodyString set the request body as string.

func (*Request) SetBodyXmlBytes 

func (r *Request) SetBodyXmlBytes(body []byte) *Request

SetBodyXmlBytes set the request body as []byte and set Content-Type header as "text/xml; charset=utf-8"

func (*Request) SetBodyXmlMarshal 

func (r *Request) SetBodyXmlMarshal(v interface{}) *Request

SetBodyXmlMarshal set the request body that marshaled from object, and set Content-Type header as "text/xml; charset=utf-8"

func (*Request) SetBodyXmlString 

func (r *Request) SetBodyXmlString(body string) *Request

SetBodyXmlString set the request body as string and set Content-Type header as "text/xml; charset=utf-8"

func (*Request) SetContentType 

func (r *Request) SetContentType(contentType string) *Request

SetContentType set the `Content-Type` for the request.

func (*Request) SetContext 

func (r *Request) SetContext(ctx context.Context) *Request

SetContext method sets the context.Context for current Request. It allows to interrupt the request execution if ctx.Done() channel is closed. See https://blog.golang.org/context article and the "context" package documentation.

func (*Request) SetCookies 

func (r *Request) SetCookies(cookies ...*http.Cookie) *Request

SetCookies set cookies at request level.

func (*Request) SetDumpOptions 

func (r *Request) SetDumpOptions(opt *DumpOptions) *Request

SetDumpOptions sets DumpOptions at request level.

func (*Request) SetError 

func (r *Request) SetError(error interface{}) *Request

SetError set the result that response body will be unmarshaled to if request is error ( status `code >= 400`).

func (*Request) SetFile 

func (r *Request) SetFile(paramName, filePath string) *Request

SetFile sets up a multipart form, read file from filePath automatically to upload.

func (*Request) SetFileReader 

func (r *Request) SetFileReader(paramName, filePath string, reader io.Reader) *Request

SetFileReader sets up a multipart form with a reader to upload file.

func (*Request) SetFiles 

func (r *Request) SetFiles(files map[string]string) *Request

SetFiles sets up a multipart form from a map, which key is the param name, value is the file path.

func (*Request) SetFormData 

func (r *Request) SetFormData(data map[string]string) *Request

SetFormData set the form data from map, not used if method not allow payload.

func (*Request) SetFormDataFromValues 

func (r *Request) SetFormDataFromValues(data urlpkg.Values) *Request

SetFormDataFromValues set the form data from url.Values, not used if method not allow payload.

func (*Request) SetHeader 

func (r *Request) SetHeader(key, value string) *Request

SetHeader set a header at request level.

func (*Request) SetHeaders 

func (r *Request) SetHeaders(hdrs map[string]string) *Request

SetHeaders set the header at request level.

func (*Request) SetOutput 

func (r *Request) SetOutput(output io.Writer) *Request

SetOutput the io.Writer that response body will be downloaded to.

func (*Request) SetOutputFile 

func (r *Request) SetOutputFile(file string) *Request

SetOutputFile the file that response body will be downloaded to.

func (*Request) SetPathParam 

func (r *Request) SetPathParam(key, value string) *Request

SetPathParam sets the URL path parameters from a key-value paire at request level.

func (*Request) SetPathParams 

func (r *Request) SetPathParams(params map[string]string) *Request

SetPathParams sets the URL path parameters from a map at request level.

func (*Request) SetQueryParam 

func (r *Request) SetQueryParam(key, value string) *Request

SetQueryParam set an URL query parameter with a key-value pair at request level.

func (*Request) SetQueryParams 

func (r *Request) SetQueryParams(params map[string]string) *Request

SetQueryParams sets the URL query parameters with a map at client level.

func (*Request) SetQueryString 

func (r *Request) SetQueryString(query string) *Request

SetQueryString set URL query parameters using the raw query string.

func (*Request) SetResult 

func (r *Request) SetResult(result interface{}) *Request

SetResult set the result that response body will be unmarshaled to if request is success (status `code >= 200 and <= 299`).

func (*Request) TraceInfo 

func (r *Request) TraceInfo() TraceInfo

TraceInfo returns the trace information, only available when trace is enabled.

type RequestMiddleware 

type RequestMiddleware func(*Client, *Request) error

RequestMiddleware type is for request middleware, called before a request is sent

type Response 

type Response struct {
	*http.Response
	Request *Request
	// contains filtered or unexported fields
}

Response is the http response.

func Delete 

func Delete(url string) (*Response, error)

Delete is a global wrapper methods which delegated to the default client, create a request and Delete for request.

func Get 

func Get(url string) (*Response, error)

Get is a global wrapper methods which delegated to the default client, create a request and Get for request. 

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

Head is a global wrapper methods which delegated to the default client, create a request and Head for request.

func MustDelete 

func MustDelete(url string) *Response

MustDelete is a global wrapper methods which delegated to the default client, create a request and MustDelete for request.

func MustGet 

func MustGet(url string) *Response

MustGet is a global wrapper methods which delegated to the default client, create a request and MustGet for request.

func MustHead 

func MustHead(url string) *Response

MustHead is a global wrapper methods which delegated to the default client, create a request and MustHead for request.

func MustOptions 

func MustOptions(url string) *Response

MustOptions is a global wrapper methods which delegated to the default client, create a request and MustOptions for request.

func MustPatch 

func MustPatch(url string) *Response

MustPatch is a global wrapper methods which delegated to the default client, create a request and MustPatch for request.

func MustPost 

func MustPost(url string) *Response

MustPost is a global wrapper methods which delegated to the default client, create a request and Get for request.

func MustPut 

func MustPut(url string) *Response

MustPut is a global wrapper methods which delegated to the default client, create a request and MustPut for request.

func Options 

func Options(url string) (*Response, error)

Options is a global wrapper methods which delegated to the default client, create a request and Options for request.

func Patch 

func Patch(url string) (*Response, error)

Patch is a global wrapper methods which delegated to the default client, create a request and Patch for request.

func Post 

func Post(url string) (*Response, error)

Post is a global wrapper methods which delegated to the default client, create a request and Post for request.

func Put 

func Put(url string) (*Response, error)

Put is a global wrapper methods which delegated to the default client, create a request and Put for request.

func (*Response) Bytes 

func (r *Response) Bytes() []byte

Bytes return the response body as []bytes that hava already been read, could be nil if not read, the following cases are already read:

  1. `Request.SetResult` or `Request.SetError` is called.
  2. `Client.DisableAutoReadResponse(false)` is not called, also `Request.SetOutput` and `Request.SetOutputFile` is not called.

func (*Response) Dump 

func (r *Response) Dump() string

Dump return the string content that have been dumped for the request. `Request.Dump` or `Request.DumpXXX` MUST have been called.

func (*Response) Error 

func (r *Response) Error() interface{}

Error returns the error object if it has one.

func (*Response) GetContentType 

func (r *Response) GetContentType() string

GetContentType return the `Content-Type` header value.

func (*Response) IsError 

func (r *Response) IsError() bool

IsError method returns true if HTTP status `code >= 400` otherwise false.

func (*Response) IsSuccess 

func (r *Response) IsSuccess() bool

IsSuccess method returns true if HTTP status `code >= 200 and <= 299` otherwise false.

func (*Response) ReceivedAt 

func (r *Response) ReceivedAt() time.Time

ReceivedAt returns the timestamp that response we received.

func (*Response) Result 

func (r *Response) Result() interface{}

Result returns the response value as an object if it has one

func (*Response) String 

func (r *Response) String() string

String returns the response body as string that hava already been read, could be nil if not read, the following cases are already read:

  1. `Request.SetResult` or `Request.SetError` is called.
  2. `Client.DisableAutoReadResponse(false)` is not called, also `Request.SetOutput` and `Request.SetOutputFile` is not called.

func (*Response) ToBytes 

func (r *Response) ToBytes() ([]byte, error)

ToBytes returns the response body as []byte, read body if not have been read.

func (*Response) ToString 

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

ToString returns the response body as string, read body if not have been read.

func (*Response) TotalTime 

func (r *Response) TotalTime() time.Duration

TotalTime returns the total time of the request, from request we sent to response we received.

func (*Response) TraceInfo 

func (r *Response) TraceInfo() TraceInfo

TraceInfo returns the TraceInfo from Request.

func (*Response) Unmarshal 

func (r *Response) Unmarshal(v interface{}) error

Unmarshal unmarshals response body into the specified object according to response `Content-Type`.

func (*Response) UnmarshalJson 

func (r *Response) UnmarshalJson(v interface{}) error

UnmarshalJson unmarshals JSON response body into the specified object.

func (*Response) UnmarshalXml 

func (r *Response) UnmarshalXml(v interface{}) error

UnmarshalXml unmarshals XML response body into the specified object.

type ResponseMiddleware 

type ResponseMiddleware func(*Client, *Response) error

ResponseMiddleware type is for response middleware, called after a response has been received

type ResponseOptions 

type ResponseOptions struct {
	// DisableAutoDecode, if true, prevents auto detect response
	// body's charset and decode it to utf-8
	DisableAutoDecode bool

	// AutoDecodeContentType specifies an optional function for determine
	// whether the response body should been auto decode to utf-8.
	// Only valid when DisableAutoDecode is true.
	AutoDecodeContentType func(contentType string) bool
}

ResponseOptions determines that how should the response been processed.

type TLSConn added in v3.2.0 

type TLSConn interface {
	net.Conn
	ConnectionState() tls.ConnectionState
	Handshake() error
}

TLSConn is the recommended interface for the connection returned by the DailTLS function (Client.SetDialTLS, Transport.DialTLSContext), so that the TLS handshake negotiation can automatically decide whether to use HTTP2 or HTTP1 (ALPN). If this interface is not implemented, HTTP1 will be used by default.

type TraceInfo 

type TraceInfo struct {
	// DNSLookupTime is a duration that transport took to perform
	// DNS lookup.
	DNSLookupTime time.Duration

	// ConnectTime is a duration that took to obtain a successful connection.
	ConnectTime time.Duration

	// TCPConnectTime is a duration that took to obtain the TCP connection.
	TCPConnectTime time.Duration

	// TLSHandshakeTime is a duration that TLS handshake took place.
	TLSHandshakeTime time.Duration

	// FirstResponseTime is a duration that server took to respond first byte since
	// connection ready (after tls handshake if it's tls and not a reused connection).
	FirstResponseTime time.Duration

	// ResponseTime is a duration since first response byte from server to
	// request completion.
	ResponseTime time.Duration

	// TotalTime is a duration that total request took end-to-end.
	TotalTime time.Duration

	// IsConnReused is whether this connection has been previously
	// used for another HTTP request.
	IsConnReused bool

	// IsConnWasIdle is whether this connection was obtained from an
	// idle pool.
	IsConnWasIdle bool

	// ConnIdleTime is a duration how long the connection was previously
	// idle, if IsConnWasIdle is true.
	ConnIdleTime time.Duration

	// RemoteAddr returns the remote network address.
	RemoteAddr net.Addr
}

func (TraceInfo) Blame 

func (t TraceInfo) Blame() string

func (TraceInfo) String 

func (t TraceInfo) String() string

type Transport 

type Transport struct {

	// ForceHTTP1 force using HTTP/1.1
	ForceHTTP1 bool

	// Proxy specifies a function to return a proxy for a given
	// Request. If the function returns a non-nil error, the
	// request is aborted with the provided error.
	//
	// The proxy type is determined by the URL scheme. "http",
	// "https", and "socks5" are supported. If the scheme is empty,
	// "http" is assumed.
	//
	// If Proxy is nil or returns a nil *URL, no proxy is used.
	Proxy func(*http.Request) (*url.URL, error)

	// DialContext specifies the dial function for creating unencrypted TCP connections.
	// If DialContext is nil, then the transport dials using package net.
	//
	// DialContext runs concurrently with calls to RoundTrip.
	// A RoundTrip call that initiates a dial may end up using
	// a connection dialed previously when the earlier connection
	// becomes idle before the later DialContext completes.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)

	// DialTLSContext specifies an optional dial function for creating
	// TLS connections for non-proxied HTTPS requests.
	//
	// If DialTLSContext is nil, DialContext and TLSClientConfig are used.
	//
	// If DialTLSContext is set, the Dial and DialContext hooks are not used for HTTPS
	// requests and the TLSClientConfig and TLSHandshakeTimeout
	// are ignored. The returned net.Conn is assumed to already be
	// past the TLS handshake.
	DialTLSContext func(ctx context.Context, network, addr string) (net.Conn, error)

	// TLSClientConfig specifies the TLS configuration to use with
	// tls.Client.
	// If nil, the default configuration is used.
	// If non-nil, HTTP/2 support may not be enabled by default.
	TLSClientConfig *tls.Config

	// TLSHandshakeTimeout specifies the maximum amount of time waiting to
	// wait for a TLS handshake. Zero means no timeout.
	TLSHandshakeTimeout time.Duration

	// DisableKeepAlives, if true, disables HTTP keep-alives and
	// will only use the connection to the server for a single
	// HTTP request.
	//
	// This is unrelated to the similarly named TCP keep-alives.
	DisableKeepAlives bool

	// DisableCompression, if true, prevents the Transport from
	// requesting compression with an "Accept-Encoding: gzip"
	// request header when the Request contains no existing
	// Accept-Encoding value. If the Transport requests gzip on
	// its own and gets a gzipped response, it's transparently
	// decoded in the Response.Body. However, if the user
	// explicitly requested gzip it is not automatically
	// uncompressed.
	DisableCompression bool

	// MaxIdleConns controls the maximum number of idle (keep-alive)
	// connections across all hosts. Zero means no limit.
	MaxIdleConns int

	// MaxIdleConnsPerHost, if non-zero, controls the maximum idle
	// (keep-alive) connections to keep per-host. If zero,
	// defaultMaxIdleConnsPerHost is used.
	MaxIdleConnsPerHost int

	// MaxConnsPerHost optionally limits the total number of
	// connections per host, including connections in the dialing,
	// active, and idle states. On limit violation, dials will block.
	//
	// Zero means no limit.
	MaxConnsPerHost int

	// IdleConnTimeout is the maximum amount of time an idle
	// (keep-alive) connection will remain idle before closing
	// itself.
	// Zero means no limit.
	IdleConnTimeout time.Duration

	// ResponseHeaderTimeout, if non-zero, specifies the amount of
	// time to wait for a server's response headers after fully
	// writing the request (including its body, if any). This
	// time does not include the time to read the response body.
	ResponseHeaderTimeout time.Duration

	// ExpectContinueTimeout, if non-zero, specifies the amount of
	// time to wait for a server's first response headers after fully
	// writing the request headers if the request has an
	// "Expect: 100-continue" header. Zero means no timeout and
	// causes the body to be sent immediately, without
	// waiting for the server to approve.
	// This time does not include the time to send the request header.
	ExpectContinueTimeout time.Duration

	// TLSNextProto specifies how the Transport switches to an
	// alternate protocol (such as HTTP/2) after a TLS ALPN
	// protocol negotiation. If Transport dials an TLS connection
	// with a non-empty protocol name and TLSNextProto contains a
	// map entry for that key (such as "h2"), then the func is
	// called with the request's authority (such as "example.com"
	// or "example.com:1234") and the TLS connection. The function
	// must return a http.RoundTripper that then handles the request.
	// If TLSNextProto is not nil, HTTP/2 support is not enabled
	// automatically.
	TLSNextProto map[string]func(authority string, c TLSConn) http.RoundTripper

	// ProxyConnectHeader optionally specifies headers to send to
	// proxies during CONNECT requests.
	// To set the header dynamically, see GetProxyConnectHeader.
	ProxyConnectHeader http.Header

	// GetProxyConnectHeader optionally specifies a func to return
	// headers to send to proxyURL during a CONNECT request to the
	// ip:port target.
	// If it returns an error, the Transport's RoundTrip fails with
	// that error. It can return (nil, nil) to not add headers.
	// If GetProxyConnectHeader is non-nil, ProxyConnectHeader is
	// ignored.
	GetProxyConnectHeader func(ctx context.Context, proxyURL *url.URL, target string) (http.Header, error)

	// MaxResponseHeaderBytes specifies a limit on how many
	// response bytes are allowed in the server's response
	// header.
	//
	// Zero means to use a default limit.
	MaxResponseHeaderBytes int64

	// WriteBufferSize specifies the size of the write buffer used
	// when writing to the transport.
	// If zero, a default (currently 4KB) is used.
	WriteBufferSize int

	// ReadBufferSize specifies the size of the read buffer used
	// when reading from the transport.
	// If zero, a default (currently 4KB) is used.
	ReadBufferSize int

	// ForceAttemptHTTP2 controls whether HTTP/2 is enabled when a non-zero
	// Dial, DialTLS, or DialContext func or TLSClientConfig is provided.
	// By default, use of any those fields conservatively disables HTTP/2.
	// To use a custom dialer or TLS config and still attempt HTTP/2
	// upgrades, set this to true.
	ForceAttemptHTTP2 bool

	*ResponseOptions

	Debugf func(format string, v ...interface{})
	// contains filtered or unexported fields
}

Transport is an implementation of http.RoundTripper that supports HTTP, HTTPS, and HTTP proxies (for either HTTP or HTTPS with CONNECT).

By default, Transport caches connections for future re-use. This may leave many open connections when accessing many hosts. This behavior can be managed using Transport's CloseIdleConnections method and the MaxIdleConnsPerHost and DisableKeepAlives fields.

Transports should be reused instead of created as needed. Transports are safe for concurrent use by multiple goroutines.

A Transport is a low-level primitive for making HTTP and HTTPS requests. For high-level functionality, such as cookies and redirects, see Client.

Transport uses HTTP/1.1 for HTTP URLs and either HTTP/1.1 or HTTP/2 for HTTPS URLs, depending on whether the server supports HTTP/2, and how the Transport is configured. The DefaultTransport supports HTTP/2. To explicitly enable HTTP/2 on a transport, use golang.org/x/net/http2 and call ConfigureTransport. See the package docs for more about HTTP/2.

Responses with status codes in the 1xx range are either handled automatically (100 expect-continue) or ignored. The one exception is HTTP status code 101 (Switching Protocols), which is considered a terminal status and returned by RoundTrip. To see the ignored 1xx responses, use the httptrace trace package's ClientTrace.Got1xxResponse.

Transport only retries a request upon encountering a network error if the request is idempotent and either has no body or has its Request.GetBody defined. HTTP requests are considered idempotent if they have HTTP methods GET, HEAD, OPTIONS, or TRACE; or if their Header map contains an "Idempotency-Key" or "X-Idempotency-Key" entry. If the idempotency key value is a zero-length slice, the request is treated as idempotent but the header is not sent on the wire.

func (*Transport) CancelRequest deprecated 

func (t *Transport) CancelRequest(req *http.Request)

CancelRequest cancels an in-flight request by closing its connection. CancelRequest should only be called after RoundTrip has returned.

Deprecated: Use Request.WithContext to create a request with a cancelable context instead. CancelRequest cannot cancel HTTP/2 requests.

func (*Transport) Clone 

func (t *Transport) Clone() *Transport

Clone returns a deep copy of t's exported fields.

func (*Transport) CloseIdleConnections 

func (t *Transport) CloseIdleConnections()

CloseIdleConnections closes any connections which were previously connected from previous requests but are now sitting idle in a "keep-alive" state. It does not interrupt any connections currently in use.

func (*Transport) DisableDump 

func (t *Transport) DisableDump()

DisableDump disables the dump.

func (*Transport) EnableDump 

func (t *Transport) EnableDump(opt *DumpOptions)

EnableDump enables the dump for all requests with specified dump options.

func (*Transport) RegisterProtocol 

func (t *Transport) RegisterProtocol(scheme string, rt http.RoundTripper)

RegisterProtocol registers a new protocol with scheme. The Transport will pass requests using the given scheme to rt. It is rt's responsibility to simulate HTTP request semantics.

RegisterProtocol can be used by other packages to provide implementations of protocol schemes like "ftp" or "file".

If rt.RoundTrip returns ErrSkipAltProtocol, the Transport will handle the RoundTrip itself for that one request, as if the protocol were not registered.

func (*Transport) RoundTrip 

func (t *Transport) RoundTrip(req *http.Request) (resp *http.Response, err error)

RoundTrip implements the RoundTripper interface.

For higher-level HTTP client support (such as handling of cookies and redirects), see Get, Post, and the Client type.

Like the RoundTripper interface, the error types returned by RoundTrip are unspecified.

Source Files

View all Source files

Directories

Path Synopsis
Package internal contains HTTP internals shared by net/http and net/http/httputil.
 Package internal contains HTTP internals shared by net/http and net/http/httputil.
ascii
charsetutil
godebug
Package godebug parses the GODEBUG environment variable.
 Package godebug parses the GODEBUG environment variable.
testcert
Package testcert contains a test-only localhost certificate.
 Package testcert contains a test-only localhost certificate.
util

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.