middleware

Documentation

Overview

Package middleware contains HTTP middlewares that wrap a HTTP handler to provide ancilliary functionality such as capturing HTTP details into the request context or printing debug information on incoming requests.

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 LogContext(logFromCtx func(context.Context) middleware.Logger) func(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 ...any) func(http.Handler) http.Handler
• func RequestID(options ...middleware.RequestIDOption) func(http.Handler) http.Handler
• func RequestIDHeaderOption(name string) middleware.RequestIDOption
• func SampleSize(s int) middleware.TraceOption
• func SamplingPercent(p int) middleware.TraceOption
• func SmartRedirectSlashes(next http.Handler) http.Handler
• 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) Flush()
  • func (w *ResponseCapture) Hijack() (net.Conn, *bufio.ReadWriter, error)
  • func (w *ResponseCapture) Push(target string, opts *http.PushOptions) 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.

Deprecated: use OpenTelemetry instead, see for example github.com/goadesign/clue. This function will be removed in a future version of Goa.

func LogContext

func LogContext(logFromCtx func(context.Context) middleware.Logger) func(http.Handler) http.Handler

LogContext returns a middleware that logs the incoming requests similarly to Log. LogContext calls the given function with the request context to extract the logger.

Deprecated: use OpenTelemetry instead, see for example github.com/goadesign/clue. This function will be removed in a future version of Goa.

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 header 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 ...any) 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)))

// enable options for using "Custom-Id" header.
service.Use(middleware.RequestID(middleware.RequestIDHeaderOption("Custom-Id"))

Deprecated: use OpenTelemetry instead, see for example github.com/goadesign/clue. This function will be removed in a future version of Goa.

func RequestIDHeaderOption

func RequestIDHeaderOption(name string) middleware.RequestIDOption

RequestIDHeaderOption sets the name of the header used to capture the incoming request ID. This option also automatically enabled the use of that header.

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 SmartRedirectSlashes

func SmartRedirectSlashes(next http.Handler) http.Handler

SmartRedirectSlashes is a middleware that matches the request path with patterns added to the router and redirects it.

If a pattern is added to the router with a trailing slash, any matches on that pattern without a trailing slash will be redirected to the version with the slash. If a pattern does not have a trailing slash, matches on that pattern with a trailing slash will be redirected to the version without.

This middleware depends on chi, so it needs to be mounted on chi's router. It make the router behavior similar to httptreemux.

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. Deprecated: use OpenTelemetry instead, see for example https://github.com/goadesign/clue. This function will be removed in a future version of Goa.

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.

Deprecated: this type is deprecated and will be removed in a future version of Goa.

func CaptureResponse

func CaptureResponse(w http.ResponseWriter) *ResponseCapture

CaptureResponse creates a ResponseCapture that wraps the given ResponseWriter.

Deprecated: Use OpenTelemetry instead, see for example github.com/goadesign/clue. This function will be removed in a future version of Goa.

func (*ResponseCapture) Flush

func (w *ResponseCapture) Flush()

Flush implements the http.Flusher interface if the underlying response writer supports it.

func (*ResponseCapture) Hijack

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

Hijack supports the http.Hijacker interface.

func (*ResponseCapture) Push

func (w *ResponseCapture) Push(target string, opts *http.PushOptions) error

Push implements the http.Pusher interface if the underlying response writer supports it.

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.