middleware

README

goa Middlewares

The middleware package provides middlewares that do not depend on additional packages other than the ones already used by goa. These middlewares provide functionality that is useful to most microservices:

• LogRequest enables logging of incoming requests and corresponding responses. The log format is entirely configurable. The default format logs the request HTTP method, path and parameters as well as the corresponding action and controller names. It also logs the request duration and response length. It also logs the request payload if the DEBUG log level is enabled. Finally if the RequestID middleware is mounted LogRequest logs the unique request ID with each log entry.

• LogResponse logs the content of the response body if the DEBUG log level is enabled.

• RequestID injects a unique ID in the request context. This ID is used by the logger and can be used by controller actions as well. The middleware looks for the ID in the RequestIDHeader header and if not found creates one.

• Recover recover panics and logs the panic object and backtrace.

• Timeout sets a deadline in the request context. Controller actions may subscribe to the context channel to get notified when the timeout expires.

• RequireHeader checks for the presence of a header in the request with a value matching a given regular expression. If the header is absent or does not match the regexp the middleware sends a HTTP response with a given HTTP status.

Other middlewares listed below are provided as separate Go packages.

Gzip

Package gzip contributed by @tylerb adds the ability to compress response bodies using gzip format as specified in RFC 1952.

Security

package security contains middleware that should be used in conjunction with the security DSL.

Documentation

Index

• Constants
• func ContextRequestID(ctx context.Context) (reqID string)
• func ErrorHandler(service *goa.Service, verbose bool) goa.Middleware
• func LogRequest(verbose bool) goa.Middleware
• func LogResponse() goa.Middleware
• func Recover() goa.Middleware
• func RequestID() goa.Middleware
• func RequestIDWithHeader(requestIDHeader string) goa.Middleware
• func RequestIDWithHeaderAndLengthLimit(requestIDHeader string, lengthLimit int) goa.Middleware
• func RequireHeader(service *goa.Service, pathPattern *regexp.Regexp, requiredHeaderName string, ...) goa.Middleware
• func Timeout(timeout time.Duration) goa.Middleware

Constants

const (
	// RequestIDHeader is the name of the header used to transmit the request ID.
	RequestIDHeader = "X-Request-Id"

	// DefaultRequestIDLengthLimit is the default maximum length for the request ID header value.
	DefaultRequestIDLengthLimit = 128
)

Functions

func ContextRequestID

func ContextRequestID(ctx context.Context) (reqID string)

ContextRequestID extracts the Request ID from the context.

func ErrorHandler

func ErrorHandler(service *goa.Service, verbose bool) goa.Middleware

ErrorHandler turns a Go error into an HTTP response. It should be placed in the middleware chain below the logger middleware so the logger properly logs the HTTP response. ErrorHandler understands instances of goa.ServiceError and returns the status and response body embodied in them, it turns other Go error types into a 500 internal error response. If verbose is false the details of internal errors is not included in HTTP responses.

func LogRequest

func LogRequest(verbose bool) goa.Middleware

LogRequest creates a request logger middleware. This middleware is aware of the RequestID middleware and if registered after it leverages the request ID for logging. If verbose is true then the middlware logs the request and response bodies.

func LogResponse

func LogResponse() goa.Middleware

LogResponse creates a response logger middleware. Only Logs the raw response data without accumulating any statistics.

func Recover

func Recover() goa.Middleware

Recover is a middleware that recovers panics and maps them to errors.

func RequestID

func RequestID() goa.Middleware

RequestID is a middleware that injects a request ID into the context of each request. Retrieve it using ctx.Value(ReqIDKey). If the incoming request has a RequestIDHeader header then that value is used else a random value is generated.

func RequestIDWithHeader

func RequestIDWithHeader(requestIDHeader string) goa.Middleware

RequestIDWithHeader behaves like the middleware RequestID, but it takes the request id header as the (first) argument.

func RequestIDWithHeaderAndLengthLimit

func RequestIDWithHeaderAndLengthLimit(requestIDHeader string, lengthLimit int) goa.Middleware

RequestIDWithHeaderAndLengthLimit behaves like the middleware RequestID, but it takes the request id header as the (first) argument and a length limit for truncation of the request header value if it exceeds a reasonable length. The limit can be negative for unlimited.

func RequireHeader

func RequireHeader(
	service *goa.Service,
	pathPattern *regexp.Regexp,
	requiredHeaderName string,
	requiredHeaderValue *regexp.Regexp,
	failureStatus int) goa.Middleware

RequireHeader requires a request header to match a value pattern. If the header is missing or does not match then the failureStatus is the response (e.g. http.StatusUnauthorized). If pathPattern is nil then any path is included. If requiredHeaderValue is nil then any value is accepted so long as the header is non-empty.

func Timeout

func Timeout(timeout time.Duration) goa.Middleware

Timeout sets a global timeout for all controller actions. The timeout notification is made through the context, it is the responsability of the request handler to handle it. For example:

func (ctrl *Controller) DoLongRunningAction(ctx *DoLongRunningActionContext) error {
	action := NewLongRunning()      // setup long running action
	c := make(chan error, 1)        // create return channel
	go func() { c <- action.Run() } // Launch long running action goroutine
	select {
	case <- ctx.Done():             // timeout triggered
		action.Cancel()         // cancel long running action
		<-c                     // wait for Run to return.
		return ctx.Err()        // retrieve cancel reason
	case err := <-c:   		// action finished on time
		return err  		// forward its return value
	}
}

Package golang.org/x/net/context/ctxhttp contains an implementation of an HTTP client which is context-aware:

func (ctrl *Controller) HttpAction(ctx *HttpActionContext) error {
	req, err := http.NewRequest("GET", "http://iamaslowservice.com", nil)
	// ...
	resp, err := ctxhttp.Do(ctx, nil, req) // returns if timeout triggers
	// ...
}

Controller actions can check if a timeout is set by calling the context Deadline method.