req

package module
v3.42.3 Latest Latest
Warning

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

Go to latest
Published: Jan 5, 2024 License: MIT Imports: 62 Imported by: 458

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: Simple and easy to use, providing rich client-level and request-level settings, all of which are intuitive and chainable methods.
  • 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 Request or Client, 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.
  • Support Multiple HTTP Versions: Support HTTP/1.1, HTTP/2, and HTTP/3, and can automatically detect the server side and select the optimal HTTP version for requests, 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).
  • HTTP Fingerprinting: Support http fingerprint impersonation, so that we can access websites that prohibit crawler programs by identifying http fingerprints (See HTTP Fingerprint).
  • Multiple Authentication Methods: You can use HTTP Basic Auth, Bearer Auth Token and Digest Auth out of box (see Authentication).
  • 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: req.Transport is exportable. Compared with http.Transport, it also supports HTTP3, dump content, middleware, etc. It can directly replace the Transport of http.Client in existing projects, and obtain more powerful functions with minimal code change.
  • Extensible: Support Middleware for Request, Response, Client and Transport (See Request and Response Middleware) and Client and Transport Middleware).

Get Started

Install

You first need Go installed (version 1.20+ is required), then you can use the below Go command to install req:

go get github.com/imroc/req/v3

Import

Import req to your code:

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

Basic Usage

# assume the following codes in main.go file
$ cat main.go
package main

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

func main() {
    req.DevMode() // Treat the package name as a Client, enable development mode
    req.MustGet("https://httpbin.org/uuid") // Treat the package name as a Request, send GET request.

    req.EnableForceHTTP1() // Force using HTTP/1.1
    req.MustGet("https://httpbin.org/uuid")
}
$ go run main.go
2022/05/19 10:05:07.920113 DEBUG [req] HTTP/2 GET https://httpbin.org/uuid
:authority: httpbin.org
:method: GET
:path: /uuid
:scheme: https
user-agent: req/v3 (https://github.com/imroc/req/v3)
accept-encoding: gzip

:status: 200
date: Thu, 19 May 2022 02:05:08 GMT
content-type: application/json
content-length: 53
server: gunicorn/19.9.0
access-control-allow-origin: *
access-control-allow-credentials: true

{
  "uuid": "bd519208-35d1-4483-ad9f-e1555ae108ba"
}

2022/05/19 10:05:09.340974 DEBUG [req] HTTP/1.1 GET https://httpbin.org/uuid
GET /uuid HTTP/1.1
Host: httpbin.org
User-Agent: req/v3 (https://github.com/imroc/req/v3)
Accept-Encoding: gzip

HTTP/1.1 200 OK
Date: Thu, 19 May 2022 02:05:09 GMT
Content-Type: application/json
Content-Length: 53
Connection: keep-alive
Server: gunicorn/19.9.0
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true

{
  "uuid": "49b7f916-c6f3-49d4-a6d4-22ae93b71969"
}

The sample code above is good for quick testing purposes, which use DevMode() to see request details, and send requests using global wrapper methods that use the default client behind the scenes to initiate the request.

In production, it is recommended to explicitly create a client, and then use the same client to send all requests, please see other examples below.

Videos

The following is a series of video tutorials for req:

More

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

Simple GET

package main

import (
	"fmt"
	"github.com/imroc/req/v3"
	"log"
)

func main() {
	client := req.C() // Use C() to create a client.
	resp, err := client.R(). // Use R() to create a request.
		Get("https://httpbin.org/uuid")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(resp)
}
{
  "uuid": "a4d4430d-0e5f-412f-88f5-722d84bc2a62"
}

Advanced GET

package main

import (
  "fmt"
  "github.com/imroc/req/v3"
  "log"
  "time"
)

type ErrorMessage struct {
  Message string `json:"message"`
}

type UserInfo struct {
  Name string `json:"name"`
  Blog string `json:"blog"`
}

func main() {
  client := req.C().
    SetUserAgent("my-custom-client"). // Chainable client settings.
    SetTimeout(5 * time.Second)

  var userInfo UserInfo
  var errMsg ErrorMessage
  resp, err := client.R().
    SetHeader("Accept", "application/vnd.github.v3+json"). // Chainable request settings.
    SetPathParam("username", "imroc"). // Replace path variable in url.
    SetSuccessResult(&userInfo). // Unmarshal response body into userInfo automatically if status code is between 200 and 299.
    SetErrorResult(&errMsg). // Unmarshal response body into errMsg automatically if status code >= 400.
    EnableDump(). // Enable dump at request level, only print dump content if there is an error or some unknown situation occurs to help troubleshoot.
    Get("https://api.github.com/users/{username}")

  if err != nil { // Error handling.
    log.Println("error:", err)
    log.Println("raw content:")
    log.Println(resp.Dump()) // Record raw content when error occurs.
    return
  }

  if resp.IsErrorState() { // Status code >= 400.
    fmt.Println(errMsg.Message) // Record error message returned.
    return
  }

  if resp.IsSuccessState() { // Status code is between 200 and 299.
    fmt.Printf("%s (%s)\n", userInfo.Name, userInfo.Blog)
    return
  }

  // Unknown status code.
  log.Println("unknown status", resp.Status)
  log.Println("raw content:")
  log.Println(resp.Dump()) // Record raw content when server returned unknown status code.
}

Normally it will output (SuccessState):

roc (https://imroc.cc)

More Advanced GET

You can set up a unified logic for error handling on the client, so that each time you send a request you only need to focus on the success situation, reducing duplicate code.

package main

import (
	"fmt"
	"github.com/imroc/req/v3"
	"log"
	"time"
)

type ErrorMessage struct {
	Message string `json:"message"`
}

func (msg *ErrorMessage) Error() string {
	return fmt.Sprintf("API Error: %s", msg.Message)
}

type UserInfo struct {
	Name string `json:"name"`
	Blog string `json:"blog"`
}

var client = req.C().
	SetUserAgent("my-custom-client"). // Chainable client settings.
	SetTimeout(5 * time.Second).
	EnableDumpEachRequest().
	SetCommonErrorResult(&ErrorMessage{}).
	OnAfterResponse(func(client *req.Client, resp *req.Response) error {
		if resp.Err != nil { // There is an underlying error, e.g. network error or unmarshal error.
			return nil
		}
		if errMsg, ok := resp.ErrorResult().(*ErrorMessage); ok {
			resp.Err = errMsg // Convert api error into go error
			return nil
		}
		if !resp.IsSuccessState() {
			// Neither a success response nor a error response, record details to help troubleshooting
			resp.Err = fmt.Errorf("bad status: %s\nraw content:\n%s", resp.Status, resp.Dump())
		}
		return nil
	})

func main() {
	var userInfo UserInfo
	resp, err := client.R().
		SetHeader("Accept", "application/vnd.github.v3+json"). // Chainable request settings
		SetPathParam("username", "imroc").
		SetSuccessResult(&userInfo). // Unmarshal response body into userInfo automatically if status code is between 200 and 299.
		Get("https://api.github.com/users/{username}")

	if err != nil { // Error handling.
		log.Println("error:", err)
		return
	}

	if resp.IsSuccessState() { // Status code is between 200 and 299.
		fmt.Printf("%s (%s)\n", userInfo.Name, userInfo.Blog)
	}
}

Simple POST

package main

import (
  "fmt"
  "github.com/imroc/req/v3"
  "log"
)

type Repo struct {
  Name string `json:"name"`
  Url  string `json:"url"`
}

type Result struct {
  Data string `json:"data"`
}

func main() {
  client := req.C().DevMode()
  var result Result

  resp, err := client.R().
    SetBody(&Repo{Name: "req", Url: "https://github.com/imroc/req"}).
    SetSuccessResult(&result).
    Post("https://httpbin.org/post")
  if err != nil {
    log.Fatal(err)
  }

  if !resp.IsSuccessState() {
    fmt.Println("bad response status:", resp.Status)
    return
  }
  fmt.Println("++++++++++++++++++++++++++++++++++++++++++++++++")
  fmt.Println("data:", result.Data)
  fmt.Println("++++++++++++++++++++++++++++++++++++++++++++++++")
}
2022/05/19 20:11:00.151171 DEBUG [req] HTTP/2 POST https://httpbin.org/post
:authority: httpbin.org
:method: POST
:path: /post
:scheme: https
user-agent: req/v3 (https://github.com/imroc/req/v3)
content-type: application/json; charset=utf-8
content-length: 55
accept-encoding: gzip

{"name":"req","website":"https://github.com/imroc/req"}

:status: 200
date: Thu, 19 May 2022 12:11:00 GMT
content-type: application/json
content-length: 651
server: gunicorn/19.9.0
access-control-allow-origin: *
access-control-allow-credentials: true

{
  "args": {},
  "data": "{\"name\":\"req\",\"website\":\"https://github.com/imroc/req\"}",
  "files": {},
  "form": {},
  "headers": {
    "Accept-Encoding": "gzip",
    "Content-Length": "55",
    "Content-Type": "application/json; charset=utf-8",
    "Host": "httpbin.org",
    "User-Agent": "req/v3 (https://github.com/imroc/req/v3)",
    "X-Amzn-Trace-Id": "Root=1-628633d4-7559d633152b4307288ead2e"
  },
  "json": {
    "name": "req",
    "website": "https://github.com/imroc/req"
  },
  "origin": "103.7.29.30",
  "url": "https://httpbin.org/post"
}

++++++++++++++++++++++++++++++++++++++++++++++++
data: {"name":"req","url":"https://github.com/imroc/req"}
++++++++++++++++++++++++++++++++++++++++++++++++

Do API Style

If you like, you can also use a Do API style like the following to make requests:

package main

import (
	"fmt"
	"github.com/imroc/req/v3"
)

type APIResponse struct {
	Origin string `json:"origin"`
	Url    string `json:"url"`
}

func main() {
	var resp APIResponse
	c := req.C().SetBaseURL("https://httpbin.org/post")
	err := c.Post().
		SetBody("hello").
		Do().
		Into(&resp)
	if err != nil {
		panic(err)
	}
	fmt.Println("My IP is", resp.Origin)
}
My IP is 182.138.155.113
  • The order of chain calls is more intuitive: first call Client to create a request with a specified Method, then use chain calls to set the request, then use Do() to fire the request, return Response, and finally call Response.Into to unmarshal response body into specified object.
  • Response.Into will return an error if an error occurs during sending the request or during unmarshalling.
  • The url of some APIs is fixed, and different types of requests are implemented by passing different bodies. In this scenario, Client.SetBaseURL can be used to set a unified url, and there is no need to set the url for each request when initiating a request. Of course, you can also call Request.SetURL to set it if you need it.

Build SDK With Req

Here is an example of building GitHub's SDK with req, using two styles (GetUserProfile_Style1, GetUserProfile_Style2).

import (
	"context"
	"fmt"
	"github.com/imroc/req/v3"
)

type ErrorMessage struct {
	Message string `json:"message"`
}

// Error implements go error interface.
func (msg *ErrorMessage) Error() string {
	return fmt.Sprintf("API Error: %s", msg.Message)
}

type GithubClient struct {
	*req.Client
}

func NewGithubClient() *GithubClient {
	return &GithubClient{
		Client: req.C().
			SetBaseURL("https://api.github.com").
			SetCommonErrorResult(&ErrorMessage{}).
			EnableDumpEachRequest().
			OnAfterResponse(func(client *req.Client, resp *req.Response) error {
				if resp.Err != nil { // There is an underlying error, e.g. network error or unmarshal error.
					return nil
				}
				if errMsg, ok := resp.ErrorResult().(*ErrorMessage); ok {
					resp.Err = errMsg // Convert api error into go error
					return nil
				}
				if !resp.IsSuccessState() {
					// Neither a success response nor a error response, record details to help troubleshooting
					resp.Err = fmt.Errorf("bad status: %s\nraw content:\n%s", resp.Status, resp.Dump())
				}
				return nil
			}),
	}
}

type UserProfile struct {
	Name string `json:"name"`
	Blog string `json:"blog"`
}

// GetUserProfile_Style1 returns the user profile for the specified user.
// Github API doc: https://docs.github.com/en/rest/users/users#get-a-user
func (c *GithubClient) GetUserProfile_Style1(ctx context.Context, username string) (user *UserProfile, err error) {
	_, err = c.R().
		SetContext(ctx).
		SetPathParam("username", username).
		SetSuccessResult(&user).
		Get("/users/{username}")
	return
}

// GetUserProfile_Style2 returns the user profile for the specified user.
// Github API doc: https://docs.github.com/en/rest/users/users#get-a-user
func (c *GithubClient) GetUserProfile_Style2(ctx context.Context, username string) (user *UserProfile, err error) {
	err = c.Get("/users/{username}").
		SetPathParam("username", username).
		Do(ctx).
		Into(&user)
	return
}

Contributing

If you have a bug report or feature request, you can open an issue, and pull requests are also welcome.

Contact

If you have questions, feel free to reach out to us in the following ways:

Sponsors

If you like req and it really helps you, feel free to reward me with a cup of coffee, and don't forget to mention your github id.


Wechat

Alipay

Many thanks to the following sponsors:


M-Cosmosss 🥇

aadog 🥈

License

Req released under MIT license, refer LICENSE file.

Documentation

Index

Constants

View Source
const (
	// HeaderOderKey is the key of header order, which specifies the order
	// of the http header.
	HeaderOderKey = "__header_order__"
	// PseudoHeaderOderKey is the key of pseudo header order, which specifies
	// the order of the http2 and http3 pseudo header.
	PseudoHeaderOderKey = "__pseudo_header_order__"
)

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 Client.GetClient.

func GetCookies added in v3.37.0

func GetCookies(url string) ([]*http.Cookie, error)

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

func GetTLSClientConfig added in v3.6.0

func GetTLSClientConfig() *tls.Config

GetTLSClientConfig is a global wrapper methods which delegated to the default client's Client.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
	FormData              urlpkg.Values
	DebugLog              bool
	AllowGetMethodPayload bool
	*Transport
	// 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 Client.AddCommonQueryParam.

func AddCommonQueryParams added in v3.23.0

func AddCommonQueryParams(key string, values ...string) *Client

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

func AddCommonRetryCondition added in v3.9.0

func AddCommonRetryCondition(condition RetryConditionFunc) *Client

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

func AddCommonRetryHook added in v3.9.0

func AddCommonRetryHook(hook RetryHookFunc) *Client

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

func C

func C() *Client

C create a new client.

func ClearCookies added in v3.19.0

func ClearCookies() *Client

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

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 Client.DevMode.

func DisableAllowGetMethodPayload

func DisableAllowGetMethodPayload() *Client

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

func DisableAutoDecode

func DisableAutoDecode() *Client

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

func DisableAutoReadResponse

func DisableAutoReadResponse() *Client

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

func DisableCompression

func DisableCompression() *Client

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

func DisableDebugLog

func DisableDebugLog() *Client

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

func DisableDumpAll

func DisableDumpAll() *Client

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

func DisableForceHttpVersion added in v3.4.0

func DisableForceHttpVersion() *Client

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

func DisableH2C added in v3.20.0

func DisableH2C() *Client

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

func DisableInsecureSkipVerify added in v3.6.0

func DisableInsecureSkipVerify() *Client

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

func DisableKeepAlives

func DisableKeepAlives() *Client

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

func DisableTraceAll

func DisableTraceAll() *Client

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

func EnableAllowGetMethodPayload

func EnableAllowGetMethodPayload() *Client

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

func EnableAutoDecode

func EnableAutoDecode() *Client

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

func EnableAutoReadResponse

func EnableAutoReadResponse() *Client

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

func EnableCompression

func EnableCompression() *Client

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

func EnableDebugLog

func EnableDebugLog() *Client

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

func EnableDumpAll

func EnableDumpAll() *Client

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

func EnableDumpAllAsync

func EnableDumpAllAsync() *Client

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

func EnableDumpAllTo

func EnableDumpAllTo(output io.Writer) *Client

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

func EnableDumpAllToFile

func EnableDumpAllToFile(filename string) *Client

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

func EnableDumpAllWithoutBody

func EnableDumpAllWithoutBody() *Client

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

func EnableDumpAllWithoutHeader

func EnableDumpAllWithoutHeader() *Client

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

func EnableDumpAllWithoutRequest added in v3.1.0

func EnableDumpAllWithoutRequest() *Client

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

func EnableDumpAllWithoutRequestBody

func EnableDumpAllWithoutRequestBody() *Client

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

func EnableDumpAllWithoutResponse

func EnableDumpAllWithoutResponse() *Client

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

func EnableDumpAllWithoutResponseBody

func EnableDumpAllWithoutResponseBody() *Client

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

func EnableDumpEachRequest added in v3.18.0

func EnableDumpEachRequest() *Client

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

func EnableDumpEachRequestWithoutBody added in v3.18.0

func EnableDumpEachRequestWithoutBody() *Client

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

func EnableDumpEachRequestWithoutHeader added in v3.18.0

func EnableDumpEachRequestWithoutHeader() *Client

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

func EnableDumpEachRequestWithoutRequest added in v3.18.0

func EnableDumpEachRequestWithoutRequest() *Client

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

func EnableDumpEachRequestWithoutRequestBody added in v3.18.0

func EnableDumpEachRequestWithoutRequestBody() *Client

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

func EnableDumpEachRequestWithoutResponse added in v3.18.0

func EnableDumpEachRequestWithoutResponse() *Client

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

func EnableDumpEachRequestWithoutResponseBody added in v3.18.0

func EnableDumpEachRequestWithoutResponseBody() *Client

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

func EnableForceHTTP1 added in v3.2.0

func EnableForceHTTP1() *Client

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

func EnableForceHTTP2 added in v3.4.0

func EnableForceHTTP2() *Client

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

func EnableForceHTTP3 added in v3.14.0

func EnableForceHTTP3() *Client

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

func EnableH2C added in v3.20.0

func EnableH2C() *Client

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

func EnableHTTP3 added in v3.14.0

func EnableHTTP3() *Client

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

func EnableInsecureSkipVerify added in v3.6.0

func EnableInsecureSkipVerify() *Client

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

func EnableKeepAlives

func EnableKeepAlives() *Client

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

func EnableTraceAll

func EnableTraceAll() *Client

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

func ImpersonateChrome added in v3.40.0

func ImpersonateChrome() *Client

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

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 Client.OnAfterResponse.

func OnBeforeRequest

func OnBeforeRequest(m RequestMiddleware) *Client

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

func SetAutoDecodeAllContentType added in v3.3.0

func SetAutoDecodeAllContentType() *Client

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

func SetAutoDecodeContentType

func SetAutoDecodeContentType(contentTypes ...string) *Client

SetAutoDecodeContentType is a global wrapper methods which delegated to the default client's Client.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 Client.SetAutoDecodeAllTypeFunc.

func SetBaseURL

func SetBaseURL(u string) *Client

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

func SetCertFromFile

func SetCertFromFile(certFile, keyFile string) *Client

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

func SetCerts

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

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

func SetCommonBasicAuth

func SetCommonBasicAuth(username, password string) *Client

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

func SetCommonBearerAuthToken

func SetCommonBearerAuthToken(token string) *Client

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

func SetCommonContentType

func SetCommonContentType(ct string) *Client

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

func SetCommonCookies

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

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

func SetCommonDigestAuth added in v3.37.0

func SetCommonDigestAuth(username, password string) *Client

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

func SetCommonDumpOptions

func SetCommonDumpOptions(opt *DumpOptions) *Client

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

func SetCommonError deprecated added in v3.12.0

func SetCommonError(err interface{}) *Client

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

Deprecated: Use SetCommonErrorResult instead.

func SetCommonErrorResult added in v3.31.0

func SetCommonErrorResult(err interface{}) *Client

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

func SetCommonFormData

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

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

func SetCommonFormDataFromValues

func SetCommonFormDataFromValues(data url.Values) *Client

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

func SetCommonHeader

func SetCommonHeader(key, value string) *Client

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

func SetCommonHeaderOrder added in v3.39.0

func SetCommonHeaderOrder(keys ...string) *Client

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

func SetCommonHeaders

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

SetCommonHeaders is a global wrapper methods which delegated to the default client's Client.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 Client.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 Client.SetCommonPathParams.

func SetCommonPseudoHeaderOder added in v3.39.0

func SetCommonPseudoHeaderOder(keys ...string) *Client

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

func SetCommonQueryParam

func SetCommonQueryParam(key, value string) *Client

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

func SetCommonQueryParams

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

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

func SetCommonQueryString

func SetCommonQueryString(query string) *Client

SetCommonQueryString is a global wrapper methods which delegated to the default client's Client.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's Client.SetCommonRetryBackoffInterval.

func SetCommonRetryCondition added in v3.9.0

func SetCommonRetryCondition(condition RetryConditionFunc) *Client

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

func SetCommonRetryCount added in v3.9.0

func SetCommonRetryCount(count int) *Client

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

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's Client.SetCommonRetryFixedInterval.

func SetCommonRetryHook added in v3.9.0

func SetCommonRetryHook(hook RetryHookFunc) *Client

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

func SetCommonRetryInterval added in v3.9.0

func SetCommonRetryInterval(getRetryIntervalFunc GetRetryIntervalFunc) *Client

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

func SetCookieJar

func SetCookieJar(jar http.CookieJar) *Client

SetCookieJar is a global wrapper methods which delegated to the default client's Client.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 Client.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 Client.SetDialTLS.

func SetHTTP2ConnectionFlow added in v3.40.0

func SetHTTP2ConnectionFlow(flow uint32) *Client

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

func SetHTTP2HeaderPriority added in v3.40.0

func SetHTTP2HeaderPriority(priority http2.PriorityParam) *Client

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

func SetHTTP2MaxHeaderListSize added in v3.40.0

func SetHTTP2MaxHeaderListSize(max uint32) *Client

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

func SetHTTP2PingTimeout added in v3.40.0

func SetHTTP2PingTimeout(timeout time.Duration) *Client

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

func SetHTTP2PriorityFrames added in v3.40.0

func SetHTTP2PriorityFrames(frames ...http2.PriorityFrame) *Client

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

func SetHTTP2ReadIdleTimeout added in v3.40.0

func SetHTTP2ReadIdleTimeout(timeout time.Duration) *Client

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

func SetHTTP2SettingsFrame added in v3.40.0

func SetHTTP2SettingsFrame(settings ...http2.Setting) *Client

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

func SetHTTP2StrictMaxConcurrentStreams added in v3.40.0

func SetHTTP2StrictMaxConcurrentStreams(strict bool) *Client

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

func SetHTTP2WriteByteTimeout added in v3.40.0

func SetHTTP2WriteByteTimeout(timeout time.Duration) *Client

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

func SetJsonMarshal

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

SetJsonMarshal is a global wrapper methods which delegated to the default client's Client.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 Client.SetJsonUnmarshal.

func SetLogger

func SetLogger(log Logger) *Client

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

func SetOutputDirectory

func SetOutputDirectory(dir string) *Client

SetOutputDirectory is a global wrapper methods which delegated to the default client's Client.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 Client.SetProxy.

func SetProxyURL

func SetProxyURL(proxyUrl string) *Client

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

func SetRedirectPolicy

func SetRedirectPolicy(policies ...RedirectPolicy) *Client

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

func SetResponseBodyTransformer added in v3.28.0

func SetResponseBodyTransformer(fn func(rawBody []byte, req *Request, resp *Response) (transformedBody []byte, err error)) *Client

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

func SetResultStateCheckFunc added in v3.31.0

func SetResultStateCheckFunc(fn func(resp *Response) ResultState) *Client

SetResultStateCheckFunc is a global wrapper methods which delegated to the default client's Client.SetCommonResultStateCheckFunc.

func SetRootCertFromString

func SetRootCertFromString(pemContent string) *Client

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

func SetRootCertsFromFile

func SetRootCertsFromFile(pemFiles ...string) *Client

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

func SetScheme

func SetScheme(scheme string) *Client

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

func SetTLSClientConfig

func SetTLSClientConfig(conf *tls.Config) *Client

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

func SetTLSFingerprint added in v3.37.0

func SetTLSFingerprint(clientHelloID utls.ClientHelloID) *Client

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

func SetTLSFingerprint360 added in v3.37.0

func SetTLSFingerprint360() *Client

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

func SetTLSFingerprintAndroid added in v3.37.0

func SetTLSFingerprintAndroid() *Client

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

func SetTLSFingerprintChrome added in v3.37.0

func SetTLSFingerprintChrome() *Client

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

func SetTLSFingerprintEdge added in v3.37.0

func SetTLSFingerprintEdge() *Client

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

func SetTLSFingerprintFirefox added in v3.37.0

func SetTLSFingerprintFirefox() *Client

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

func SetTLSFingerprintIOS added in v3.37.0

func SetTLSFingerprintIOS() *Client

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

func SetTLSFingerprintQQ added in v3.37.0

func SetTLSFingerprintQQ() *Client

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

func SetTLSFingerprintRandomized added in v3.37.0

func SetTLSFingerprintRandomized() *Client

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

func SetTLSFingerprintSafari added in v3.37.0

func SetTLSFingerprintSafari() *Client

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

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 Client.SetTLSHandshakeTimeout.

func SetTimeout

func SetTimeout(d time.Duration) *Client

SetTimeout is a global wrapper methods which delegated to the default client's Client.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's Client.SetUnixSocket.

func SetUserAgent

func SetUserAgent(userAgent string) *Client

SetUserAgent is a global wrapper methods which delegated to the default client's Client.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 Client.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 Client.SetXmlUnmarshal.

func WrapRoundTrip added in v3.17.0

func WrapRoundTrip(wrappers ...RoundTripWrapper) *Client

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

func WrapRoundTripFunc added in v3.17.0

func WrapRoundTripFunc(funcs ...RoundTripWrapperFunc) *Client

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

func (*Client) AddCommonQueryParam

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

AddCommonQueryParam add a URL query parameter with a key-value pair for requests fired from the client.

func (*Client) AddCommonQueryParams added in v3.23.0

func (c *Client) AddCommonQueryParams(key string, values ...string) *Client

AddCommonQueryParams add one or more values of specified URL query parameter for requests fired from the client.

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 requests fired from the client, which will be executed before a retry.

func (*Client) ClearCookies added in v3.19.0

func (c *Client) ClearCookies() *Client

ClearCookies clears all cookies if cookie is enabled, including cookies from cookie jar and cookies set by SetCommonCookies. Note: The cookie jar will not be cleared if you called SetCookieJar instead of SetCookieJarFactory.

func (*Client) Clone

func (c *Client) Clone() *Client

Clone copy and returns the Client

func (*Client) Delete added in v3.15.0

func (c *Client) Delete(url ...string) *Request

Delete create a new DELETE request.

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 requests fired from the client.

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) DisableH2C added in v3.20.0

func (c *Client) DisableH2C() *Client

DisableH2C disables HTTP/2 over TCP without TLS.

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 requests fired from the client.

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 requests fired from the client, including all content for the request and response by default.

func (*Client) EnableDumpAllAsync

func (c *Client) EnableDumpAllAsync() *Client

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

func (*Client) EnableDumpAllToFile

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

EnableDumpAllToFile enable dump for requests fired from the client and output to the specified file.

func (*Client) EnableDumpAllWithoutBody

func (c *Client) EnableDumpAllWithoutBody() *Client

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

func (*Client) EnableDumpAllWithoutHeader

func (c *Client) EnableDumpAllWithoutHeader() *Client

EnableDumpAllWithoutHeader enable dump for requests fired from the client 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 requests fired from the client without request, can be used if you only care about the response.

func (*Client) EnableDumpAllWithoutRequestBody

func (c *Client) EnableDumpAllWithoutRequestBody() *Client

EnableDumpAllWithoutRequestBody enable dump for requests fired from the client 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 requests fired from the client without response, can be used if you only care about the request.

func (*Client) EnableDumpAllWithoutResponseBody

func (c *Client) EnableDumpAllWithoutResponseBody() *Client

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

func (*Client) EnableDumpEachRequest added in v3.18.0

func (c *Client) EnableDumpEachRequest() *Client

EnableDumpEachRequest enable dump at the request-level for each request, and only temporarily stores the dump content in memory, call Response.Dump() to get the dump content when needed.

func (*Client) EnableDumpEachRequestWithoutBody added in v3.18.0

func (c *Client) EnableDumpEachRequestWithoutBody() *Client

EnableDumpEachRequestWithoutBody enable dump without body at the request-level for each request, and only temporarily stores the dump content in memory, call Response.Dump() to get the dump content when needed.

func (*Client) EnableDumpEachRequestWithoutHeader added in v3.18.0

func (c *Client) EnableDumpEachRequestWithoutHeader() *Client

EnableDumpEachRequestWithoutHeader enable dump without header at the request-level for each request, and only temporarily stores the dump content in memory, call Response.Dump() to get the dump content when needed.

func (*Client) EnableDumpEachRequestWithoutRequest added in v3.18.0

func (c *Client) EnableDumpEachRequestWithoutRequest() *Client

EnableDumpEachRequestWithoutRequest enable dump without request at the request-level for each request, and only temporarily stores the dump content in memory, call Response.Dump() to get the dump content when needed.

func (*Client) EnableDumpEachRequestWithoutRequestBody added in v3.18.0

func (c *Client) EnableDumpEachRequestWithoutRequestBody() *Client

EnableDumpEachRequestWithoutRequestBody enable dump without request body at the request-level for each request, and only temporarily stores the dump content in memory, call Response.Dump() to get the dump content when needed.

func (*Client) EnableDumpEachRequestWithoutResponse added in v3.18.0

func (c *Client) EnableDumpEachRequestWithoutResponse() *Client

EnableDumpEachRequestWithoutResponse enable dump without response at the request-level for each request, and only temporarily stores the dump content in memory, call Response.Dump() to get the dump content when needed.

func (*Client) EnableDumpEachRequestWithoutResponseBody added in v3.18.0

func (c *Client) EnableDumpEachRequestWithoutResponseBody() *Client

EnableDumpEachRequestWithoutResponseBody enable dump without response body at the request-level for each request, and only temporarily stores the dump content in memory, call Response.Dump() to get the dump content when needed.

func (*Client) EnableForceHTTP1 added in v3.2.0

func (c *Client) EnableForceHTTP1() *Client

EnableForceHTTP1 enable force using HTTP1 (disabled by default).

Attention: This method should not be called when ImpersonateXXX, SetTLSFingerPrint or SetTLSHandshake and other methods that will customize the tls handshake are called.

func (*Client) EnableForceHTTP2 added in v3.4.0

func (c *Client) EnableForceHTTP2() *Client

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

Attention: This method should not be called when ImpersonateXXX, SetTLSFingerPrint or SetTLSHandshake and other methods that will customize the tls handshake are called.

func (*Client) EnableForceHTTP3 added in v3.14.0

func (c *Client) EnableForceHTTP3() *Client

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

Attention: This method should not be called when ImpersonateXXX, SetTLSFingerPrint or SetTLSHandshake and other methods that will customize the tls handshake are called.

func (*Client) EnableH2C added in v3.20.0

func (c *Client) EnableH2C() *Client

EnableH2C enables HTTP/2 over TCP without TLS.

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 requests fired from the client (http3 currently does not support trace).

func (*Client) Get added in v3.15.0

func (c *Client) Get(url ...string) *Request

Get create a new GET request, accepts 0 or 1 url.

func (*Client) GetClient added in v3.8.0

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

GetClient returns the underlying `http.Client`.

func (*Client) GetCookies added in v3.35.0

func (c *Client) GetCookies(url string) ([]*http.Cookie, error)

GetCookies get cookies from the underlying `http.Client`'s `CookieJar`.

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) Head added in v3.15.0

func (c *Client) Head(url ...string) *Request

Head create a new HEAD request.

func (*Client) ImpersonateChrome added in v3.40.0

func (c *Client) ImpersonateChrome() *Client

ImpersonateChrome impersonates Chrome browser (version 109).

func (*Client) ImpersonateFirefox added in v3.40.0

func (c *Client) ImpersonateFirefox() *Client

ImpersonateFirefox impersonates Firefox browser (version 105).

func (*Client) ImpersonateSafari added in v3.40.1

func (c *Client) ImpersonateSafari() *Client

ImpersonateSafari impersonates Safari browser (version 16).

func (*Client) NewParallelDownload added in v3.24.0

func (c *Client) NewParallelDownload(url string) *ParallelDownload

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) OnError added in v3.42.0

func (c *Client) OnError(hook ErrorHook) *Client

OnError set the error hook which will be executed if any error returned, even if the occurs before request is sent (e.g. invalid URL).

func (*Client) Options added in v3.15.0

func (c *Client) Options(url ...string) *Request

Options create a new OPTIONS request.

func (*Client) Patch added in v3.15.0

func (c *Client) Patch(url ...string) *Request

Patch create a new PATCH request.

func (*Client) Post added in v3.15.0

func (c *Client) Post(url ...string) *Request

Post create a new POST request.

func (*Client) Put added in v3.15.0

func (c *Client) Put(url ...string) *Request

Put create a new PUT request.

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 requests fired from the client.

func (*Client) SetCommonBearerAuthToken

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

SetCommonBearerAuthToken set the bearer auth token for requests fired from the client.

func (*Client) SetCommonContentType

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

SetCommonContentType set the `Content-Type` header for requests fired from the client.

func (*Client) SetCommonCookies

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

SetCommonCookies set HTTP cookies for requests fired from the client.

func (*Client) SetCommonDigestAuth added in v3.37.0

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

SetCommonDigestAuth sets the Digest Access auth scheme for requests fired from the client. If a server responds with 401 and sends a Digest challenge in the WWW-Authenticate Header, requests will be resent with the appropriate Authorization Header.

For Example: To set the Digest scheme with user "roc" and password "123456"

client.SetCommonDigestAuth("roc", "123456")

Information about Digest Access Authentication can be found in RFC7616:

https://datatracker.ietf.org/doc/html/rfc7616

See `Request.SetDigestAuth`

func (*Client) SetCommonDumpOptions

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

SetCommonDumpOptions configures the underlying Transport's DumpOptions for requests fired from the client.

func (*Client) SetCommonError deprecated 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 no error occurs but Response.ResultState returns ErrorState, by default it is HTTP status `code >= 400`, you can also use SetCommonResultStateChecker to customize the result state check logic.

Deprecated: Use SetCommonErrorResult instead.

func (*Client) SetCommonErrorResult added in v3.31.0

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

SetCommonErrorResult set the common result that response body will be unmarshalled to if no error occurs but Response.ResultState returns ErrorState, by default it is HTTP status `code >= 400`, you can also use SetCommonResultStateChecker to customize the result state check logic.

func (*Client) SetCommonFormData

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

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

func (*Client) SetCommonHeader

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

SetCommonHeader set a header for requests fired from the client.

func (*Client) SetCommonHeaderNonCanonical added in v3.11.0

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

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

func (*Client) SetCommonHeaderOrder added in v3.39.0

func (c *Client) SetCommonHeaderOrder(keys ...string) *Client

SetCommonHeaderOrder set the order of the http header requests fired from the client (case-insensitive). For example:

client.R().SetCommonHeaderOrder(
    "custom-header",
    "cookie",
    "user-agent",
    "accept-encoding",
).Get(url

func (*Client) SetCommonHeaders

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

SetCommonHeaders set headers for requests fired from the client.

func (*Client) SetCommonHeadersNonCanonical added in v3.11.0

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

SetCommonHeadersNonCanonical set headers for requests fired from the client 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 requests fired from the client.

func (*Client) SetCommonPathParams added in v3.7.0

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

SetCommonPathParams set path parameters for requests fired from the client.

func (*Client) SetCommonPseudoHeaderOder added in v3.39.0

func (c *Client) SetCommonPseudoHeaderOder(keys ...string) *Client

SetCommonPseudoHeaderOder set the order of the pseudo http header requests fired from the client (case-insensitive). Note this is only valid for http2 and http3. For example:

client.SetCommonPseudoHeaderOder(
    ":scheme",
    ":authority",
    ":path",
    ":method",
)

func (*Client) SetCommonQueryParam

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

SetCommonQueryParam set a URL query parameter with a key-value pair for requests fired from the client.

func (*Client) SetCommonQueryParams

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

SetCommonQueryParams set URL query parameters with a map for requests fired from the client.

func (*Client) SetCommonQueryString

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

SetCommonQueryString set URL query parameters with a raw query string for requests fired from the client.

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 requests fired from the client. 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 requests fired from the client. It will retry infinitely if count is negative.

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 requests fired from the client.

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 requests fired from the client, 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 cookie jar to the underlying `http.Client`, set to nil if you want to disable cookies. Note: If you use Client.Clone to clone a new Client, the new client will share the same cookie jar as the old Client after cloning. Use SetCookieJarFactory instead if you want to create a new CookieJar automatically when cloning a client.

func (*Client) SetCookieJarFactory added in v3.41.0

func (c *Client) SetCookieJarFactory(factory func() *cookiejar.Jar) *Client

SetCookieJarFactory set the functional factory of cookie jar, which creates cookie jar that store cookies for underlying `http.Client`. After client clone, the cookie jar of the new client will also be regenerated using this factory function.

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) SetHTTP2ConnectionFlow added in v3.40.0

func (c *Client) SetHTTP2ConnectionFlow(flow uint32) *Client

SetHTTP2ConnectionFlow set the default http2 connection flow, which is the increment value of initial WINDOW_UPDATE frame.

func (*Client) SetHTTP2HeaderPriority added in v3.40.0

func (c *Client) SetHTTP2HeaderPriority(priority http2.PriorityParam) *Client

SetHTTP2HeaderPriority set the header priority param.

func (*Client) SetHTTP2MaxHeaderListSize added in v3.33.0

func (c *Client) SetHTTP2MaxHeaderListSize(max uint32) *Client

SetHTTP2MaxHeaderListSize set the http2 MaxHeaderListSize, which is the http2 SETTINGS_MAX_HEADER_LIST_SIZE to send in the initial settings frame. It is how many bytes of response headers are allowed. Unlike the http2 spec, zero here means to use a default limit (currently 10MB). If you actually want to advertise an unlimited value to the peer, Transport interprets the highest possible value here (0xffffffff or 1<<32-1) to mean no limit.

func (*Client) SetHTTP2PingTimeout added in v3.33.0

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

SetHTTP2PingTimeout set the http2 PingTimeout, which is the timeout after which the connection will be closed if a response to Ping is not received. Defaults to 15s

func (*Client) SetHTTP2PriorityFrames added in v3.40.0

func (c *Client) SetHTTP2PriorityFrames(frames ...http2.PriorityFrame) *Client

SetHTTP2PriorityFrames set the ordered http2 priority frames.

func (*Client) SetHTTP2ReadIdleTimeout added in v3.33.0

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

SetHTTP2ReadIdleTimeout set the http2 ReadIdleTimeout, which is the timeout after which a health check using ping frame will be carried out if no frame is received on the connection. Note that a ping response will is considered a received frame, so if there is no other traffic on the connection, the health check will be performed every ReadIdleTimeout interval. If zero, no health check is performed.

func (*Client) SetHTTP2SettingsFrame added in v3.40.0

func (c *Client) SetHTTP2SettingsFrame(settings ...http2.Setting) *Client

SetHTTP2SettingsFrame set the ordered http2 settings frame.

func (*Client) SetHTTP2StrictMaxConcurrentStreams added in v3.33.0

func (c *Client) SetHTTP2StrictMaxConcurrentStreams(strict bool) *Client

SetHTTP2StrictMaxConcurrentStreams set the http2 StrictMaxConcurrentStreams, which controls whether the server's SETTINGS_MAX_CONCURRENT_STREAMS should be respected globally. If false, new TCP connections are created to the server as needed to keep each under the per-connection SETTINGS_MAX_CONCURRENT_STREAMS limit. If true, the server's SETTINGS_MAX_CONCURRENT_STREAMS is interpreted as a global limit and callers of RoundTrip block when needed, waiting for their turn.

func (*Client) SetHTTP2WriteByteTimeout added in v3.33.0

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

SetHTTP2WriteByteTimeout set the http2 WriteByteTimeout, which is the timeout after which the connection will be closed no data can be written to it. The timeout begins when data is available to write, and is extended whenever any bytes are written.

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) SetResponseBodyTransformer added in v3.28.0

func (c *Client) SetResponseBodyTransformer(fn func(rawBody []byte, req *Request, resp *Response) (transformedBody []byte, err error)) *Client

SetResponseBodyTransformer set the response body transformer, which can modify the response body before unmarshalled if auto-read response body is not disabled.

func (*Client) SetResultStateCheckFunc added in v3.31.0

func (c *Client) SetResultStateCheckFunc(fn func(resp *Response) ResultState) *Client

SetResultStateCheckFunc overrides the default result state checker with customized one, which returns SuccessState when HTTP status `code >= 200 and <= 299`, and returns ErrorState when HTTP status `code >= 400`, otherwise returns UnknownState.

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) SetTLSFingerprint added in v3.36.0

func (c *Client) SetTLSFingerprint(clientHelloID utls.ClientHelloID) *Client

SetTLSFingerprint set the tls fingerprint for tls handshake, will use utls (https://github.com/refraction-networking/utls) to perform the tls handshake, which uses the specified clientHelloID to simulate the tls fingerprint. Note this is valid for HTTP1 and HTTP2, not HTTP3.

func (*Client) SetTLSFingerprint360 added in v3.36.0

func (c *Client) SetTLSFingerprint360() *Client

SetTLSFingerprint360 uses tls fingerprint of 360 browser.

func (*Client) SetTLSFingerprintAndroid added in v3.36.0

func (c *Client) SetTLSFingerprintAndroid() *Client

SetTLSFingerprintAndroid uses tls fingerprint of Android.

func (*Client) SetTLSFingerprintChrome added in v3.36.0

func (c *Client) SetTLSFingerprintChrome() *Client

SetTLSFingerprintChrome uses tls fingerprint of Chrome browser.

func (*Client) SetTLSFingerprintEdge added in v3.36.0

func (c *Client) SetTLSFingerprintEdge() *Client

SetTLSFingerprintEdge uses tls fingerprint of Edge browser.

func (*Client) SetTLSFingerprintFirefox added in v3.36.0

func (c *Client) SetTLSFingerprintFirefox() *Client

SetTLSFingerprintFirefox uses tls fingerprint of Firefox browser.

func (*Client) SetTLSFingerprintIOS added in v3.36.0

func (c *Client) SetTLSFingerprintIOS() *Client

SetTLSFingerprintIOS uses tls fingerprint of IOS.

func (*Client) SetTLSFingerprintQQ added in v3.36.0

func (c *Client) SetTLSFingerprintQQ() *Client

SetTLSFingerprintQQ uses tls fingerprint of QQ browser.

func (*Client) SetTLSFingerprintRandomized added in v3.36.1

func (c *Client) SetTLSFingerprintRandomized() *Client

SetTLSFingerprintRandomized uses randomized tls fingerprint.

func (*Client) SetTLSFingerprintSafari added in v3.36.0

func (c *Client) SetTLSFingerprintSafari() *Client

SetTLSFingerprintSafari uses tls fingerprint of Safari browser.

func (*Client) SetTLSHandshake added in v3.36.1

func (c *Client) SetTLSHandshake(fn func(ctx context.Context, addr string, plainConn net.Conn) (conn net.Conn, tlsState *tls.ConnectionState, err error)) *Client

SetTLSHandshake set the custom tls handshake function, only valid for HTTP1 and HTTP2, not HTTP3, it specifies an optional dial function for tls handshake, it works even if a proxy is set, can be used to customize the tls fingerprint.

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 requests fired from the client.

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 requests fired from the client.

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.

func (*Client) WrapRoundTrip added in v3.16.0

func (c *Client) WrapRoundTrip(wrappers ...RoundTripWrapper) *Client

WrapRoundTrip adds a client middleware function that will give the caller an opportunity to wrap the underlying http.RoundTripper.

func (*Client) WrapRoundTripFunc added in v3.16.0

func (c *Client) WrapRoundTripFunc(funcs ...RoundTripWrapperFunc) *Client

WrapRoundTripFunc adds a client middleware function that will give the caller an opportunity to wrap the underlying http.RoundTripper.

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
	RequestOutput        io.Writer
	ResponseOutput       io.Writer
	RequestHeaderOutput  io.Writer
	RequestBodyOutput    io.Writer
	ResponseHeaderOutput io.Writer
	ResponseBodyOutput   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 ErrorHook added in v3.42.0

type ErrorHook func(client *Client, req *Request, resp *Response, err error)

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 Content-Type
	ContentType string

	// 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 HttpRoundTripFunc added in v3.17.0

type HttpRoundTripFunc func(req *http.Request) (resp *http.Response, err error)

HttpRoundTripFunc is a http.RoundTripper implementation, which is a simple function.

func (HttpRoundTripFunc) RoundTrip added in v3.17.0

func (fn HttpRoundTripFunc) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper.

type HttpRoundTripWrapper added in v3.17.0

type HttpRoundTripWrapper func(rt http.RoundTripper) http.RoundTripper

HttpRoundTripWrapper is transport middleware function.

type HttpRoundTripWrapperFunc added in v3.17.0

type HttpRoundTripWrapperFunc func(rt http.RoundTripper) HttpRoundTripFunc

HttpRoundTripWrapperFunc is transport middleware function, more convenient than HttpRoundTripWrapper.

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 ParallelDownload added in v3.24.0

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

func (*ParallelDownload) Do added in v3.24.0

func (pd *ParallelDownload) Do(ctx ...context.Context) error

func (*ParallelDownload) SetConcurrency added in v3.24.0

func (pd *ParallelDownload) SetConcurrency(concurrency int) *ParallelDownload

func (*ParallelDownload) SetFileMode added in v3.24.0

func (pd *ParallelDownload) SetFileMode(perm os.FileMode) *ParallelDownload

func (*ParallelDownload) SetOutput added in v3.24.0

func (pd *ParallelDownload) SetOutput(output io.Writer) *ParallelDownload

func (*ParallelDownload) SetOutputFile added in v3.24.0

func (pd *ParallelDownload) SetOutputFile(filename string) *ParallelDownload

func (*ParallelDownload) SetSegmentSize added in v3.24.0

func (pd *ParallelDownload) SetSegmentSize(segmentSize int64) *ParallelDownload

func (*ParallelDownload) SetTempRootDir added in v3.24.0

func (pd *ParallelDownload) SetTempRootDir(tempRootDir string) *ParallelDownload

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
	Body         []byte
	GetBody      GetContentFunc
	// URL is an auto-generated field, and is nil in request middleware (OnBeforeRequest),
	// consider using RawURL if you want, it's not nil in client middleware (WrapRoundTripFunc)
	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 AddQueryParams added in v3.23.0

func AddQueryParams(key string, values ...string) *Request

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

func DisableForceChunkedEncoding() *Request

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

func DisableForceMultipart added in v3.21.1

func DisableForceMultipart() *Request

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

func EnableCloseConnection() *Request

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

func EnableForceChunkedEncoding() *Request

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

func EnableForceMultipart added in v3.21.1

func EnableForceMultipart() *Request

EnableForceMultipart is a global wrapper methods which delegated to the default client, create a request and EnableForceMultipart 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 Client.NewRequest.

func R

func R() *Request

R is a global wrapper methods which delegated to the default client's Client.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 SetDigestAuth added in v3.37.0

func SetDigestAuth(username, password string) *Request

SetDigestAuth is a global wrapper methods which delegated to the default client, create a request and SetDigestAuth 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 deprecated

func SetError(error interface{}) *Request

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

Deprecated: Use SetErrorResult instead.

func SetErrorResult added in v3.31.0

func SetErrorResult(error interface{}) *Request

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

func SetFormDataAnyType(data map[string]interface{}) *Request

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

func SetHeaderOrder(keys ...string) *Request

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

func SetPseudoHeaderOrder(keys ...string) *Request

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

func SetQueryParamsAnyType(params map[string]interface{}) *Request

SetQueryParamsAnyType is a global wrapper methods which delegated to the default client, create a request and SetQueryParamsAnyType 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 deprecated

func SetResult(result interface{}) *Request

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

Deprecated: Use SetSuccessResult instead.

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 SetSuccessResult added in v3.31.0

func SetSuccessResult(result interface{}) *Request

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

func SetURL added in v3.15.0

func SetURL(url string) *Request

SetURL is a global wrapper methods which delegated to the default client, create a request and SetURL 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) AddQueryParams added in v3.23.0

func (r *Request) AddQueryParams(key string, values ...string) *Request

AddQueryParams add one or more values of specified 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) DisableAutoReadResponse added in v3.26.4

func (r *Request) DisableAutoReadResponse() *Request

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

func (*Request) DisableForceChunkedEncoding added in v3.21.0

func (r *Request) DisableForceChunkedEncoding() *Request

DisableForceChunkedEncoding disables force using chunked encoding when uploading.

func (*Request) DisableForceMultipart added in v3.21.1

func (r *Request) DisableForceMultipart() *Request

DisableForceMultipart disables force using multipart to upload form data.

func (*Request) DisableTrace

func (r *Request) DisableTrace() *Request

DisableTrace disables trace.

func (*Request) Do added in v3.15.0

func (r *Request) Do(ctx ...context.Context) *Response

Do fires http request, 0 or 1 context is allowed, and returns the *Response which is always not nil, and Response.Err is not nil if error occurs.

func (*Request) EnableAutoReadResponse added in v3.26.4

func (r *Request) EnableAutoReadResponse() *Request

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

func (*Request) EnableCloseConnection added in v3.26.1

func (r *Request) EnableCloseConnection() *Request

EnableCloseConnection closes the connection after sending this request and reading its response if set to true in HTTP/1.1 and HTTP/2.

Setting this field prevents re-use of TCP connections between requests to the same hosts event if EnableKeepAlives() were called.

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) EnableForceChunkedEncoding added in v3.21.0

func (r *Request) EnableForceChunkedEncoding() *Request

EnableForceChunkedEncoding enables force using chunked encoding when uploading.

func (*Request) EnableForceMultipart added in v3.21.1

func (r *Request) EnableForceMultipart() *Request

EnableForceMultipart enables force using multipart to upload form data.

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

func (r *Request) GetClient() *Client

GetClient returns the current client used by request.

func (*Request) Head

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

Head fires http request with HEAD method and the specified URL.

func (*Request) HeaderToString added in v3.17.3

func (r *Request) HeaderToString() string

HeaderToString get all header as string.

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) OnAfterResponse added in v3.37.0

func (r *Request) OnAfterResponse(m ResponseMiddleware) *Request

OnAfterResponse add a response middleware which hooks after response received.

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 with specified method and url, returns the *Response which is always not nil, and the error is not nil if error occurs.

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) SetClient added in v3.22.0

func (r *Request) SetClient(client *Client) *Request

SetClient change the client of request dynamically.

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.

Attention: make sure call SetContext before EnableDumpXXX if you want to dump at the request level.

func (*Request) SetCookies

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

SetCookies set http cookies for the request.

func (*Request) SetDigestAuth added in v3.37.0

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

SetDigestAuth sets the Digest Access auth scheme for the HTTP request. If a server responds with 401 and sends a Digest challenge in the WWW-Authenticate Header, the request will be resent with the appropriate Authorization Header.

For Example: To set the Digest scheme with username "roc" and password "123456"

client.R().SetDigestAuth("roc", "123456")

Information about Digest Access Authentication can be found in RFC7616:

https://datatracker.ietf.org/doc/html/rfc7616

This method overrides the username and password set by method `Client.SetCommonDigestAuth`.

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 deprecated

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

SetError set the result that response body will be unmarshalled to if no error occurs and Response.ResultState() returns ErrorState, by default it requires HTTP status `code >= 400`, you can also use Request.SetResultStateCheckFunc or Client.SetResultStateCheckFunc to customize the result state check logic.

Deprecated: Use SetErrorResult result.

func (*Request) SetErrorResult added in v3.31.0

func (r *Request) SetErrorResult(err interface{}) *Request

SetErrorResult set the result that response body will be unmarshalled to if no error occurs and Response.ResultState() returns ErrorState, by default it requires HTTP status `code >= 400`, you can also use Request.SetResultStateCheckFunc or Client.SetResultStateCheckFunc to customize the result state check logic.

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) SetFormDataAnyType added in v3.17.1

func (r *Request) SetFormDataAnyType(data map[string]interface{}) *Request

SetFormDataAnyType set the form data from a map, which value could be any type, will convert to string automatically. It 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) SetHeaderOrder added in v3.39.0

func (r *Request) SetHeaderOrder(keys ...string) *Request

SetHeaderOrder set the order of the http header (case-insensitive). For example:

client.R().SetHeaderOrder(
    "custom-header",
    "cookie",
    "user-agent",
    "accept-encoding",
)

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) SetPseudoHeaderOrder added in v3.39.0

func (r *Request) SetPseudoHeaderOrder(keys ...string) *Request

SetPseudoHeaderOrder set the order of the pseudo http header (case-insensitive). Note this is only valid for http2 and http3. For example:

client.R().SetPseudoHeaderOrder(
    ":scheme",
    ":authority",
    ":path",
    ":method",
)

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) SetQueryParamsAnyType added in v3.17.2

func (r *Request) SetQueryParamsAnyType(params map[string]interface{}) *Request

SetQueryParamsAnyType set URL query parameters from a map for the request. The value of map is any type, will be convert to string automatically.

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 deprecated

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

SetResult set the result that response Body will be unmarshalled to if no error occurs and Response.ResultState() returns SuccessState, by default it requires HTTP status `code >= 200 && code <= 299`, you can also use Request.SetResultStateCheckFunc or Client.SetResultStateCheckFunc to customize the result state check logic.

Deprecated: Use SetSuccessResult instead.

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. It will retry infinitely if count is negative.

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) SetSuccessResult added in v3.31.0

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

SetSuccessResult set the result that response Body will be unmarshalled to if no error occurs and Response.ResultState() returns SuccessState, by default it requires HTTP status `code >= 200 && code <= 299`, you can also use Request.SetResultStateCheckFunc or Client.SetResultStateCheckFunc to customize the result state check logic.

func (*Request) SetURL added in v3.15.0

func (r *Request) SetURL(url string) *Request

SetURL set the url for request.

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 *Client, req *Request) error

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

type Response

type Response struct {
	// The underlying http.Response is embed into Response.
	*http.Response
	// Err is the underlying error, not nil if some error occurs.
	// Usually used in the ResponseMiddleware, you can skip logic in
	// ResponseMiddleware that doesn't need to be executed when err occurs.
	Err error
	// Request is the Response's related Request.
	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` and `Request.DisableAutoReadResponse` is not called, and 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 deprecated

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

Error returns the automatically unmarshalled object when Request.SetErrorResult or Client.SetCommonErrorResult is called, and ResultState returns ErrorState. Otherwise, return nil.

Deprecated: Use ErrorResult instead.

func (*Response) ErrorResult added in v3.31.0

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

ErrorResult returns the automatically unmarshalled object when Request.SetErrorResult or Client.SetCommonErrorResult is called, and ResultState returns ErrorState. Otherwise, return nil.

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) HeaderToString added in v3.17.3

func (r *Response) HeaderToString() string

HeaderToString get all header as string.

func (*Response) Into added in v3.15.0

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

Into unmarshalls response body into the specified object according to response `Content-Type`.

func (*Response) IsError deprecated

func (r *Response) IsError() bool

IsError method returns true if no error occurs and HTTP status `code >= 400` by default, you can also use Request.SetResultStateCheckFunc to customize the result state check logic.

Deprecated: Use IsErrorState instead.

func (*Response) IsErrorState added in v3.31.0

func (r *Response) IsErrorState() bool

IsErrorState method returns true if no error occurs and HTTP status `code >= 400` by default, you can also use Request.SetResultStateCheckFunc to customize the result state check logic.

func (*Response) IsSuccess deprecated

func (r *Response) IsSuccess() bool

IsSuccess method returns true if no error occurs and HTTP status `code >= 200 and <= 299` by default, you can also use Request.SetResultStateCheckFunc to customize the result state check logic.

Deprecated: Use IsSuccessState instead.

func (*Response) IsSuccessState added in v3.31.0

func (r *Response) IsSuccessState() bool

IsSuccessState method returns true if no error occurs and HTTP status `code >= 200 and <= 299` by default, you can also use Request.SetResultStateCheckFunc to customize the result state check logic.

func (*Response) ReceivedAt

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

ReceivedAt returns the timestamp that response we received.

func (*Response) Result deprecated

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

Result returns the automatically unmarshalled object if Request.SetSuccessResult is called and ResultState returns SuccessState. Otherwise, return nil.

Deprecated: Use SuccessResult instead.

func (*Response) ResultState added in v3.31.0

func (r *Response) ResultState() ResultState

ResultState returns the result state. By default, it returns SuccessState if HTTP status `code >= 400`, and returns ErrorState if HTTP status `code >= 400`, otherwise returns UnknownState. You can also use Request.SetResultStateCheckFunc or Client.SetResultStateCheckFunc to customize the result state check logic.

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` and `Request.DisableAutoReadResponse` is not called, and also `Request.SetOutput` and `Request.SetOutputFile` is not called.

func (*Response) SuccessResult added in v3.31.0

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

SuccessResult returns the automatically unmarshalled object if Request.SetSuccessResult is called and ResultState returns SuccessState. Otherwise, return nil.

func (*Response) ToBytes

func (r *Response) ToBytes() (body []byte, err 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 unmarshalls response body into the specified object according to response `Content-Type`.

func (*Response) UnmarshalJson

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

UnmarshalJson unmarshalls JSON response body into the specified object.

func (*Response) UnmarshalXml

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

UnmarshalXml unmarshalls XML response body into the specified object.

type ResponseMiddleware

type ResponseMiddleware func(client *Client, resp *Response) error

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

type ResultState added in v3.31.0

type ResultState int

ResultState represents the state of the result.

const (
	// SuccessState indicates the response is in success state,
	// and result will be unmarshalled if Request.SetSuccessResult
	// is called.
	SuccessState ResultState = iota
	// ErrorState indicates the response is in error state,
	// and result will be unmarshalled if Request.SetErrorResult
	// or Client.SetCommonErrorResult is called.
	ErrorState
	// UnknownState indicates the response is in unknown state,
	// and handler will be invoked if Request.SetUnknownResultHandlerFunc
	// or Client.SetCommonUnknownResultHandlerFunc is called.
	UnknownState
)

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 RoundTripFunc added in v3.16.0

type RoundTripFunc func(req *Request) (resp *Response, err error)

RoundTripFunc is a RoundTripper implementation, which is a simple function.

func (RoundTripFunc) RoundTrip added in v3.16.0

func (fn RoundTripFunc) RoundTrip(req *Request) (*Response, error)

RoundTrip implements RoundTripper.

type RoundTripWrapper added in v3.16.0

type RoundTripWrapper func(rt RoundTripper) RoundTripper

RoundTripWrapper is client middleware function.

type RoundTripWrapperFunc added in v3.16.0

type RoundTripWrapperFunc func(rt RoundTripper) RoundTripFunc

RoundTripWrapperFunc is client middleware function, more convenient than RoundTripWrapper.

type RoundTripper added in v3.17.0

type RoundTripper interface {
	RoundTrip(*Request) (*Response, error)
}

RoundTripper is the interface of req's Client.

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 {
	Headers http.Header
	Cookies []*http.Cookie

	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 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) DisableH2C added in v3.20.0

func (t *Transport) DisableH2C() *Transport

DisableH2C disables HTTP2 over TCP without TLS.

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) EnableH2C added in v3.20.0

func (t *Transport) EnableH2C() *Transport

EnableH2C enables HTTP2 over TCP without TLS.

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 optional 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, which specifies the dial function for creating unencrypted TCP connections. If it is nil, then the transport dials using package net.

The dial function 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 dial function completes.

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, which specifies an optional dial function for creating TLS connections for non-proxied HTTPS requests (proxy will not work if set).

If it is nil, DialContext and TLSClientConfig are used.

If it is set, the function that set in SetDial is 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.

func (*Transport) SetExpectContinueTimeout added in v3.14.0

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

SetExpectContinueTimeout set the 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.

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, which 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.

func (*Transport) SetHTTP2ConnectionFlow added in v3.40.0

func (t *Transport) SetHTTP2ConnectionFlow(flow uint32) *Transport

SetHTTP2ConnectionFlow set the default http2 connection flow, which is the increment value of initial WINDOW_UPDATE frame.

func (*Transport) SetHTTP2HeaderPriority added in v3.40.0

func (t *Transport) SetHTTP2HeaderPriority(priority http2.PriorityParam) *Transport

SetHTTP2HeaderPriority set the header priority param.

func (*Transport) SetHTTP2MaxHeaderListSize added in v3.33.0

func (t *Transport) SetHTTP2MaxHeaderListSize(max uint32) *Transport

SetHTTP2MaxHeaderListSize set the http2 MaxHeaderListSize, which is the http2 SETTINGS_MAX_HEADER_LIST_SIZE to send in the initial settings frame. It is how many bytes of response headers are allowed. Unlike the http2 spec, zero here means to use a default limit (currently 10MB). If you actually want to advertise an unlimited value to the peer, Transport interprets the highest possible value here (0xffffffff or 1<<32-1) to mean no limit.

func (*Transport) SetHTTP2PingTimeout added in v3.33.0

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

SetHTTP2PingTimeout set the http2 PingTimeout, which is the timeout after which the connection will be closed if a response to Ping is not received. Defaults to 15s

func (*Transport) SetHTTP2PriorityFrames added in v3.40.0

func (t *Transport) SetHTTP2PriorityFrames(frames ...http2.PriorityFrame) *Transport

SetHTTP2PriorityFrames set the ordered http2 priority frames.

func (*Transport) SetHTTP2ReadIdleTimeout added in v3.33.0

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

SetHTTP2ReadIdleTimeout set the http2 ReadIdleTimeout, which is the timeout after which a health check using ping frame will be carried out if no frame is received on the connection. Note that a ping response will is considered a received frame, so if there is no other traffic on the connection, the health check will be performed every ReadIdleTimeout interval. If zero, no health check is performed.

func (*Transport) SetHTTP2SettingsFrame added in v3.40.0

func (t *Transport) SetHTTP2SettingsFrame(settings ...http2.Setting) *Transport

SetHTTP2SettingsFrame set the ordered http2 settings frame.

func (*Transport) SetHTTP2StrictMaxConcurrentStreams added in v3.33.0

func (t *Transport) SetHTTP2StrictMaxConcurrentStreams(strict bool) *Transport

SetHTTP2StrictMaxConcurrentStreams set the http2 StrictMaxConcurrentStreams, which controls whether the server's SETTINGS_MAX_CONCURRENT_STREAMS should be respected globally. If false, new TCP connections are created to the server as needed to keep each under the per-connection SETTINGS_MAX_CONCURRENT_STREAMS limit. If true, the server's SETTINGS_MAX_CONCURRENT_STREAMS is interpreted as a global limit and callers of RoundTrip block when needed, waiting for their turn.

func (*Transport) SetHTTP2WriteByteTimeout added in v3.33.0

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

SetHTTP2WriteByteTimeout set the http2 WriteByteTimeout, which is the timeout after which the connection will be closed no data can be written to it. The timeout begins when data is available to write, and is extended whenever any bytes are written.

func (*Transport) SetIdleConnTimeout added in v3.14.0

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

SetIdleConnTimeout set the IdleConnTimeout, which is the maximum amount of time an idle (keep-alive) connection will remain idle before closing itself.

Zero means no limit.

func (*Transport) SetMaxConnsPerHost added in v3.14.0

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

SetMaxConnsPerHost set the 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.

func (*Transport) SetMaxIdleConns added in v3.14.0

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

SetMaxIdleConns set the MaxIdleConns, which controls the maximum number of idle (keep-alive) connections across all hosts. Zero means no limit.

func (*Transport) SetMaxResponseHeaderBytes added in v3.14.0

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

SetMaxResponseHeaderBytes set the MaxResponseHeaderBytes, which specifies a limit on how many response bytes are allowed in the server's response header.

Zero means to use a default limit.

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, which 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.

func (*Transport) SetProxyConnectHeader added in v3.14.0

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

SetProxyConnectHeader set the ProxyConnectHeader, which optionally specifies headers to send to proxies during CONNECT requests. To set the header dynamically, see SetGetProxyConnectHeader.

func (*Transport) SetReadBufferSize added in v3.14.0

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

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

func (*Transport) SetResponseHeaderTimeout added in v3.14.0

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

SetResponseHeaderTimeout set the 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.

func (*Transport) SetTLSClientConfig added in v3.14.0

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

SetTLSClientConfig set the custom TLSClientConfig, which 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.

func (*Transport) SetTLSHandshake added in v3.36.1

func (t *Transport) SetTLSHandshake(fn func(ctx context.Context, addr string, plainConn net.Conn) (conn net.Conn, tlsState *tls.ConnectionState, err error)) *Transport

SetTLSHandshake set the custom tls handshake function, only valid for HTTP1 and HTTP2, not HTTP3, it specifies an optional dial function for tls handshake, it works even if a proxy is set, can be used to customize the tls fingerprint.

func (*Transport) SetTLSHandshakeTimeout added in v3.14.0

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

SetTLSHandshakeTimeout set the TLSHandshakeTimeout, which specifies the maximum amount of time waiting to wait for a TLS handshake.

Zero means no timeout.

func (*Transport) SetWriteBufferSize added in v3.14.0

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

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

func (*Transport) WrapRoundTrip added in v3.16.0

func (t *Transport) WrapRoundTrip(wrappers ...HttpRoundTripWrapper) *Transport

WrapRoundTrip adds a transport middleware function that will give the caller an opportunity to wrap the underlying http.RoundTripper.

func (*Transport) WrapRoundTripFunc added in v3.16.0

func (t *Transport) WrapRoundTripFunc(funcs ...HttpRoundTripWrapperFunc) *Transport

WrapRoundTripFunc adds a transport middleware function that will give the caller an opportunity to wrap the underlying http.RoundTripper.

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.

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.
godebug
Package godebug parses the GODEBUG environment variable.
Package godebug parses the GODEBUG environment variable.
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.
pkg
tls

Jump to

Keyboard shortcuts

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