On this page

Configuration Reference

All configuration is done by setting fields on the *Mux returned by muxmaster.New(). New sets production-safe defaults; a zero-value Mux{} does not have them (for example, its RedirectTrailingSlash is false).

Table of Contents


When Configuration Takes Effect

The first call to ServeHTTP copies every option and handler field into an internal snapshot, and requests read only that snapshot. Assigning a field after the first request has no effect until you call Rebuild(), which discards the snapshot and the cached 404, 405, OPTIONS and redirect handlers; the next request takes a new snapshot. Rebuild is safe to call while the server is serving.

mux.HandleMethodNotAllowed = false
mux.Rebuild() // the next request uses the new value

Set all fields before the server starts whenever possible.

Field Default after New()
RedirectTrailingSlash true
RedirectFixedPath false
HandleMethodNotAllowed true
HandleOPTIONS true
RedirectCode 0 (301 for GET and HEAD, 307 otherwise)
CaseInsensitive false
UseRawPath false
UnescapePathValues false
PoolFastParams false
PoolRequestBundle false
NotFound, MethodNotAllowed, GlobalOPTIONS, ErrorHandler, PanicHandler nil (built-in behaviour)

Router Behaviour

RedirectTrailingSlash

mux.RedirectTrailingSlash = true // default

Automatically redirects requests with a trailing slash mismatch:

  • GET /users/ → 301 redirect to /users (when /users is registered but not /users/)
  • GET /users → 301 redirect to /users/ (when /users/ is registered but not /users)

Other methods receive 307 by default. The redirect code is controlled by RedirectCode. No redirect is issued for / or for CONNECT requests.

Set to false to return 404 in both cases instead of redirecting.


RedirectFixedPath

mux.RedirectFixedPath = false // default

When true, a request whose path has no route is checked again with its path.Clean form, and redirected there if that path has a route:

  • Removes extra slashes: GET //users → 301 to /users
  • Resolves dots: GET /a/../users → 301 to /users

It does not change letter case. With the default false, such requests receive 404 (or 405).

Security: the default is false because path canonicalisation can bypass middleware that inspects the raw path. To serve the cleaned path without a redirect, use mux.Pre(middleware.CleanPath()) instead.


HandleMethodNotAllowed

mux.HandleMethodNotAllowed = true // default

When true, and the URL matches a registered route but not for the requested method, MuxMaster responds with 405 Method Not Allowed and sets the Allow header to the list of allowed methods.

When false, such requests receive a 404 Not Found instead.

The response handler can be customized via mux.MethodNotAllowed.


HandleOPTIONS

mux.HandleOPTIONS = true // default

Automatically responds to an OPTIONS request for a path that has routes but no explicit OPTIONS handler: status 204 No Content, an empty body, and an Allow header listing the registered methods in the order GET, HEAD, POST, PUT, PATCH, DELETE, CONNECT, TRACE, QUERY, followed by OPTIONS. An explicitly registered OPTIONS route takes precedence.

To customize the OPTIONS response globally:

mux.GlobalOPTIONS = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Access-Control-Allow-Methods", w.Header().Get("Allow"))
    w.WriteHeader(http.StatusNoContent)
})

Set to false to send unmatched OPTIONS requests to the 405 or 404 handling instead. The CORS middleware answers preflight requests itself (204) before the router's OPTIONS handling runs, so it works with either setting.

Note — Asterisk-form OPTIONS * HTTP/1.1: By default, net/http intercepts and answers asterisk-form OPTIONS requests directly (see Middleware — Pre routing for details). These requests never reach GlobalOPTIONS. To route them through MuxMaster, set http.Server.DisableGeneralOptionsHandler = true.


RedirectCode

mux.RedirectCode = 0 // default

The HTTP status code used for redirects triggered by RedirectTrailingSlash and RedirectFixedPath. With 0, GET and HEAD receive 301 Moved Permanently and every other method, including QUERY, receives 307 Temporary Redirect, which preserves the method and body. A non-zero value is used for every method. Common values:

Code Constant Semantics
301 http.StatusMovedPermanently Permanent redirect (cached)
302 http.StatusFound Temporary redirect (not cached)
307 http.StatusTemporaryRedirect Temporary, preserves method
308 http.StatusPermanentRedirect Permanent, preserves method

If you set 301 or 302, clients may change a POST (or other non-GET) request to GET when following the redirect; prefer 307 or 308 when the method must be preserved.


Path Matching

CaseInsensitive

mux.CaseInsensitive = false // default

When true, static segments of a pattern match regardless of letter case. A request for /Users/42 matches a route registered as /users/:id, and captured parameter values keep the case of the request (/USERS/AbC gives id = "AbC").

No redirect is issued; the handler sees the original URL. Lookup ignores this option.


UseRawPath

mux.UseRawPath = false // default

When true, MuxMaster uses r.URL.RawPath for route matching instead of r.URL.Path. This matters when path values contain percent-encoded slashes (%2F):

  • r.URL.Path: /files/a%2Fb is decoded to /files/a/b and would match /files/*filepath with filepath = "/a/b" (two separate segments)
  • r.URL.RawPath: /files/a%2Fb is kept as-is and matches /files/*filepath with filepath = "/a%2Fb" (treated as a single segment)

Enable this only if your application legitimately uses encoded slashes in URL paths.


UnescapePathValues

mux.UnescapePathValues = false // default

Takes effect only when UseRawPath is also true. With UseRawPath = false (the default), net/http has already decoded the path, so parameter values are already decoded and a second decode is never applied.

With UseRawPath = true, parameters are captured from the raw path, still percent-encoded; setting UnescapePathValues = true decodes them. For the route /files/:name and the request /files/a%2Fb:

UseRawPath UnescapePathValues Result
false either 404: the decoded path /files/a/b has an extra segment
true false name = "a%2Fb"
true true name = "a/b"

Security: with both options true, a captured value can contain a real / (and ..). Clean and confine it before using it as a file or URL path. MuxMaster logs a warning when a route is registered with this combination, and both Mux.ServeFiles and Group.ServeFiles panic rather than register under it. See SECURITY.md.


Opt-in Pools

mux.PoolRequestBundle = false // default
mux.PoolFastParams    = false // default

PoolRequestBundle recycles the per-request bundle of Handle routes with parameters; PoolFastParams recycles the Params slice of HandleFast routes with 1–3 parameters. Both remove the per-request allocation but require that handlers never retain the request (or ps) after returning. See the Maximum Performance Guide before enabling either.


Custom Handlers

NotFound

mux.NotFound = myNotFoundHandler

Called when no route matches the request path. Defaults to http.NotFound (plain-text 404).

mux.NotFound = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    muxmaster.JSON(w, http.StatusNotFound, map[string]string{
        "error": "not found",
        "path":  r.URL.Path,
    })
})

MethodNotAllowed

mux.MethodNotAllowed = myMethodNotAllowedHandler

Called when the path matches a route but not for the requested HTTP method. The Allow header is set to the list of allowed methods before this handler is called. When it is nil, the router writes 405 Method Not Allowed as plain text with X-Content-Type-Options: nosniff.

mux.MethodNotAllowed = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    muxmaster.JSON(w, http.StatusMethodNotAllowed, map[string]string{
        "error":   "method not allowed",
        "allowed": w.Header().Get("Allow"),
    })
})

Only active when HandleMethodNotAllowed is true.


GlobalOPTIONS

mux.GlobalOPTIONS = myOptionsHandler

Called instead of the default 204 No Content for every auto-handled OPTIONS request. The Allow header is already set when this handler runs.

Only active when HandleOPTIONS is true.

Middleware wrapping:

The automatic OPTIONS response is wrapped by any global middleware registered via Use(). The wrapper is applied dynamically: if you call Use() after assigning GlobalOPTIONS, the OPTIONS handler will be re-wrapped with the new middleware chain. This ensures that authentication, rate-limiting, logging, and other policies apply to OPTIONS responses.


PanicHandler

mux.PanicHandler = func(w http.ResponseWriter, r *http.Request, rcv any) { ... }

If set, recovers panics raised anywhere in ServeHTTP — Pre middleware, Use middleware and handlers of both Handle and HandleFast routes — and calls this function with the value passed to panic() as rcv. A RecovererWithLogger middleware catches the panics raised inside it first, so PanicHandler does not see those. PanicHandler must not panic itself: a second panic is not recovered by MuxMaster and reaches net/http, which closes the connection.

mux.PanicHandler = func(w http.ResponseWriter, r *http.Request, rcv any) {
    log.Printf("panic: %v", rcv)
    http.Error(w, "Internal Server Error", http.StatusInternalServerError)
}

ErrorHandler

mux.ErrorHandler = func(w http.ResponseWriter, r *http.Request, err error) { ... }

Called for every HandlerFuncE that returns a non-nil error. When it is nil, the router writes a plain-text 500 Internal Server Error, even if the error is an HTTPError. See Error Handling for details.


Complete Example

mux := muxmaster.New()

// Routing behaviour
mux.RedirectTrailingSlash  = true
mux.RedirectFixedPath      = false // keep false unless you need path.Clean redirects
mux.HandleMethodNotAllowed = true
mux.HandleOPTIONS          = true
mux.RedirectCode           = 0 // 301 for GET/HEAD, 307 otherwise

// Path matching
mux.CaseInsensitive       = false
mux.UseRawPath            = false
mux.UnescapePathValues    = false

// Custom error responses (JSON)
mux.NotFound = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    muxmaster.JSON(w, http.StatusNotFound, map[string]string{"error": "not found"})
})

mux.MethodNotAllowed = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    muxmaster.JSON(w, http.StatusMethodNotAllowed, map[string]string{
        "error":   "method not allowed",
        "allowed": w.Header().Get("Allow"),
    })
})

mux.PanicHandler = func(w http.ResponseWriter, r *http.Request, rcv any) {
    log.Printf("panic: %v\n%s", rcv, debug.Stack())
    muxmaster.JSON(w, http.StatusInternalServerError, map[string]string{
        "error": "internal server error",
    })
}

mux.ErrorHandler = func(w http.ResponseWriter, r *http.Request, err error) {
    code := http.StatusInternalServerError
    var he muxmaster.HTTPError
    if errors.As(err, &he) {
        code = he.StatusCode()
    } else {
        log.Printf("unhandled error: %v", err)
    }
    muxmaster.JSON(w, code, map[string]string{"error": err.Error()})
}

See Also

  • Routing — trailing slash and path normalization in more detail
  • Error Handling — custom error handler patterns
  • Middleware — CleanPath and StripSlashes as alternatives to redirect-based normalization

Common questions

How do I configure a MuxMaster router?

Set the exported fields of the *Mux returned by muxmaster.New() before the server starts, for example mux.HandleMethodNotAllowed = false.

MuxMaster has no option functions or configuration struct. New sets the defaults: RedirectTrailingSlash, HandleMethodNotAllowed, and HandleOPTIONS are true; every other flag is false, and RedirectCode is 0.

What happens if I change a field after the server has started?

A field changed after the first request has no effect until you call mux.Rebuild(), because the first ServeHTTP call freezes the configuration into a snapshot.

Rebuild discards the snapshot and the cached 404, 405, OPTIONS, and redirect handlers, and is safe to call while the server is serving.

Which status code do MuxMaster's automatic redirects use?

With RedirectCode left at 0, trailing-slash and fixed-path redirects use 301 Moved Permanently for GET and HEAD and 307 Temporary Redirect for every other method, including QUERY.

A non-zero RedirectCode is used for every method. RedirectFixedPath is false by default, because a redirect to a cleaned path can bypass middleware that inspects the raw path.

Upstream source

This page mirrors docs/configuration.md at the v1.3.0 tag. The behaviour it describes is implemented in mux.go.