handlers

package
v0.0.0-...-33f293e Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 16, 2024 License: BSD-3-Clause, BSD-3-Clause Imports: 17 Imported by: 0

README

gorilla/handlers

Testing Codecov GoDoc Sourcegraph

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:

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

View Source 
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"
)

Variables

This section is empty.

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/unix-world/smartgoext/web-http/handlers"
    "github.com/unix-world/smartgoext/web-http/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 CustomLoggingHandler 

func CustomLoggingHandler(out io.Writer, h http.Handler, f LogFormatter) http.Handler

CustomLoggingHandler provides a way to supply a custom log formatter while taking advantage of the mechanisms in this package.

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), X-Forwarded-Host for the host 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

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

func OptionStatusCode 

func OptionStatusCode(code int) CORSOption

OptionStatusCode sets a custom status code on the OPTIONS requests. Default behaviour sets it to 200 to reflect best practices. This is option is not mandatory and can be used if you need a custom status code (i.e 204).

More informations on the spec: https://fetch.spec.whatwg.org/#cors-preflight-fetch

type LogFormatter 

type LogFormatter func(writer io.Writer, params LogFormatterParams)

LogFormatter gives the signature of the formatter function passed to CustomLoggingHandler.

type LogFormatterParams 

type LogFormatterParams struct {
	Request    *http.Request
	URL        url.URL
	TimeStamp  time.Time
	StatusCode int
	Size       int
}

LogFormatterParams is the structure any formatter will be handed when time to log comes.

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 stack traces on panic.

func PrintRecoveryStack 

func PrintRecoveryStack(shouldPrint 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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.