Documentation
¶
Overview ¶
Package midware defines an interface for the common http middleware pattern and provides functionality for sensibly chaining middleware to create complex http handlers. In addition to defining abstractions related to the interface the package provides a small collection of middleware implementations. Many more exist in third-party packages which can be found by searching for "http middleware" on https://pkg.go.dev.
For example, automatic gzip compression of response bodies (if supported by the receiving client) can be found in package github.com/NYTimes/gziphandler. The middleware from the gziphandler package can be composed with middleware from this package using the Func and Chain types.
middleware := midware.Chain{
// the gzip handler is first in the chain because it has the highest
// priority, it will see the incoming request first and the last
// middleware to touch the response body which is particularly
// important here.
midware.Func(gziphandler.GzipHandler),
midware.TraceHeaders("", false),
// Because of its placement here the path override handler will see
// request tracing headers and any response body it serves will be
// compressed by the outermost gzip middleware.
midware.PathOverrides{
"/override": overrideHandler,
},
}
http.ListenAndServe(":8080", middleware.Wrap(myapp))
Index ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultAWSHeader = "X-Amzn-Trace-Id"
DefaultAWSHeader is the default AWS header that can be used for request tracing to track HTTP requests from clients to targets or other services
var DefaultAzureHeader = "X-Appgw-Trace-Id"
DefaultAzureHeader is the default Azure header that contains a unique guid generated by application gateway for each client request and presented in the forwarded request to the backend pool member.
var DefaultTraceHeader = "X-Request-Id"
DefaultTraceHeader is the default header when TraceHeaders is given an empty string instead of a valid header name.
Functions ¶
func ServerFixed ¶
ServerFixed returns a string indented to be used as the primary component in ServerResponseHeader. ServerFixed ignores any leading and trailing whitespace in its arguments. If version is non-empty the server header component will render the two strings joined by a slash, like the following:
fmt.Sprintf("%s/%s", name, version)
The name argument of ServerFixed should be non-empty but that is not enforced. If passed two empty strings ServerFixed will return an empty string.
func ServerFixedFunc ¶
ServerFixedFunc returns a function which can be used as a secondary component in ServerResponseHeader for cases where the software's name and version is known ahead of time. The returned component is equivalent to the following function closure:
func() string {
return ServerFixed(name, version)
}
Types ¶
type Chain ¶
type Chain []Middleware
Chain is an ordered sequence of middleware which itself acts as a compound middleware. A chain defines middlewares the order in which middleware are applied, from the outermost http handler (reading the raw http transport) to the innermost handler (just prior to the application serving the request)
Chain can be a helpful abstraction because it tends to match a person's intuition about ordering middleware and reduce confusion. The Middleware interface otherwise forces middleware handlers to be bound to the application in the opposite order from which they are applied.
type Func ¶
Func is a function that acts as middleware. Typically third-party middleware will need to be wrapped as a Func before they may be used in a Chain.
type Middleware ¶
type Middleware interface {
// Wrap returns an intermediate http handler which may handle requests
// itself or invoke next to serve the request (performing intermediate
// processing including modification of requests or outgoing data.
Wrap(next http.Handler) http.Handler
}
Middleware defines the basic pattern for http middleware. Middleware can be thought of as a configuration for which the Wrap method produces an instance of the configured middleware.
func ServerResponseHeader ¶
func ServerResponseHeader(primary string, secondary ...func() string) Middleware
ServerResponseHeader returns a middleware that renders the given sequence of server components (presumably in "software[/version]" format) and includes them in the Server response header. Any secondary components which are supplied in addition to primary will be rendered in sequence and delimited by a single whitespace. Any component which renders an empty string or one consisting solely of whitespace is ignored and other values will have leading and trailing whitespace trimmed. ServerResponseHeader overwrites any Server header that was set earlier (by another middleware).
ServerResponseHeader will panic immediately if the primary component does not contain a valid token (RFC2616). It is recommended that the primary component be the result of ServerFixed called with a const, non-empty name argument.
BUG: Neither ServerResponseHeader nor its returned middleware check components for invalid control characters. Because of this it is important that application end users and unchecked code not be permitted to inject content into server response header components.
func TraceHeaders ¶
func TraceHeaders(header string, allow bool) Middleware
TraceHeaders ensures all incoming http requests have an identifying header for tracing and automatically includes a matching header in http responses. If allow is true then requests are allowed to specify their own ids which are assumed to be unique, otherwise any existing header will be overwritten before deferring to the inner http handler. If header is the empty string then DefaultTraceHeader will contain the tracing identifier.
type PathOverrides ¶
PathOverrides is middleware which overrides handling for a specified set of http request paths. Each entry in a PathOverrides map is an http request path and the associated handler will be used to serve that path instead of allowing the middleware's "natural" inner handler to serve the request.
PathOverrides does not support overriding subtrees (paths ending with '/') in the way that http.ServeMux supports path patterns. Keys in PathOverrides are expected to be complete, rooted paths.
Source Files