req

package module
v3.14.2 Latest Latest
Warning

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

 Go to latest Published: Aug 2, 2022 License: MIT Imports: 55 Imported by: 803

README

req

Simple Go HTTP client with Black Magic

Build Status Go Report Card License GitHub Releases Mentioned in Awesome Go

Documentation

Full documentation is available on the official website: https://req.cool.

Features

  • Simple and Powerful: Providing rich client-level and request-level settings, all of which are intuitive and chainable methods, and the request-level setting takes precedence if both are set.
  • Easy Debugging: Powerful and convenient debug utilities, including debug logs, performance traces, and even dump the complete request and response content (see Debugging).
  • Easy API Testing: API testing can be done with minimal code, no need to explicitly create any Requests and Clients, or even to handle errors (See Quick HTTP Test)
  • Smart by Default: Detect and decode to utf-8 automatically if possible to avoid garbled characters (See Auto Decode), marshal request body and unmarshal response body automatically according to the Content-Type.
  • Works fine with HTTP2: Support both with HTTP/2 and HTTP/1.1, and HTTP/2 is preferred by default if server support, you can also force the protocol if you want (See Force HTTP version).
  • Support Retry: Support automatic request retry and is fully customizable (See Retry).
  • Easy Download and Upload: You can download and upload files with simple request settings, and even set a callback to show real-time progress (See Download and Upload).
  • Exportable: Transport is exportable, which support dump requests, it's easy to integrate with existing http.Client, so you can debug APIs with minimal code change.
  • Extensible: Support Middleware for Request and Response (See Request and Response Middleware).

Get Started

Install

go get github.com/imroc/req/v3

Import

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

Basic Usage

// For testing, you can create and send a request with the global wrapper methods
// that use the default client behind the scenes to initiate the request (you can
// just treat package name `req` as a Client or Request, no need to create any client
// or Request explicitly).
req.DevMode() //  Use Client.DevMode to see all details, try and surprise :)
req.Get("https://httpbin.org/get") // Use Request.Get to send a GET request.

// In production, create a client explicitly and reuse it to send all requests
client := req.C(). // Use C() to create a client and set with chainable client settings.
    SetUserAgent("my-custom-client").
    SetTimeout(5 * time.Second).
    DevMode()
resp, err := client.R(). // Use R() to create a request and set with chainable request settings.
    SetHeader("Accept", "application/vnd.github.v3+json").
    SetPathParam("username", "imroc").
    SetQueryParam("page", "1").
    SetResult(&result). // Unmarshal response into struct automatically if status code >= 200 and <= 299.
    SetError(&errMsg). // Unmarshal response into struct automatically if status code >= 400.
    EnableDump(). // Enable dump at request level to help troubleshoot, log content only when an unexpected exception occurs.
    Get("https://api.github.com/users/{username}/repos")
if err != nil {
    // Handle error.
    // ...
    return
}
if resp.IsSuccess() {
    // Handle result.
    // ...
    return
}
if resp.IsError() {
    // Handle errMsg.	
    // ...
    return
}
// Handle unexpected response (corner case).
err = fmt.Errorf("got unexpected response, raw dump:\n%s", resp.Dump())
// ...

Videos

More

Check more introduction, tutorials, examples, best practices and API references on the official website.

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 GetClient added in v3.8.0 

func GetClient() *http.Client

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

func GetTLSClientConfig added in v3.6.0 

func GetTLSClientConfig() *tls.Config

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

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 AddCommonRetryCondition added in v3.9.0 

func AddCommonRetryCondition(condition RetryConditionFunc) *Client

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

func AddCommonRetryHook added in v3.9.0 

func AddCommonRetryHook(hook RetryHookFunc) *Client

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

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 DisableForceHttpVersion added in v3.4.0 

func DisableForceHttpVersion() *Client

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

func DisableInsecureSkipVerify added in v3.6.0 

func DisableInsecureSkipVerify() *Client

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

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 EnableForceHTTP2 added in v3.4.0 

func EnableForceHTTP2() *Client

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

func EnableForceHTTP3 added in v3.14.0 

func EnableForceHTTP3() *Client

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

func EnableHTTP3 added in v3.14.0 

func EnableHTTP3() *Client

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

func EnableInsecureSkipVerify added in v3.6.0 

func EnableInsecureSkipVerify() *Client

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

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 SetAutoDecodeAllContentType added in v3.3.0 

func SetAutoDecodeAllContentType() *Client

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

func SetAutoDecodeContentType 

func SetAutoDecodeContentType(contentTypes ...string) *Client

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

func SetAutoDecodeContentTypeFunc added in v3.3.0 

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

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

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 SetCommonError added in v3.12.0 

func SetCommonError(err interface{}) *Client

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

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 url.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 SetCommonPathParam added in v3.7.0 

func SetCommonPathParam(key, value string) *Client

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

func SetCommonPathParams added in v3.7.0 

func SetCommonPathParams(pathParams map[string]string) *Client

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

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 SetCommonRetryBackoffInterval added in v3.9.0 

func SetCommonRetryBackoffInterval(min, max time.Duration) *Client

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

func SetCommonRetryCondition added in v3.9.0 

func SetCommonRetryCondition(condition RetryConditionFunc) *Client

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

func SetCommonRetryCount added in v3.9.0 

func SetCommonRetryCount(count int) *Client

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

func SetCommonRetryFixedInterval added in v3.9.0 

func SetCommonRetryFixedInterval(interval time.Duration) *Client

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

func SetCommonRetryHook added in v3.9.0 

func SetCommonRetryHook(hook RetryHookFunc) *Client

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

func SetCommonRetryInterval added in v3.9.0 

func SetCommonRetryInterval(getRetryIntervalFunc GetRetryIntervalFunc) *Client

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

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) (*url.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 SetUnixSocket added in v3.9.0 

func SetUnixSocket(file string) *Client

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

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 for all requests.

func (*Client) AddCommonRetryCondition added in v3.9.0 

func (c *Client) AddCommonRetryCondition(condition RetryConditionFunc) *Client

AddCommonRetryCondition adds a retry condition, which determines whether the request should retry.

func (*Client) AddCommonRetryHook added in v3.9.0 

func (c *Client) AddCommonRetryHook(hook RetryHookFunc) *Client

AddCommonRetryHook adds a retry hook for all requests, which will be executed before a retry.

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 level log for deeper insights. 3. Trace all requests, so you can get trace info to analyze performance.

func (*Client) DisableAllowGetMethodPayload 

func (c *Client) DisableAllowGetMethodPayload() *Client

DisableAllowGetMethodPayload disable 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 disable debug level log (disabled by default).

func (*Client) DisableDumpAll 

func (c *Client) DisableDumpAll() *Client

DisableDumpAll disable dump for all requests.

func (*Client) DisableForceHttpVersion added in v3.4.0 

func (c *Client) DisableForceHttpVersion() *Client

DisableForceHttpVersion disable force using specified http version (disabled by default).

func (*Client) DisableHTTP3 added in v3.14.0 

func (c *Client) DisableHTTP3() *Client

DisableHTTP3 disables the http3 protocol.

func (*Client) DisableInsecureSkipVerify added in v3.6.0 

func (c *Client) DisableInsecureSkipVerify() *Client

DisableInsecureSkipVerify disable send https without verifing the server's certificates (disabled by default).

func (*Client) DisableKeepAlives 

func (c *Client) DisableKeepAlives() *Client

DisableKeepAlives disable the 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 disable trace for all requests.

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 enable 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).

func (*Client) EnableDebugLog 

func (c *Client) EnableDebugLog() *Client

EnableDebugLog enable debug level log (disabled by default).

func (*Client) EnableDumpAll 

func (c *Client) EnableDumpAll() *Client

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

func (*Client) EnableDumpAllAsync 

func (c *Client) EnableDumpAllAsync() *Client

EnableDumpAllAsync enable 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 enable dump for all requests and output to the specified io.Writer.

func (*Client) EnableDumpAllToFile 

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

EnableDumpAllToFile enable dump for all requests and output to the specified file.

func (*Client) EnableDumpAllWithoutBody 

func (c *Client) EnableDumpAllWithoutBody() *Client

EnableDumpAllWithoutBody enable dump for all requests without body, can be used if you only care about the header.

func (*Client) EnableDumpAllWithoutHeader 

func (c *Client) EnableDumpAllWithoutHeader() *Client

EnableDumpAllWithoutHeader enable dump for all requests without header, can be used if you only care about the body.

func (*Client) EnableDumpAllWithoutRequest added in v3.1.0 

func (c *Client) EnableDumpAllWithoutRequest() *Client

EnableDumpAllWithoutRequest enables dump for all requests without request, can be used if you only care about the response.

func (*Client) EnableDumpAllWithoutRequestBody 

func (c *Client) EnableDumpAllWithoutRequestBody() *Client

EnableDumpAllWithoutRequestBody enable dump for all requests without request body, can be used in the upload request to avoid dumping the unreadable binary content.

func (*Client) EnableDumpAllWithoutResponse 

func (c *Client) EnableDumpAllWithoutResponse() *Client

EnableDumpAllWithoutResponse enable dump for all requests without response, can be used if you only care about the request.

func (*Client) EnableDumpAllWithoutResponseBody 

func (c *Client) EnableDumpAllWithoutResponseBody() *Client

EnableDumpAllWithoutResponseBody enable dump for all requests without response body, can be used in the download request to avoid dumping the unreadable binary content.

func (*Client) EnableForceHTTP1 added in v3.2.0 

func (c *Client) EnableForceHTTP1() *Client

EnableForceHTTP1 enable force using HTTP1 (disabled by default).

func (*Client) EnableForceHTTP2 added in v3.4.0 

func (c *Client) EnableForceHTTP2() *Client

EnableForceHTTP2 enable force using HTTP2 for https requests (disabled by default).

func (*Client) EnableForceHTTP3 added in v3.14.0 

func (c *Client) EnableForceHTTP3() *Client

EnableForceHTTP3 enable force using HTTP3 for https requests (disabled by default).

func (*Client) EnableHTTP3 added in v3.14.0 

func (c *Client) EnableHTTP3() *Client

EnableHTTP3 enables the http3 protocol.

func (*Client) EnableInsecureSkipVerify added in v3.6.0 

func (c *Client) EnableInsecureSkipVerify() *Client

EnableInsecureSkipVerify enable send https without verifing the server's certificates (disabled by default).

func (*Client) EnableKeepAlives 

func (c *Client) EnableKeepAlives() *Client

EnableKeepAlives enables HTTP keep-alives (enabled by default).

func (*Client) EnableTraceAll 

func (c *Client) EnableTraceAll() *Client

EnableTraceAll enable trace for all requests (http3 currently does not support trace).

func (*Client) GetClient added in v3.8.0 

func (c *Client) GetClient() *http.Client

GetClient returns the underlying `http.Client`.

func (*Client) GetLogger added in v3.14.0 

func (c *Client) GetLogger() Logger

GetLogger return the internal logger, usually used in middleware.

func (*Client) GetTLSClientConfig added in v3.6.0 

func (c *Client) GetTLSClientConfig() *tls.Config

GetTLSClientConfig return the underlying tls.Config.

func (*Client) GetTransport added in v3.14.0 

func (c *Client) GetTransport() *Transport

GetTransport return the underlying transport.

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) SetAutoDecodeAllContentType added in v3.3.0 

func (c *Client) SetAutoDecodeAllContentType() *Client

SetAutoDecodeAllContentType enable try auto-detect charset and decode all content type 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 (e.g. "json", "xml", "html", "text").

func (*Client) SetAutoDecodeContentTypeFunc added in v3.3.0 

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

SetAutoDecodeContentTypeFunc set the function that determines whether the specified `Content-Type` should 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 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 HTTP cookies for all requests.

func (*Client) SetCommonDumpOptions 

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

SetCommonDumpOptions configures the underlying Transport's DumpOptions for all requests.

func (*Client) SetCommonError added in v3.12.0 

func (c *Client) SetCommonError(err interface{}) *Client

SetCommonError set the common result that response body will be unmarshalled to if it is an error response ( status `code >= 400`).

func (*Client) SetCommonFormData 

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

SetCommonFormData set the form data from map for all requests which request 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 request method allows payload.

func (*Client) SetCommonHeader 

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

SetCommonHeader set a header for all requests.

func (*Client) SetCommonHeaderNonCanonical added in v3.11.0 

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

SetCommonHeaderNonCanonical set a header for all requests which key is a non-canonical key (keep case unchanged), only valid for HTTP/1.1.

func (*Client) SetCommonHeaders 

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

SetCommonHeaders set headers for all requests.

func (*Client) SetCommonHeadersNonCanonical added in v3.11.0 

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

SetCommonHeadersNonCanonical set headers for all requests which key is a non-canonical key (keep case unchanged), only valid for HTTP/1.1.

func (*Client) SetCommonPathParam added in v3.7.0 

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

SetCommonPathParam set a path parameter for all requests.

func (*Client) SetCommonPathParams added in v3.7.0 

func (c *Client) SetCommonPathParams(pathParams map[string]string) *Client

SetCommonPathParams set path parameters 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 for all requests.

func (*Client) SetCommonQueryParams 

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

SetCommonQueryParams set URL query parameters with a map for all requests.

func (*Client) SetCommonQueryString 

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

SetCommonQueryString set URL query parameters with a raw query string for all requests.

func (*Client) SetCommonRetryBackoffInterval added in v3.9.0 

func (c *Client) SetCommonRetryBackoffInterval(min, max time.Duration) *Client

SetCommonRetryBackoffInterval set retry to use a capped exponential backoff with jitter for all requests. https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/

func (*Client) SetCommonRetryCondition added in v3.9.0 

func (c *Client) SetCommonRetryCondition(condition RetryConditionFunc) *Client

SetCommonRetryCondition sets the retry condition, which determines whether the request should retry. It will override other retry conditions if any been added before.

func (*Client) SetCommonRetryCount added in v3.9.0 

func (c *Client) SetCommonRetryCount(count int) *Client

SetCommonRetryCount enables retry and set the maximum retry count for all requests.

func (*Client) SetCommonRetryFixedInterval added in v3.9.0 

func (c *Client) SetCommonRetryFixedInterval(interval time.Duration) *Client

SetCommonRetryFixedInterval set retry to use a fixed interval for all requests.

func (*Client) SetCommonRetryHook added in v3.9.0 

func (c *Client) SetCommonRetryHook(hook RetryHookFunc) *Client

SetCommonRetryHook set the retry hook which will be executed before a retry. It will override other retry hooks if any been added before.

func (*Client) SetCommonRetryInterval added in v3.9.0 

func (c *Client) SetCommonRetryInterval(getRetryIntervalFunc GetRetryIntervalFunc) *Client

SetCommonRetryInterval sets the custom GetRetryIntervalFunc for all requests, you can use this to implement your own backoff retry algorithm. For example: 

	 req.SetCommonRetryInterval(func(resp *req.Response, attempt int) time.Duration {
     sleep := 0.01 * math.Exp2(float64(attempt))
     return time.Duration(math.Min(2, sleep)) * time.Second
	 })

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 `DialContext` function to Transport.

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` function to Transport. Make sure the returned `conn` implements pkg/tls.Conn if you want your customized `conn` supports HTTP2.

func (*Client) SetJsonMarshal 

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

SetJsonMarshal set the 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 customized logger for client, will disable log if set to nil.

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 proxy from the proxy URL.

func (*Client) SetRedirectPolicy 

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

SetRedirectPolicy set the RedirectPolicy which controls the behavior of receiving redirect responses (usually responses with 301 and 302 status code), see the predefined AllowedDomainRedirectPolicy, AllowedHostRedirectPolicy, MaxRedirectPolicy, NoRedirectPolicy, SameDomainRedirectPolicy and SameHostRedirectPolicy.

func (*Client) SetRootCertFromString 

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

SetRootCertFromString set root certificates from string.

func (*Client) SetRootCertsFromFile 

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

SetRootCertsFromFile set root certificates from files.

func (*Client) SetScheme 

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

SetScheme set the default scheme for client, will be used when there is no scheme in the request URL (e.g. "github.com/imroc/req").

func (*Client) SetTLSClientConfig 

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

SetTLSClientConfig set the TLS client config. Be careful! Usually you don't need this, you can directly set the tls configuration with methods like EnableInsecureSkipVerify, SetCerts etc. Or you can call GetTLSClientConfig to get the current tls configuration to avoid overwriting some important configurations, such as not setting NextProtos will not use http2 by default.

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 timeout for all requests.

func (*Client) SetUnixSocket added in v3.9.0 

func (c *Client) SetUnixSocket(file string) *Client

SetUnixSocket set client to dial connection use unix socket. For example: 

client.SetUnixSocket("/var/run/custom.sock")

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 ContentDisposition added in v3.5.1 

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

ContentDisposition represents parameters in `Content-Disposition` MIME header of multipart request.

func (*ContentDisposition) Add added in v3.5.1 

func (c *ContentDisposition) Add(key, value string) *ContentDisposition

Add adds a new key-value pair of Content-Disposition

type DownloadCallback added in v3.10.0 

type DownloadCallback func(info DownloadInfo)

DownloadCallback is the callback which will be invoked during response body download.

type DownloadInfo added in v3.10.0 

type DownloadInfo struct {
	// Response is the corresponding Response during download.
	Response *Response
	// downloaded body length in bytes.
	DownloadedSize int64
}

DownloadInfo is the information for each DownloadCallback call.

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

Clone return a copy of DumpOptions

type FileUpload added in v3.5.0 

type FileUpload struct {
	// "name" parameter in `Content-Disposition`
	ParamName string
	// "filename" parameter in `Content-Disposition`
	FileName string
	// The file to be uploaded.
	GetFileContent GetContentFunc
	// Optional file length in bytes.
	FileSize int64

	// Optional extra ContentDisposition parameters.
	// According to the HTTP specification, this should be nil,
	// but some servers may not follow the specification and
	// requires `Content-Disposition` parameters more than just
	// "name" and "filename".
	ExtraContentDisposition *ContentDisposition
}

FileUpload represents a "form-data" multipart

type GetContentFunc added in v3.9.0 

type GetContentFunc func() (io.ReadCloser, error)

type GetRetryIntervalFunc added in v3.9.0 

type GetRetryIntervalFunc func(resp *Response, attempt int) time.Duration

GetRetryIntervalFunc is a function that determines how long should sleep between retry attempts.

type Logger 

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

Logger is the abstract logging interface, gives control to the Req 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

RedirectPolicy represents the redirect policy for Client.

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 AlwaysCopyHeaderRedirectPolicy added in v3.9.6 

func AlwaysCopyHeaderRedirectPolicy(headers ...string) RedirectPolicy

AlwaysCopyHeaderRedirectPolicy ensures that the given sensitive headers will always be copied on redirect. By default, golang will copy all of the original request's headers on redirect, unless they're sensitive, like "Authorization" or "Www-Authenticate". Only send sensitive ones to the same origin, or subdomains thereof (https://go-review.googlesource.com/c/go/+/28930/) Check discussion: https://github.com/golang/go/issues/4800 For example: 

client.SetRedirectPolicy(req.AlwaysCopyHeaderRedirectPolicy("Authorization"))

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

SameDomainRedirectPolicy allows redirect only if the redirected domain is the same as original domain, e.g. redirect to "www.imroc.cc" from "imroc.cc" is allowed, but redirect to "google.com" is not allowed.

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 {
	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
	RetryAttempt int
	RawURL       string // read only
	Method       string

	URL *urlpkg.URL
	// contains filtered or unexported fields
}

Request struct is used to compose and fire individual request from req client. Request provides lots of chainable settings which can override client level settings.

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 AddRetryCondition added in v3.9.0 

func AddRetryCondition(condition RetryConditionFunc) *Request

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

func AddRetryHook added in v3.9.0 

func AddRetryHook(hook RetryHookFunc) *Request

AddRetryHook is a global wrapper methods which delegated to the default client, create a request and AddRetryHook 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 SetDownloadCallback added in v3.10.0 

func SetDownloadCallback(callback DownloadCallback) *Request

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

func SetDownloadCallbackWithInterval added in v3.10.0 

func SetDownloadCallbackWithInterval(callback DownloadCallback, minInterval time.Duration) *Request

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

func SetDumpOptions 

func SetDumpOptions(opt *DumpOptions) *Request

SetDumpOptions is a global wrapper methods which delegated to the default client, create a request and SetDumpOptions for 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 SetFileBytes added in v3.5.0 

func SetFileBytes(paramName, filename string, content []byte) *Request

SetFileBytes is a global wrapper methods which delegated to the default client, create a request and SetFileBytes 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 SetFileUpload added in v3.5.0 

func SetFileUpload(f ...FileUpload) *Request

SetFileUpload is a global wrapper methods which delegated to the default client, create a request and SetFileUpload 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 url.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 SetRetryBackoffInterval added in v3.9.0 

func SetRetryBackoffInterval(min, max time.Duration) *Request

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

func SetRetryCondition added in v3.9.0 

func SetRetryCondition(condition RetryConditionFunc) *Request

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

func SetRetryCount added in v3.9.0 

func SetRetryCount(count int) *Request

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

func SetRetryFixedInterval added in v3.9.0 

func SetRetryFixedInterval(interval time.Duration) *Request

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

func SetRetryHook added in v3.9.0 

func SetRetryHook(hook RetryHookFunc) *Request

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

func SetRetryInterval added in v3.9.0 

func SetRetryInterval(getRetryIntervalFunc GetRetryIntervalFunc) *Request

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

func SetUploadCallback added in v3.10.0 

func SetUploadCallback(callback UploadCallback) *Request

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

func SetUploadCallbackWithInterval added in v3.10.0 

func SetUploadCallbackWithInterval(callback UploadCallback, minInterval time.Duration) *Request

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

func (*Request) AddQueryParam 

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

AddQueryParam add a URL query parameter for the request.

func (*Request) AddRetryCondition added in v3.9.0 

func (r *Request) AddRetryCondition(condition RetryConditionFunc) *Request

AddRetryCondition adds a retry condition, which determines whether the request should retry.

func (*Request) AddRetryHook added in v3.9.0 

func (r *Request) AddRetryHook(hook RetryHookFunc) *Request

AddRetryHook adds a retry hook which will be executed before a retry.

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 fires http request with DELETE method and the 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 (http3 currently does not support trace).

func (*Request) Get 

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

Get fires http request with GET method and the specified URL.

func (*Request) Head 

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

Head fires http request with HEAD method and the 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. should only be used to test without error handling.

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 fires http request with OPTIONS method and the specified URL.

func (*Request) Patch 

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

Patch fires http request with PATCH method and the specified URL.

func (*Request) Post 

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

Post fires http request with POST method and the specified URL.

func (*Request) Put 

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

Put fires http request with PUT method and the specified URL.

func (*Request) Send 

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

Send fires http request and return the *Response which is always not nil, and the error is not nil if some error happens.

func (*Request) SetBasicAuth 

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

SetBasicAuth set basic auth for the request.

func (*Request) SetBearerAuthToken 

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

SetBearerAuthToken set bearer auth token for the request.

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 http cookies for the request.

func (*Request) SetDownloadCallback added in v3.10.0 

func (r *Request) SetDownloadCallback(callback DownloadCallback) *Request

SetDownloadCallback set the DownloadCallback which will be invoked at least every 200ms during file upload, usually used to show download progress.

func (*Request) SetDownloadCallbackWithInterval added in v3.10.0 

func (r *Request) SetDownloadCallbackWithInterval(callback DownloadCallback, minInterval time.Duration) *Request

SetDownloadCallbackWithInterval set the DownloadCallback which will be invoked at least every `minInterval` during file upload, usually used to show download progress.

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 unmarshalled to if request is error ( status `code >= 400`).

func (*Request) SetFile 

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

SetFile set up a multipart form from file path to upload, which read file from filePath automatically to upload.

func (*Request) SetFileBytes added in v3.5.0 

func (r *Request) SetFileBytes(paramName, filename string, content []byte) *Request

SetFileBytes set up a multipart form with given []byte to upload.

func (*Request) SetFileReader 

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

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

func (*Request) SetFileUpload added in v3.5.0 

func (r *Request) SetFileUpload(uploads ...FileUpload) *Request

SetFileUpload set the fully custimized multipart file upload options.

func (*Request) SetFiles 

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

SetFiles set up a multipart form from a map to upload, which key is the parameter name, and value is the file path.

func (*Request) SetFormData 

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

SetFormData set the form data from a map, will not been used if request method does not allow payload.

func (*Request) SetFormDataFromValues 

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

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

func (*Request) SetHeader 

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

SetHeader set a header for the request.

func (*Request) SetHeaderNonCanonical added in v3.11.0 

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

SetHeaderNonCanonical set a header for the request which key is a non-canonical key (keep case unchanged), only valid for HTTP/1.1.

func (*Request) SetHeaders 

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

SetHeaders set headers from a map for the request.

func (*Request) SetHeadersNonCanonical added in v3.11.0 

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

SetHeadersNonCanonical set headers from a map for the request which key is a non-canonical key (keep case unchanged), only valid for HTTP/1.1.

func (*Request) SetOutput 

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

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

func (*Request) SetOutputFile 

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

SetOutputFile set the file that response body will be downloaded to.

func (*Request) SetPathParam 

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

SetPathParam set a URL path parameter for the request.

func (*Request) SetPathParams 

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

SetPathParams set URL path parameters from a map for the request.

func (*Request) SetQueryParam 

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

SetQueryParam set an URL query parameter for the request.

func (*Request) SetQueryParams 

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

SetQueryParams set URL query parameters from a map for the request.

func (*Request) SetQueryString 

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

SetQueryString set URL query parameters for the request using raw query string.

func (*Request) SetResult 

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

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

func (*Request) SetRetryBackoffInterval added in v3.9.0 

func (r *Request) SetRetryBackoffInterval(min, max time.Duration) *Request

SetRetryBackoffInterval set retry to use a capped exponential backoff with jitter. https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/

func (*Request) SetRetryCondition added in v3.9.0 

func (r *Request) SetRetryCondition(condition RetryConditionFunc) *Request

SetRetryCondition sets the retry condition, which determines whether the request should retry. It will override other retry conditions if any been added before (including client-level retry conditions).

func (*Request) SetRetryCount added in v3.9.0 

func (r *Request) SetRetryCount(count int) *Request

SetRetryCount enables retry and set the maximum retry count.

func (*Request) SetRetryFixedInterval added in v3.9.0 

func (r *Request) SetRetryFixedInterval(interval time.Duration) *Request

SetRetryFixedInterval set retry to use a fixed interval.

func (*Request) SetRetryHook added in v3.9.0 

func (r *Request) SetRetryHook(hook RetryHookFunc) *Request

SetRetryHook set the retry hook which will be executed before a retry. It will override other retry hooks if any been added before (including client-level retry hooks).

func (*Request) SetRetryInterval added in v3.9.0 

func (r *Request) SetRetryInterval(getRetryIntervalFunc GetRetryIntervalFunc) *Request

SetRetryInterval sets the custom GetRetryIntervalFunc, you can use this to implement your own backoff retry algorithm. For example: 

	 req.SetRetryInterval(func(resp *req.Response, attempt int) time.Duration {
     sleep := 0.01 * math.Exp2(float64(attempt))
     return time.Duration(math.Min(2, sleep)) * time.Second
	 })

func (*Request) SetUploadCallback added in v3.10.0 

func (r *Request) SetUploadCallback(callback UploadCallback) *Request

SetUploadCallback set the UploadCallback which will be invoked at least every 200ms during file upload, usually used to show upload progress.

func (*Request) SetUploadCallbackWithInterval added in v3.10.0 

func (r *Request) SetUploadCallbackWithInterval(callback UploadCallback, minInterval time.Duration) *Request

SetUploadCallbackWithInterval set the UploadCallback which will be invoked at least every `minInterval` during file upload, usually used to show upload progress.

func (*Request) TraceInfo 

func (r *Request) TraceInfo() TraceInfo

TraceInfo returns the trace information, only available if trace is enabled (see Request.EnableTrace and Client.EnableTraceAll).

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) GetHeader added in v3.13.0 

func (r *Response) GetHeader(key string) string

GetHeader returns the response header value by key.

func (*Response) GetHeaderValues added in v3.13.0 

func (r *Response) GetHeaderValues(key string) []string

GetHeaderValues returns the response header values by key.

func (*Response) GetStatus added in v3.13.0 

func (r *Response) GetStatus() string

GetStatus returns the response status.

func (*Response) GetStatusCode added in v3.13.0 

func (r *Response) GetStatusCode() int

GetStatusCode returns the response status code.

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 RetryConditionFunc added in v3.9.0 

type RetryConditionFunc func(resp *Response, err error) bool

RetryConditionFunc is a retry condition, which determines whether the request should retry.

type RetryHookFunc added in v3.9.0 

type RetryHookFunc func(resp *Response, err error)

RetryHookFunc is a retry hook which will be executed before a retry.

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
}

TraceInfo represents the trace information.

func (TraceInfo) Blame 

func (t TraceInfo) Blame() string

Blame return the human-readable reason of why request is slowing.

func (TraceInfo) String 

func (t TraceInfo) String() string

String return the details of trace information.

type Transport 

type Transport struct {
	transport.Options
	// 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 NewTransport added in v3.14.0 

func NewTransport() *Transport

NewTransport is an alias of T

func T added in v3.14.0 

func T() *Transport

T create a new Transport.

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) DisableAutoDecode added in v3.14.0 

func (t *Transport) DisableAutoDecode() *Transport

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

func (*Transport) DisableDump 

func (t *Transport) DisableDump()

DisableDump disables the dump.

func (*Transport) DisableForceHttpVersion added in v3.14.0 

func (t *Transport) DisableForceHttpVersion() *Transport

DisableForceHttpVersion disable force using specified http version (disabled by default).

func (*Transport) DisableHTTP3 added in v3.14.0 

func (t *Transport) DisableHTTP3()

func (*Transport) EnableAutoDecode added in v3.14.0 

func (t *Transport) EnableAutoDecode() *Transport

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

func (*Transport) EnableDump 

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

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

func (*Transport) EnableForceHTTP1 added in v3.14.0 

func (t *Transport) EnableForceHTTP1() *Transport

EnableForceHTTP1 enable force using HTTP1 (disabled by default).

func (*Transport) EnableForceHTTP2 added in v3.14.0 

func (t *Transport) EnableForceHTTP2() *Transport

EnableForceHTTP2 enable force using HTTP2 for https requests (disabled by default).

func (*Transport) EnableForceHTTP3 added in v3.14.0 

func (t *Transport) EnableForceHTTP3() *Transport

EnableForceHTTP3 enable force using HTTP3 for https requests (disabled by default).

func (*Transport) EnableHTTP3 added in v3.14.0 

func (t *Transport) EnableHTTP3()

func (*Transport) GetMaxIdleConns added in v3.14.0 

func (t *Transport) GetMaxIdleConns() int

GetMaxIdleConns returns MaxIdleConns.

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.

func (*Transport) SetAutoDecodeAllContentType added in v3.14.0 

func (t *Transport) SetAutoDecodeAllContentType() *Transport

SetAutoDecodeAllContentType enable try auto-detect charset and decode all content type to utf-8.

func (*Transport) SetAutoDecodeContentType added in v3.14.0 

func (t *Transport) SetAutoDecodeContentType(contentTypes ...string)

SetAutoDecodeContentType set the content types that will be auto-detected and decode to utf-8 (e.g. "json", "xml", "html", "text").

func (*Transport) SetAutoDecodeContentTypeFunc added in v3.14.0 

func (t *Transport) SetAutoDecodeContentTypeFunc(fn func(contentType string) bool) *Transport

SetAutoDecodeContentTypeFunc set the function that determines whether the specified `Content-Type` should be auto-detected and decode to utf-8.

func (*Transport) SetDebug added in v3.14.0 

func (t *Transport) SetDebug(debugf func(format string, v ...interface{})) *Transport

SetDebug set the debug function.

func (*Transport) SetDial added in v3.14.0 

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

SetDial set the custom DialContext function, only valid for HTTP1 and HTTP2.

func (*Transport) SetDialTLS added in v3.14.0 

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

SetDialTLS set the custom DialTLSContext function, only valid for HTTP1 and HTTP2.

func (*Transport) SetExpectContinueTimeout added in v3.14.0 

func (t *Transport) SetExpectContinueTimeout(timeout time.Duration) *Transport

SetExpectContinueTimeout set the ExpectContinueTimeout.

func (*Transport) SetGetProxyConnectHeader added in v3.14.0 

func (t *Transport) SetGetProxyConnectHeader(fn func(ctx context.Context, proxyURL *url.URL, target string) (http.Header, error)) *Transport

SetGetProxyConnectHeader set the GetProxyConnectHeader function.

func (*Transport) SetIdleConnTimeout added in v3.14.0 

func (t *Transport) SetIdleConnTimeout(timeout time.Duration) *Transport

SetIdleConnTimeout set the IdleConnTimeout.

func (*Transport) SetMaxConnsPerHost added in v3.14.0 

func (t *Transport) SetMaxConnsPerHost(max int) *Transport

SetMaxConnsPerHost set the MaxConnsPerHost.

func (*Transport) SetMaxIdleConns added in v3.14.0 

func (t *Transport) SetMaxIdleConns(max int) *Transport

SetMaxIdleConns set the MaxIdleConns.

func (*Transport) SetMaxResponseHeaderBytes added in v3.14.0 

func (t *Transport) SetMaxResponseHeaderBytes(max int64) *Transport

SetMaxResponseHeaderBytes set the MaxResponseHeaderBytes.

func (*Transport) SetProxy added in v3.14.0 

func (t *Transport) SetProxy(proxy func(*http.Request) (*url.URL, error)) *Transport

SetProxy set the http proxy, only valid for HTTP1 and HTTP2.

func (*Transport) SetProxyConnectHeader added in v3.14.0 

func (t *Transport) SetProxyConnectHeader(header http.Header) *Transport

SetProxyConnectHeader set the ProxyConnectHeader.

func (*Transport) SetReadBufferSize added in v3.14.0 

func (t *Transport) SetReadBufferSize(size int) *Transport

SetReadBufferSize set the ReadBufferSize.

func (*Transport) SetResponseHeaderTimeout added in v3.14.0 

func (t *Transport) SetResponseHeaderTimeout(timeout time.Duration) *Transport

SetResponseHeaderTimeout set the ResponseHeaderTimeout.

func (*Transport) SetTLSClientConfig added in v3.14.0 

func (t *Transport) SetTLSClientConfig(cfg *tls.Config) *Transport

SetTLSClientConfig set the custom tle client config.

func (*Transport) SetTLSHandshakeTimeout added in v3.14.0 

func (t *Transport) SetTLSHandshakeTimeout(timeout time.Duration) *Transport

SetTLSHandshakeTimeout set the TLSHandshakeTimeout.

func (*Transport) SetWriteBufferSize added in v3.14.0 

func (t *Transport) SetWriteBufferSize(size int) *Transport

SetWriteBufferSize set the WriteBufferSize.

type UploadCallback added in v3.10.0 

type UploadCallback func(info UploadInfo)

UploadCallback is the callback which will be invoked during multipart upload.

type UploadInfo added in v3.10.0 

type UploadInfo struct {
	// parameter name in multipart upload
	ParamName string
	// filename in multipart upload
	FileName string
	// total file length in bytes.
	FileSize int64
	// uploaded file length in bytes.
	UploadedSize int64
}

UploadInfo is the information for each UploadCallback call.

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.
altsvcutil
ascii
charsets
common
dump
godebug
Package godebug parses the GODEBUG environment variable.
 Package godebug parses the GODEBUG environment variable.
header
http2
http3
mocks
mocks/quic
Package mockquic is a generated GoMock package.
 Package mockquic is a generated GoMock package.
netutil
protocol
qtls
quicvarint
socks
Package socks provides a SOCKS version 5 client implementation.
 Package socks provides a SOCKS version 5 client implementation.
testcert
Package testcert contains a test-only localhost certificate.
 Package testcert contains a test-only localhost certificate.
tests
transport
util
utils
pkg
altsvc
tls

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.