req

package module
v2.0.0-alpha.2 Latest Latest
Warning

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

Go to latest
Published: Jan 21, 2022 License: MIT Imports: 47 Imported by: 3

README

req

GoDoc

A golang http request library for humans

Features

  • Simple and chainable methods for client and request settings
  • Rich syntax sugar, greatly improving development efficiency
  • Powerful debugging capabilities
  • The settings can be dynamically adjusted, making it possible to debug in the production environment

Install

go get github.com/imroc/req/v2

Documentation

Index

Constants

View Source
const (
	CONTENT_TYPE_APPLICATION_JSON_UTF8 = "application/json; charset=UTF-8"
	CONTENT_TYPE_APPLICATION_XML_UTF8  = "application/xml; charset=UTF-8"
	CONTENT_TYPE_TEXT_XML_UTF8         = "text/xml; charset=UTF-8"
	CONTENT_TYPE_TEXT_HTML_UTF8        = "text/html; charset=UTF-8"
	CONTENT_TYPE_TEXT_PLAIN_UTF8       = "text/plain; charset=UTF-8"
)
View Source
const DefaultMaxIdleConnsPerHost = 2

DefaultMaxIdleConnsPerHost is the default value of Transport's MaxIdleConnsPerHost.

Variables

View Source
var ErrBodyReadAfterClose = errors.New("http: invalid Read on closed Body")

ErrBodyReadAfterClose is returned when reading a Request or Response Body after the body has been closed. This typically happens when the body is read after an HTTP Handler calls WriteHeader or Write on its ResponseWriter.

View Source
var ErrLineTooLong = internal.ErrLineTooLong

ErrLineTooLong is returned when reading request or response bodies with malformed chunked encoding.

View Source
var NoBody = noBody{}

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

Functions

func CanonicalMIMEHeaderKey

func CanonicalMIMEHeaderKey(s string) string

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

func ProxyFromEnvironment

func ProxyFromEnvironment(req *http.Request) (*url.URL, error)

ProxyFromEnvironment returns the URL of the proxy to use for a given request, as indicated by the environment variables HTTP_PROXY, HTTPS_PROXY and NO_PROXY (or the lowercase versions thereof). HTTPS_PROXY takes precedence over HTTP_PROXY for https requests.

The environment values may be either a complete URL or a "host[:port]", in which case the "http" scheme is assumed. The schemes "http", "https", and "socks5" are supported. An error is returned if the value is a different form.

A nil URL and nil error are returned if no proxy is defined in the environment, or a proxy should not be used for the given request, as defined by NO_PROXY.

As a special case, if req.URL.Host is "localhost" (with or without a port number), then a nil URL and nil error will be returned.

func ProxyURL

func ProxyURL(fixedURL *url.URL) func(*http.Request) (*url.URL, error)

ProxyURL returns a proxy function (for use in a Transport) that always returns the same URL.

func SetDefaultClient

func SetDefaultClient(c *Client)

Types

type Body

type Body struct {
	io.ReadCloser
	// contains filtered or unexported fields
}

func (Body) Bytes

func (body Body) Bytes() ([]byte, error)

func (Body) MustBytes

func (body Body) MustBytes() []byte

func (Body) MustSave

func (body Body) MustSave(dst io.Writer)

func (Body) MustSaveFile

func (body Body) MustSaveFile(filename string)

func (Body) MustString

func (body Body) MustString() string

func (Body) MustUnmarshal

func (body Body) MustUnmarshal(v interface{})

func (Body) MustUnmarshalJson

func (body Body) MustUnmarshalJson(v interface{})

func (Body) MustUnmarshalXml

func (body Body) MustUnmarshalXml(v interface{})

func (Body) Save

func (body Body) Save(dst io.Writer) error

func (Body) SaveFile

func (body Body) SaveFile(filename string) error

func (Body) String

func (body Body) String() (string, error)

func (Body) Unmarshal

func (body Body) Unmarshal(v interface{}) error

func (Body) UnmarshalJson

func (body Body) UnmarshalJson(v interface{}) error

func (Body) UnmarshalXml

func (body Body) UnmarshalXml(v interface{}) error

type Client

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

func C

func C() *Client

func DefaultClient

func DefaultClient() *Client

func NewClient

func NewClient() *Client

NewClient is the alias of C()

func (*Client) DisableDump

func (c *Client) DisableDump() *Client

func (*Client) DumpOptions

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

func (*Client) EnableDump

func (c *Client) EnableDump(opts ...DumpOption) *Client

func (*Client) Header

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

func (*Client) NewRequest

func (c *Client) NewRequest() *Request

NewRequest is the alias of R()

func (*Client) R

func (c *Client) R() *Request

func (*Client) ResponseOption

func (c *Client) ResponseOption(opts ...ResponseOption) *Client

func (*Client) ResponseOptions

func (c *Client) ResponseOptions(opts ResponseOptions) *Client

func (*Client) Timeout

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

func (*Client) UserAgent

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

type DumpOption

type DumpOption func(*DumpOptions)

func DumpAll

func DumpAll() DumpOption

func DumpAsync

func DumpAsync() DumpOption

func DumpBody

func DumpBody() DumpOption

func DumpHead

func DumpHead() DumpOption

func DumpRequest

func DumpRequest() DumpOption

func DumpResponse

func DumpResponse() DumpOption

func DumpTo

func DumpTo(output io.Writer) DumpOption

func DumpToFile

func DumpToFile(filename string) DumpOption

type DumpOptions

type DumpOptions struct {
	Output       io.Writer
	RequestHead  bool
	RequestBody  bool
	ResponseHead bool
	ResponseBody bool
	Async        bool
}

func DefaultDumpOptions

func DefaultDumpOptions() *DumpOptions

func (*DumpOptions) Set

func (do *DumpOptions) Set(opts ...DumpOption)

type Request

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

func New

func New() *Request

func (*Request) Body

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

func (*Request) BodyBytes

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

func (*Request) BodyJsonBytes

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

func (*Request) BodyJsonMarshal

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

func (*Request) BodyJsonString

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

func (*Request) BodyString

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

func (*Request) Delete

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

func (*Request) Error

func (r *Request) Error() error

func (*Request) Get

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

func (*Request) Head

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

func (*Request) Method

func (r *Request) Method(method string) *Request

func (*Request) MustDelete

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

func (*Request) MustGet

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

func (*Request) MustHead

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

func (*Request) MustOptions

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

func (*Request) MustPatch

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

func (*Request) MustPost

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

func (*Request) MustPut

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

func (*Request) Options

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

func (*Request) Patch

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

func (*Request) Post

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

func (*Request) Put

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

func (*Request) Send

func (r *Request) Send() (resp *Response, err error)

func (*Request) URL

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

type Response

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

func (*Response) Body

func (r *Response) Body() Body

type ResponseOption

type ResponseOption func(o *ResponseOptions)

func AutoDecodeContentType

func AutoDecodeContentType(contentTypes ...string) ResponseOption

AutoDecodeContentType specifies that the response body should been auto-decoded when content type contains keywords that here given.

func AutoDecodeContentTypeFunc

func AutoDecodeContentTypeFunc(fn func(contentType string) bool) ResponseOption

AutoDecodeContentTypeFunc customize the function to determine whether response body should auto decode with specified content type.

func DisableAutoDecode

func DisableAutoDecode() ResponseOption

DisableAutoDecode disable the response body auto-decode to improve performance.

func DiscardBody

func DiscardBody() ResponseOption

type ResponseOptions

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

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

	Discard bool
}

type Transport

type Transport struct {

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

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

	// Dial specifies the dial function for creating unencrypted TCP connections.
	//
	// Dial 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 completes.
	//
	// Deprecated: Use DialContext instead, which allows the transport
	// to cancel dials as soon as they are no longer needed.
	// If both are set, DialContext takes priority.
	Dial func(network, addr string) (net.Conn, error)

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

	// DialTLS specifies an optional dial function for creating
	// TLS connections for non-proxied HTTPS requests.
	//
	// Deprecated: Use DialTLSContext instead, which allows the transport
	// to cancel dials as soon as they are no longer needed.
	// If both are set, DialTLSContext takes priority.
	DialTLS func(network, addr string) (net.Conn, error)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	ResponseOptions
	// contains filtered or unexported fields
}

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

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

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

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

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

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

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

func (*Transport) CancelRequest deprecated

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

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

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

func (*Transport) Clone

func (t *Transport) Clone() *Transport

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

func (*Transport) CloseIdleConnections

func (t *Transport) CloseIdleConnections()

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

func (*Transport) DisableDump

func (t *Transport) DisableDump()

func (*Transport) EnableDump

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

func (*Transport) RegisterProtocol

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

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

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

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

func (*Transport) RoundTrip

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

RoundTrip implements the RoundTripper interface.

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

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

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.

Jump to

Keyboard shortcuts

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