Documentation
¶
Overview ¶
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. These types are analogous to https://pkg.go.dev/github.com/justinas/alice.
This package provide the Func type as an analog to http.HandlerFunc. When implementing middleware, chaining function calls through Func works as with serverside middleware.
CloseIdleConnections ¶
When decorating http.RoundTripper, care should be take to avoid covering up the CloseIdleConnections method. This method is used by the enclosing http.Client. If middleware does not properly expose CloseIdleConnections, then there is no way to invoke this method through the client:
// CloseIdleConnections is lost in decoration
func MyConstructor(next http.RoundTripper) http.RoundTripper {
return roundtrip.Func(func(request *http.Request) (*http.Response, error) {
// some interesting decorator code here
return next.RoundTrip(request)
})
}
To assist with this, PreserveCloseIdler is provided to ensure that Constructor code properly exposes a CloseIdleConnections method:
// CloseIdleConnections is now available on the returned http.RoundTripper
func MyConstructor(next http.RoundTripper) http.RoundTripper {
return roundtrip.PreserveCloseIdler(
next,
roundtrip.Func(func(request *http.Request) (*http.Response, error) {
// some interesting decorator code here
return next.RoundTrip(request)
}),
)
}
If a constructor wants to decorate both the RoundTrip and CloseIdleConnections methods, the Decorator type and CloseIdleConnections function in this package can be used to facilitate this:
func MyConstructor(next http.RoundTripper) http.RoundTripper {
return roundtrip.Decorator{
RoundTrip: roundTrip.Func(func(request *http.Request) (*http.Response, error) {
// some interesting decorator code here
return next.RoundTrip(request)
}),
CloseIdler: roundtrip.CloseIdlerFunc(func() {
// do some decorator things here
roundtrip.CloseIdleConnections(next)
}),
}
}
The Chain type exposes CloseIdleConnections even if any chained constructors do not.
See: https://pkg.go.dev/net/http#Client.CloseIdleConnections
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CloseIdleConnections ¶
func CloseIdleConnections(rt http.RoundTripper)
CloseIdleConnections invokes the CloseIdleConnections method of a round tripper if that object exposes that method. Otherwise, this method does nothing.
This function simplifies decoration code for CloseIdler.
func PreserveCloseIdler ¶
func PreserveCloseIdler(next, decorator http.RoundTripper) http.RoundTripper
PreserveCloseIdler is a helper for preserving the CloseIdleConnections behavior of an http.RoundTripper when a middleware doesn't wish to decorate that method.
If decorator provides a CloseIdleConnections method, it is returned as is.
If next provides a CloseIdleConnections method, and decorator does not, then an http.RoundTripper is returned that delegates RoundTrip calls to the decorator instance and CloseIdleConnections calls to the next instance.
If neither next nor decorated provides a CloseIdleConnections method, then this method does nothing and simply returns decorator.
Types ¶
type Chain ¶
type Chain struct {
// contains filtered or unexported fields
}
Chain is an immutable sequence of constructors. This type is essentially a bundle of middleware for HTTP clients.
func NewChain ¶
func NewChain(ctors ...Constructor) (c Chain)
NewChain creates a chain from a sequence of constructors. The constructors are always applied in the order presented here.
func (Chain) Append ¶
func (c Chain) Append(more ...Constructor) (nc Chain)
Append adds additional Constructors to this chain, and returns the new chain. This chain is not modified. If more has zero length, this chain is returned.
func (Chain) Extend ¶
Extend is like Append, except that the additional Constructors come from another chain
func (Chain) Then ¶ added in v0.1.2
func (c Chain) Then(next http.RoundTripper) http.RoundTripper
Then applies the given sequence of middleware to the next http.RoundTripper. In keeping with the de facto standard with net/http, if next is nil, then http.DefaultTransport is decorated.
If next provides a CloseIdleConnections method, it is preserved and available in the returned http.RoundTripper. Additionally, if any constructors decorate CloseIdleConnections, that decoration is preserved in the final product. This enables the http.Client.CloseIdleConnections method to work properly.
See: https://pkg.go.dev/net/http#Client.CloseIdleConnections
type CloseIdler ¶
type CloseIdler interface {
CloseIdleConnections()
}
CloseIdler is the strategy for closing idle connections. This package makes this behavior explicit so that middleware will not hide this behavior.
type CloseIdlerFunc ¶
type CloseIdlerFunc func()
CloseIdlerFunc is a function that implements CloseIdler. Useful when the CloseIdleConnections method needs to be decorated.
func (CloseIdlerFunc) CloseIdleConnections ¶
func (cif CloseIdlerFunc) CloseIdleConnections()
type Constructor ¶
type Constructor func(http.RoundTripper) http.RoundTripper
Constructor applies clientside middleware to an http.RoundTripper.
Care should be taken not to hide the CloseIdleConnections method of the given round tripper. Otherwise, a containing http.Client's CloseIdleConnections method will be a noop. The Decorator type in this package facilitates decoration of round trippers while preserving CloseIdleConnections behavior. Constructors executed as part of a Chain preserve this behavior automatically.
func Header ¶ added in v0.1.6
func Header(hf func(http.Header)) Constructor
Header adds a middleware Constructor that uses a closure to modify each request header. Both httpaux.Header.SetTo and httpaux.Header.AddTo can be used as this closure.
type Decorator ¶
type Decorator struct {
// RoundTripper is the object that receives RoundTrip calls. Note that the Func
// type in this package can be used here.
http.RoundTripper
// CloseIdler is the object that receives CloseIdleConnections calls. When decorating
// a round tripper, this field guarantees that an http.Client can close idle connections.
CloseIdler
}
Decorator is a convenience for decorating an http.RoundTripper in a manner that preserves CloseIdleConnections behavior. This type is used automatically by the CloseIdleConnections function, but can be used for other custom decoration.
Source Files