middleware

Documentation

Overview

Package middleware contains HTTP middlewares that wrap a HTTP handler to provide additional functionality.

The package contains the following middlewares:

• Logging server middleware for logging requests and responses.
• Request ID server middleware to include a unique request ID on receiving a HTTP request.
• Tracing middleware for server and client.
• AWS X-Ray middleware for server and client that produce X-Ray segments.

Example to use the server middleware:

var handler http.Handler = goahttp.NewMuxer()
handler = middleware.RequestID()(handler)

Example to use the client middleware:

var doer goahttp.Doer = &http.Client{}
doer = xray.WrapDoer(doer)

Index

• Constants
• func Debug(mux goahttp.Muxer, w io.Writer) func(http.Handler) http.Handler
• func DiscardFromTrace(discard *regexp.Regexp) middleware.TraceOption
• func Log(l middleware.Logger) func(h http.Handler) http.Handler
• func MaxSamplingRate(r int) middleware.TraceOption
• func PopulateRequestContext() func(http.Handler) http.Handler
• func RequestContext(ctx context.Context) func(http.Handler) http.Handler
• func RequestContextKeyVals(keyvals ...interface{}) func(http.Handler) http.Handler
• func RequestID(options ...middleware.RequestIDOption) func(http.Handler) http.Handler
• func SampleSize(s int) middleware.TraceOption
• func SamplingPercent(p int) middleware.TraceOption
• func SpanIDFunc(f middleware.IDFunc) middleware.TraceOption
• func Trace(opts ...middleware.TraceOption) func(http.Handler) http.Handler
• func TraceIDFunc(f middleware.IDFunc) middleware.TraceOption
• func UseXRequestIDHeaderOption(f bool) middleware.RequestIDOption
• func XRequestHeaderLimitOption(limit int) middleware.RequestIDOption
• type Doer
  • func WrapDoer(doer Doer) Doer
• type ResponseCapture
  • func CaptureResponse(w http.ResponseWriter) *ResponseCapture
  • func (w *ResponseCapture) Hijack() (net.Conn, *bufio.ReadWriter, error)
  • func (w *ResponseCapture) Write(b []byte) (int, error)
  • func (w *ResponseCapture) WriteHeader(code int)

Constants

const (
	// RequestMethodKey is the request context key used to store r.Method created by
	// the PopulateRequestContext middleware.
	RequestMethodKey ctxKey = iota + 1

	// RequestURIKey is the request context key used to store r.RequestURI created by
	// the PopulateRequestContext middleware.
	RequestURIKey

	// RequestPathKey is the request context key used to store r.URL.Path created by
	// the PopulateRequestContext middleware.
	RequestPathKey

	// RequestProtoKey is the request context key used to store r.Proto created by
	// the PopulateRequestContext middleware.
	RequestProtoKey

	// RequestHostKey is the request context key used to store r.Host created by
	// the PopulateRequestContext middleware.
	RequestHostKey

	// RequestRemoteAddrKey is the request context key used to store r.RemoteAddr
	// created by the PopulateRequestContext middleware.
	RequestRemoteAddrKey

	// RequestXForwardedForKey is the request context key used to store the
	// X-Forwarded-For header created by the PopulateRequestContext middleware.
	RequestXForwardedForKey

	// RequestXForwardedProtoKey is the request context key used to store the
	// X-Forwarded-Proto header created by the PopulateRequestContext middleware.
	RequestXForwardedProtoKey

	// RequestXRealIPKey is the request context key used to store the
	// X-Real-IP header created by the PopulateRequestContext middleware.
	RequestXRealIPKey

	// RequestAuthorizationKey is the request context key used to store the
	// Authorization header created by the PopulateRequestContext middleware.
	RequestAuthorizationKey

	// RequestRefererKey is the request context key used to store Referer header
	// created by the PopulateRequestContext middleware.
	RequestRefererKey

	// RequestUserAgentKey is the request context key used to store the User-Agent
	// header created by the PopulateRequestContext middleware.
	RequestUserAgentKey

	// RequestXRequestIDKey is the request context key used to store the X-Request-Id
	// header created by the PopulateRequestContext middleware.
	RequestXRequestIDKey

	// RequestAcceptKey is the request context key used to store the Accept header
	// created by the PopulateRequestContext middleware.
	RequestAcceptKey

	// RequestXCSRFTokenKey is the request context key used to store X-Csrf-Token header
	// created by the PopulateRequestContext middleware.
	RequestXCSRFTokenKey
)

const (
	// TraceIDHeader is the default name of the HTTP request header
	// containing the current TraceID if any.
	TraceIDHeader = "TraceID"

	// ParentSpanIDHeader is the default name of the HTTP request header
	// containing the parent span ID if any.
	ParentSpanIDHeader = "ParentSpanID"
)

Functions

func Debug

func Debug(mux goahttp.Muxer, w io.Writer) func(http.Handler) http.Handler

Debug returns a debug middleware which prints detailed information about incoming requests and outgoing responses including all headers, parameters and bodies.

func DiscardFromTrace

func DiscardFromTrace(discard *regexp.Regexp) middleware.TraceOption

DiscardFromTrace adds a regular expression for matching a request path to be discarded from tracing. see middleware.DiscardFromTrace() for more details.

func Log

func Log(l middleware.Logger) func(h http.Handler) http.Handler

Log returns a middleware that logs incoming HTTP requests and outgoing responses. The middleware uses the request ID set by the RequestID middleware or creates a short unique request ID if missing for each incoming request and logs it with the request and corresponding response details.

The middleware logs the incoming requests HTTP method and path as well as the originator of the request. The originator is computed by looking at the X-Forwarded-For HTTP header or - absent of that - the originating IP. The middleware also logs the response HTTP status code, body length (in bytes) and timing information.

func MaxSamplingRate

func MaxSamplingRate(r int) middleware.TraceOption

MaxSamplingRate is a wrapper for the top-level MaxSamplingRate.

func PopulateRequestContext

func PopulateRequestContext() func(http.Handler) http.Handler

PopulateRequestContext returns a middleware which populates a number of standard HTTP reqeust values into the request context. Those values may be extracted using the corresponding ContextKey type in this package.

func RequestContext

func RequestContext(ctx context.Context) func(http.Handler) http.Handler

RequestContext returns a middleware which initializes the request context.

func RequestContextKeyVals

func RequestContextKeyVals(keyvals ...interface{}) func(http.Handler) http.Handler

RequestContextKeyVals returns a middleware which adds the given key/value pairs to the request context.

func RequestID

func RequestID(options ...middleware.RequestIDOption) func(http.Handler) http.Handler

RequestID returns a middleware, which initializes the context with a unique value under the RequestIDKey key. Optionally uses the incoming "X-Request-Id" header, if present, with or without a length limit to use as request ID. the default behavior is to always generate a new ID.

examples of use:

service.Use(middleware.RequestID())

// enable options for using "X-Request-Id" header with length limit.
service.Use(middleware.RequestID(
  middleware.UseXRequestIDHeaderOption(true),
  middleware.XRequestHeaderLimitOption(128)))

func SampleSize

func SampleSize(s int) middleware.TraceOption

SampleSize is a wrapper for the top-level SampleSize.

func SamplingPercent

func SamplingPercent(p int) middleware.TraceOption

SamplingPercent is a wrapper for the top-level SamplingPercent.

func SpanIDFunc

func SpanIDFunc(f middleware.IDFunc) middleware.TraceOption

SpanIDFunc is a wrapper for the top-level SpanIDFunc.

func Trace

func Trace(opts ...middleware.TraceOption) func(http.Handler) http.Handler

Trace returns a trace middleware that initializes the trace information in the request context.

func TraceIDFunc

func TraceIDFunc(f middleware.IDFunc) middleware.TraceOption

TraceIDFunc is a wrapper for the top-level TraceIDFunc.

func UseXRequestIDHeaderOption

func UseXRequestIDHeaderOption(f bool) middleware.RequestIDOption

UseXRequestIDHeaderOption enables/disables using "X-Request-Id" header.

func XRequestHeaderLimitOption

func XRequestHeaderLimitOption(limit int) middleware.RequestIDOption

XRequestHeaderLimitOption sets the option for using "X-Request-Id" header.

Types

type Doer

type Doer interface {
	Do(*http.Request) (*http.Response, error)
}

Doer is the http client Do interface.

func WrapDoer

func WrapDoer(doer Doer) Doer

WrapDoer wraps a goa client Doer and sets the trace headers so that the downstream service may properly retrieve the parent span ID and trace ID.

type ResponseCapture

type ResponseCapture struct {
	http.ResponseWriter
	StatusCode    int
	ContentLength int
}

ResponseCapture is a http.ResponseWriter which captures the response status code and content length.

func CaptureResponse

func CaptureResponse(w http.ResponseWriter) *ResponseCapture

CaptureResponse creates a ResponseCapture that wraps the given ResponseWriter.

func (*ResponseCapture) Hijack

func (w *ResponseCapture) Hijack() (net.Conn, *bufio.ReadWriter, error)

Hijack supports the http.Hijacker interface.

func (*ResponseCapture) Write

func (w *ResponseCapture) Write(b []byte) (int, error)

Write computes the written len and stores it in ContentLength.

func (*ResponseCapture) WriteHeader

func (w *ResponseCapture) WriteHeader(code int)

WriteHeader records the value of the status code before writing it.