README
¶
httpaux
The missing functionality from net/http
Summary
httpaux augments golang's net/http package with a few extra goodies.
- Middleware for clients in the form of http.RoundTripper decoration
- Standardized middleware interfaces
- Busy server middleware to limit serverside traffic
- Observable http.ResponseWriter middleware that provides a standard way for http.Handler decorators to examine what was written to the response by nested handlers
- Gate middleware to control server and client traffic
- An efficient, immutable Header type for writing static headers
- A configurable
ConstantHandlerthat writes hardcoded information to responses Errorwhich can be used to wrap service and middleware errors in a form that makes rendering responses easier. This type is compatible with frameworks likego-kit.httpmockpackage for mock-style testing with HTTP clientsretrypackage with configurable retry for clients including exponential backoff
Table of Contents
Code of Conduct
This project and everyone participating in it are governed by the XMiDT Code Of Conduct. By participating, you agree to this Code.
Install
go get github.com/xmidt-org/httpaux
Contributing
Refer to CONTRIBUTING.md.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Cleanup ¶ added in v0.1.2
Cleanup is a utility function for ensuring that a client response's Body is drained and closed. This function does not set the Body to nil.
If either the response or the response.Body field is nil, this function does nothing.
func EncodeError ¶ added in v0.1.4
func EncodeError(_ context.Context, err error, rw http.ResponseWriter)
EncodeError is a gokit-style error coder for server code that consistently writes JSON for all errors. The builtin gokit error encoder will write text/plain for anything it doesn't recognize, giving rise to inconsistent messages when some errors implement json.Marshaler and others do not.
This function also honors embedded errors via the errors package. If any error in the chain provides the specialized methods such as StatusCode, that error is used for that portion of the HTTP response.
func IsTemporary ¶ added in v0.1.2
IsTemporary tests if the given error is marked as a temporary error. This method returns true if the given error or what the error wraps exposes a Temporary() bool method that returns true.
This function uses errors.As to traverse the error wrappers.
Types ¶
type ConstantHandler ¶
type ConstantHandler struct {
// StatusCode is the response code to pass to http.ResponseWriter.WriteHeader.
// If this value is less than 100 (which also includes being unset), then no
// response code is written which will trigger the default of http.StatusOK.
StatusCode int
// Header is the set of headers added to every response
Header Header
// ContentType is the MIME type of the Body. This will override anything written by
// the Headers closure. This field has no effect if Body is not also set. If Body is
// set and this field is unset, then no Content-Type header is written by this handler.
// A Content-Type may still be written by other infrastructure or by the Headers closure, however.
ContentType string
// Body is the optional HTTP entity body. If unset, nothing is written for the response body.
// A Content-Length header will be explicitly set if this field is set.
Body []byte
}
ConstantHandler is an http.Handler that writes a statically defined HTTP response. Very useful for testing and for default behavior.
func ConstantJSON ¶
func ConstantJSON(v interface{}) (ch ConstantHandler, err error)
ConstantJSON is a convenience for constructing a ConstantHandler that returns a static JSON message. The encoding/json package is used to marshal v.
func (ConstantHandler) ServeHTTP ¶
func (ch ConstantHandler) ServeHTTP(response http.ResponseWriter, _ *http.Request)
ServeHTTP returns the constant information in the response.
type Error ¶
type Error struct {
// Err is the cause of this error. This field is required.
//
// Typically, this field is set to the service-layer error or other error
// that occurred below the presentation layer.
Err error
// Message is the optional message to associate with this error
Message string
// Code is the response code to use for this error. If unset, http.StatusInternalServerError
// is used instead.
Code int
// Header is the optional set of HTTP headers to associate with this error
Header http.Header
}
Error is a convenient carrier of error information that exposes HTTP response information. This type implements several interfaces in popular packages like go-kit.
The primary use case for this type is wrapping errors so they can be easily rendered as HTTP responses.
func (*Error) Error ¶
Error fulfills the error interface. Message is included in this text if it is supplied.
func (*Error) Headers ¶
Headers returns the optional headers to associate with this error's response
func (*Error) MarshalJSON ¶
MarshalJSON produces a JSON representation of this error. The Err field is marshaled as "cause". If the Message field is set, it is marshaled as "message".
func (*Error) StatusCode ¶
StatusCode returns the Code field, or http.StatusInternalServerError if that field is less than 100.
type Header ¶
type Header struct {
// contains filtered or unexported fields
}
Header is a more efficient version of http.Header for situations where a number of HTTP headers are stored in memory and reused. Rather than a map, a simple list of headers is maintained in canonicalized form. This is much faster to iterate over than a map, which becomes important when the same Header is used to add headers to many requests.
A Header instance is immutable once created.
func NewHeaderFromMap ¶
NewHeaderFromMap allows a Header to be built directly from a map[string]string rather than an http.Header.
func NewHeaders ¶
NewHeaders takes a variadic list of values and interprets them as alternating name/value pairs, with each pair specifying an HTTP header. Duplicate header names are supported, which results in multivalued headers. If v contains an odd number of strings, the last string is interpreted as a header with a blank value.
func (Header) RoundTrip ¶
func (h Header) RoundTrip(next http.RoundTripper) http.RoundTripper
RoundTrip is a client middleware that adds all these headers to the http.Request prior to invoking the next http.RoundTripper. As an optimization, if this Header is empty no decoration is done. Next is returned as is in that case.
If next is nil and this Header is non-empty, then http.DefaultTransport is decorated.
This method can be used as a roundtrip.Constructor or as part of a roundtrip.Chain:
h := httpaux.Header("Header", "Value")
c := roundtrip.NewChain(
h.RoundTrip,
)
func (Header) SetTo ¶
SetTo overwrites headers in the destination with the ones defined by this Header.
func (Header) Then ¶
Then is a server middleware that adds all the headers to the http.ResponseWriter prior to invoking the next handler. As an optimization, if this Header is empty no decoration is done.
This method can be used as part of server middle with libraries like justinas/alice:
h := roundtrip.NewHeader("Header", "Value")
c := alice.New(
h.Then,
)
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package gate implements a simple atomic boolean that controls access to HTTP client or server functionality
|
Package gate implements a simple atomic boolean that controls access to HTTP client or server functionality |
|
Package httpmock provides stretchr/testify/mock integration
|
Package httpmock provides stretchr/testify/mock integration |
|
Package observe exposes a standard way of decorating http.ResponseWriter objects so that they can be examined by infrastructure such as logging and metrics.
|
Package observe exposes a standard way of decorating http.ResponseWriter objects so that they can be examined by infrastructure such as logging and metrics. |
|
Package retry implements retry logic for HTTP clients.
|
Package retry implements retry logic for HTTP clients. |
|
Package roundtrip provides middleware and a few utility types for use with http.RoundTripper Middleware The Constructor and Chain types provide a way for application code to decorate an http.RoundTripper, usually an http.Transport, to any arbitrary depth.
|
Package roundtrip provides middleware and a few utility types for use with http.RoundTripper Middleware The Constructor and Chain types provide a way for application code to decorate an http.RoundTripper, usually an http.Transport, to any arbitrary depth. |