Documentation
¶
Index ¶
- Constants
- Variables
- func CanonicalMIMEHeaderKey(s string) string
- func ProxyFromEnvironment(req *http.Request) (*url.URL, error)
- func ProxyURL(fixedURL *url.URL) func(*http.Request) (*url.URL, error)
- func SetDefaultClient(c *Client)
- type Body
- func (body Body) Bytes() ([]byte, error)
- func (body Body) MustBytes() []byte
- func (body Body) MustSave(dst io.Writer)
- func (body Body) MustSaveFile(filename string)
- func (body Body) MustString() string
- func (body Body) MustUnmarshal(v interface{})
- func (body Body) MustUnmarshalJson(v interface{})
- func (body Body) MustUnmarshalXml(v interface{})
- func (body Body) Save(dst io.Writer) error
- func (body Body) SaveFile(filename string) error
- func (body Body) String() (string, error)
- func (body Body) Unmarshal(v interface{}) error
- func (body Body) UnmarshalJson(v interface{}) error
- func (body Body) UnmarshalXml(v interface{}) error
- type Client
- func (c *Client) DisableDump() *Client
- func (c *Client) DumpOptions(opt *DumpOptions) *Client
- func (c *Client) EnableDump(opts ...DumpOption) *Client
- func (c *Client) Header(key, value string) *Client
- func (c *Client) NewRequest() *Request
- func (c *Client) R() *Request
- func (c *Client) ResponseOption(opts ...ResponseOption) *Client
- func (c *Client) ResponseOptions(opts ResponseOptions) *Client
- func (c *Client) Timeout(d time.Duration) *Client
- func (c *Client) UserAgent(userAgent string) *Client
- type DumpOption
- type DumpOptions
- type Request
- func (r *Request) Body(body interface{}) *Request
- func (r *Request) BodyBytes(body []byte) *Request
- func (r *Request) BodyJsonBytes(body []byte) *Request
- func (r *Request) BodyJsonMarshal(v interface{}) *Request
- func (r *Request) BodyJsonString(body string) *Request
- func (r *Request) BodyString(body string) *Request
- func (r *Request) Delete(url string) (*Response, error)
- func (r *Request) Error() error
- func (r *Request) Get(url string) (*Response, error)
- func (r *Request) Head(url string) (*Response, error)
- func (r *Request) Method(method string) *Request
- func (r *Request) MustDelete(url string) *Response
- func (r *Request) MustGet(url string) *Response
- func (r *Request) MustHead(url string) (*Response, error)
- func (r *Request) MustOptions(url string) *Response
- func (r *Request) MustPatch(url string) *Response
- func (r *Request) MustPost(url string) *Response
- func (r *Request) MustPut(url string) *Response
- func (r *Request) Options(url string) (*Response, error)
- func (r *Request) Patch(url string) (*Response, error)
- func (r *Request) Post(url string) (*Response, error)
- func (r *Request) Put(url string) (*Response, error)
- func (r *Request) Send() (resp *Response, err error)
- func (r *Request) URL(url string) *Request
- type Response
- type ResponseOption
- type ResponseOptions
- type Transport
- func (t *Transport) CancelRequest(req *http.Request)deprecated
- func (t *Transport) Clone() *Transport
- func (t *Transport) CloseIdleConnections()
- func (t *Transport) DisableDump()
- func (t *Transport) EnableDump(opt *DumpOptions)
- func (t *Transport) RegisterProtocol(scheme string, rt http.RoundTripper)
- func (t *Transport) RoundTrip(req *http.Request) (resp *http.Response, err error)
Constants ¶
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" )
const DefaultMaxIdleConnsPerHost = 2
DefaultMaxIdleConnsPerHost is the default value of Transport's MaxIdleConnsPerHost.
Variables ¶
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.
var ErrLineTooLong = internal.ErrLineTooLong
ErrLineTooLong is returned when reading request or response bodies with malformed chunked encoding.
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 ¶
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 ¶
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 ¶
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) MustSaveFile ¶
func (Body) MustString ¶
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) UnmarshalJson ¶
func (Body) UnmarshalXml ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
func DefaultClient ¶
func DefaultClient() *Client
func (*Client) DisableDump ¶
func (*Client) DumpOptions ¶
func (c *Client) DumpOptions(opt *DumpOptions) *Client
func (*Client) EnableDump ¶
func (c *Client) EnableDump(opts ...DumpOption) *Client
func (*Client) ResponseOption ¶
func (c *Client) ResponseOption(opts ...ResponseOption) *Client
func (*Client) ResponseOptions ¶
func (c *Client) ResponseOptions(opts ResponseOptions) *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 (*Request) BodyJsonBytes ¶
func (*Request) BodyJsonMarshal ¶
func (*Request) BodyJsonString ¶
func (*Request) BodyString ¶
func (*Request) MustDelete ¶
func (*Request) MustOptions ¶
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
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) 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.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package internal contains HTTP internals shared by net/http and net/http/httputil.
|
Package internal contains HTTP internals shared by net/http and net/http/httputil. |
|
godebug
Package godebug parses the GODEBUG environment variable.
|
Package godebug parses the GODEBUG environment variable. |