handlers

gorilla/handlers is a lightweight collection of standalone HTTP middleware for Go’s net/http package, covering common concerns like access logging, gzip/deflate compression, CORS, method overriding, and proxy header handling. Each handler wraps an http.Handler and works with net/http directly, so it drops into any router or framework that speaks the standard library’s handler interface.

Part of the broader Gorilla web toolkit, the package favors small, independently usable pieces over a monolithic middleware stack — you import only the handlers you need. It has shipped since 2013 and is widely used as a dependency by other Go web libraries and applications needing production-grade request logging, compression, and CORS support without adopting a full framework.

What You Get

• Apache Common and Combined Log Format request logging via LoggingHandler and CombinedLoggingHandler
• Gzip/deflate response compression with CompressHandler and CompressHandlerLevel
• A full CORS middleware with functional options for origins, methods, headers, and credentials
• ProxyHeaders middleware that normalizes X-Forwarded-* and RFC7239 Forwarded headers into the request
• RecoveryHandler for catching panics and returning a 500 instead of crashing the server
• MethodHandler and HTTPMethodOverrideHandler for routing and overriding HTTP methods
• CanonicalHost middleware for redirecting requests to a canonical domain
• ContentTypeHandler for validating incoming Content-Type headers

Common Use Cases

• Adding Apache-style access logs to a Go HTTP service without a full observability stack
• Enabling gzip compression for JSON/HTML API responses to cut bandwidth
• Exposing a public API safely by configuring explicit CORS origins, methods, and headers
• Running a Go service behind nginx/HAProxy/ELB and needing the correct client IP/scheme from proxy headers
• Preventing a single panicking handler from taking down the whole server in production
• Supporting HTML forms and legacy clients that can’t send PUT/PATCH/DELETE by allowing method override

Under The Hood

Architecture The package is a flat, single-Go-package collection of independent middleware — handlers.go, compress.go, cors.go, proxy_headers.go, recovery.go, logging.go, and canonical.go — with no internal layering or shared state between them. Nearly every handler follows the same decorator pattern, either func(http.Handler) http.Handler or a small struct wrapping an http.Handler and implementing ServeHTTP itself, so any handler can be composed with any other by nesting function calls. The only cross-file dependency is a shared responseLogger/compressResponseWriter pattern for intercepting Write/WriteHeader calls, and an external httpsnoop dependency is used to preserve optional interfaces like http.Hijacker and http.Flusher when wrapping the ResponseWriter. Removing or replacing any single handler has no effect on the others, which is the intended design.

Tech Stack The module targets Go 1.20 and depends on the standard library almost exclusively (net/http, compress/gzip, compress/flate, regexp), with a single third-party dependency, github.com/felixge/httpsnoop v1.0.3, used to wrap http.ResponseWriter without losing optional interface support. There is no build tooling beyond go build/go test; a Makefile wires up golangci-lint, gosec, and govulncheck for local and CI verification, and GitHub Actions runs the test suite on push.

Code Quality Every source file has a matching _test.go counterpart (handlers_test.go, compress_test.go, cors_test.go, canonical_test.go, logging_test.go, proxy_headers_test.go, recovery_test.go), and CI runs tests with -race -cover. Error handling is mostly explicit — panics are recovered deliberately in RecoveryHandler and errors from write operations are checked — though a couple of //nolint markers flag known style debt around ignored type-assertion errors that the maintainers left as TODOs rather than silently swallowing. Exported identifiers carry full godoc comments, naming is idiomatic Go, and golangci-lint/gosec/govulncheck run in the verify pipeline.

API Design The consistent decorator signature (func(h http.Handler) http.Handler) means most handlers can be composed with zero configuration — just wrap the next handler in the chain — while the more configurable ones (CORS, RecoveryHandler) use the functional-options pattern (CORSOption, RecoveryOption) instead of large config structs, keeping call sites terse. Because everything operates on the standard http.Handler interface, the package integrates with any router (net/http’s ServeMux, gorilla/mux, chi, etc.) with no adapter code required, and the public API surface is small and has stayed stable across its decade of releases.