mux

Documentation

Overview

Package mux routes HTTP requests using path templates compiled to Go regular expressions.

Templates

Templates match the complete path visible to their router and are anchored automatically. Literal segments are escaped. A :placeholder matches one non-empty segment, while a *wildcard matches one or more segments:

m.Get("/users/:id", func(w http.ResponseWriter, r *http.Request) {
	id := mux.URLParam(r, "id")
	// ...
})

m.Get("/files/*path", func(w http.ResponseWriter, r *http.Request) {
	path := mux.URLParam(r, "path")
	// ...
})

A placeholder or wildcard must occupy its complete path segment. Use RegisterConstraint before registering routes to replace the default matcher for parameters with a particular name.

Routes are evaluated in registration order and the first matching route with a handler for the request method wins.

Sub-routers

Route mounts a child router at a path prefix. The prefix is removed from the path used for matching in the child, while handlers retain the original URL:

m.Route("/api", func(r mux.Router) {
	r.Get("/widgets/:id", ...) // matches GET /api/widgets/123
})

Once a Route prefix matches, its child owns the namespace and produces the final 404 or 405 response when no child endpoint handles the request.

Index

• func URLParam(r *http.Request, name string) string
• func URLParamFromCtx(ctx context.Context, name string) string
• func ValidPattern(pattern string) error
• type Logger
• type Middlewares
• type Mux
  • func New(opts ...Option) *Mux
  • func (mx *Mux) Connect(pattern string, handler http.HandlerFunc)
  • func (mx *Mux) Delete(pattern string, handler http.HandlerFunc)
  • func (mx *Mux) Get(pattern string, handler http.HandlerFunc)
  • func (mx *Mux) Group(fn func(r Router)) Router
  • func (mx *Mux) Handle(pattern string, handler http.Handler)
  • func (mx *Mux) HandleFunc(pattern string, handler http.HandlerFunc)
  • func (mx *Mux) Head(pattern string, handler http.HandlerFunc)
  • func (mx *Mux) Method(method, pattern string, handler http.Handler)
  • func (mx *Mux) MethodFunc(method, pattern string, handler http.HandlerFunc)
  • func (mx *Mux) MethodNotAllowed(handler http.HandlerFunc)
  • func (mx *Mux) NotFound(handler http.HandlerFunc)
  • func (mx *Mux) Options(pattern string, handler http.HandlerFunc)
  • func (mx *Mux) Patch(pattern string, handler http.HandlerFunc)
  • func (mx *Mux) Post(pattern string, handler http.HandlerFunc)
  • func (mx *Mux) Put(pattern string, handler http.HandlerFunc)
  • func (mx *Mux) RegisterConstraint(name, expression string)
  • func (mx *Mux) Route(pattern string, fn func(r Router)) Router
  • func (mx *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (mx *Mux) Trace(pattern string, handler http.HandlerFunc)
  • func (mx *Mux) Use(middlewares ...func(http.Handler) http.Handler)
  • func (mx *Mux) With(middlewares ...func(http.Handler) http.Handler) Router
• type Option
  • func WithLogger(l Logger) Option
  • func WithMethodNotAllowedHandler(h http.HandlerFunc) Option
  • func WithNotFoundHandler(h http.HandlerFunc) Option
• type Router

Functions

func URLParam

func URLParam(r *http.Request, name string) string

URLParam returns the value of the named regex capture group for the current request, or "" if no such group matched.

func URLParamFromCtx

func URLParamFromCtx(ctx context.Context, name string) string

URLParamFromCtx returns the value of the named regex capture group stored in ctx, or "" if no such group matched.

func ValidPattern

func ValidPattern(pattern string) error

ValidPattern reports whether pattern is a valid route template. Route templates begin with '/', contain literal path segments, and may use :placeholder or *wildcard segments.

Types

type Logger

type Logger interface {
	Debug(msg string, args ...any)
}

Logger is the minimal logging surface mux uses. *slog.Logger satisfies it directly, so New(WithLogger(slog.Default())) works without an adapter; other loggers need only a small shim.

type Middlewares

type Middlewares []func(http.Handler) http.Handler

Middlewares is a slice of standard middleware handlers.

type Mux

type Mux struct {
	// contains filtered or unexported fields
}

Mux routes HTTP requests using path templates.

func New

func New(opts ...Option) *Mux

New returns a newly initialized Mux that implements the Router interface, configured by the given options. Call New() for defaults, or pass options such as WithNotFoundHandler to customize behavior.

func (*Mux) Connect

func (mx *Mux) Connect(pattern string, handler http.HandlerFunc)

Connect registers a CONNECT handler for pattern.

func (*Mux) Delete

func (mx *Mux) Delete(pattern string, handler http.HandlerFunc)

Delete registers a DELETE handler for pattern.

func (*Mux) Get

func (mx *Mux) Get(pattern string, handler http.HandlerFunc)

Get registers a GET handler for pattern.

func (*Mux) Group

func (mx *Mux) Group(fn func(r Router)) Router

Group adds an inline router with its own middleware stack.

func (*Mux) Handle

func (mx *Mux) Handle(pattern string, handler http.Handler)

Handle registers handler for all methods matching pattern.

func (*Mux) HandleFunc

func (mx *Mux) HandleFunc(pattern string, handler http.HandlerFunc)

HandleFunc registers handler for all methods matching pattern.

func (*Mux) Head

func (mx *Mux) Head(pattern string, handler http.HandlerFunc)

Head registers a HEAD handler for pattern.

func (*Mux) Method

func (mx *Mux) Method(method, pattern string, handler http.Handler)

Method registers handler for method and pattern.

func (*Mux) MethodFunc

func (mx *Mux) MethodFunc(method, pattern string, handler http.HandlerFunc)

MethodFunc registers handler for method and pattern.

func (*Mux) MethodNotAllowed

func (mx *Mux) MethodNotAllowed(handler http.HandlerFunc)

MethodNotAllowed sets the handler used when a path matches but its method does not.

func (*Mux) NotFound

func (mx *Mux) NotFound(handler http.HandlerFunc)

NotFound sets the handler used when no route matches.

func (*Mux) Options

func (mx *Mux) Options(pattern string, handler http.HandlerFunc)

Options registers an OPTIONS handler for pattern.

func (*Mux) Patch

func (mx *Mux) Patch(pattern string, handler http.HandlerFunc)

Patch registers a PATCH handler for pattern.

func (*Mux) Post

func (mx *Mux) Post(pattern string, handler http.HandlerFunc)

Post registers a POST handler for pattern.

func (*Mux) Put

func (mx *Mux) Put(pattern string, handler http.HandlerFunc)

Put registers a PUT handler for pattern.

func (*Mux) RegisterConstraint

func (mx *Mux) RegisterConstraint(name, expression string)

RegisterConstraint sets the regular-expression fragment used by parameters with name in routes registered through this router scope. Constraints are inherited by child scopes and may be overridden there. It panics when the name or expression is invalid, when the name was already registered in this scope, or when routes have already been registered through this scope.

func (*Mux) Route

func (mx *Mux) Route(pattern string, fn func(r Router)) Router

Route creates a child router and mounts it at pattern. Once pattern matches, the child router owns that path namespace, including its 404 and 405 responses. The matched prefix is removed from the path used for child route matching; handlers continue to see the original request URL.

func (*Mux) ServeHTTP

func (mx *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Mux) Trace

func (mx *Mux) Trace(pattern string, handler http.HandlerFunc)

Trace registers a TRACE handler for pattern.

func (*Mux) Use

func (mx *Mux) Use(middlewares ...func(http.Handler) http.Handler)

Use appends middleware to the router's middleware stack.

func (*Mux) With

func (mx *Mux) With(middlewares ...func(http.Handler) http.Handler) Router

With returns an inline router using the supplied middleware.

type Option

type Option func(*Mux)

Option configures a Mux at construction time. Pass options to New.

func WithLogger

func WithLogger(l Logger) Option

WithLogger sets the debug logger. By default the router logs nothing.

func WithMethodNotAllowedHandler

func WithMethodNotAllowedHandler(h http.HandlerFunc) Option

WithMethodNotAllowedHandler sets the handler invoked when a route matches the request path but not its method.

func WithNotFoundHandler

func WithNotFoundHandler(h http.HandlerFunc) Option

WithNotFoundHandler sets the handler invoked when no route matches the request path.

type Router

type Router interface {
	http.Handler

	// Use appends one or more middlewares to the Router stack.
	Use(middlewares ...func(http.Handler) http.Handler)

	// Group adds an inline Router with a fresh middleware and constraint scope.
	Group(fn func(r Router)) Router

	// Route creates and mounts a child Router at pattern.
	Route(pattern string, fn func(r Router)) Router

	// RegisterConstraint defines the regular-expression fragment used for
	// parameters with name in routes registered through this scope.
	RegisterConstraint(name, expression string)

	// Handle and HandleFunc add routes matching all HTTP methods.
	Handle(pattern string, h http.Handler)
	HandleFunc(pattern string, h http.HandlerFunc)

	// Method and MethodFunc add routes matching method.
	Method(method, pattern string, h http.Handler)
	MethodFunc(method, pattern string, h http.HandlerFunc)

	Connect(pattern string, h http.HandlerFunc)
	Delete(pattern string, h http.HandlerFunc)
	Get(pattern string, h http.HandlerFunc)
	Head(pattern string, h http.HandlerFunc)
	Options(pattern string, h http.HandlerFunc)
	Patch(pattern string, h http.HandlerFunc)
	Post(pattern string, h http.HandlerFunc)
	Put(pattern string, h http.HandlerFunc)
	Trace(pattern string, h http.HandlerFunc)

	// NotFound defines a handler for unmatched routes.
	NotFound(h http.HandlerFunc)

	// MethodNotAllowed defines a handler for matched paths without a handler for
	// the request method.
	MethodNotAllowed(h http.HandlerFunc)
}

Router is the routing surface implemented by Mux.