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

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

Index

• Constants
• func CombinedLoggingHandler(out io.Writer, h http.Handler) http.Handler
• func CompressHandler(h http.Handler) 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
• type MethodHandler
  • func (h MethodHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)

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

func ContentTypeHandler

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

ContentTypeHandler wraps and returns a http.Handler, validating the request content type is acompatible 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 -

Types

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 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)