README
¶
httpx 
Go package augmenting the standard net/http package with more basic building blocks for writing http applications.
Motivations
The intent of this package is to provide reusable tools that fit well with the standard net package and extend it with features that aren't available.
Documentation
¶
Index ¶
- Constants
- func Negotiate(accept string, types ...string) string
- func NegotiateEncoding(accept string, codings ...string) string
- func NewEncodingHandler(handler http.Handler, contentEncodings ...ContentEncoding) http.Handler
- func NewEncodingTransport(transport http.RoundTripper, contentEncodings ...ContentEncoding) http.RoundTripper
- func StatusHandler(status int) http.Handler
- type Accept
- type AcceptEncoding
- func (accept AcceptEncoding) Format(w fmt.State, r rune)
- func (accept AcceptEncoding) Len() int
- func (accept AcceptEncoding) Less(i int, j int) bool
- func (accept AcceptEncoding) Negotiate(codings ...string) string
- func (accept AcceptEncoding) String() string
- func (accept AcceptEncoding) Swap(i int, j int)
- type AcceptEncodingItem
- type AcceptItem
- type ConnTransport
- type ContentEncoding
- type DeflateEncoding
- type GzipEncoding
- type MediaParam
- type MediaRange
- type MediaType
- type RetryHandler
- type RetryTransport
- type ReverseProxy
- type RoundTripperFunc
- type Server
- type UpgradeMap
- type UpgradeMux
- type ZlibEncoding
Constants ¶
const ( // DefaultMaxAttempts is the default number of attempts used by RetryHandler // and RetryTransport. DefaultMaxAttempts = 10 )
Variables ¶
This section is empty.
Functions ¶
func Negotiate ¶
Negotiate performs an Accept header negotiation where the server can expose the content in the given list of types.
If none types match the method returns the first element in the list of types.
Here's an example of a typical use of this function:
accept := Negotiate(req.Header.Get("Accept"), "image/png", "image/jpg")
func NegotiateEncoding ¶
NegotiateEncoding performs an Accept-Encoding header negotiation where the server can expose the content in the given list of codings.
If none types match the method returns an empty string to indicate that the server should not apply any encoding to its response.
Here's an exmaple of a typical use of this function:
encoding := NegotiateEncoding(req.Get("Accept-Encoding"), "gzip", "deflate")
func NewEncodingHandler ¶
func NewEncodingHandler(handler http.Handler, contentEncodings ...ContentEncoding) http.Handler
NewEncodingHandler wraps handler to support encoding the responses by negotiating the coding based on the given list of supported content encodings.
If contentEncodings is nil (no arguments were passed) the returned handler uses DefaultEncodings.
func NewEncodingTransport ¶
func NewEncodingTransport(transport http.RoundTripper, contentEncodings ...ContentEncoding) http.RoundTripper
NewEncodingTransport wraps transport to support decoding the responses with specified content encodings.
If contentEncodings is nil (no arguments were passed) the returned transport uses DefaultEncodings.
func StatusHandler ¶
StatusHandler returns a HTTP handler that always responds with status and an empty body.
Types ¶
type Accept ¶
type Accept []AcceptItem
Accept is the representation of an Accept header.
func ParseAccept ¶
ParseAccept parses the value of an Accept header from s.
func (Accept) Negotiate ¶
Negotiate performs an Accept header negotiation where the server can expose the content in the given list of types.
If none types match the method returns the first element in the list of types.
type AcceptEncoding ¶
type AcceptEncoding []AcceptEncodingItem
AcceptEncoding respresents an Accept-Encoding header.
func ParseAcceptEncoding ¶
func ParseAcceptEncoding(s string) (accept AcceptEncoding, err error)
ParseAcceptEncoding parses an Accept-Encoding header value from s.
func (AcceptEncoding) Format ¶
func (accept AcceptEncoding) Format(w fmt.State, r rune)
Format satisfies the fmt.Formatter interface.
func (AcceptEncoding) Less ¶
func (accept AcceptEncoding) Less(i int, j int) bool
Less satisfies sort.Interface.
func (AcceptEncoding) Negotiate ¶
func (accept AcceptEncoding) Negotiate(codings ...string) string
Negotiate performs an Accept-Encoding header negotiation where the server can expose the content in the given list of codings.
If none types match the method returns an empty string to indicate that the server should not apply any encoding to its response.
func (AcceptEncoding) String ¶
func (accept AcceptEncoding) String() string
String satisfies the fmt.Stringer interface.
func (AcceptEncoding) Swap ¶
func (accept AcceptEncoding) Swap(i int, j int)
Swap satisfies sort.Interface.
type AcceptEncodingItem ¶
type AcceptEncodingItem struct {
// contains filtered or unexported fields
}
AcceptEncodingItem represents a single item in an Accept-Encoding header.
func ParseAcceptEncodingItem ¶
func ParseAcceptEncodingItem(s string) (item AcceptEncodingItem, err error)
ParseAcceptEncodingItem parses a single item in an Accept-Encoding header.
func (AcceptEncodingItem) Format ¶
func (item AcceptEncodingItem) Format(w fmt.State, _ rune)
Format satisfies the fmt.Formatter interface.
func (AcceptEncodingItem) String ¶
func (item AcceptEncodingItem) String() string
String satisfies the fmt.Stringer interface.
type AcceptItem ¶
type AcceptItem struct {
// contains filtered or unexported fields
}
AcceptItem is the representation of an item in an Accept header.
func ParseAcceptItem ¶
func ParseAcceptItem(s string) (item AcceptItem, err error)
ParseAcceptItem parses a single item in an Accept header.
func (AcceptItem) Format ¶
func (item AcceptItem) Format(w fmt.State, _ rune)
Format satisfies the fmt.Formatter interface.
func (AcceptItem) String ¶
func (item AcceptItem) String() string
String satisfies the fmt.Stringer interface.
type ConnTransport ¶
type ConnTransport struct {
// Conn is the connection to use to send requests and receive responses.
Conn net.Conn
// Buffer may be set to a bufio.ReadWriter which will be used to buffer all
// I/O done on the connection.
Buffer *bufio.ReadWriter
// DialContext is used to open a connection when Conn is set to nil.
// If the function is nil the transport uses a default dialer.
DialContext func(context.Context, string, string) (net.Conn, error)
// 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
// 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 int
}
ConnTransport is a http.RoundTripper that works on a pre-established network connection.
type ContentEncoding ¶
type ContentEncoding interface {
// Coding returns the format in which the content encoding's writers
// can encode HTTP responses.
Coding() string
// NewReader wraps r in a reader that supports the content encoding's
// format.
NewReader(r io.Reader) (io.ReadCloser, error)
// NewWriter wraps w in a writer that applies the content encoding's
// format.
NewWriter(w io.Writer) (io.WriteCloser, error)
}
ContentEncoding is an interfae implemented by types that provide the implementation of a content encoding for HTTP responses.
type DeflateEncoding ¶
type DeflateEncoding struct {
Level int
}
DeflateEncoding implements the ContentEncoding interface for the deflate algorithm.
func NewDeflateEncoding ¶
func NewDeflateEncoding() *DeflateEncoding
NewDeflateEncoding creates a new content encoding with the default compression level.
func NewDeflateEncodingLevel ¶
func NewDeflateEncodingLevel(level int) *DeflateEncoding
NewDeflateEncodingLevel creates a new content encoding with the given compression level.
func (*DeflateEncoding) Coding ¶
func (e *DeflateEncoding) Coding() string
Coding satsifies the ContentEncoding interface.
func (*DeflateEncoding) NewReader ¶
func (e *DeflateEncoding) NewReader(r io.Reader) (io.ReadCloser, error)
NewReader satisfies the ContentEncoding interface.
func (*DeflateEncoding) NewWriter ¶
func (e *DeflateEncoding) NewWriter(w io.Writer) (io.WriteCloser, error)
NewWriter satsifies the ContentEncoding interface.
type GzipEncoding ¶
type GzipEncoding struct {
Level int
}
GzipEncoding implements the ContentEncoding interface for the gzip algorithm.
func NewGzipEncoding ¶
func NewGzipEncoding() *GzipEncoding
NewGzipEncoding creates a new content encoding with the default compression level.
func NewGzipEncodingLevel ¶
func NewGzipEncodingLevel(level int) *GzipEncoding
NewGzipEncodingLevel creates a new content encoding with the given compression level.
func (*GzipEncoding) Coding ¶
func (e *GzipEncoding) Coding() string
Coding satsifies the ContentEncoding interface.
func (*GzipEncoding) NewReader ¶
func (e *GzipEncoding) NewReader(r io.Reader) (io.ReadCloser, error)
NewReader satisfies the ContentEncoding interface.
func (*GzipEncoding) NewWriter ¶
func (e *GzipEncoding) NewWriter(w io.Writer) (io.WriteCloser, error)
NewWriter satsifies the ContentEncoding interface.
type MediaParam ¶
type MediaParam struct {
// contains filtered or unexported fields
}
MediaParam is a representation of a HTTP media parameter as described in https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
func ParseMediaParam ¶
func ParseMediaParam(s string) (p MediaParam, err error)
ParseMediaParam parses a string representation of a HTTP media parameter from s.
func (MediaParam) Format ¶
func (p MediaParam) Format(w fmt.State, _ rune)
Format satisfies the fmt.Formatter interface.
func (MediaParam) String ¶
func (p MediaParam) String() string
String satisfies the fmt.Stringer interface.
type MediaRange ¶
type MediaRange struct {
// contains filtered or unexported fields
}
MediaRange is a representation of a HTTP media range as described in https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
func ParseMediaRange ¶
func ParseMediaRange(s string) (r MediaRange, err error)
ParseMediaRange parses a string representation of a HTTP media range from s.
func (MediaRange) Format ¶
func (r MediaRange) Format(w fmt.State, _ rune)
Format satisfies the fmt.Formatter interface.
func (MediaRange) Param ¶
func (r MediaRange) Param(name string) string
Param return the value of the parameter with name, which will be an empty string if none was found.
func (MediaRange) String ¶
func (r MediaRange) String() string
String satisfies the fmt.Stringer interface.
type MediaType ¶
type MediaType struct {
// contains filtered or unexported fields
}
MediaType is a representation of a HTTP media type which is usually expressed in the form of a main and sub type as in "main/sub", where both may be the special wildcard token "*".
func ParseMediaType ¶
ParseMediaType parses the media type in s.
type RetryHandler ¶
type RetryHandler struct {
// Handler is the sub-handler that the RetryHandler delegates requests to.
//
// ServeHTTP will panic if Handler is nil.
Handler http.Handler
// MaxAttampts is the maximum number of attempts that the handler will make
// at handling a single request.
// Zero means to use a default value.
MaxAttempts int
}
A RetryHandler is a http.Handler which retries calls to its sub-handler if they fail with a 5xx code. When a request is retried the handler will apply an exponential backoff to maximize the chances of success (because it is usually unlikely that a failed request will succeed right away).
Note that only idempotent methods are retried, because the handler doesn't have enough context about why it failed, it wouldn't be safe to retry other HTTP methods.
func (*RetryHandler) ServeHTTP ¶
func (h *RetryHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP satisfies the http.Handler interface.
type RetryTransport ¶
type RetryTransport struct {
// Transport is the sub-transport that the RetryTransport delegates requests
// to.
//
// http.DefaultTransport is used if Transport is nil.
Transport http.RoundTripper
// MaxAttampts is the maximum number of attempts that the handler will make
// at handling a single request.
// Zero means to use a default value.
MaxAttempts int
}
RetryTransport is a http.RoundTripper which retries calls to its sub-handler if they failed with connection or server errors. When a request is retried the handler will apply an exponential backoff to maximize the chances of success (because it is usually unlikely that a failed request will succeed right away).
Note that only idempotent methods are retried, because the handler doesn't have enough context about why it failed, it wouldn't be safe to retry other HTTP methods.
type ReverseProxy ¶
type ReverseProxy struct {
// Transport is used to forward HTTP requests to backend servers. If nil,
// http.DefaultTransport is used instead.
Transport http.RoundTripper
// DialContext is used for dialing new TCP connections on HTTP upgrades or
// CONNECT requests.
DialContext func(context.Context, string, string) (net.Conn, error)
// TLSClientConfig specifies the TLS configuration to use for HTTP upgrades
// that happen over a secured link.
// If nil, the default configuration is used.
TLSClientConfig *tls.Config
}
ReverseProxy is a HTTP handler which implements the logic of a reverse HTTP proxy, forwarding incoming requests to backend servers.
The implementation is similar to httputil.ReverseProxy but the implementation has some differences. Instead of using a Director function to rewrite the request to its destination the proxy expects the request it receives to be already well constructed to be forwarded to a backend server. Any conforming HTTP client aware of being behing a proxy would have included the full URL in the request line which the proxy will use to extract the backend address.
The proxy also converts the X-Forwarded headers to Forwarded as defined by RFC 7239 (see https://tools.ietf.org/html/rfc7239).
HTTP upgrades are also supported by this reverse HTTP proxy implementation, the proxy forwards the HTTP handshake requesting an upgrade to the backend server, then if it gets a successful 101 Switching Protocol response it will start acting as a simple TCP tunnel between the client and backend server.
Finally, the proxy also properly handles the Max-Forward header for TRACE and OPTIONS methods, decrementing the value or directly responding to the client if it reaches zero.
func (*ReverseProxy) ServeHTTP ¶
func (p *ReverseProxy) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP satisfies the http.Handler interface.
type RoundTripperFunc ¶
RoundTripperFunc makes it possible to use regular functions as transports for HTTP clients.
type Server ¶
type Server struct {
// Handler is called by the server for each HTTP request it received.
Handler http.Handler
// Upgrader is called by the server when an HTTP upgrade is detected.
Upgrader http.Handler
// IdleTimeout is the maximum amount of time the server waits on an inactive
// connection before closing it.
// Zero means no timeout.
IdleTimeout time.Duration
// ReadTimeout is the maximum amount of time the server waits for a request
// to be fully read.
// Zero means no timeout.
ReadTimeout time.Duration
// WriteTimeout is the maximum amount of time the server gives for responses
// to be sent.
// Zero means no timeout.
WriteTimeout time.Duration
// MaxHeaderBytes controls the maximum number of bytes the will read parsing
// the request header's keys and values, including the request line. It does
// not limit the size of the request body.
// If zero, http.DefaultMaxHeaderBytes is used.
MaxHeaderBytes int
// ErrorLog specifies an optional logger for errors that occur when
// attempting to proxy the request. If nil, logging goes to os.Stderr via
// the log package's standard logger.
ErrorLog *log.Logger
// ServerName is the name of the server, returned in the "Server" response
// header field.
ServerName string
}
A Server implements the netx.Handler interface, it provides the handling of HTTP requests from a net.Conn, graceful shutdowns...
func (*Server) ServeProxy ¶
ServeProxy satisfies the netx.ProxyHandler interface, it is used to support transparent HTTP proxies, it rewrites the request to take into account the fact that it was received on an intercepted connection and that the client wasn't aware that it was being proxied.
type UpgradeMap ¶
UpgradeMap maps protocol names to HTTP handlers that should be used to perform upgrades from HTTP to a different protocol.
It is expected that the upgrade handler flushes and hijacks the connection after sending the response, and doesn't return from its ServeHTTP method until it's done serving the connection (or it would be closed prematuraly).
A special-case is made for the name "*" which indicates that the handler is set as a the fallback upgrade handler to handle unrecognized protocols.
Keys in the UpgradeMap map should be formatted with http.CanonicalHeaderKey.
func (UpgradeMap) ServeHTTP ¶
func (u UpgradeMap) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP satisfies the http.Handler interface so an UpgradeMap can be used as handler on an HTTP server.
type UpgradeMux ¶
type UpgradeMux struct {
// contains filtered or unexported fields
}
UpgradeMux maps protocol names to HTTP handlers that should be used to perform upgrades from HTTP to a different protocol.
It is expected that the upgrade handler flushes and hijacks the connection after sending the response, and doesn't return from its ServeHTTP method until it's done serving the connection (or it would be closed prematuraly).
UpgradeMux exposes the exact same API than http.ServeMux, therefore is safe to use by multiple concurrent goroutines.
func NewUpgradeMux ¶
func NewUpgradeMux() *UpgradeMux
NewUpgradeMux allocates and returns a new UpgradeMux.
func (*UpgradeMux) Handle ¶
func (mux *UpgradeMux) Handle(name string, handler http.Handler)
Handle registers a handler for the given protocol name. If a handler already exists for name, Handle panics.
A special-case is made for the name "*" which indicates that the handler is set as a the fallback upgrade handler to handle unrecognized protocols.
func (*UpgradeMux) HandleFunc ¶
func (mux *UpgradeMux) HandleFunc(name string, handler func(http.ResponseWriter, *http.Request))
HandleFunc registers a handler function for the given protocol name. If a handler already exists for name, HandleFunc panics.
func (*UpgradeMux) Handler ¶
func (mux *UpgradeMux) Handler(req *http.Request) http.Handler
Handler returns the appropriate http.Handler for serving req.
func (*UpgradeMux) ServeHTTP ¶
func (mux *UpgradeMux) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP satisfies the http.Handler interface so UpgradeMux can be used as handler on an HTTP server.
type ZlibEncoding ¶
type ZlibEncoding struct {
Level int
}
ZlibEncoding implements the ContentEncoding interface for the zlib algorithm.
func NewZlibEncoding ¶
func NewZlibEncoding() *ZlibEncoding
NewZlibEncoding creates a new content encoding with the default compression level.
func NewZlibEncodingLevel ¶
func NewZlibEncodingLevel(level int) *ZlibEncoding
NewZlibEncodingLevel creates a new content encoding with the given compression level.
func (*ZlibEncoding) Coding ¶
func (e *ZlibEncoding) Coding() string
Coding satsifies the ContentEncoding interface.
func (*ZlibEncoding) NewReader ¶
func (e *ZlibEncoding) NewReader(r io.Reader) (io.ReadCloser, error)
NewReader satisfies the ContentEncoding interface.
func (*ZlibEncoding) NewWriter ¶
func (e *ZlibEncoding) NewWriter(w io.Writer) (io.WriteCloser, error)
NewWriter satsifies the ContentEncoding interface.
Source Files
Directories