mux

gorilla/mux implements a request router and dispatcher for Go’s net/http package. Like the standard library’s http.ServeMux, a mux.Router matches incoming requests against a list of registered routes and calls the handler for whichever route matches — but it goes far beyond prefix matching, supporting URL path templates with named and regex-constrained variables, host matching, HTTP method restriction, header and query-value matchers, and fully custom matcher functions.

Because Router implements http.Handler directly, it drops into any existing net/http-based server without adapters. Routes can be named and later “reversed” into concrete URLs (including host and query variables), which keeps templates and redirects from hardcoding paths. Nested subrouters let an application group related routes under a shared host or path prefix so common conditions are only evaluated once, which also serves as a performance optimization for large route tables.

As one of the original and most widely deployed Go routers, mux has shaped the ergonomics that most Go routing libraries since have followed: chainable route builders, http.Handler-native middleware via a simple func(http.Handler) http.Handler signature, and context-based access to matched route variables from within handlers.

What You Get

• A Router that implements http.Handler, so it registers directly with http.Handle or an http.Server without any adapter layer
• Path templates with named variables and optional regex constraints (e.g. /articles/{category}/{id:[0-9]+}), retrievable in handlers via mux.Vars(r)
• Matchers for host, path prefix, HTTP methods, headers (including regex), URL schemes, and query values, composable on a single route
• Named routes that can be reversed into concrete URLs, hosts, or paths via Route.URL(), URLHost(), and URLPath()
• Subrouters for grouping routes under a shared host or path prefix, evaluated depth-first and reused for common-condition optimization
• Router- and route-level middleware via a MiddlewareFunc chain, plus a built-in CORSMethodMiddleware helper
• Configurable NotFoundHandler and MethodNotAllowedHandler for custom 404/405 responses
• A Walk function to traverse the full route tree, including nested subrouters, for introspection or documentation generation

Common Use Cases

• Routing REST API endpoints with path parameters, e.g. mapping GET /products/{key} and POST /articles/{category} to distinct handlers
• Serving a single-page application’s static assets alongside a JSON API from the same router, using PathPrefix and a custom spaHandler
• Building host- or subdomain-based routing, e.g. matching {subdomain}.example.com and extracting the subdomain as a route variable
• Applying shared middleware — logging, authentication, CORS — across a group of routes via Router.Use or Route.Use
• Building reversible, named URLs for redirects and templates so route paths are defined once and never hardcoded elsewhere
• Enforcing HTTP method and content-type/header constraints per route, e.g. restricting an endpoint to POST with a specific Content-Type

Under The Hood

Architecture

A mux.Router holds an ordered slice of *Route plus a name-indexed map for URL reversal; Router.ServeHTTP cleans the incoming path (redirecting to the canonical form unless SkipClean is set), then delegates to Router.Match, which walks routes in registration order and returns the first one whose matchers all pass. Each Route embeds a shared routeConf (host/path regexps, matcher list, build scheme) that subrouters copy via copyRouteConf so nested routers inherit parent constraints without mutating them. Matched route variables and the matched Route/Router are threaded through the request via context.WithValue rather than global state, and middleware is applied in Match itself by wrapping the resolved handler back-to-front — so a single request pass both selects and decorates the handler with no second traversal. Subrouters are just Routes whose handler or matcher is itself a *Router, which is what lets Walk and Match recurse depth-first through the tree.

Tech Stack

Pure standard library — net/http, net/url, regexp, path, context, and strings are the only imports across the whole package (go.mod declares zero external dependencies, targeting Go 1.20+). Path and host templates compile down to regexp.Regexp instances at route-registration time via an internal routeRegexp abstraction (regexp.go), with a package-level RegexpCompileFunc variable left overridable for callers who need custom compilation behavior. There is no build step beyond the Go toolchain, and the Makefile wires up golangci-lint, gosec, and govulncheck as opt-in local/CI targets rather than bundled dependencies.

Code Quality

The project has an extensive test suite (mux_test.go, route_test.go, regexp_test.go, middleware_test.go, old_test.go, plus benchmark and runnable example tests) exercising path/host/query/header matching, subrouting, URL building, and middleware ordering, run in CI with -race and coverage reporting across two Go versions. GitHub Actions also runs gosec (static security analysis) and govulncheck (known-vulnerability scanning) on every push and PR to main. Error handling is explicit and typed via sentinel errors (ErrMethodMismatch, ErrNotFound, ErrMetadataKeyNotFound) rather than panics, and exported types carry full godoc comments including a dedicated doc.go package overview.

API Design The API follows a fluent, chainable builder style — r.HandleFunc(path, handler).Methods(“GET”).Host(”…”) — that composes naturally with Go’s http.Handler interface, so it requires no custom request/response types and no non-standard handler signature. Getting started is a two-line NewRouter() plus http.Handle(”/”, router), and the one non-obvious step (reading path variables via mux.Vars(r) from context rather than a handler argument) is documented in the package overview and reflected consistently across every example file.