handlers

README

gorilla/handlers

Package handlers is a collection of handlers (aka "HTTP middleware") for use with Go's net/http package (or any framework supporting http.Handler), including:

• LoggingHandler for logging HTTP requests in the Apache Common Log Format.
• CombinedLoggingHandler for logging HTTP requests in the Apache Combined Log Format commonly used by both Apache and nginx.
• CompressHandler for gzipping responses.
• ContentTypeHandler for validating requests against a list of accepted content types.
• MethodHandler for matching HTTP methods against handlers in a map[string]http.Handler
• ProxyHeaders for populating r.RemoteAddr and r.URL.Scheme based on the X-Forwarded-For, X-Real-IP, X-Forwarded-Proto and RFC7239 Forwarded headers when running a Go server behind a HTTP reverse proxy.
• CanonicalHost for re-directing to the preferred host when handling multiple domains (i.e. multiple CNAME aliases).
• RecoveryHandler for recovering from unexpected panics.

Other handlers are documented on the Gorilla website.

Example

A simple example using handlers.LoggingHandler and handlers.CompressHandler:

import (
    "net/http"
    "github.com/gorilla/handlers"
)

func main() {
    r := http.NewServeMux()

    // Only log requests to our admin dashboard to stdout
    r.Handle("/admin", handlers.LoggingHandler(os.Stdout, http.HandlerFunc(ShowAdminDashboard)))
    r.HandleFunc("/", ShowIndex)

    // Wrap our server with our gzip handler to gzip compress all responses.
    http.ListenAndServe(":8000", handlers.CompressHandler(r))
}

License

BSD licensed. See the included LICENSE file for details.

Documentation

Overview

Package handlers is a collection of handlers (aka "HTTP middleware") for use with Go's net/http package (or any framework supporting http.Handler).

The package includes handlers for logging in standardised formats, compressing HTTP responses, validating content types and other useful tools for manipulating requests and responses.

Index

• Constants
• func CORS(opts ...CORSOption) func(http.Handler) http.Handler
• func CanonicalHost(domain string, code int) func(h http.Handler) http.Handler
• func CombinedLoggingHandler(out io.Writer, h http.Handler) http.Handler
• func CompressHandler(h http.Handler) http.Handler
• func CompressHandlerLevel(h http.Handler, level int) http.Handler
• func ContentTypeHandler(h http.Handler, contentTypes ...string) http.Handler
• func HTTPMethodOverrideHandler(h http.Handler) http.Handler
• func LoggingHandler(out io.Writer, h http.Handler) http.Handler
• func ProxyHeaders(h http.Handler) http.Handler
• func RecoveryHandler(opts ...RecoveryOption) func(h http.Handler) http.Handler
• type CORSOption
  • func AllowCredentials() CORSOption
  • func AllowedHeaders(headers []string) CORSOption
  • func AllowedMethods(methods []string) CORSOption
  • func AllowedOriginValidator(fn OriginValidator) CORSOption
  • func AllowedOrigins(origins []string) CORSOption
  • func ExposedHeaders(headers []string) CORSOption
  • func IgnoreOptions() CORSOption
  • func MaxAge(age int) CORSOption
• type MethodHandler
  • func (h MethodHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type OriginValidator
• type RecoveryHandlerLogger
• type RecoveryOption
  • func PrintRecoveryStack(print bool) RecoveryOption
  • func RecoveryLogger(logger RecoveryHandlerLogger) RecoveryOption

Constants

const (
	// HTTPMethodOverrideHeader is a commonly used
	// http header to override a request method.
	HTTPMethodOverrideHeader = "X-HTTP-Method-Override"
	// HTTPMethodOverrideFormKey is a commonly used
	// HTML form key to override a request method.
	HTTPMethodOverrideFormKey = "_method"
)

Functions

func CORS

func CORS(opts ...CORSOption) func(http.Handler) http.Handler

CORS provides Cross-Origin Resource Sharing middleware. Example:

import (
    "net/http"

    "github.com/gorilla/handlers"
    "github.com/gorilla/mux"
)

func main() {
    r := mux.NewRouter()
    r.HandleFunc("/users", UserEndpoint)
    r.HandleFunc("/projects", ProjectEndpoint)

    // Apply the CORS middleware to our top-level router, with the defaults.
    http.ListenAndServe(":8000", handlers.CORS()(r))
}

func CanonicalHost

func CanonicalHost(domain string, code int) func(h http.Handler) http.Handler

CanonicalHost is HTTP middleware that re-directs requests to the canonical domain. It accepts a domain and a status code (e.g. 301 or 302) and re-directs clients to this domain. The existing request path is maintained.

Note: If the provided domain is considered invalid by url.Parse or otherwise returns an empty scheme or host, clients are not re-directed.

Example:

r := mux.NewRouter()
canonical := handlers.CanonicalHost("http://www.gorillatoolkit.org", 302)
r.HandleFunc("/route", YourHandler)

log.Fatal(http.ListenAndServe(":7000", canonical(r)))

func CombinedLoggingHandler

func CombinedLoggingHandler(out io.Writer, h http.Handler) http.Handler

CombinedLoggingHandler return a http.Handler that wraps h and logs requests to out in Apache Combined Log Format.

See http://httpd.apache.org/docs/2.2/logs.html#combined for a description of this format.

LoggingHandler always sets the ident field of the log to -

func CompressHandler

func CompressHandler(h http.Handler) http.Handler

CompressHandler gzip compresses HTTP responses for clients that support it via the 'Accept-Encoding' header.

Compressing TLS traffic may leak the page contents to an attacker if the page contains user input: http://security.stackexchange.com/a/102015/12208

func CompressHandlerLevel

func CompressHandlerLevel(h http.Handler, level int) http.Handler

CompressHandlerLevel gzip compresses HTTP responses with specified compression level for clients that support it via the 'Accept-Encoding' header.

The compression level should be gzip.DefaultCompression, gzip.NoCompression, or any integer value between gzip.BestSpeed and gzip.BestCompression inclusive. gzip.DefaultCompression is used in case of invalid compression level.

func ContentTypeHandler

func ContentTypeHandler(h http.Handler, contentTypes ...string) http.Handler

ContentTypeHandler wraps and returns a http.Handler, validating the request content type is compatible with the contentTypes list. It writes a HTTP 415 error if that fails.

Only PUT, POST, and PATCH requests are considered.

func HTTPMethodOverrideHandler

func HTTPMethodOverrideHandler(h http.Handler) http.Handler

HTTPMethodOverrideHandler wraps and returns a http.Handler which checks for the X-HTTP-Method-Override header or the _method form key, and overrides (if valid) request.Method with its value.

This is especially useful for HTTP clients that don't support many http verbs. It isn't secure to override e.g a GET to a POST, so only POST requests are considered. Likewise, the override method can only be a "write" method: PUT, PATCH or DELETE.

Form method takes precedence over header method.

func LoggingHandler

func LoggingHandler(out io.Writer, h http.Handler) http.Handler

LoggingHandler return a http.Handler that wraps h and logs requests to out in Apache Common Log Format (CLF).

See http://httpd.apache.org/docs/2.2/logs.html#common for a description of this format.

LoggingHandler always sets the ident field of the log to -

Example:

r := mux.NewRouter()
r.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
	w.Write([]byte("This is a catch-all route"))
})
loggedRouter := handlers.LoggingHandler(os.Stdout, r)
http.ListenAndServe(":1123", loggedRouter)

func ProxyHeaders

func ProxyHeaders(h http.Handler) http.Handler

ProxyHeaders inspects common reverse proxy headers and sets the corresponding fields in the HTTP request struct. These are X-Forwarded-For and X-Real-IP for the remote (client) IP address, X-Forwarded-Proto or X-Forwarded-Scheme for the scheme (http|https) and the RFC7239 Forwarded header, which may include both client IPs and schemes.

NOTE: This middleware should only be used when behind a reverse proxy like nginx, HAProxy or Apache. Reverse proxies that don't (or are configured not to) strip these headers from client requests, or where these headers are accepted "as is" from a remote client (e.g. when Go is not behind a proxy), can manifest as a vulnerability if your application uses these headers for validating the 'trustworthiness' of a request.

func RecoveryHandler

func RecoveryHandler(opts ...RecoveryOption) func(h http.Handler) http.Handler

RecoveryHandler is HTTP middleware that recovers from a panic, logs the panic, writes http.StatusInternalServerError, and continues to the next handler.

Example:

r := mux.NewRouter()
r.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
	panic("Unexpected error!")
})

http.ListenAndServe(":1123", handlers.RecoveryHandler()(r))

Types

type CORSOption

type CORSOption func(*cors) error

CORSOption represents a functional option for configuring the CORS middleware.

func AllowCredentials

func AllowCredentials() CORSOption

AllowCredentials can be used to specify that the user agent may pass authentication details along with the request.

func AllowedHeaders

func AllowedHeaders(headers []string) CORSOption

AllowedHeaders adds the provided headers to the list of allowed headers in a CORS request. This is an append operation so the headers Accept, Accept-Language, and Content-Language are always allowed. Content-Type must be explicitly declared if accepting Content-Types other than application/x-www-form-urlencoded, multipart/form-data, or text/plain.

func AllowedMethods

func AllowedMethods(methods []string) CORSOption

AllowedMethods can be used to explicitly allow methods in the Access-Control-Allow-Methods header. This is a replacement operation so you must also pass GET, HEAD, and POST if you wish to support those methods.

func AllowedOriginValidator

func AllowedOriginValidator(fn OriginValidator) CORSOption

AllowedOriginValidator sets a function for evaluating allowed origins in CORS requests, represented by the 'Allow-Access-Control-Origin' HTTP header.

func AllowedOrigins

func AllowedOrigins(origins []string) CORSOption

AllowedOrigins sets the allowed origins for CORS requests, as used in the 'Allow-Access-Control-Origin' HTTP header. Note: Passing in a []string{"*"} will allow any domain.

func ExposedHeaders

func ExposedHeaders(headers []string) CORSOption

ExposeHeaders can be used to specify headers that are available and will not be stripped out by the user-agent.

func IgnoreOptions

func IgnoreOptions() CORSOption

IgnoreOptions causes the CORS middleware to ignore OPTIONS requests, instead passing them through to the next handler. This is useful when your application or framework has a pre-existing mechanism for responding to OPTIONS requests.

func MaxAge

func MaxAge(age int) CORSOption

MaxAge determines the maximum age (in seconds) between preflight requests. A maximum of 10 minutes is allowed. An age above this value will default to 10 minutes.

type MethodHandler

type MethodHandler map[string]http.Handler

MethodHandler is an http.Handler that dispatches to a handler whose key in the MethodHandler's map matches the name of the HTTP request's method, eg: GET

If the request's method is OPTIONS and OPTIONS is not a key in the map then the handler responds with a status of 200 and sets the Allow header to a comma-separated list of available methods.

If the request's method doesn't match any of its keys the handler responds with a status of HTTP 405 "Method Not Allowed" and sets the Allow header to a comma-separated list of available methods.

func (MethodHandler) ServeHTTP

func (h MethodHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)

type OriginValidator

type OriginValidator func(string) bool

OriginValidator takes an origin string and returns whether or not that origin is allowed.

type RecoveryHandlerLogger

type RecoveryHandlerLogger interface {
	Println(...interface{})
}

RecoveryHandlerLogger is an interface used by the recovering handler to print logs.

type RecoveryOption

type RecoveryOption func(http.Handler)

RecoveryOption provides a functional approach to define configuration for a handler; such as setting the logging whether or not to print strack traces on panic.

func PrintRecoveryStack

func PrintRecoveryStack(print bool) RecoveryOption

PrintRecoveryStack is a functional option to enable or disable printing stack traces on panic.

func RecoveryLogger

func RecoveryLogger(logger RecoveryHandlerLogger) RecoveryOption

RecoveryLogger is a functional option to override the default logger