goa: github.com/goadesign/goa/middleware Index | Files | Directories

package middleware

import "github.com/goadesign/goa/middleware"


Package Files

context.go error_handler.go log_request.go log_response.go recover.go request_id.go required_header.go timeout.go tracer.go


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


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

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

func ContextParentSpanID Uses

func ContextParentSpanID(ctx context.Context) string

ContextParentSpanID returns the parent span ID extracted from the given context if any, the empty string otherwise.

func ContextRequestID Uses

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

ContextRequestID extracts the Request ID from the context.

func ContextSpanID Uses

func ContextSpanID(ctx context.Context) string

ContextSpanID returns the span ID extracted from the given context if any, the empty string otherwise.

func ContextTraceID Uses

func ContextTraceID(ctx context.Context) string

ContextTraceID returns the trace ID extracted from the given context if any, the empty string otherwise.

func ErrorHandler Uses

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. If you use github.com/pkg/errors then wrapping the error will allow a trace to be printed to the logs

func LogRequest Uses

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 Uses

func LogResponse() goa.Middleware

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

func Recover Uses

func Recover() goa.Middleware

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

func RequestID Uses

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 Uses

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 Uses

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 Uses

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 Uses

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.

func TraceDoer Uses

func TraceDoer(doer client.Doer) client.Doer

TraceDoer 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.

func Tracer Uses

func Tracer(sampleRate int, spanIDFunc, traceIDFunc IDFunc) goa.Middleware

Tracer returns a middleware that initializes the trace information in the context. The information can be retrieved using any of the ContextXXX functions.

sampleRate must be a value between 0 and 100. It represents the percentage of requests that should be traced.

spanIDFunc and traceIDFunc are the functions used to create Span and Trace IDs respectively. This is configurable so that the created IDs are compatible with the various backend tracing systems. The xray package provides implementations that produce AWS X-Ray compatible IDs.

If the incoming request has a TraceIDHeader header then the sample rate is disregarded and the tracing is enabled.

func WithTrace Uses

func WithTrace(ctx context.Context, traceID, spanID, parentID string) context.Context

WithTrace returns a context containing the given trace, span and parent span IDs.

type IDFunc Uses

type IDFunc func() string

IDFunc is a function that produces span and trace IDs for cosumption by tracing systems such as Zipkin or AWS X-Ray.



Package middleware imports 16 packages (graph) and is imported by 20 packages. Updated 2017-03-18. Refresh now. Tools for package owners.