middleware

Documentation

Overview

Package middleware provides symbols for HTTP "middleware" which wraps handlers to perform common behaviors, such as authentication, headers, and compression.

Index

• Constants
• Variables
• func BackendErrorHandler(code int, userErr error, sysErr error) http.Handler
• func DisabledRouteHandler() http.Handler
• func GzipIfAccepts(r *http.Request, w http.ResponseWriter, b []byte) ([]byte, error)
• func GzipResponse(w http.ResponseWriter, r *http.Request, bytes []byte)
• func NotImplementedHandler() http.Handler
• func Use(h http.HandlerFunc, middlewares []Middleware) http.HandlerFunc
• func WrapAccessLog(secret string, h http.Handler) http.HandlerFunc
• func WrapHeaders(h http.HandlerFunc) http.HandlerFunc
• func WrapPanicRecover(h http.HandlerFunc) http.HandlerFunc
• type AuthBase
  • func (a AuthBase) GetWrapper(privLevelRequired int) Middleware
• type Middleware
  • func GetDefault(secret string, requestTimeout time.Duration) []Middleware
  • func GetWrapAccessLog(secret string) Middleware
  • func RequiredPermissionsMiddleware(requiredPerms []string) Middleware
  • func TimeOutWrapper(timeout time.Duration) Middleware

Constants

const AccessLogTimeFormat = "02/Jan/2006:15:04:05 -0700"

AccessLogTimeFormat is the time format of the access log, as used by time.Time.Format.

const DefaultRequestTimeout = time.Second * time.Duration(60)

DefaultRequestTimeout is the default request timeout, if no timeout is configured. This should be used by all Traffic Ops routing, and is recommended for use by plugins.

const IMSHIT = "IMS_HIT"

IMSHIT when a 304(Not Modified) was returned

const IMSMISS = "IMS_MISS"

IMSMISS when anything other than a 304 was returned, meaning that something changed after the If-Modified-Since time of the request

const NONIMS = "NON_IMS"

These are the different status values associated with an If-Modified-Since(IMS) request NONIMS when the request doesn't contain the If-Modified-Since header

const RouteID = "RouteID"

RouteID

Variables

var ServerName = "traffic_ops_golang" + "/" + about.About.Version

ServerName is the name and version of Traffic Ops. Things that print the server application name and version, for example in headers or logs, should use this.

Functions

func BackendErrorHandler

func BackendErrorHandler(code int, userErr error, sysErr error) http.Handler

func DisabledRouteHandler

func DisabledRouteHandler() http.Handler

DisabledRouteHandler returns a http.Handler which returns a HTTP 5xx code to the client, and an error message indicating the route is currently disabled. This is used for routes which have been disabled via configuration. See config.ConfigTrafficOpsGolang.RoutingBlacklist.DisabledRoutes.

func GzipIfAccepts

func GzipIfAccepts(r *http.Request, w http.ResponseWriter, b []byte) ([]byte, error)

GzipIfAccepts gzips the given bytes, writes a `Content-Encoding: gzip` header to the given writer, and returns the gzipped bytes, if the Request supports GZip (has an Accept-Encoding header). Else, returns the bytes unmodified. Note the given bytes are NOT written to the given writer. It is assumed the bytes may need to pass thru other middleware before being written. TODO: drichardson - refactor these to a generic area

func GzipResponse

func GzipResponse(w http.ResponseWriter, r *http.Request, bytes []byte)

GzipResponse takes a function which cannot error and returns only bytes, and wraps it as a http.HandlerFunc. The errContext is logged if the write fails, and should be enough information to trace the problem (function name, endpoint, request parameters, etc). It gzips the given bytes and writes them to w, as well as writing the appropriate 'Content-Encoding: gzip' header, if the request included an 'Accept-Encoding: gzip' header. If the request doesn't accept gzip, the bytes are written to w unmodified.

func NotImplementedHandler

func NotImplementedHandler() http.Handler

NotImplementedHandler returns a http.Handler which returns to the client a HTTP 501 Not Implemented status code, and a body which is a standard Traffic Ops error JSON. Note this is common usage in Traffic Ops for unimplemented endpoints (for example, which were impossible or impractical to rewrite from Perl). This is a something of a misuse of the HTTP spec. RFC 7231 states 501 Not Implemented is intended for HTTP Methods which are not implemented. However, it's not a clear violation of the Spec, and Traffic Ops has determined it is the safest and least ambiguous way to indicate endpoints which no longer or don't yet exist.

func Use

func Use(h http.HandlerFunc, middlewares []Middleware) http.HandlerFunc

Use takes a slice of middlewares, and applies them in reverse order (which is the intuitive behavior) to the given HandlerFunc h. It returns a HandlerFunc which will call all middlewares, and then h.

func WrapAccessLog

func WrapAccessLog(secret string, h http.Handler) http.HandlerFunc

WrapAccessLog takes the cookie secret and a http.Handler, and returns a HandlerFunc which writes to the Access Log (which is the lib/go-log EventLog) after the HandlerFunc finishes. This is not a Middleware, because it needs the secret as a parameter. For a Middleware, see GetWrapAccessLog.

func WrapHeaders

func WrapHeaders(h http.HandlerFunc) http.HandlerFunc

WrapHeaders is a Middleware which adds common headers and behavior to the handler. It specifically:

• Adds default CORS headers to the response.
• Adds the Whole-Content-SHA512 checksum header to the response.
• Gzips the response and sets the Content-Encoding header, if the client sent an Accept-Encoding: gzip header.
• Adds the Vary: Accept-Encoding header to the response

func WrapPanicRecover

func WrapPanicRecover(h http.HandlerFunc) http.HandlerFunc

WrapPanicRecover is a Middleware which adds a panic recover call to the given HandlerFunc h. If h throws an unhandled panic, an error is logged and an Internal Server Error is returned to the client.

Types

type AuthBase

type AuthBase struct {
	Secret   string
	Override Middleware
}

AuthBase is the basic authentication object for middleware. It contains the data required for authentication, as well as a function to get a Middleware to perform authentication.

func (AuthBase) GetWrapper

func (a AuthBase) GetWrapper(privLevelRequired int) Middleware

GetWrapper returns a Middleware which performs authentication of the current user at the given privilege level. The returned Middleware also adds the auth.CurrentUser object to the request context, which may be retrieved by a handler via api.NewInfo or auth.GetCurrentUser.

type Middleware

type Middleware func(handlerFunc http.HandlerFunc) http.HandlerFunc

Middleware is an HTTP dispatch "middleware" function. A Middleware is a function which takes an http.HandlerFunc and returns a new http.HandlerFunc, typically wrapping the execution of the given handlerFunc with some additional behavior. For example, adding headers or gzipping the body.

func GetDefault

func GetDefault(secret string, requestTimeout time.Duration) []Middleware

GetDefault returns the default middleware for Traffic Ops. This includes writing to the access log, a request timeout, default headers such as CORS, and compression.

func GetWrapAccessLog

func GetWrapAccessLog(secret string) Middleware

GetWrapAccessLog returns a Middleware which writes to the Access Log (which is the lib/go-log EventLog) after the HandlerFunc finishes.

func RequiredPermissionsMiddleware

func RequiredPermissionsMiddleware(requiredPerms []string) Middleware

RequiredPermissionsMiddleware produces a Middleware that checks that the authenticated user has all of the passed Permissions. If they are missing one or more Permissions, an error is returned to the client and handling is terminated early.

This will try to deduce the authenticated user regardless of Middleware order, but calling an AuthBase.GetWrapper-produced Middleware *after* this Middleware will result in extra db calls, so for best results this should always be used after that Middleware.

func TimeOutWrapper

func TimeOutWrapper(timeout time.Duration) Middleware

TimeOutWrapper is a Middleware which adds the given timeout to the request. This causes the request to abort and return an error to the user if the handler takes longer than the timeout to execute.