httpx

Documentation

Index

• Constants
• Variables
• func CloneHeader(h http.Header) http.Header
• func HasToken(v, token string) bool
• func ProxyFromEnvironment(req *http.Request) (*url.URL, error)
• func ProxyURL(fixedURL *url.URL) func(*http.Request) (*url.URL, error)
• type ConnectMethod
  • func (cm *ConnectMethod) Addr() string
  • func (cm *ConnectMethod) AttachAuthHeaders(h http.Header)
  • func (cm *ConnectMethod) ProxyAuth() string
  • func (cm *ConnectMethod) Scheme() string
  • func (cm *ConnectMethod) TLSHost() string
• type Transport
  • func (t *Transport) CancelRequest(req *http.Request, err error)
  • func (t *Transport) CloseIdleConnections()
  • func (t *Transport) ConnectMethodForRequest(treq *TransportRequest) (cm ConnectMethod, err error)
  • func (t *Transport) DoDial(ctx context.Context, cm ConnectMethod) (conn net.Conn, tlsState *tls.ConnectionState, isProxy bool, ...)
  • func (t *Transport) RegisterProtocol(scheme string, rt http.RoundTripper)
  • func (t *Transport) RoundTrip(req *http.Request) (resp *http.Response, err error)
• type TransportRequest

Constants

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 ErrSkipAltProtocol = errors.New("net/http: skip alternate protocol")

ErrSkipAltProtocol is a sentinel error value defined by Transport.RegisterProtocol.

Functions

func CloneHeader

func CloneHeader(h http.Header) http.Header

func HasToken

func HasToken(v, token string) bool

HasToken reports whether token appears with v, ASCII case-insensitive, with space or comma boundaries. token must be all lowercase. v may contain mixed cased.

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

Types

type ConnectMethod

type ConnectMethod struct {
	ProxyURL       *url.URL    // nil for no proxy, else full proxy URL
	ProxyTLSConfig *tls.Config // TLS config for proxy
	TargetScheme   string      // "http" or "https"
	TargetAddr     string      // Not used if proxy + http targetScheme (4th example in table)
}

ConnectMethod is the map key (in its String form) for keeping persistent TCP connections alive for subsequent HTTP requests.

A connect method may be of the following types:

Cache key form Description ----------------- ------------------------- |http|foo.com http directly to server, no proxy |https|foo.com https directly to server, no proxy http://proxy.com|https|foo.com http to proxy, then CONNECT to foo.com http://proxy.com|http http to proxy, http to anywhere after that

Note: no support to https to the proxy yet.

func (*ConnectMethod) Addr

func (cm *ConnectMethod) Addr() string

addr returns the first hop "host:port" to which we need to TCP connect.

func (*ConnectMethod) AttachAuthHeaders

func (cm *ConnectMethod) AttachAuthHeaders(h http.Header)

func (*ConnectMethod) ProxyAuth

func (cm *ConnectMethod) ProxyAuth() string

proxyAuth returns the Proxy-Authorization header to set on requests, if applicable.

func (*ConnectMethod) Scheme

func (cm *ConnectMethod) Scheme() string

scheme returns the first hop scheme: http, https, or socks5

func (*ConnectMethod) TLSHost

func (cm *ConnectMethod) TLSHost() string

tlsHost returns the host name to match against the peer's TLS certificate.

type Transport

type Transport struct {

	// (deprecated) Proxy specifies a function to return a proxy
	// for a given Request. Proxy2 is a preferred alternative to it.
	// If the function returns a non-nil error, the request is
	// aborted with the provided error.
	// If Proxy is nil or returns a nil *URL, no proxy is used.
	Proxy func(*http.Request) (*url.URL, error)

	// Proxy2 specifies a function to return a proxy for a given
	// Request. Proxy2 is preferred to Proxy.  If the function
	// returns a non-nil error, the request is aborted with the
	// provided error.
	// If Proxy is nil or returns a nil *URL, no proxy is used.
	Proxy2 func(*http.Request) (*url.URL, *tls.Config, error)

	// Dial specifies the dial function for creating unencrypted
	// TCP connections.
	// If Dial is nil, net.Dial is used.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)

	// (deprecated) DialTLS specifies an optional dial function
	// for creating TLS connections for first-hop HTTPS requests.
	//
	// If DialTLS is nil, Dial and TLSClientConfig are used.
	//
	// If DialTLS is set, the Dial hook 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.
	DialTLS func(ctx context.Context, network, addr string) (net.Conn, error)

	// DialTLS2 specifies an optional dial function for creating
	// TLS connections for first-hop HTTPS requests.
	// DialTLS2 is preferred to DialTLS.
	//
	// If DialTLS is nil, Dial and TLSClientConfig are used.
	//
	// If DialTLS is set, the Dial hook 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.
	DialTLS2 func(ctx context.Context, network, addr string, config *tls.Config) (net.Conn, error)

	// TLSClientConfig specifies the TLS configuration to use with
	// tls.Client. If nil, the default configuration is used.
	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, prevents re-use of TCP connections
	// between different HTTP requests.
	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) to keep per-host.  If zero,
	// DefaultMaxIdleConnsPerHost is used.
	MaxIdleConnsPerHost 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 NPN/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 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.
	ProxyConnectHeader http.Header

	// 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
	// contains filtered or unexported fields
}

Transport is an implementation of RoundTripper that supports HTTP, HTTPS, and HTTP proxies (for either HTTP or HTTPS with CONNECT). Transport can also cache connections for future re-use.

func (*Transport) CancelRequest

func (t *Transport) CancelRequest(req *http.Request, err error)

Cancel an in-flight request, recording the error value.

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) ConnectMethodForRequest

func (t *Transport) ConnectMethodForRequest(treq *TransportRequest) (cm ConnectMethod, err error)

func (*Transport) DoDial

func (t *Transport) DoDial(ctx context.Context, cm ConnectMethod) (conn net.Conn, tlsState *tls.ConnectionState, isProxy bool, mutateHeaderFunc func(http.Header), err error)

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.

type TransportRequest

type TransportRequest struct {
	*http.Request             // original request, not to be mutated
	Extra         http.Header // extra headers to write, or nil
	// contains filtered or unexported fields
}

transportRequest is a wrapper around a *http.Request that adds optional extra headers to write.